Graft: 코딩 에이전트를 위한 코드베이스 맵 활용법

코딩 에이전트를 위한 코드베이스 맵이란 무엇인가

코딩 에이전트를 위한 코드베이스 맵은 저장소에 대한 영구적인 인덱스입니다. 에이전트는 매 세션마다 처음부터 grep을 수행하는 대신 이 인덱스를 참조하여 정보를 찾습니다. Graft는 이러한 아이디어를 구현한 도구 중 하나입니다. 이 도구는 tree-sitter를 사용하여 코드를 파싱하고, 연결된 마크다운 노드 폴더와 심볼별 연결 그래프를 생성합니다. 또한 MCP(코딩 에이전트가 외부 도구를 호출할 때 사용하는 표준 인터페이스인 Model Context Protocol)를 통해 검색 도구를 제공합니다.

Graft는 프록시나 게이트웨이가 아닙니다. 에이전트와 모델 API 사이에는 아무것도 존재하지 않습니다. 맵은 에이전트가 읽을 수 있는 디스크상의 폴더일 뿐입니다. 이러한 차이는 해결하려는 문제의 성격을 결정합니다. 자체 호스팅 토큰 게이트웨이는 이미 전송 중인 요청을 측정하고 라우팅하는 반면, 맵은 전송해야 하는 요청의 수 자체를 줄여줍니다.

이 기술은 본 도구보다 오래되었으며 앞으로도 계속 사용될 것입니다. 도구의 작동 방식보다 기술 자체를 먼저 이해하십시오.

코딩 에이전트가 구조를 재탐색하며 컨텍스트를 소모하는 이유

이미 50번은 본 저장소에서 작업을 시작하는 에이전트를 관찰해 보십시오. 에이전트는 디렉터리 목록을 나열합니다. 특정 심볼을 찾기 위해 grep을 실행합니다. 함수 정의를 찾으려고 파일 3개를 열고, 누가 그 함수를 호출하는지 확인하려고 네 번째 파일을 엽니다. 이 중 어느 것도 실제 작업은 아닙니다. 이는 방향을 잡는 과정이며, 매 세션마다 입력 토큰 비용을 지불해야 합니다.

원인은 간단합니다. 모델은 세션 간에 기억을 유지하지 못합니다. 에이전트가 프로젝트 구조에 대해 학습한 모든 내용은 세션이 종료될 때 폐기되는 컨텍스트 윈도우에 존재했습니다. 따라서 동일한 탐색 과정이 매번 처음부터 다시 실행되며, 그 비용은 온전히 지불됩니다. 대규모 저장소에서는 수정 작업보다 방향을 잡는 단계에 더 많은 비용이 듭니다. 코드를 찾는 데 도구 호출 10번, 수정하는 데 1번이 사용되는 식입니다. 방향 탐색은 비용의 절반을 차지하며, 수정 작업이 나머지 절반입니다. 이것이 바로 작동하는 가장 작은 변경 사항을 유지하는 기술을 지도와 함께 사용하는 것이, 둘 중 하나를 선택하는 것보다 가치 있는 이유입니다.

지도는 탐색 과정을 모델에서 디스크로 옮김으로써 이 반복 고리를 끊어냅니다. 파서가 저장소를 한 번 훑으며 어떤 심볼이 어디에 정의되어 있고 무엇이 무엇을 호출하는지 기록한 뒤, 코드가 변경될 때마다 해당 기록을 최신 상태로 유지합니다. 에이전트는 질문 하나만 던지면 파일과 행 번호가 포함된 답변을 얻습니다. 반복적인 탐색이 저렴한 조회 작업으로 바뀝니다.

여러분은 이미 이보다 약한 형태의 방식을 사용하고 있습니다. 관례를 명시한 AGENTS.md는 에이전트가 매번 관례를 다시 유추하지 않도록 막아줍니다. 생성된 지도는 에이전트가 구조를 다시 유추하지 않도록 막아줍니다. 차이점은 작성 주체입니다. 지침 파일은 사람이 직접 작성하므로 크기가 작게 유지됩니다. 반면 지도는 파서가 생성하므로 만 개가 넘는 파일도 다룰 수 있습니다. 세션 내에서 예산이 실제로 어디에 쓰이는지에 대해서는 Claude Code가 컨텍스트 윈도우를 사용하는 방식에서 비용 산정 내역을 다룹니다.

