한 개발자가 AI 코딩 에이전트가 세션 간에도 코드베이스의 위치를 파악할 수 있도록 하는 3계층 코드베이스 맵을 출시했습니다.

AI 에이전트에게 맵이 필요한 이유

채팅 기반 코딩 어시스턴트는 프롬프트 창이 열려 있는 동안에만 저장소에 대한 멘탈 모델(mental model)을 구축합니다. 컨텍스트 창이 닫히면 모델은 증발해 버리고, 에이전트는 심볼, 임포트, 파일 관계를 처음부터 다시 찾아내야 합니다. 이러한 반복 작업은 컴퓨팅 자원을 낭비하며, 개발자가 파일 사이를 이동하거나 휴식 후 프로젝트로 돌아왔을 때 에이전트의 유용성을 떨어뜨립니다.

맵을 구성하는 세 가지 계층

  • Structural layer (구조 계층) – 심볼, 함수 호출 및 임포트 문에 대한 카탈로그입니다. "무엇이 무엇을 호출하는가"라는 정적인 질문에 답합니다.
  • Temporal layer (시간 계층) – 파일 변경률(churn rates) 및 소유권 이력과 같은 git 기반 신호입니다. 코드의 어느 부분이 가장 자주 변경되는지, 그리고 누가 해당 부분을 주로 수정하는지 보여줍니다.
  • Behavioral layer (행동 계층) – 에이전트 자체의 편집 및 탐색 이력에서 추출한 실제 사용 패턴입니다. 코딩 세션 중에 실제로 함께 열리는 파일이 무엇인지 밝혀내어, 정적 분석이 놓치는 "진정한 이웃(true neighbors)"을 찾아냅니다.

행동 계층은 단순히 코드가 어떻게 연결되어 있는지가 아니라, 개발자(및 에이전트)가 실제로 어떻게 작업하는지를 반영하기 때문에 가장 큰 비중을 차지합니다.

에이전트에게 맵을 제공하는 두 가지 방법

  1. Ambient Path – 모든 상호작용에 주입되는 간결한 요약입니다. 추가 호출 없이도 에이전트에게 "현재 X 모듈에 있으며, 주변에 이러한 심볼들이 있습니다"라는 즉각적인 스냅샷을 제공합니다.
  2. Deep Path – 더 풍부한 세부 정보(예: 자주 함께 변경되는 파일 목록 또는 최근 소유권 타임라인)가 필요할 때 에이전트가 호출할 수 있는 온디맨드(on-demand) 쿼리 도구입니다.

Ambient 정보와 Deep 정보를 분리함으로써 일상적인 프롬프트는 가볍게 유지하면서도, 필요할 때는 깊이 있는 정보를 제공할 수 있습니다.

시스템을 가볍게 유지하는 설계 규칙

  • 무거운 언어 서버(language servers)는 건너뜁니다. 맵은 전체 타입 추론(type inference) 대신 얕은 파싱(shallow parsing)에 의존합니다. 목표는 성숙한 정적 분석 도구보다 뛰어난 엔진을 만드는 것이 아니라, 행동적 통찰력을 통해 이를 보완하는 것입니다.
  • 그래프를 프로젝트 단위로 제한합니다. 시스템은 여러 저장소에 걸쳐 글로벌 의존성 그래프를 구축하지 않습니다. 이러한 제한은 메모리 사용량을 줄이고 업데이트 속도를 높입니다.
  • 기존 메모리 저장소를 재사용합니다. 파일 변경 로그는 에이전트 자체의 도구 호출 메모리에서 가져오므로, 중복 저장을 방지하고 데이터 소스를 일관되게 유지합니다.

실제 맵 구축 과정

  1. 구조 데이터 수집: 소스 파일을 빠르게 훑으며 심볼과 임포트 라인을 추출합니다.
  2. 시간 지표 추출: 저장소의 git 히스토리에서 어떤 파일에 커밋이 가장 많이 발생하는지, 작성자가 누구인지 기록하여 시간 지표를 가져옵니다.
  3. 행동 신호 수집: 실제 코딩 세션 동안 에이전트의 파일 열기, 편집 및 탐색 동작을 기록하여 행동 신호를 수집합니다. 이 로그는 행동적 이웃을 정의하는 "공동 발생(co-occurrence)" 행렬의 기초가 됩니다.
  4. Ambient Path 채우기: 현재 작업과 가장 관련성이 높은 심볼 및 파일의 짧고 정렬된 목록을 생성합니다.
  5. Deep Path 노출: 가벼운 쿼리 함수 세트(예: "최근 세션에서 함께 편집된 파일 목록")로 제공합니다.

빠른 훅(fast hooks)은 편집이 발생할 때마다 즉시 캡처하고, 느린 백그라운드 스윕(background sweeps)은 변경률 통계를 재계산합니다. 이들이 결합되어 개발자의 워크플로우를 방해하지 않으면서 맵을 최신 상태로 유지합니다.

진행 과정에서 얻은 교훈

  • Ambient와 On-demand를 분리하십시오. 항상 존재하는 요약을 아주 작게 유지하여 토큰 팽창을 방지하고, 더 풍부한 쿼리는 선택 사항으로 둡니다.
  • 작업별로 컨텍스트의 우선순위를 정하십시오. 현재 편집 중인 작업에 따라 Ambient 심볼의 순서를 정하면 더 유용한 제안을 얻을 수 있습니다.
  • 공격적이지만 지능적으로 새로고침하십시오. 빠른 훅은 빈도가 높은 변경 사항을 캡처하고, 주기적인 스캔은 빈도가 낮은 변경 및 소유권 변화를 처리합니다.
  • 속도를 위해서는 얕은 파싱이 유리합니다. 깊은 타입 분석은 맵의 강점인 행동적 통찰력을 제공하지 못하면서 지연 시간만 늘립니다.

핵심 요약: 정적 구조, git 기반 히스토리, 실제 사용 패턴을 압축된 2단계 액세스 모델로 계층화함으로써, 개발자는 AI 코딩 에이전트에게 지속 가능한 코드베이스 맵을 제공할 수 있습니다. 항상 존재하는 요약을 작게 유지하면 토큰 팽창을 방지할 수 있습니다.