lat.md — AGENTS.md 한 장으로는 안 될 때 코드베이스를 지식 그래프로 바꾸는 법

AI 코딩 에이전트 시대에 코드베이스의 맥락을 효율적으로 전달하는 문제는 소프트웨어 개발의 핵심 과제로 부상했다. lat.md(Agent Lattice)는 마크다운 기반 지식 그래프로 코드베이스 전반의 설계 결정, 도메인 지식, 컴포넌트 간 관계를 구조화하여 AI 에이전트와 인간 개발자 모두가 활용할 수 있는 실용적 컨텍스트 엔지니어링 도구다. 단일 AGENTS.md 파일의 한계를 넘어 확장 가능한 지식 그래프 구조를 제공함으로써, 에이전트가 세션 간 지식을 축적하고 불필요한 코드베이스 탐색을 최소화할 수 있게 한다.

AGENTS.md 한 장이 감당 못 하는 지점

AGENTS.md는 작은 프로젝트에서는 효과적이지만 코드베이스가 성장할수록 단일 평면 파일 방식은 심각한 확장성 문제를 드러낸다. 프로젝트가 수만 라인을 넘어서면 핵심 설계 결정이 파묻히고, 비즈니스 로직은 문서화되지 않으며, 에이전트는 존재하지 않는 컨텍스트를 환각(hallucination)하기 시작한다.

