lat.md: 코드베이스를 위한 Markdown 기반 Agent Knowledge Graph

TL;DR Highlight

설계 결정과 도메인 지식을 연결된 Markdown 파일 그래프로 관리하는 도구는 AI 에이전트가 코드 탐색 없이 빠르게 컨텍스트를 파악하도록 한다.

Who Should Read

Claude Code, GitHub Copilot 등 AI 에이전트를 활용해 중대형 코드베이스를 개발하는 팀에서 에이전트의 컨텍스트 관리와 hallucination 문제를 겪고 있는 개발자.

Core Mechanics

AGENTS.md 단일 파일 방식은 프로젝트가 커질수록 유지보수가 불가능해진다. 핵심 설계 결정이 파일 안에 묻혀버리고, 비즈니스 로직은 문서화되지 않으며, 에이전트는 찾을 수 있어야 할 컨텍스트를 hallucinate하게 된다.
lat.md는 프로젝트 루트의 lat.md/ 디렉토리에 서로 연결된 Markdown 파일들을 두는 방식으로 동작한다. 섹션끼리는 [[wiki links]] 문법으로 연결하고, Markdown 파일에서 코드로는 [[src/auth.ts#validateToken]] 형식으로 링크하며, 소스 파일에서는 // @lat: [[section-id]] 주석으로 역참조할 수 있다.
lat check 명령어가 링크 유효성과 코드-스펙 동기화를 검사해준다. 특히 require-code-mention: true 옵션을 붙인 테스트 스펙은 반드시 테스트 코드에서 // @lat: 주석으로 참조해야 하며, 참조 없는 스펙은 lat check가 플래그로 표시한다.
에이전트 워크플로우 관점에서의 핵심 가치는 검색 효율이다. 에이전트가 코드베이스를 grep으로 뒤지는 대신 knowledge graph를 검색해서 설계 결정, 제약사항, 도메인 컨텍스트를 빠르고 일관되게 찾을 수 있다.
지식 보존(Knowledge retention) 문제를 해결한다. 보통 에이전트 세션이 끝나면 그 세션에서 파악한 컨텍스트와 추론 과정이 사라지는데, 에이전트가 작업하면서 파악한 지식을 lat.md 그래프에 기록해두면 다음 세션이 처음부터 다시 발견하지 않아도 된다.
인간 개발자 워크플로우도 개선된다. diff를 리뷰할 때 코드 변경부터 보는 게 아니라 lat.md/의 의미적 변경(무엇이 왜 바뀌었는지)을 먼저 파악한 뒤 코드 리뷰를 보조로 사용하는 방식을 제안한다.
에이전트가 lat 파일을 직접 관리하도록 설계되어 있다. 개발자는 에이전트에게 작업을 시키면서 동시에 관련 lat.md 섹션도 업데이트하도록 지시할 수 있고, Markdown 파일이라 일반 PR 리뷰 프로세스와 git blame을 그대로 활용할 수 있다.

Evidence

staleness(문서 노후화) 문제가 가장 핵심 우려사항으로 등장했다. 누군가 패키지를 rename하면 그래프가 즉시 구식이 된다는 지적이 있었고, 이에 대해 Markdown을 repo에 두면 일반 PR 리뷰를 거치고 git blame도 쓸 수 있어서 전통적인 지식 그래프보다 낫다는 반론이 나왔다. pre-commit hook이나 CI 잡으로 stale 노드를 갱신하는 것이 실용적 해결책으로 제안됐다.
실제 효과에 대한 회의론도 있었다. 'AGENTS.md 대비, 혹은 중첩 AGENTS.md 대비 실제로 에이전트 성능이 몇 % 향상되는지 벤치마크를 보여달라'는 요청이 여러 댓글에서 나왔다. '아이디어는 쿨하지만 vibes만으로는 도입을 설득하기 어렵다, 10% 이상 개선이 측정되면 적극 도입하겠다'는 의견이 대표적이었다.
비슷한 패턴을 이미 쓰고 있다는 경험담도 있었다. Claude Code의 slash command 이후부터 3~4개의 긴 문서를 모듈별 그룹으로 분리해서 에이전트가 실제 하는 작업에 따라 관련 문서만 로드하도록 설계했다는 사용자가 있었다. 유지보수 자체는 어렵지 않은데, 오히려 컨텍스트 조직 방법을 고민하는 데 시간을 너무 많이 쓰는 게 문제라는 공통적인 경험이 공유됐다.
AST/RAG 방식과의 비교 질문이 있었다. 코드베이스에 AST나 RAG를 구축하면 변경 시 자동 업데이트가 되고, agent가 AST/RAG 검색으로 광범위하게 탐색한 뒤 LSP로 드릴다운하는 방식으로 검색 단계를 50% 빠르게 했다는 경험을 공유하며 lat.md가 이와 비교해 어떤 추가 가치를 주는지 물었다.
10M+ LOC 규모의 C/C++ 코드베이스에서 각 폴더에 해당 영역과 클래스를 설명하는 작은 Markdown 파일을 두는 방식이 Claude와 Codex를 그라운딩하는 데 효과적이었다는 실사용 경험도 있었다. 또한 mkdocs처럼 렌더링해서 실제 문서처럼 보이게 만드는 것이 사람들이 리뷰를 진지하게 하도록 유도하는 데 중요하다는 조언도 나왔다.

How to Apply

중대형 프로젝트에서 AI 에이전트가 자꾸 엉뚱한 설계 결정을 하거나 기존 패턴을 무시하는 경우, lat.md/ 디렉토리를 만들고 핵심 도메인 개념, 아키텍처 결정, 금지 패턴 등을 wiki 링크로 연결된 섹션으로 정리한 뒤 에이전트 시스템 프롬프트에 lat.md/ 탐색을 먼저 하도록 지시하면 hallucination을 줄일 수 있다.
테스트 커버리지 추적에 활용할 수 있다. 테스트 스펙을 lat.md/ 섹션으로 작성하고 require-code-mention: true를 설정한 뒤, CI 파이프라인에 lat check를 추가하면 테스트 코드에서 // @lat: 주석으로 참조하지 않은 스펙을 자동으로 감지할 수 있다.
에이전트 세션 간 컨텍스트 유실 문제가 있다면, 에이전트 작업 지시 시 '작업 완료 후 관련 설계 결정과 발견한 제약사항을 해당 lat.md 섹션에 업데이트하라'는 지시를 포함시켜라. 이렇게 하면 다음 세션의 에이전트가 같은 내용을 재발견하는 데 쓰는 토큰과 시간을 줄일 수 있다.
코드 리뷰 프로세스를 개선하고 싶다면, PR 리뷰 시 코드 diff 대신 lat.md/ 변경사항을 먼저 읽어서 무엇이 왜 변경됐는지 파악하는 습관을 팀 내 도입해보자. Markdown이라 git diff가 자연스럽게 동작하고, 코드 변경의 의미가 명확해져 리뷰 효율이 올라간다.

Code Example

snippet

// 소스 파일에서 lat.md 섹션으로 역참조하는 방법
// @lat: [[auth/token-validation]]
function validateToken(token: string): boolean {
  // ...
}

// lat.md 파일에서 위키 링크 사용 예시 (lat.md/auth/token-validation.md)
## Token Validation

See also: [[auth/session-management]], [[security/rate-limiting]]

Implemented in: [[src/auth.ts#validateToken]]

---

// lat check 실행 방법 (package.json scripts)
{
  "scripts": {
    "lat:check": "lat check"
  }
}

// CI에서 staleness 감지를 위한 GitHub Actions 예시
- name: Check lat.md integrity
  run: pnpm lat:check

Terminology

Knowledge Graph데이터를 노드(개념)와 엣지(관계)로 표현하는 구조. lat.md에서는 Markdown 파일이 노드, wiki 링크가 엣지 역할을 한다.

AGENTS.mdAI 에이전트에게 프로젝트 컨텍스트를 알려주는 단일 Markdown 파일. Claude나 Codex 같은 AI가 작업 전 읽는 일종의 'AI를 위한 README'다.

wiki links[[파일명]] 형식으로 문서끼리 서로 참조하는 링크 문법. Obsidian 같은 메모 앱에서 유래했으며, lat.md에서 섹션 간 관계를 표현하는 데 사용한다.

LSPLanguage Server Protocol의 약자. VS Code 같은 에디터가 코드 자동완성, 정의 이동 등을 제공하기 위해 사용하는 프로토콜로, 코드의 구조적 정보를 쿼리할 수 있다.

ASTAbstract Syntax Tree(추상 구문 트리)의 약자. 소스 코드를 파싱해서 트리 구조로 만든 것으로, 코드의 구조를 프로그램적으로 분석하는 데 사용한다.

RAGRetrieval-Augmented Generation의 약자. LLM이 답변할 때 외부 문서를 검색해서 참고하도록 하는 기법으로, 코드베이스 탐색에도 적용 가능하다.