Lat.md: 코드베이스를 위한 마크다운 기반 지식 그래프

Lat.md는 마크다운 파일을 사용하여 코드베이스에 대한 지식 그래프를 구축하는 도구입니다. AGENTS.md가 확장성 문제를 겪는 문제를 해결합니다—프로젝트가 커질수록 단일 평면 파일을 유지하는 것이 비현실적이 되어, 묻혀버린 설계 결정, 문서화되지 않은 비즈니스 로직, AI 에이전트의 맥락 오류를 초래합니다.

작동 방식

도메인 지식을 프로젝트 루트의 lat.md/ 디렉토리에 저장된 상호 연결된 마크다운 파일 그래프로 압축합니다. 섹션은 [[file#Section#Subsection]]과 같은 [[위키 링크]]로 서로 연결되고, 마크다운 파일은 [[src/auth.ts#validateToken]]으로 코드에 연결되며, 소스 파일은 TypeScript에서는 // @lat: [[section-id]] 또는 Python에서는 # @lat: [[section-id]]와 같은 주석을 사용하여 다시 연결됩니다. lat check 명령은 참조 일관성을 보장합니다.

주요 기능

• 에이전트를 위한 빠른 코딩: 코드를 grep하는 대신, 에이전트는 지식 그래프를 검색하여 설계 결정, 제약 조건 및 도메인 맥락을 일관되게 발견합니다.
• 사람을 위한 빠른 워크플로우: 에이전트는 lat 파일을 유지합니다; 변경 사항을 검토할 때, lat.md/의 의미론적 변경 사항부터 시작하여 무엇이 왜 변경되었는지 이해하고, 코드 검토를 부차적으로 만듭니다.
• 지식 보존: 에이전트는 작업하면서 프롬프트의 맥락과 추론을 그래프에 캡처하여, 미래 세션이 다시 발견하는 대신 완전한 맥락으로 시작할 수 있도록 합니다.
• 강제 적용이 있는 테스트 스펙: 테스트 케이스는 require-code-mention: true로 표시된 lat.md/ 섹션에 설명될 수 있습니다. 각 스펙은 테스트 코드의 // @lat: 주석으로 참조되어야 하며, lat check는 백링크가 없는 스펙을 표시합니다.

CLI 명령

• lat init: 인기 있는 코딩 에이전트를 설정하여 lat를 최신 상태로 유지하고 올바르게 만듭니다.
• lat check: 참조 일관성을 강제 적용합니다; 에이전트는 작업을 마치기 전에 자동으로 호출합니다.
• lat search 및 lat section: 에이전트는 끝없는 grep 호출 대신 프롬프트를 이해하고 그래프를 탐색하기 위해 이를 사용합니다.
• lat locate: 이름으로 섹션을 찾습니다(정확하거나 유사한).
• lat refs: 섹션을 참조하는 것을 찾습니다.
• lat expand: 에이전트를 위한 프롬프트에서 [[refs]]를 확장합니다.
• lat mcp: 편집기 통합을 위한 MCP 서버를 시작합니다.

설치 및 설정

npm install -g lat.md로 설치한 후, 저장소에서 lat init을 실행하여 lat.md/ 디렉토리를 스캐폴딩합니다. 아키텍처, 비즈니스 로직 또는 테스트 스펙을 설명하는 마크다운 파일을 작성하고 필요에 따라 연결합니다.

의미론적 검색(lat search)을 위해서는 OpenAI(sk-...) 또는 Vercel AI Gateway(vck_...) API 키가 필요합니다. 키는 다음 순서로 해결됩니다: LAT_LLM_KEY 환경 변수(직접 값), LAT_LLM_KEY_FILE 환경 변수(키가 포함된 파일 경로), LAT_LLM_KEY_HELPER 환경 변수(10초 타임아웃으로 키를 출력하는 셸 명령), 또는 lat에 의해 저장된 구성 파일.