단일 AGENTS.md의 한계를 극복하고 상호 연결된 마크다운 지식 그래프를 구축하는 lat.md 도입 및 활용 전략

## lat.md 개요 및 도입 배경

lat.md는 단일 `AGENTS.md` 파일이 프로젝트 성장에 따라 비대해지면서 발생하는 구조적 한계를 극복하기 위해 설계된 **코드베이스 지식 그래프 구축 도구**입니다. 프로젝트의 주요 아키텍처 설계 결정, 비즈니스 로직, 테스트 사양 등을 상호 연결된 마크다운 파일들의 그래프 형태로 루트의 `lat.md/` 디렉터리에 저장하여 관리합니다. AI 코딩 에이전트는 코드베이스 전체를 맹목적으로 탐색하는 대신 이 지식 그래프를 활용하여 도메인 컨텍스트를 빠르고 일관되게 파악할 수 있습니다. 또한 개발자는 코드 변경 사유와 아키텍처의 변화를 문서 단위로 먼저 확인함으로써 리뷰 프로세스를 최적화할 수 있으며, 결과적으로 에이전트의 환각(Hallucination) 현상을 줄이고 프로젝트의 핵심 지식을 영구적으로 보존할 수 있습니다.

## 핵심 작동 원리 및 마크다운 확장 문법

lat.md는 기본 마크다운 문법에 옵시디언(Obsidian) 스타일의 **위키 링크(`[[target]]`) 문법**을 도입하여 문서와 소스 코드를 유기적으로 연결합니다. `[[lat.md/path#Heading]]`과 같이 전체 경로를 명시할 수 있을 뿐만 아니라, 파일 이름이 고유한 경우에는 디렉터리 경로를 생략한 짧은 참조(`[[setup#Install]]`)도 지원합니다. 가장 강력한 특징은 마크다운 문서 내에서 소스 코드 내부의 특정 기호(함수, 클래스, 메서드 등)를 직접 링크할 수 있다는 점입니다. TypeScript, Python, Rust, Go, C 등 다양한 언어를 지원하며, `[[src/server.ts#App#listen]]`이나 C 언어의 `[[src/app.h#Greeter#prefix]]`처럼 세밀한 코드 레벨 링크가 가능합니다. 이러한 코드 링크 파싱은 트리시터(Tree-sitter)를 활용하여 참조된 파일만 분석하는 지연 평가(Lazy parsing) 방식으로 효율적으로 처리됩니다.

## 양방향 코드 참조와 테스트 스펙 커버리지 검증

마크다운 문서가 소스 코드를 가리키는 것에 더해, 소스 코드 역시 주석을 통해 마크다운 문서를 가리키는 **양방향 참조 시스템**을 지원합니다. 개발자나 AI 에이전트는 소스 코드 내부에 `// @lat: [[section-id]]` (Python의 경우 `# @lat:`) 형태의 주석을 작성하여, 해당 구현 코드가 어떤 설계 문서나 테스트 사양에 기반하고 있는지 명시합니다. 특히, `lat.md` 파일 상단에 YAML 프런트매터로 `require-code-mention: true`를 설정할 경우, 문서의 모든 하위 섹션(Leaf section)이 실제 테스트 코드에서 최소 한 번 이상 `@lat:` 주석으로 참조되었는지를 강제할 수 있습니다. 이를 통해 `lat check code-refs` 명령어는 명세서와 실제 구현 코드 간의 불일치를 찾아내며 완벽한 테스트 추적성을 보장합니다.

## 에이전트 통합 및 모델 컨텍스트 프로토콜(MCP) 지원

다양한 AI 코딩 도구와의 원활한 통합을 위해 `lat init` 명령어는 Claude Code, Cursor, Copilot, Pi, OpenCode 등 여러 에이전트에 맞는 최적화된 설정을 자동으로 구성해 줍니다. Claude나 Cursor 같은 에이전트에서는 종료 훅(Stop hook)을 사용하여, AI가 작업을 마치고 사용자에게 응답하기 전에 반드시 **`lat check`를 실행하고 코드와 문서 간의 동기화 상태를 점검하도록 강제**합니다. 또한, `lat mcp` 명령어를 통해 표준 MCP(Model Context Protocol) 서버를 실행함으로써, IDE와 코딩 에이전트가 `lat_search`, `lat_locate`, `lat_check`, `lat_expand` 등의 도구를 네이티브 기능처럼 호출하여 실시간으로 지식 그래프에 접근하고 문맥을 파악할 수 있도록 돕습니다.

