lat.md는 코드베이스에 대한 지식을 상호 연결된 마크다운 파일 그래프로 압축해 관리하는 CLI 도구다. AI 에이전트가 코드를 무한정 grep하는 대신 지식 그래프를 검색해 핵심 설계 결정, 제약 사항, 도메인 컨텍스트를 빠르고 일관되게 파악할 수 있도록 설계되었다. 에이전트와 사람 모두를 위한 코드베이스 문서화의 새로운 접근 방식으로, GitHub에서 1,400개 이상의 스타를 보유하고 있다.

https://github.com/1st1/lat.md

소개

AI 코딩 에이전트가 확산되면서 AGENTS.md 같은 단일 평문 파일로 프로젝트 컨텍스트를 전달하는 방식의 한계가 드러났다. 프로젝트가 성장할수록 하나의 파일에 모든 설계 결정을 담기 어려워지고, 핵심 비즈니스 로직은 묻히며, 에이전트는 알아야 할 컨텍스트를 환각으로 채우게 된다.

lat.md는 이 문제를 그래프 구조로 해결한다. 프로젝트 루트의 lat.md/ 디렉터리 안에 상호 링크된 마크다운 파일들이 위키 형태로 존재한다. 섹션은 wiki links로 연결되고, 소스 파일은 src/auth.ts#validateToken으로 직접 참조된다. 소스 코드에서는 // @lat: section-id 주석으로 역링크를 걸고, lat check가 이 참조 무결성을 자동으로 검증한다.

에이전트는 세션이 끝나면 컨텍스트를 잃지만, lat.md에 지식을 누적하면 다음 세션이 빈 상태에서 재발견하는 과정을 반복하지 않아도 된다.

주요 기능

에이전트와 사람 모두를 위한 워크플로 가속

에이전트는 lat search, lat section 명령으로 지식 그래프를 탐색해 설계 결정과 도메인 컨텍스트를 즉시 찾는다. 개발자는 코드 diff를 검토하기 전에 lat.md/ 내 시맨틱 변경 사항부터 확인해 “무엇이 왜 바뀌었는지”를 먼저 파악한다.

지식 보존

프롬프트 세션에서 발생한 컨텍스트와 추론이 그래프에 누적된다. 에이전트는 작업하면서 지식을 그래프에 캡처하므로, 다음 세션은 처음부터 전체 컨텍스트를 확보한 상태로 시작한다.

테스트 스펙과 검증

lat.md/ 내 섹션을 테스트 스펙으로 정의하고 require-code-mention: true를 지정할 수 있다. 각 스펙은 테스트 코드에서 // @lat: 주석으로 반드시 참조되어야 하며, lat check가 역링크 없는 스펙을 자동으로 감지한다.

참조 무결성 강제

lat check 명령이 모든 위키 링크와 코드 참조의 유효성을 검사한다. 에이전트는 작업 완료 전 이 명령을 자동으로 호출해 지식 그래프가 코드와 동기화 상태를 유지하도록 한다.

MCP 서버 및 에디터 통합

lat mcp 명령으로 MCP 서버를 시작해 에디터와 통합할 수 있다. lat init이 Claude Code, Cursor 등 인기 코딩 에이전트에 훅(hook)과 지침을 자동으로 설정한다.

아키텍처

lat.md의 프로젝트 구조는 다음과 같다.

my-project/
├── lat.md/
│   ├── architecture.md    # 시스템 설계, 핵심 결정
│   ├── auth.md            # 인증·인가 로직
│   └── tests.md           # 테스트 스펙 (require-code-mention: true)
├── src/
│   ├── auth.ts            # // @lat: auth#OAuth Flow
│   └── server.ts          # // @lat: architecture#Request Pipeline
└── ...

섹션 간 링크는 file#Section#Subsection 문법을 사용한다. 시맨틱 검색(lat search)은 임베딩 기반으로 동작하며 OpenAI 또는 Vercel AI Gateway API 키가 필요하다.

설치 및 빠른 시작

npm install -g lat.md
lat init

lat init은 lat.md/ 디렉터리를 스캐폴딩하고 코딩 에이전트에 훅을 설정한다.

CLI 명령어

lat check                        # 위키 링크 및 코드 참조 유효성 검사
lat locate "OAuth Flow"          # 섹션 이름으로 위치 검색 (정확·퍼지)
lat section "auth#OAuth Flow"    # 섹션 내용과 링크·참조 출력
lat refs "auth#OAuth Flow"       # 해당 섹션을 참조하는 항목 검색
lat search "how do we auth?"     # 임베딩 기반 시맨틱 검색
lat expand "fix OAuth Flow"  # 에이전트용 refs 확장
lat mcp                          # MCP 서버 시작

개발 환경

Node.js 22 이상, pnpm 필요.

pnpm install && pnpm build && pnpm test

라이선스

MIT License

관련 문서