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

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

// 소스 파일에서 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

Related Resources

• https://github.com/1st1/lat.md
• https://x.com/mitsuhiko/status/2037649308086902989?s=20
• https://www.youtube.com/watch?v=gIOtYnI-8_c