Graft가 실제로 빌드하는 것

저장소 루트의 graft/ 폴더 아래에 두 개의 아티팩트가 생성됩니다.

첫 번째는 링크된 마크다운으로 작성된 노드 그래프이며, 노드당 파일 하나씩 생성됩니다. 각 노드에는 평문 요약, 소스 코드에서 추출한 핵심 로직 라인인 "crux", 콘텐츠 해시가 포함된 정확한 소스 파일, 다른 노드로 연결되는 타입 지정 위키링크(depends_on, part_of, uses, implements), 그리고 재생성 시에도 유지되어 파서가 추론할 수 없는 맥락을 기록할 수 있는 노트 섹션이 포함됩니다.

두 번째는 tree-sitter가 추출하는 심볼별 구조 그래프인 graft/.graph/wiring.json입니다. 여기에는 정의, 참조, 그리고 이들 사이의 호출 엣지가 포함됩니다.

이 분리는 중요합니다. 절반만 모델이 필요하기 때문입니다. graft build는 순수 tree-sitter를 사용하며 LLM(대규모 언어 모델)을 호출하지 않으므로 결정론적이며 비용이 발생하지 않습니다. graft build --deep는 작성된 요약과 심볼별 crux를 추가하며, 이는 비용이 발생하는 모델 호출입니다.

언어 지원은 계층화되어 있으며, 이 계층에 따라 호출 그래프를 얼마나 신뢰할 수 있는지 결정됩니다. TypeScript, JavaScript, Python, Go, Java는 스코프를 인식하는 파일 간 해석을 지원합니다. Rust, C, C++, C#, Ruby, PHP, Kotlin, Scala, Swift, Elixir, Solidity, OCaml, Zig, Dart는 심볼과 일반적인 호출 엣지를 제공합니다. 즉, 엣지가 해석된 참조가 아닌 이름 일치일 수 있습니다. 컴파일러 수준의 엣지는 --lsp과 rust-analyzer 또는 gopls과 같은 언어 서버를 통해 선택적으로 사용할 수 있습니다.

Graft 설치 및 버전 고정

Graft는 Node.js 20 이상이 필요하며 MIT 라이선스를 따릅니다. 2026년 8월 기준 최신 릴리스는 0.10.1이며, 첫 번째 공개 버전인 0.1.0은 2026년 7월에 출시되었습니다. 아직 초기 단계의 소프트웨어임을 유의하십시오.

npm install -g @nanonets/graft@0.10.1
npm ls -g @nanonets/graft

npm ls -g 명령을 실행하면 @nanonets/graft@0.10.1이 출력되어야 합니다. 의도적으로 해당 버전을 고정하십시오. 단순히 npm install -g @nanonets/graft을 실행하면 실행 시점의 latest 태그를 가져오게 되는데, 한 달에 여러 번 마이너 릴리스가 배포되는 프로젝트의 경우 화요일에 설치한 도구와 월요일에 동료가 설치한 도구가 서로 다를 수 있습니다. 버전을 고정하면 모든 사용자에게 동일한 CLI 플래그와 그래프 형식이 유지되므로, 사용자가 직접 업그레이드 시점을 결정할 수 있습니다.

그런 다음 소유하고 있는 저장소에 연결하십시오:

cd /path/to/your/repo
graft init --dry-run
graft init

graft init은 연결할 코딩 에이전트를 선택하라는 메시지를 표시한 뒤 그래프를 빌드합니다. --dry-run를 먼저 실행하여 수정 예정인 파일 목록을 확인하십시오. 일부 파일은 저장소 외부에 위치할 수 있습니다. graft init는 멱등성을 가지며 기존 설정을 덮어쓰지 않으므로, 두 번 실행해도 안전합니다.