## 통합 CLI 명령어 기반의 지식 그래프 탐색 기능

`lat` CLI는 지식 그래프를 탐색하고 문서를 유지 보수하는 핵심 도구 모음입니다. `lat locate`는 쿼리와 정확히 일치하거나, 부분 일치, 퍼지(Fuzzy) 매칭 등을 통해 원하는 문서 섹션을 매우 빠르게 찾아 출력합니다. `lat section` 명령어는 검색된 특정 섹션의 전체 본문은 물론, 해당 섹션이 가리키는 외부 링크와 반대로 이 섹션을 참조하고 있는 다른 문서 및 소스 코드 위치까지 한눈에 보여주어 RAG 검색 결과 탐색에 유용합니다. 이외에도 에이전트가 프롬프트 내의 위키 링크를 풀어서 해석할 때 사용하는 `lat expand` 명령어와 특정 문서나 코드가 어디서 참조되고 있는지 역추적하는 `lat refs` 등 강력한 탐색 명령어들이 제공됩니다.

## 시맨틱 검색 엔진과 내장 로컬 벡터 데이터베이스

사용자의 자연어 질의를 이해하고 관련 문서를 찾아주기 위해 **`lat search` 명령어를 기반으로 한 시맨틱 검색(Semantic search) 엔진이 탑재**되어 있습니다. 이 기능은 외부의 무거운 벡터 데이터베이스 인프라에 의존하지 않고, 내부적으로 Turso의 libsql을 로컬 파일 모드로 구동하여 단일 `.cache/vectors.db` 데이터베이스 내에서 `F32_BLOB` 타입과 KNN 쿼리를 통해 구현됩니다. OpenAI의 `text-embedding-3-small` 모델 등을 활용하며, 문서 내용의 변경 여부를 SHA-256 해시로 비교하여 새롭거나 수정된 섹션만 선택적으로 다시 임베딩하므로 API 호출 비용을 획기적으로 절감합니다. 테스트 환경을 위해서는 실제 API 호출 없이 작동하는 RAG 리플레이 서버 기능도 지원하여 완벽한 오프라인 테스트가 가능합니다.

## 엄격한 문서 구조화 규칙 및 자동 검증 시스템

lat.md는 문서 품질을 높이고 일관성을 유지하기 위해 철저한 구조적 제약을 강제하며, 이를 통합 명령어인 `lat check`가 실시간으로 검사합니다. 가장 엄격한 규칙 중 하나는 마크다운 문서의 모든 섹션 제목 바로 아래에 **반드시 하위 제목이 나오기 전 최소 한 문장 이상의 '리딩 패러그래프(Leading paragraph)'가 존재해야 한다**는 것입니다. 이 첫 번째 문단은 검색 결과나 RAG 컨텍스트에서 섹션의 개요로 활용되므로 위키 링크 구문을 제외하고 최대 250자를 넘지 않아야 합니다. 더불어 `lat.md/` 내부의 모든 하위 디렉터리에는 디렉터리 이름과 동일한 인덱스 파일(예: `api/api.md`)이 존재하여 내부 파일 목록을 리스트 형태로 제공해야 하며, 이를 `check index` 명령어가 검증하여 누락된 파일을 찾아냅니다.

## 개발 파이프라인 및 CI/CD 워크플로우

lat.md 시스템은 TypeScript ESM 환경을 기반으로 구축되었으며 패키지 매니저로는 pnpm만을 엄격하게 사용합니다. 안정성을 유지하기 위해 Vitest 테스트 프레임워크를 바탕으로, 가상의 `lat.md/` 미니 프로젝트 환경을 갖춘 여러 픽스처(Fixture) 디렉터리를 활용하여 CLI 명령어와 기능에 대한 포괄적인 통합 테스트를 수행합니다. GitHub Actions로 구성된 자동화된 CI/CD 파이프라인은 코드가 `main` 브랜치에 병합될 때마다 `package.json`의 버전 변경 사항을 감지하여 자동으로 npm에 신규 버전을 배포(Publish)하고 GitHub 릴리스 노트를 생성하는 프로세스를 갖추고 있습니다. 로컬 개발 환경과 동일하게 런타임 파일 경로 탐색 시 `.gitignore`를 철저히 존중하며, 모든 릴리스는 엄격한 타입 검증(`tsc --noEmit`)을 통과해야 합니다.