Lat.md — 마크다운으로 코드베이스의 지식 그래프를 만드는 AI 에이전트 도구

AI 코딩 에이전트의 고질적인 문제

AI 코딩 에이전트를 써보신 분들은 아마 이런 경험이 있을 거예요. 프로젝트가 좀 커지면 AI가 코드베이스의 전체 구조를 제대로 파악하지 못해서 엉뚱한 파일을 수정하거나, 이미 있는 유틸리티 함수를 또 만들거나, 모듈 간 의존 관계를 무시하고 코드를 짜는 거죠. 이건 근본적으로 AI가 코드베이스에 대한 "지도"를 갖고 있지 않기 때문이에요. 매번 필요한 파일을 검색해서 읽어야 하니까, 숲을 보지 못하고 나무만 보게 되는 거예요.

Lat.md(Agent Lattice)는 바로 이 문제를 해결하려고 나온 도구예요. 코드베이스의 구조와 관계를 마크다운 파일로 정리된 지식 그래프(Knowledge Graph)로 만들어서, AI 에이전트가 프로젝트의 전체 맥락을 빠르게 파악할 수 있게 해주는 거죠.

지식 그래프가 뭐고, 왜 마크다운인가

지식 그래프라는 말이 좀 거창하게 들릴 수 있는데, 쉽게 말하면 "이 프로젝트에서 뭐가 있고, 그것들이 서로 어떻게 연결되어 있는지"를 정리한 지도예요. 예를 들어 "UserService는 UserRepository에 의존하고, UserRepository는 PostgreSQL 데이터베이스에 연결되어 있다" 같은 관계들을 체계적으로 기록하는 거죠.

그런데 왜 하필 마크다운일까요? 여기에 꽤 실용적인 이유가 있어요. 첫째, 마크다운은 사람이 읽고 쓰기 쉬워요. JSON이나 XML로 된 그래프 데이터는 도구 없이는 읽기 힘들잖아요. 둘째, 마크다운은 Git으로 버전 관리가 되니까 코드와 함께 변경 이력을 추적할 수 있어요. 셋째, 그리고 이게 가장 중요한데, 현재 대부분의 AI 코딩 에이전트들이 마크다운 컨텍스트 파일을 자연스럽게 읽을 수 있어요. Claude의 CLAUDE.md, Cursor의 .cursorrules 같은 것들이 다 마크다운 기반이거든요.

실제로 어떻게 동작하나

Lat.md는 프로젝트 루트에 .lat/ 디렉토리를 만들고, 그 안에 코드베이스의 각 모듈, 패키지, 주요 컴포넌트에 대한 마크다운 파일을 생성해요. 각 파일은 해당 컴포넌트의 역할, 주요 인터페이스, 다른 컴포넌트와의 관계를 기술하고 있고요.

이걸 "격자(Lattice)" 구조라고 부르는 이유가 있는데, 단순한 트리(폴더 구조)가 아니라 모듈 간의 횡단적인 관계까지 표현하기 때문이에요. 파일 시스템에서는 src/services/user.ts와 src/repositories/user.ts가 서로 다른 폴더에 있지만, 실제로는 강하게 연결되어 있잖아요. Lat.md는 이런 논리적 관계를 명시적으로 기록하는 거예요.

AI 에이전트가 작업을 시작할 때 이 격자 파일들을 먼저 읽으면, 코드를 직접 탐색하기 전에 "아, 이 프로젝트는 이런 구조이고, 내가 수정하려는 부분은 이 모듈들과 연결되어 있구나"라는 맥락을 갖고 시작할 수 있어요. 마치 새로운 회사에 입사했을 때 아키텍처 문서를 먼저 읽는 것처럼요.

비슷한 접근과의 비교

사실 이 문제를 해결하려는 시도가 Lat.md만 있는 건 아니에요. Cursor의 .cursorrules 파일이나 Claude Code의 CLAUDE.md도 AI에게 프로젝트 컨텍스트를 제공하는 목적이 있죠. 하지만 이것들은 보통 하나의 파일에 프로젝트 전체 규칙과 맥락을 담다 보니, 프로젝트가 커지면 파일이 너무 길어지거나 내용이 추상적이 되기 쉬워요.

Lat.md의 차별점은 이걸 여러 파일로 분산시켜서 각 모듈 수준의 세밀한 맥락을 제공한다는 거예요. AI가 특정 모듈을 작업할 때 그 모듈의 격자 파일만 로드하면 되니까 토큰 낭비도 줄고, 정보의 밀도도 높아지죠.

또 다른 접근으로는 코드를 임베딩(embedding)해서 벡터 DB에 저장하는 RAG(Retrieval-Augmented Generation) 방식이 있는데, 이건 검색 정확도에 의존하고 구조적 관계를 표현하기 어렵다는 한계가 있어요. Lat.md는 명시적으로 관계를 기술하니까 이 부분에서 보완적인 역할을 할 수 있어요.

한국 개발자에게 주는 시사점

AI 코딩 도구를 실무에서 적극 활용하고 있는 팀이라면, "AI에게 프로젝트 맥락을 어떻게 효과적으로 전달할 것인가"는 점점 중요한 문제가 되고 있어요. Lat.md를 바로 도입하지 않더라도, 이 도구가 제시하는 아이디어 자체가 유용해요. 프로젝트의 모듈 관계를 마크다운으로 정리해두는 습관은 AI 도구 활용 효율을 높일 뿐 아니라, 새로 합류하는 팀원의 온보딩에도 큰 도움이 되거든요.

아직 초기 단계의 프로젝트이고 GitHub에서 공개된지 얼마 안 됐기 때문에, 프로덕션에 바로 쓰기보다는 사이드 프로젝트에서 한번 실험해보면서 이 접근법의 가능성을 탐색해보는 게 좋을 것 같아요.

정리하자면

AI 코딩 에이전트의 효과는 결국 "얼마나 좋은 맥락을 제공하느냐"에 달려있는데, Lat.md는 코드베이스의 구조를 마크다운 기반 지식 그래프로 만들어 이 문제를 정면으로 공략하는 도구예요. 여러분은 AI 코딩 도구에 프로젝트 맥락을 전달하기 위해 어떤 방법을 쓰고 계신가요?