2026년 8월 기준으로 Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf 및 AdaL에 대한 연결을 지원합니다. Claude Code는 가장 깊은 수준의 통합을 제공합니다. MCP 서버 항목, 그래프 크기와 최신 상태를 보여주는 상태 표시줄, 편집 후 그래프를 재빌드하는 훅, 그리고 .claude/ 아래의 스킬 파일이 포함됩니다. 나머지 에이전트들은 도구의 존재를 알리는 지침이나 규칙 파일을 제공받습니다. 따라서 "지원"한다는 의미는 Graft가 연결 설정을 작성한다는 뜻이며, 에이전트가 자체 규칙 파일을 무시하면 맵 또한 무시하게 됩니다. 이것이 에이전트가 작성한 지침을 무시하는 일반적인 이유이며, 이 경우에도 동일하게 적용됩니다.

리포지토리에 포함되는 항목과 git에서 제외되는 항목

graft init 이후, 다음 항목들이 생성됩니다.

• graft/: 마크다운 노드 그래프와 graft/.graph/wiring.json입니다. 사용자를 위해 .gitignore에 추가됩니다.
• .mcp.json: graft MCP 서버를 등록하여 Claude Code가 이를 시작하도록 합니다.
• .claude/settings.json: 제자리에 병합되어 상태 표시줄과 편집 후 훅(post-edit hooks)을 추가합니다.
• AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/graft.mdc, .kiro/steering/graft.md, .windsurf/rules/graft.md 및 .adal/skills/graft/SKILL.md: 선택한 에이전트와 일치하는 파일에 마커로 구분된 섹션이 추가됩니다.
• ~/.codex/config.toml, ~/.codex/hooks.json 및 ~/.codex/hooks/graft/graft-hooks.cjs: 시스템 전체에 적용되며, Codex를 선택할 때만 작성됩니다. graft init --no-global은 이를 건너뛰며, graft init --no-hooks는 훅 심(hook shim)만 건너뜁니다.

그래프는 node_modules와 같은 캐시입니다. 커밋하지 마십시오. 코드를 기반으로 수 초 내에 다시 생성되며 거의 모든 편집 시마다 변경됩니다. 이를 커밋하면 한 줄짜리 수정 사항이 수백 개의 파일에 대한 diff로 변하여 검토자가 읽을 수 없게 됩니다. 대신 AGENTS.md 및 .mcp.json을 포함한 연결 설정(wiring)을 커밋하십시오. 팀원이 리포지토리를 복제하고 graft build을 실행하면 각자의 로컬 그래프가 생성됩니다.

첫 번째 커밋 전에 무시 규칙이 적용되었는지 확인하십시오:

grep -n graft .gitignore
git status --short

grep는 graft/을 포함하는 줄을 출력해야 하며, git status --short은 graft/ 아래에 아무것도 나열하지 않아야 합니다. 해당 출력에 graft/ 아래의 파일이 나타난다면 무시 항목이 누락되었거나 다른 곳에서 재정의된 것입니다. 커밋 전에 수정하십시오. git은 한 번 추가된 파일은 계속 추적하며, 나중에 .gitignore를 편집하더라도 추적을 중단하지 않기 때문입니다.

MCP 서버를 수동으로 등록하거나 설치한 버전으로 고정하려면 다음 항목을 사용하십시오:

{
  "mcpServers": {
    "graft": {
      "command": "npx",
      "args": ["-y", "@nanonets/graft@0.10.1", "mcp"]
    }
  }
}

grep 대신 에이전트가 호출하는 검색 도구

Graft는 MCP를 통해 6가지 도구를 제공합니다. graft_find_code는 작업 설명에 따라 파일 및 행 번호가 포함된 순위 노드를 반환합니다. graft_file_api은 본문을 제외하고 파일 내의 모든 시그니처를 반환합니다. graft_trace_calls은 호출자나 피호출자를 여러 단계 깊이로 추적합니다. graft_find_all은 심볼별로 그룹화된 정규 표현식 일치 항목을 반환합니다. graft_repo_map는 익숙하지 않은 저장소를 처음 파악할 때 사용합니다. graft_check_freshness은 그래프가 코드와 여전히 일치하는지 보고합니다.

각 도구에는 CLI 대응 명령어가 있으며, 이를 통해 에이전트가 실제로 무엇을 전달받는지 확인할 수 있습니다.

graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --json