lat.md는 이 문제를 해결하기 위해 원칙을 세운다. 지식의 그래프화는 프로젝트 루트의 lat.md/ 디렉토리 아래 상호 연결된 마크다운 파일 세트로 도메인 지식을 압축하는 것이다. 각 섹션은 [[wiki links]]로 서로 연결되며, 마크다운 파일은 [[src/auth.ts#validateToken]] 형태로 실제 코드에 직접 링크된다. 양방향 참조는 소스 파일이 // @lat: [[section-id]] 주석으로 지식 그래프를 역참조하는 것으로, 코드와 문서 사이의 일관성을 유지한다. 자동 검증은 lat check 명령이 모든 위키 링크와 코드 참조의 유효성을 검사해 문서와 코드 간 불일치가 발생하지 않도록 한다.

심볼을 추출해 그래프로 직렬화하는 파이프라인

lat.md의 아키텍처는 심볼 추출, 의존성 그래프 구성, 마크다운 직렬화, 증분 갱신의 네 단계 파이프라인으로 구성된다.

⤢✕

심볼 추출 단계에서는 Tree-sitter 기반 파서가 함수, 클래스, 인터페이스, 타입 정의 등 의미있는 심볼을 추출한다. 연구에 따르면 이 구조화된 추출 방식은 파일 탐색 에이전트 대비 토큰 소비를 6.8배에서 최대 49배까지 줄일 수 있다.

의존성 그래프 구성 단계에서는 추출된 심볼 간의 호출 관계, 임포트 관계, 상속 관계를 분석하여 코드베이스의 전체 의존성 맵을 구축한다. 이 단계에서 순환 의존성, 고도 연결 컴포넌트(hub components), 핵심 추상화 레이어가 식별된다.

마크다운 직렬화 단계에서는 추출된 지식을 인간과 LLM 모두가 쉽게 읽을 수 있는 마크다운 형식으로 변환한다. 각 섹션 파일은 관련 코드 참조, 설계 결정 맥락, 주변 섹션과의 연결 링크를 포함한다.

증분 갱신 설계는 lat.md의 실용성을 결정짓는 핵심 요소다. 전체 그래프를 매번 재생성하는 대신, 변경된 파일과 이에 직접 의존하는 섹션만 갱신한다. 이를 통해 대규모 모노레포에서도 실시간에 가까운 지식 그래프 유지가 가능하다.

에이전트가 지식 그래프를 컨텍스트로 끌어오는 방식

AI 에이전트가 lat.md를 효과적으로 활용하려면 단순한 파일 읽기를 넘어 체계적인 컨텍스트 선택과 토큰 예산 최적화가 필요하다.

⤢✕

지식 그래프 탐색 단계에서 에이전트는 lat search <query> 명령으로 LLM 임베딩 기반 시맨틱 검색을 수행한다. 단순한 키워드 매칭이 아닌 의미적 유사성으로 관련 설계 결정과 제약 조건을 발견할 수 있다.

관련 컨텍스트 선택 단계에서는 검색 결과를 작업 유형, 파일 근접성, 의존성 거리를 기준으로 우선순위를 정렬한다. lat refs <section> 명령은 특정 섹션을 참조하는 모든 코드 위치를 역추적하여 변경 영향 범위(blast radius)를 즉시 파악할 수 있게 한다.

토큰 예산 최적화는 컨텍스트 엔지니어링의 핵심이다. 연구 결과에 따르면 AI 코딩 에이전트가 소비하는 토큰의 60~80%는 실제 문제 해결이 아닌 코드베이스 탐색에 쓰인다. lat.md의 구조화된 지식 그래프는 이 탐색 비용을 사전에 상각함으로써 개별 에이전트 세션의 토큰 소비를 최대 95%까지 절감한 사례가 보고되었다.

에이전트 통합 패턴으로는 에이전트가 작업을 완료할 때마다 발견한 설계 결정을 lat.md/에 기록해 다음 세션에서 재발견 비용을 제거하는 세션 간 지식 축적 패턴, Claude Code·Codex·Cursor 등의 에이전트 종료 시점에 lat.md 갱신을 자동 트리거하는 Stop Hook 통합 패턴(v0.11부터 lat init 지원), require-code-mention: true 속성을 가진 테스트 스펙이 실제 코드에서 참조되는지 검증하는 테스트 커버리지 추적 패턴이 주목된다.

마크다운을 고른 것 자체가 설계 결정이다

lat.md가 채택한 마크다운 기반 접근법은 단순한 구현 선택이 아니라 도구의 생존 가능성을 결정하는 아키텍처 결정이다.

가독성과 LLM 친화성의 균형은 마크다운이 제공하는 핵심 가치다. 마크다운은 구조화된 텍스트이면서도 인간이 자연스럽게 읽을 수 있다. LLM이 처리하기에도 최적화되어 있어 JSON이나 YAML 같은 기계 친화적 포맷보다 실질적인 이해도가 높다.

도구 체인 통합 측면에서 마크다운 파일은 Git, GitHub Actions, CI/CD 파이프라인, IDE 플러그인과 별도의 어댑터 없이 즉시 통합된다. lat check를 CI 파이프라인에 추가하는 것만으로 PR이 지식 그래프를 파손하는 상황을 자동으로 방지할 수 있다.

버전 관리 호환성은 텍스트 기반 포맷의 자연스러운 장점이다. 지식 그래프의 변경 이력이 코드 변경 이력과 함께 Git에 보존된다. 마크다운의 라인 기반 diff는 변경 내용을 직관적으로 파악할 수 있게 하며, 충돌 해결도 이진 포맷에 비해 훨씬 용이하다.

확장 가능한 섹션 구조는 프로젝트 성장에 유연하게 대응한다. 초기에는 lat init으로 기본 구조를 스캐폴딩하고, 프로젝트가 성장하면서 섹션을 추가하거나 분리한다. 계층적 디렉토리 구조와 위키 링크의 조합으로 플랫 파일의 한계 없이 수백 개의 섹션을 관리할 수 있다.

실전에서 쓰는 CLI 명령

lat.md의 주요 CLI 명령과 실무 활용 패턴을 정리한다.

# 프로젝트 초기화 (Codex, OpenCode, Cursor stop hook 자동 등록)
lat init

# 모든 위키 링크 및 코드 참조 유효성 검사
lat check

# 섹션 이름으로 위치 찾기
lat locate "authentication"

# 섹션 상세 보기 (링크 및 소스 코드 스니펫 포함, v0.10+)
lat section auth/token-validation

# 특정 섹션을 참조하는 모든 항목 찾기
lat refs auth/token-validation

# LLM 임베딩 기반 시맨틱 검색
lat search "user session management"

실무에서 권장되는 워크플로우는 다음과 같다. 새 기능 개발 전 lat search로 관련 설계 결정을 먼저 확인하고, 구현 중 소스에 // @lat: [[section-id]] 주석을 추가하며, PR 전 lat check로 지식 그래프 일관성을 검증한다. 에이전트 세션 종료 시 발견한 새로운 패턴이나 제약을 lat.md/에 기록한다.

lat.md가 대표하는 컨텍스트 엔지니어링 패러다임은 AI 보조 개발의 품질을 결정하는 새로운 경쟁 축이 되고 있다. 2026년 현재 토큰 효율이 AI 도구 비용의 핵심 변수가 된 상황에서, 구조화된 지식 그래프는 단순한 편의 도구가 아니라 에이전트의 정확도와 비용을 동시에 개선하는 전략적 인프라다. AGENTS.md에서 시작하여 lat.md와 같은 그래프 기반 지식 체계로 발전하는 흐름은, 개발자가 이제 인간만이 아닌 기계를 위한 문서를 설계하는 새로운 역할을 맡게 됐음을 의미한다.

lat.md Agent Lattice는 단일 평면 파일의 한계를 넘어 코드베이스 지식을 그래프로 구조화함으로써 AI 에이전트의 컨텍스트 탐색 비용을 대폭 줄이고 세션 간 지식 축적을 가능하게 하는 실용적 도구다. 마크다운 기반 설계는 가독성, LLM 친화성, 버전 관리 호환성을 동시에 확보하며, lat check의 자동 검증은 코드와 문서 사이의 일관성을 CI 수준에서 보장한다.