Lat.md: Agent Lattice: 코드베이스를 위한 지식 그래프, Markdown으로 작성

Source: Hacker News

코드베이스를 위한 지식 그래프, 마크다운으로 작성되었습니다.

The problem

AGENTS.md는 규모가 커지지 못합니다. 작은 프로젝트는 하나의 평면 파일로 설명할 수 있지만, 코드베이스가 성장함에 따라 하나의 거대한 문서를 유지하는 것은 비현실적입니다. 핵심 설계 결정은 묻혀 버리고, 비즈니스 로직은 문서화되지 않으며, 에이전트는 찾아볼 수 있어야 할 컨텍스트를 떠올리는 오류를 일으킵니다.

The idea

프로그램 도메인에 대한 지식을 그래프 형태로 압축합니다 — 프로젝트 루트에 lat.md/ 디렉터리를 두고 서로 연결된 마크다운 파일들의 집합을 두는 것입니다. 섹션들은 [[wiki links]] 로 서로 연결하고, 소스 파일은 // @lat: 주석으로 다시 연결합니다. lat check는 동기화가 깨진 부분이 없는지 확인합니다.

그 결과는 다음과 같은 구조화된 지식 베이스가 됩니다:

• 📈 Scales — 필요에 따라 파일과 섹션을 원하는 만큼 나눌 수 있습니다
• 🔗 Cross-references — 위키 링크([[cli#search#Indexing]])가 개념들을 탐색 가능한 그래프로 연결합니다
• ✅ Stays in sync — lat check가 모든 링크가 해석되는지, 필요한 코드 참조가 존재하는지를 검증합니다
• 🔍 Is searchable — 모든 섹션에 대해 정확 검색, 퍼지 검색, 의미(벡터) 검색을 지원합니다
• 🤝 Works for humans and machines — 어떤 편집기(또는 Obsidian)에서도 읽을 수 있고, lat CLI를 통해 에이전트가 질의할 수 있습니다

Install

npm install -g lat.md

그 다음 사용하려는 레포지토리에서 lat init을 실행합니다.

How it works

lat init을 실행해 lat.md/ 디렉터리를 스캐폴드한 뒤, 아키텍처, 비즈니스 로직, 테스트 사양 등 중요한 내용을 마크다운 파일에 작성합니다. 섹션 간에는 [[file#Section#Subsection]] 구문으로 연결하고, 소스 코드 심볼에는 [[src/auth.ts#validateToken]] 로 연결합니다. 구현을 개념에 연결하려면 소스 코드에 // @lat: [[section-id]](Python에서는 # @lat: [[section-id]]) 주석을 달아줍니다.

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]]
└── ...

CLI

lat init                        # lat.md/ 디렉터리 스캐폴드
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 서버 시작

Configuration

의미 검색(lat search)을 사용하려면 OpenAI(sk-...) 또는 Vercel AI Gateway(vck_...) API 키가 필요합니다. 키는 다음 순서로 확인됩니다:

1. LAT_LLM_KEY 환경 변수 — 직접 값 지정
2. LAT_LLM_KEY_FILE 환경 변수 — 키가 들어 있는 파일 경로
3. LAT_LLM_KEY_HELPER 환경 변수 — 키를 출력하는 셸 명령(10 초 제한)
4. 설정 파일 — lat init으로 저장됩니다. 위치를 보려면 lat config를 실행하세요.

Development

Node.js 22+와 pnpm이 필요합니다.

pnpm install
pnpm build
pnpm test