graft ask은 파일 내용 대신 file:line 참조가 포함된 순위 노드를 출력해야 합니다. 이것이 전체 메커니즘입니다. 에이전트는 10개의 파일을 읽어 올바른 파일을 찾는 대신, 포인터를 받아 하나의 파일만 엽니다. 직접 그래프를 확인하고 싶다면 graft viz을 사용하여 localhost에서 대화형 뷰어를 열 수 있습니다. 30초 안에 답할 수 있는 질문에 대해 graft ask가 유용한 결과를 반환하지 않는다면, 그래프가 오래되었거나 해당 언어가 광범위한 계층(broad tier)에 속해 있는 것이며, 이 경우 맵은 에이전트에게도 도움이 되지 않습니다.

간과하기 쉬운 비용이 하나 있습니다. 6개의 도구 정의가 세션 전체의 모든 요청에 대한 시스템 프롬프트에 주입됩니다. 에이전트가 맵을 사용하든 아니든 이 비용은 발생합니다. 컨텍스트에 들어갈 만큼 작은 저장소에서는, 이 고정 비용이 탐색을 통해 절약하는 비용보다 더 클 수 있습니다.

코드 변경 시 그래프에 발생하는 일

구조적 새로고침은 비용이 저렴하며 자동으로 수행됩니다. Graft는 git 대신 작업 트리를 읽으므로, 커밋하지 않은 수정 사항이나 스테이징한 수정 사항 모두 동일하게 인식됩니다. 쿼리는 상태(stat)가 변경된 파일만 다시 파싱하며, 프로젝트 문서에 따르면 이는 약 3 ms의 오버헤드가 발생합니다. 또한 턴 종료 시 수행되는 재빌드는 코드가 이동한 파일만 건드립니다. 디스크의 그래프를 다시 파싱하지 않고 응답하려면 GRAFT_NO_REFRESH=1를 설정하거나 --no-refresh을 전달하십시오. 모든 항목을 강제로 콜드 리파싱하려면 --no-reuse을 전달하십시오. 이는 Graft 자체를 업그레이드한 후에 필요한 작업입니다.

모델이 작성한 절반은 다르게 동작하며, 이 부분이 조용히 잘못될 수 있는 지점입니다. 요약과 핵심 내용은 캐시됩니다. 각 노드는 소스의 콘텐츠 해시를 기록하므로, 소스 파일이 변경되면 해당 노드는 최신 상태가 아닌 '오래됨(stale)'으로 표시됩니다. 이 플래그는 무언가가 이에 대응할 때만 유용합니다. graft build --deep로 새로고침을 수행하십시오. 이 작업은 모델 토큰을 다시 소모합니다.

오래된 상태를 시각화하는 방법은 다음과 같습니다.

graft check .
echo $?

종료 상태 0은 그래프가 코드와 일치함을 의미합니다. 종료 상태 1은 데이터 불일치를 의미합니다. 6개월 전의 지도가 3월에 재작성된 코드에 대해 잘못된 답변을 내놓지 않도록, pre-push 훅이나 CI의 브랜치에서 이 명령을 실행하십시오.

공개된 벤치마크 수치를 주의 깊게 읽으십시오

Graft의 주요 홍보 문구는 "최대 4배 저렴하고 3배 빠르며, 정확도는 동일하거나 더 우수함"입니다. 이 수치는 프로젝트의 README에 게시된 자체 벤치마크에서 나온 것입니다. 다음은 해당 문서에 보고된 두 가지 실행 결과입니다.

[
  {
    "label": "Controlled sweep",
    "run_count": 162,
    "token_saving_pct": 42,
    "tool_call_saving_pct": 46,
    "correctness_pct": 93,
    "baseline_correctness_pct": 93
  },
  {
    "label": "SWE-bench Verified",
    "run_count": 50,
    "token_saving_pct": 23,
    "tool_call_saving_pct": 25,
    "correctness_pct": 66,
    "baseline_correctness_pct": 54
  }
]

