lat.md(Agent Lattice): AI 코딩 에이전트와 사람을 위한 마크다운 기반 코드베이스 지식 그래프

9bow · 5월 10, 2026, 3:30오전

lat.md 소개

코드베이스가 일정 규모를 넘어가면 단일한 AGENTS.md나 README.md로 모든 설계 결정과 도메인 맥락을 담아 두기 어려워집니다. 핵심 의사결정은 길어지는 문서 깊숙이 묻히고, 비즈니스 로직이 문서화되지 않은 채 구현체에만 남으며, AI 코딩 에이전트는 결국 찾을 수 없는 맥락을 환각(Hallucination)으로 채우게 됩니다. lat.md(Agent Lattice)는 이 문제를 정면으로 다루는 오픈소스 도구로, 프로젝트 루트의 lat.md/ 디렉토리에 모이는 마크다운 파일들의 집합을 코드베이스 전용 지식 그래프(Knowledge Graph)로 다룹니다.

핵심 아이디어는 단순합니다. 마크다운 섹션끼리는 위키 링크([[wiki links]])로 연결하고, 마크다운에서 코드 심볼로는 [[src/auth.ts#validateToken]] 같은 링크로 들어가며, 코드에서는 // @lat: [[section-id]] 주석으로 다시 그래프로 돌아오게 합니다. 이렇게 양방향으로 묶인 그래프 위에서 lat check 같은 명령이 참조 무결성(Referential Integrity)을 강제하기 때문에, 시간이 지나도 문서와 코드가 손쉽게 어긋나지 않도록 유지할 수 있습니다.

이 접근의 1차적인 수혜자는 AI 에이전트입니다. 에이전트는 코드 전체를 grep으로 훑는 대신, 그래프에서 설계 결정·제약·도메인 맥락을 빠르고 일관되게 검색해 사용할 수 있습니다. 사람의 측면에서도 풀 리퀘스트(Pull Request) 리뷰를 코드보다 먼저 lat.md/의 의미적 변경부터 살펴봄으로써 "무엇이, 왜 바뀌었는가" 를 빠르게 파악할 수 있고, 세션 종료와 함께 휘발되던 프롬프트의 추론 맥락도 그래프에 누적되어 다음 세션에서 그대로 재사용됩니다.

lat.md의 동작 원리와 디렉토리 구조

lat init 명령으로 프로젝트 루트에 lat.md/ 디렉토리를 만들면, 아키텍처·인증·테스트 명세 같은 문서를 자유롭게 작성할 수 있습니다. 섹션 간 링크는 [[file#Section#Subsection]] 문법으로 표현하며, 코드 심볼로 들어갈 때는 파일 경로와 심볼 이름을 함께 적습니다. 코드 쪽에는 // @lat: [[section-id]] 주석을 달아 어느 섹션과 짝이 되는지를 명시합니다. Python 코드라면 # 주석을 사용하면 됩니다.

my-project/
├── lat.md/
│   ├── architecture.md    # system design, key decisions
│   ├── auth.md            # authentication & authorization logic
│   └── tests.md           # test specs (require-code-mention: true)
├── src/
│   ├── auth.ts            # // @lat: [[auth#OAuth Flow]]
│   └── server.ts          # // @lat: [[architecture#Request Pipeline]]
└── ...

이렇게 구성된 그래프는 lat check 명령으로 일관성을 검사할 수 있습니다. 위키 링크가 사라진 섹션을 가리키거나 코드 주석이 더 이상 존재하지 않는 섹션을 참조하면 즉시 오류로 보고됩니다. 또한 테스트 명세 파일에 require-code-mention: true 메타데이터를 적어 두면, 각 명세는 반드시 // @lat: 주석이 달린 테스트 코드와 짝을 이루어야 하며, 짝이 없는 명세는 lat check가 누락된 백링크(Backlink)로 표시합니다. 결과적으로 테스트 커버리지를 코드가 아닌 지식 그래프 차원에서 관리하고 리뷰할 수 있습니다.

lat.md CLI와 에이전트 통합

lat.md는 Node.js 기반 CLI를 통해 사람과 에이전트가 동일한 방식으로 그래프를 탐색·유지보수할 수 있도록 설계되어 있습니다. 주요 명령은 다음과 같습니다.

lat init: lat.md/ 디렉토리를 스캐폴딩하고, 인기 코딩 에이전트가 lat을 자동으로 갱신·검증하도록 훅(Hook)과 지시 사항을 설치합니다.
lat check: 위키 링크와 코드 참조의 정합성을 검사합니다. 에이전트가 작업을 마무리하기 전에 자동으로 호출하도록 권장됩니다.
lat search: 임베딩(Embedding) 기반 의미 검색으로 자연어 질의에 가장 적합한 섹션을 찾습니다.
lat section: 특정 섹션의 본문, 링크, 참조를 한꺼번에 보여 줍니다.
lat refs: 어떤 곳에서 해당 섹션을 참조하고 있는지 역방향으로 확인합니다.
lat expand: 프롬프트에 포함된 [[refs]] 를 실제 섹션 본문으로 펼쳐 에이전트가 바로 활용하도록 합니다.
lat mcp: 모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 서버를 실행하여 IDE 클라이언트와 통합합니다.

lat init                        # scaffold a lat.md/ directory
lat check                       # validate all wiki links and code refs
lat locate "OAuth Flow"         # find sections by name (exact, fuzzy)
lat section "auth#OAuth Flow"   # show a section with its links and refs
lat refs "auth#OAuth Flow"      # find what references a section
lat search "how do we auth?"    # semantic search via embeddings
lat expand "fix [[OAuth Flow]]" # expand [[refs]] in a prompt for agents
lat mcp                         # start MCP server for editor integration

lat search는 의미 검색을 위해 OpenAI(sk-...)나 Vercel AI Gateway(vck_...)의 API 키가 필요합니다. 키는 LAT_LLM_KEY 환경 변수로 직접 지정하거나, LAT_LLM_KEY_FILE 로 파일 경로를 넘기거나, LAT_LLM_KEY_HELPER 셸 명령(타임아웃 10초)을 통해 외부 비밀 관리 도구에서 가져오는 식으로 해결할 수 있습니다. 운영 환경에서는 헬퍼 스크립트로 통합하여 평문 키 노출을 줄이는 방식이 권장됩니다.

lat.md 설치 및 활용 시나리오

설치는 npm을 통해 한 줄로 진행되며, 사용을 시작하려는 저장소에서 lat init을 실행하면 됩니다. lat.md는 Node.js 22 이상과 pnpm을 요구합니다.

npm install -g lat.md

# 사용하려는 저장소에서
cd /path/to/my-project
lat init

활용 시나리오는 다양합니다. 프로젝트 초기에 architecture.md에 시스템 다이어그램과 핵심 의사결정 로그를 적어 두고, 새로운 인증 기능을 추가할 때마다 auth.md에 의도를 남기면, AI 에이전트가 이후 비슷한 기능을 추가하라는 지시를 받았을 때 같은 패턴을 발견하기 쉬워집니다. 또한 회귀 버그 수정 사례를 tests.md 의 테스트 명세 섹션에 등록하고 require-code-mention: true 를 설정해 두면, 누군가 같은 시나리오에 대한 테스트를 지웠을 때 lat check가 즉시 빨간 신호를 띄웁니다.

CI 측면에서도 lat.md는 일반적인 사전 커밋 훅(Pre-commit Hook)과 GitHub 봇으로 자연스럽게 확장됩니다. 변경된 코드가 어떤 섹션과 연결되었는지를 PR 리뷰 단계에서 자동으로 노출시키거나, 백그라운드에서 그래프 품질을 점진적으로 개선하는 작업을 돌릴 수 있습니다.

lat.md 라이선스

lat.md 프로젝트는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용·수정·재배포할 수 있습니다. 저장소 내 LICENSE 파일에서 전체 조항을 확인할 수 있습니다.

lat.md 공식 홈페이지

lat.md 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~