통제된 스윕(controlled sweep)은 두 개의 저장소(그중 하나는 Graft 자체 저장소)를 대상으로 162회 실행되었으며, 작업당 3번의 시도를 거쳤습니다. 보고된 결과에 따르면 토큰 사용량은 42%, 도구 호출(tool call)은 46% 감소했습니다. SWE-bench Verified 실행은 동일한 모델을 양쪽 모두에 사용하여 50개의 인스턴스를 대상으로 수행되었으며, 토큰 23% 및 도구 호출 25% 감소라는 더 작은 절감 효과를 보고했습니다. 세 번째 실행에서는 5개의 병합된 PocketBase 풀 리퀘스트를 재현했으며, 비용은 기준치인 13.91달러 대비 11.02달러가 소요되었습니다.

이 모든 수치를 벤더 벤치마크로 간주하십시오. 이 결과가 제공하는 정보에는 두 가지 한계가 있습니다. 통제된 스윕에는 저자들이 최적화를 수행한 대상인 Graft 자체 저장소가 포함되어 있습니다. SWE-bench Verified는 잘 알려진 오픈 소스 Python 프로젝트의 이슈들로 구성된 공개 데이터셋이며, 공개 데이터셋은 의도 여부와 관계없이 도구들이 최적화되는 대상이 됩니다. 두 결과 모두 고유한 명명 습관과 데드 코드를 가진 귀하의 비공개 모노레포에 대한 보증이 될 수 없습니다.

정확도 부분은 다시 한번 확인해야 합니다. 통제된 스윕에서 정확도는 변하지 않았습니다. Graft를 사용했을 때 93%, 사용하지 않았을 때 93%였습니다. 54%에서 66%로의 상승은 SWE-bench Verified에서만 나타납니다. 토큰 비용을 절감하면서 품질을 유지하는 도구는 여전히 좋은 선택입니다. 다만, SWE-bench의 정확도 결과와 스윕의 토큰 절감 결과를 혼합하여 하나의 주장으로 인용하지 않도록 주의하십시오.

측정값을 믿기 전에 직접 토큰 변화량을 측정하십시오

가장 중요한 수치는 본인의 저장소에서 직접 얻은 데이터입니다. 이 방법은 오후 한나절이면 충분합니다.

정확하게 반복할 수 있는 작업을 선택하십시오. 편집 작업보다는 질문이 낫습니다. 편집은 저장소를 변경하므로 두 번째 실행은 더 이상 동일한 실험이 아니기 때문입니다. "로그인 경로에서 속도 제한을 적용하는 모듈은 무엇인가"와 같은 질문이 적절합니다.

텔레메트리를 켜고 본인의 터미널로 전송하십시오:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

콘솔 익스포터는 메트릭 레코드가 수집될 때마다 이를 출력합니다. 확인해야 할 항목은 claude_code.token.usage이며, 여기에는 input, output, cacheRead 또는 cacheCreation 값을 가진 type 속성이 포함되어 있습니다. 파일 내용이 도달하는 지점인 input와 cacheRead에서 방향성을 확인할 수 있습니다. 이 두 값을 합산하십시오.

맵을 연결한 상태에서 작업을 3회 반복하십시오. 매번 새로운 세션에서 실행해야 합니다. 그 후 .mcp.json에서 그래프트 항목을 제거하고 다시 3회 실행하십시오. 에이전트 실행 결과는 편차가 크고 운이 나쁜 한 번의 실행이 정반대의 결과를 보여줄 수 있으므로, 단일 실행보다는 중앙값을 비교하십시오. 도구 호출 횟수도 기록하십시오. 도구 호출은 메커니즘이고 토큰은 그 결과이므로, 도구 호출 횟수 변화 없이 토큰이 절감되었다면 다른 요소가 변경된 것입니다.

그런 다음 벤치마크에 나타나지 않는 비용을 차감하십시오. graft build --deep은 전체 새로고침이 발생할 때마다 모델 토큰을 소모합니다. 6개의 도구 스키마는 모든 요청에 포함되어 전송됩니다. 에이전트가 임대 서버에서 실행 중이라면 에이전트 비용에 상한선을 설정하여 예기치 못한 지출을 예산 범위 내로 관리할 수 있으며, 코딩 에이전트의 텔레메트리 보고 내용을 통해 익스포터를 활성화했을 때 외부로 나가는 데이터의 상세 정보를 확인할 수 있습니다.

코드베이스 맵이 더 이상 도움이 되지 않는 경우는 언제입니까?

• 저장소가 이미 컨텍스트에 완전히 들어오는 경우. 단일 소규모 서비스는 맵이 필요 없으며, 매 요청마다 6개의 도구 스키마 비용을 지불할 필요도 없습니다. 에이전트가 오늘날 한두 번의 도구 호출만으로 원하는 파일을 찾을 수 있다면 맵을 생략하십시오.
• 사용 중인 언어가 광범위 계층(broad tier)에 속하는 경우. 일반적인 호출 에지는 graft callers가 호출자를 놓치거나 이름 충돌로 인해 잘못된 호출자를 생성하게 만들 수 있습니다. 영향 범위를 신뢰하기 전에 graft grep으로 확인하십시오.
• 그래프가 최신 상태가 아닌데 아무도 눈치채지 못한 경우. graft check은 드리프트 발생 시 1을 반환하며, 이는 무언가가 이를 실행할 때만 유용합니다. 습관이 아니라 훅(hook)이나 CI 단계로 자동화해야 합니다.
• 모노레포에 범위 지정이 필요한 경우. 단일 git 모노레포는 워크스페이스 파일, go.mod, pyproject.toml 또는 Cargo.toml에 의해 자동으로 분할되며, graft ask "..." --in services/billing/는 쿼리 범위를 하나의 하위 프로젝트로 좁힙니다. 패키지별 중첩 AGENTS.md 파일을 만드는 것과 같은 직관이 맵에도 적용됩니다.
• 에이전트가 연결 구조를 무시하는 경우. 맵이 사용되고 있다고 결론짓기 전에 실제 세션에서 도구 호출을 관찰하십시오. 에이전트가 여전히 grep을 실행하고 있다면, 이는 에이전트가 규칙 파일을 읽지 않았음을 의미합니다.

FAQ

Should I commit the graft/ folder to git?

No. graft build adds graft/ to your .gitignore automatically, because the graph is a regenerable cache like node_modules. It changes on nearly every edit, so committing it buries real diffs under hundreds of generated files. Commit the wiring that tells agents the map exists, AGENTS.md and .mcp.json among them, and let each teammate run graft build locally. Verify with grep -n graft .gitignore and git status --short before your first commit, because git keeps tracking a file once it has been added, and editing .gitignore afterwards does not untrack it.

Does Graft cost money to run?

The structural half does not. graft build, graft ask, graft check and the six MCP retrieval tools are tree-sitter operations that never call a model. graft build --deep is the paid half: it writes the plain-English summaries and per-symbol cruxes through an LLM, configured with GRAFT_PROVIDER, GRAFT_API_KEY and GRAFT_MODEL, plus GRAFT_BASE_URL for any OpenAI-compatible endpoint. You can run Graft with structure only and never spend a token on the graph itself.

How much will a codebase map actually save on my repository?

Nobody can tell you without measuring. The project reports 42% fewer tokens on its own 162-run sweep and 23% on SWE-bench Verified, both against a baseline with no map. Both are vendor benchmarks, one of them run partly on Graft's own repository, and neither describes your private code. Run one repeatable question three times with the map and three times without, with CLAUDE_CODE_ENABLE_TELEMETRY=1 and OTEL_METRICS_EXPORTER=console set, then compare the median of claude_code.token.usage for the input and cacheRead types.

What happens to the graph when I refactor?

Structure re-parses itself. Graft stats the working tree and re-parses only the files that changed, so a rename is picked up on the next query at roughly 3 ms of overhead, and it sees uncommitted work because it reads files rather than git history. The model-written summaries are what goes stale: each node stores a content hash of its sources, and a changed source marks the node stale instead of rewriting it. Run graft check . to see the drift, then graft build --deep to refresh the written half.

Which coding agents can use Graft today?

As of August 2026 graft init wires Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf and AdaL. Claude Code gets the most: an MCP server entry in .mcp.json, a statusline, post-edit hooks and a skill file under .claude/. Codex gets an AGENTS.md section plus machine-wide entries under ~/.codex/, which graft init --no-global skips. The others receive a rules or steering file. Any other MCP client can use the server directly by registering the command npx -y @nanonets/graft@0.10.1 mcp.