Graft: 코딩 에이전트를 위한 코드베이스 맵 활용법
Graft는 tree-sitter를 사용하여 저장소를 파싱하고 MCP를 통해 코드베이스 맵을 제공합니다. 매 세션마다 반복되는 파일 구조 탐색과 grep 비용을 줄여 에이전트의 컨텍스트 소모를 최적화하는 방법을 확인하십시오.
코딩 에이전트를 위한 코드베이스 맵이란 무엇인가
코딩 에이전트를 위한 코드베이스 맵은 저장소에 대한 영구적인 인덱스입니다. 에이전트는 매 세션마다 처음부터 grep을 수행하는 대신 이 인덱스를 참조하여 정보를 찾습니다. Graft는 이러한 아이디어를 구현한 도구 중 하나입니다. 이 도구는 tree-sitter를 사용하여 코드를 파싱하고, 연결된 마크다운 노드 폴더와 심볼별 연결 그래프를 생성합니다. 또한 MCP(코딩 에이전트가 외부 도구를 호출할 때 사용하는 표준 인터페이스인 Model Context Protocol)를 통해 검색 도구를 제공합니다.
Graft는 프록시나 게이트웨이가 아닙니다. 에이전트와 모델 API 사이에는 아무것도 존재하지 않습니다. 맵은 에이전트가 읽을 수 있는 디스크상의 폴더일 뿐입니다. 이러한 차이는 해결하려는 문제의 성격을 결정합니다. 자체 호스팅 토큰 게이트웨이는 이미 전송 중인 요청을 측정하고 라우팅하는 반면, 맵은 전송해야 하는 요청의 수 자체를 줄여줍니다.
이 기술은 본 도구보다 오래되었으며 앞으로도 계속 사용될 것입니다. 도구의 작동 방식보다 기술 자체를 먼저 이해하십시오.
코딩 에이전트가 구조를 재탐색하며 컨텍스트를 소모하는 이유
이미 50번은 본 저장소에서 작업을 시작하는 에이전트를 지켜보십시오. 에이전트는 디렉터리 목록을 나열합니다. 특정 심볼을 찾기 위해 grep을 실행합니다. 함수가 정의된 파일을 찾으려고 파일 3개를 열고, 누가 그 함수를 호출하는지 확인하려고 네 번째 파일을 엽니다. 이 모든 과정은 실제 작업이 아닙니다. 이는 방향을 잡는 과정이며, 매 세션마다 입력 토큰 비용을 지불해야 합니다.
원인은 간단합니다. 모델은 세션 간에 기억을 유지하지 못합니다. 에이전트가 프로젝트 구조에 대해 학습한 모든 내용은 세션이 종료될 때 폐기되는 컨텍스트 윈도우에 존재했습니다. 따라서 똑같은 탐색 과정을 매번 0부터 다시 시작하며, 사용자는 그 비용을 다시 지불하게 됩니다. 프롬프트 캐싱은 최근 5분 이내, 혹은 추가 비용을 지불할 경우 최근 1시간 이내에 발생한 동일한 프롬프트 접두사에 대해서만 할인을 적용하므로, 어제의 탐색 결과를 오늘의 세션으로 가져올 수 없습니다. 대규모 저장소에서는 실제 수정 작업보다 방향을 잡는 단계에 더 많은 비용이 듭니다. 코드를 찾는 데 도구 호출 10번을 쓰고, 수정하는 데 1번을 쓰는 식입니다. 방향을 잡는 비용이 전체 청구액의 절반을 차지하고 수정 작업이 나머지 절반을 차지합니다. 이것이 바로 에이전트가 가장 작은 단위의 변경만 수행하도록 제어하는 기술을 지도와 함께 사용하는 것이, 둘 중 하나만 선택하는 것보다 가치 있는 이유입니다.
지도는 탐색 과정을 모델에서 디스크로 옮김으로써 이러한 반복 고리를 끊어냅니다. 파서가 저장소를 한 번 훑으며 어떤 심볼이 어디에 정의되어 있고 어떤 심볼이 무엇을 호출하는지 기록한 뒤, 코드가 변경될 때마다 해당 기록을 최신 상태로 유지합니다. 에이전트가 질문 하나를 던지면 파일 경로와 줄 번호가 포함된 답변을 즉시 얻습니다. 반복적인 탐색이 저렴한 조회 작업으로 바뀝니다.
여러분은 이미 이보다 약한 형태의 방식을 사용하고 있습니다. 관례를 명시한 AGENTS.md는 에이전트가 매번 관례를 새로 추론하지 않도록 막아줍니다. 생성된 지도는 에이전트가 구조를 매번 새로 추론하지 않도록 막아줍니다. 차이점은 누가 작성하느냐에 있습니다. 지침 파일은 사람이 직접 작성하므로 크기가 작게 유지됩니다. 반면 지도는 파서가 생성하므로 1만 개의 파일도 다룰 수 있습니다. 세션 내에서 예산이 실제로 어떻게 소모되는지에 대해서는 Claude Code가 컨텍스트 윈도우를 사용하는 방식에서 자세히 다룹니다.
Graft가 실제로 빌드하는 것
모두 저장소 루트의 하나의 graft/ 폴더 아래에 있는 2개의 산출물이다.
첫 번째는 연결된 Markdown으로 작성한 노드 그래프다. 노드마다 파일 하나가 있다. 각 노드에는 일반 영어 요약, 소스에서 추출한 중요한 로직 줄의 "crux", 콘텐츠 해시가 포함된 정확한 소스 파일 목록, 다른 노드를 가리키는 유형화된 위키 링크(depends_on, part_of, uses, implements), 그리고 재생성 후에도 유지되는 notes 섹션이 포함된다. notes 섹션에는 파서가 추론할 수 없는 맥락을 기록할 수 있다.
두 번째는 tree-sitter가 추출하는 심볼별 구조 그래프인 graft/.graph/wiring.json이다. 여기에는 정의, 참조, 그리고 심볼 간 호출 엣지가 포함된다.
이렇게 분리하는 이유는 두 부분 중 하나만 모델이 필요하기 때문이다. graft build는 순수한 tree-sitter로 동작하며 LLM(large language model)을 호출하지 않는다. 따라서 결정적이고 비용도 들지 않는다. graft build --deep은 작성된 요약과 심볼별 crux를 추가하며, 이 작업에는 비용을 지불해야 하는 모델 호출이 사용된다.
언어 지원은 계층화되어 있으며, 각 계층에 따라 호출 그래프를 어느 수준까지 신뢰할 수 있는지가 달라진다. TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, Swift, R은 스코프를 인식한 파일 간 해석을 지원한다. Rust, C, C++, C#, Ruby, Scala, Elixir, Solidity, OCaml, Zig, Dart, Clojure, Nix, Lua는 심볼과 일반 호출 엣지를 지원한다. 따라서 엣지가 해석된 참조가 아니라 이름 일치만 나타낼 수도 있다. 컴파일러 수준의 엣지는 --lsp와 rust-analyzer 또는 gopls 같은 language server를 사용해 선택적으로 활성화할 수 있다.
Graft 설치 및 버전 고정
Graft는 Node.js 20 이상이 필요하며 MIT 라이선스를 따릅니다. 2026년 10월 17일 기준으로 최신 릴리스는 2026년 10월 15일에 배포된 0.23.0이며, 최초 릴리스인 0.1.0은 2026년 7월에 나왔습니다. 아직 초기 단계의 소프트웨어로 간주하십시오. 2026년 10월 14일에 배포된 0.22.0 릴리스에서 프로젝트 이름이 Trail-code로 변경되었습니다. 동일한 코드가 이제 @trailhq/trail-code로도 배포되며 trail 명령을 사용하고, @nanonets/graft은 계속해서 graft 명령을 사용합니다.
이 가이드에서는 0.22 및 0.23에서 가이드가 의존하는 명령이 변경되었기 때문에, 이름 변경 전 마지막 릴리스인 2026년 9월 29일에 배포된 0.21.1 버전을 고정합니다. 0.22 버전부터 graft check는 브랜치의 diff를 저장소의 팀 학습 내용과 비교하여 충돌 시 1을 반환하며, 드리프트 탐지 기능은 graft build --check으로 이동했고, MCP 도구는 trail_*로 명명되었습니다(서버는 여전히 이전 graft_* 이름을 응답합니다). 0.23.0 변경 로그에 따르면 trail로 설정된 저장소에서 맵은 .trail/cache/으로 이동하며 Claude Code는 더 이상 MCP 서버를 제공받지 않지만, README는 여전히 graft/ 및 .mcp.json를 설명하고 있습니다. 변경 로그를 읽고 버전을 변경하기 전에 --dry-run을 실행하십시오.
npm install -g @nanonets/graft@0.21.1
npm ls -g @nanonets/graftnpm ls -g은 @nanonets/graft@0.21.1을 출력해야 합니다. 해당 버전을 의도적으로 고정하십시오. 단순히 npm install -g @nanonets/graft를 사용하면 실행 시점의 latest 태그를 가져오게 되는데, 한 달에 여러 번 마이너 릴리스가 배포되는 프로젝트의 경우 월요일에 동료가 설치한 도구와 화요일에 본인이 사용하는 도구가 달라질 수 있습니다. 버전을 고정하면 모든 사용자에게 동일한 CLI 플래그와 그래프 형식이 유지되므로, 사용자가 직접 결정할 때 업그레이드할 수 있습니다.
그런 다음 소유한 저장소에 연결하십시오:
cd /path/to/your/repo
graft init --dry-run
graft initgraft init은 연결할 코딩 에이전트를 선택하라고 요청한 뒤 그래프를 빌드합니다. 일부 파일이 저장소 외부에 위치할 수 있으므로 먼저 --dry-run를 실행하여 수정 예정인 파일 목록을 확인하십시오. graft init은 멱등성을 가지며 기존 설정을 덮어쓰지 않으므로 두 번 실행해도 안전합니다. 작업을 되돌리려면 graft uninstall를 사용하여 Graft가 작성한 모든 파일과 설정 항목을 제거하십시오. -y를 전달하기 전까지는 드라이 런(dry run)으로 작동합니다.
동일한 프롬프트에 원격 측정(telemetry) 체크박스가 포함되어 있습니다. 0.12.0 릴리스부터 Graft는 기본적으로 익명 사용 핑을 전송합니다. 여기에는 버킷화된 카운트와 고정된 레이블만 포함되며, 코드, 파일 경로, 저장소 이름은 포함되지 않습니다. 이벤트는 하루에 최대 한 번 전송되지만, npm의 postinstall 훅이 백그라운드 전송기로 즉시 전달하는 설치 이벤트는 예외입니다. graft init 과정에서 체크박스를 해제하거나, graft telemetry disable을 실행하거나, DO_NOT_TRACK=1을 설정하여 기능을 끌 수 있습니다(CI 환경에서는 자동으로 꺼집니다). graft telemetry debug는 전송하지 않고 전송할 배치 데이터를 출력합니다.
0.21.1 버전의 연결 지원 범위는 Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent, Google Antigravity입니다. Hermes Agent는 0.13.0 릴리스부터 1급 graft init 호스트였으며, 고정된 버전에서 graft init --agents hermes 및 graft init --agents antigravity는 다른 호스트와 동일하게 이 두 호스트를 선택합니다. Grok은 0.13.0 릴리스에 추가되었으며 graft init --agents grok으로 선택합니다. Claude Code는 가장 깊은 통합을 제공합니다. MCP 서버 항목, 그래프 크기와 최신 상태를 보여주는 상태 줄, 그래프를 재빌드하는 편집 후 훅, .claude/ 아래의 스킬 파일이 포함됩니다. 나머지는 에이전트에게 도구의 존재를 알리는 지침이나 규칙 파일을 제공하며(Hermes Agent와 Antigravity는 모두 AGENTS.md 섹션을 읽습니다), Grok은 자체 설정에 MCP 블록을 추가로 받습니다. 따라서 "지원"이란 Graft가 연결 설정을 작성한다는 의미이므로, 자체 규칙 파일을 무시하는 에이전트는 맵도 무시하게 됩니다. 이것이 에이전트가 작성한 지침을 무시하는 일반적인 이유이며, 여기에도 동일하게 적용됩니다.
저장소에 들어오는 항목과 git에서 제외되는 항목
graft init 후에는 다음 항목이 생성됩니다.
graft/: markdown 노드 그래프와graft/.graph/wiring.json입니다..gitignore에 자동으로 추가됩니다..mcp.json: graft MCP 서버를 등록하므로 Claude Code가 서버를 시작할 수 있습니다..claude/settings.json: 기존 위치에 병합되며 statusline과 post-edit hook을 추가합니다.AGENTS.md,GEMINI.md,.github/copilot-instructions.md,.cursor/rules/graft.mdc,.kiro/steering/graft.md,.windsurf/rules/graft.md,.grok/skills/graft/SKILL.md및.adal/skills/graft/SKILL.md: 선택한 agent에 해당하는 파일에 marker로 구분된 섹션을 추가합니다..grok/config.toml: 저장소 수준의[mcp_servers.graft]블록입니다. Grok을 선택한 경우에만 작성됩니다.~/.codex/config.toml,~/.codex/hooks.json및~/.codex/hooks/graft/graft-hooks.cjs: 시스템 전체에 작성됩니다. Codex를 선택했고~/.codex/가 이미 존재하는 경우에만 작성됩니다.graft init --no-global는 이 항목들을 건너뛰고,graft init --no-hooks는 hook shim만 자체적으로 건너뜁니다.
그래프는 node_modules와 같은 캐시입니다. 그래프를 커밋하지 마십시오. 그래프는 코드에서 몇 초 만에 다시 생성되며 거의 모든 편집에서 변경됩니다. 이를 커밋하면 검토자가 읽지 않을 수백 개 파일의 diff로 한 줄 수정이 바뀝니다. 대신 AGENTS.md와 .mcp.json를 포함한 연결 설정을 커밋하십시오. 팀원이 저장소를 clone한 뒤 graft build를 실행하면 자신의 로컬 그래프를 얻습니다.
첫 커밋 전에 ignore 규칙이 추가되었는지 확인하십시오.
grep -n graft .gitignore
git status --shortgrep에는 graft/가 포함된 줄이 출력되어야 하며, git status --short에는 graft/ 아래 항목이 출력되지 않아야 합니다. 해당 출력에 graft/ 아래 파일이 나타나면 ignore 항목이 없거나 다른 위치에서 재정의된 것입니다. 커밋하기 전에 수정하십시오. git은 파일이 한 번 추가되면 계속 추적하며, 나중에 .gitignore를 편집해도 해당 파일의 추적이 해제되지 않습니다.
MCP 서버를 직접 등록하거나 설치한 버전과 동일한 버전으로 고정하려면 항목은 다음과 같이 간단합니다.
{
"mcpServers": {
"graft": {
"command": "npx",
"args": ["-y", "@nanonets/graft@0.21.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" --jsongraft ask는 파일 내용 대신 file:line 참조가 포함된 순위 노드를 출력해야 합니다. 이것이 전체 메커니즘의 핵심입니다. 에이전트는 파일을 10개씩 읽어 적절한 파일을 찾는 대신, 포인터를 받아 파일 하나만 엽니다. graft viz는 그래프를 직접 확인하고 싶을 때 localhost에서 대화형 뷰어를 엽니다. 만약 graft ask가 30초 안에 답할 수 있는 질문에 대해 유용한 결과를 반환하지 않는다면, 질문을 다시 작성하여 재시도하지 마십시오. 순위 기반 검색은 실패할 수 있으며, 프로젝트의 기술 문서에 따르면 검색 결과가 약할 경우 graft grep, graft skeleton 또는 graft callers로 전환해야 합니다. 만약 이 도구들로도 부족하다면, 그래프의 드리프트 현상을 확인하고(0.21.1 버전에서는 graft check ., 0.22 버전부터는 graft build --check 사용) 해당 언어가 어떤 계층에 속하는지 확인하십시오. 그래프가 최신 상태가 아니거나 계층 범위가 너무 넓으면 에이전트의 검색 성능이 저하됩니다.
간과하기 쉬운 비용이 하나 있습니다. 6개의 도구 정의가 세션 내 모든 요청의 시스템 프롬프트에 주입됩니다. 에이전트가 맵을 사용하든 아니든 이 비용은 발생합니다. 컨텍스트에 충분히 들어갈 만큼 작은 저장소에서는, 이 고정 비용이 도구를 통해 절감하는 탐색 비용보다 더 클 수 있습니다.
코드 변경 시 그래프에 발생하는 변화
구조적 갱신은 비용이 적게 들며 자동으로 수행됩니다. Graft는 git이 아닌 작업 트리(working tree)를 읽으므로, 커밋하지 않은 수정 사항이나 스테이징된 수정 사항도 동일하게 인식합니다. 각 쿼리는 먼저 작업 트리의 상태를 확인한 뒤 변경된 파일만 다시 파싱합니다. 0.21.1 버전 문서에 따르면 변경 사항이 없을 때 이 확인 과정은 약 3 ms가 소요되며, 현재 README에서는 프로젝트 자체 저장소 기준으로 수십 밀리초, 약 50 ms 정도가 소요된다고 명시합니다. 턴 종료 시 재빌드는 코드가 이동한 파일에만 영향을 미칩니다. 디스크에 저장된 그래프를 재파싱 없이 사용하려면 GRAFT_NO_REFRESH=1을 설정하거나 --no-refresh를 전달하십시오. 모든 내용을 강제로 다시 파싱하려면 --no-reuse을 전달하십시오. 이는 Graft 자체를 업그레이드한 후에 권장되는 작업입니다.
모델이 작성한 절반의 데이터는 다르게 동작하며, 이 부분이 조용히 오류를 일으킬 수 있는 지점입니다. 요약과 핵심 정보는 캐시됩니다. 각 노드는 소스 파일의 콘텐츠 해시를 기록하므로, 소스 파일이 변경되면 해당 노드는 최신 상태가 아닌 'stale(오래됨)' 상태로 표시됩니다. 이 플래그는 무언가 이를 기반으로 동작할 때만 의미가 있습니다. 모델 토큰을 다시 소비하여 갱신하려면 graft build --deep를 사용하십시오.
오래된 상태(staleness)를 시각화하는 방법은 다음과 같습니다.
graft check .
echo $?고정된 0.21.1 버전에서 종료 상태 0은 그래프와 코드가 일치함을 의미하며, 종료 상태 1은 불일치(drift)를 의미합니다. 0.22 버전부터는 graft check가 팀 학습과의 충돌 시 1을 반환하며, 불일치 여부를 확인하는 게이트는 graft build --check이므로 버전을 변경할 때 명령어도 함께 수정해야 합니다. 6개월 전의 맵이 3월에 재작성된 코드에 대해 잘못된 답변을 내놓지 않도록 pre-push 훅에서 이 명령을 실행하십시오. 0.21.1 버전의 README는 graft check을 로컬 신선도 신호로 설명하며, 현재 README는 CI용으로 build --check을 나열합니다. 어떤 경우든 graft/는 git-ignored 처리되므로, CI 작업에서 그래프를 직접 빌드하지 않는 한 새로운 CI 체크아웃은 그래프 없이 시작됩니다.
공개된 벤치마크 수치를 주의 깊게 확인하십시오
0.21.1 버전의 README는 "최대 4배 저렴하고 3배 빠르며, 정확도 손실은 없거나 더 우수함"이라는 문구로 시작했습니다. 현재의 README는 해당 문구를 삭제하고 더 낮은 수치를 제시합니다. "동일한 에이전트로 동일한 작업을 162회 수행한 결과: 비용 32% 절감, 캐시되지 않은 입력 토큰 42% 감소, 시간 60% 단축, 정답률은 동일함." 이는 프로젝트의 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)은 두 개의 저장소를 대상으로 162회 실행되었으며, 각 작업당 3번의 시도를 포함합니다. 이 결과 캐시되지 않은 입력 토큰은 42%, 도구 호출은 46% 감소했다고 보고합니다. SWE-bench Verified 실행은 동일한 모델을 양쪽 그룹에 적용하여 50개의 인스턴스를 대상으로 수행되었으며, 토큰 23%와 도구 호출 25% 감소라는 더 작은 절감 효과를 보고합니다. 15개의 PocketBase 작업(개발자 질문 10개와 재현된 병합 풀 리퀘스트 5개)을 대상으로 한 세 번째 실행에서는 총 11.02달러가 소요되어 기준치인 13.91달러보다 낮았습니다.
이 모든 수치를 벤더 측 벤치마크로 간주하십시오. 이 데이터가 제공하는 정보에는 두 가지 한계가 있습니다. 통제된 스윕에는 개발자가 최적화 대상으로 삼은 Graft 자체 저장소가 포함되어 있습니다. SWE-bench Verified는 잘 알려진 오픈 소스 Python 프로젝트의 이슈를 모은 공개 데이터셋이며, 공개 데이터셋은 의도 여부와 관계없이 도구가 최적화되는 대상이 됩니다. 두 결과 모두 귀하의 사설 모노레포에 대한 보증이 될 수 없으며, 귀하의 저장소에는 고유한 명명 습관과 사용되지 않는 코드가 존재합니다.
정확도 부분은 다시 한번 확인해야 합니다. 통제된 스윕에서 정확도는 맵 사용 시 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개의 도구 스키마에 대한 비용을 지불하게 됩니다. 에이전트가 오늘날 한두 번의 도구 호출로 파일을 찾을 수 있다면 맵을 사용하지 마십시오.
- 사용 중인 언어가 광범위 계층에 속하는 경우. 일반적인 호출 에지는
graft callers이 호출자를 놓치거나 이름 충돌로 인해 잘못된 호출을 생성할 수 있음을 의미합니다. 영향 범위를 신뢰하기 전에graft grep로 확인하십시오. - 그래프가 최신 상태가 아닌데 아무도 눈치채지 못한 경우. 0.21.1 버전에서
graft check는 드리프트 발생 시 1을 반환하며 종료합니다(0.22 버전부터는graft build --check이 수행). 이는 무언가가 이를 실행할 때만 유용합니다. 습관이 아닌 pre-push 훅으로 설정하십시오. - 모노레포에 범위 지정이 필요한 경우. 단일 git 모노레포는 분할되어 있지 않지만,
graft build는pnpm-workspace.yaml,package.json워크스페이스 또는 패키지별go.mod,pyproject.toml,Cargo.toml에서 하위 프로젝트를 감지하여 이를 순위 지정 범위로 사용하며,graft ask "..." --in services/billing/은 쿼리를 하나의 하위 프로젝트로 좁힙니다. 패키지별 중첩 AGENTS.md 파일을 사용하는 것과 같은 직관이 맵에도 적용됩니다. - 에이전트가 연결 구조를 무시하는 경우. 맵이 사용되고 있다고 결론짓기 전에 실제 세션에서 도구 호출을 관찰하십시오. 여전히
grep을 실행 중인 에이전트는 규칙 파일을 읽지 않았음을 의미합니다.
FAQ
graft/ 폴더를 git에 커밋해야 합니까?
아니요. graft build는 graft/을 사용자의 .gitignore에 자동으로 추가합니다. 그래프는 node_modules와 같이 재생성 가능한 캐시이기 때문입니다. 거의 모든 편집마다 변경되므로, 이를 커밋하면 수백 개의 생성된 파일 때문에 실제 변경 사항(diff)을 확인하기 어렵습니다. 에이전트에게 맵의 존재를 알리는 배선 설정(AGENTS.md 및 .mcp.json 포함)만 커밋하고, graft build 실행은 각 팀원이 로컬에서 수행하도록 하십시오. 첫 커밋 전에 grep -n graft .gitignore 및 git status --short로 확인하십시오. git은 한 번 추가된 파일은 계속 추적하며, 이후 .gitignore를 편집해도 추적 대상에서 제외되지 않기 때문입니다.
Graft를 실행하는 데 비용이 듭니까?
구조적 부분은 비용이 들지 않습니다. graft build, graft ask, graft check 및 6개의 MCP 검색 도구는 모델을 호출하지 않는 tree-sitter 작업입니다. graft build --deep은 유료 부분입니다. 이 기능은 GRAFT_PROVIDER, GRAFT_API_KEY, GRAFT_MODEL으로 구성된 LLM과 OpenAI 호환 엔드포인트를 위한 GRAFT_BASE_URL을 사용하여 평문 요약과 심볼별 핵심 내용을 작성합니다. 구조 기능만 사용하여 Graft를 실행하면 그래프 자체에는 토큰 비용을 전혀 지불하지 않을 수 있습니다.
코드베이스 맵이 내 저장소에서 실제로 얼마나 절약됩니까?
측정해 보기 전에는 누구도 알 수 없습니다. 이 프로젝트는 자체 162회 실행 스윕에서 캐시되지 않은 입력 토큰이 42% 감소했고, SWE-bench Verified에서는 맵이 없는 기준 대비 23% 감소했다고 보고합니다. 이 수치는 모두 벤더 벤치마크이며, 하나는 Graft 자체 저장소에서 부분적으로 실행되었고, 어느 쪽도 사용자의 비공개 코드를 설명하지 않습니다. CLAUDE_CODE_ENABLE_TELEMETRY=1 및 OTEL_METRICS_EXPORTER=console를 설정한 상태에서 반복 가능한 질문을 맵이 있을 때 3번, 없을 때 3번 실행한 뒤, input 및 cacheRead 유형에 대한 claude_code.token.usage의 중앙값을 비교하십시오.
리팩터링을 하면 그래프는 어떻게 됩니까?
구조는 스스로 다시 파싱합니다. Graft는 작업 트리의 상태를 확인하고 변경된 파일만 다시 파싱하므로, 이름 변경은 다음 쿼리에서 즉시 반영됩니다. 변경 사항이 없을 경우, 이 확인 작업은 0.21.1 버전에서 약 3 ms, 현재 릴리스에서는 수십 ms 정도 소요됩니다. git 기록이 아닌 파일을 직접 읽기 때문에 커밋되지 않은 작업 내용도 파악합니다. 모델이 작성한 요약은 오래될 수 있습니다. 각 노드는 소스의 콘텐츠 해시를 저장하며, 소스가 변경되면 노드는 다시 작성되는 대신 오래된 것으로 표시됩니다. 드리프트 여부를 확인한 뒤(0.21.1 버전은 graft check ., 0.22 버전부터는 graft build --check), graft build --deep를 실행하여 작성된 부분을 새로 고치십시오.
현재 어떤 코딩 에이전트가 Graft를 사용할 수 있습니까?
고정된 0.21.1 버전에서 graft init은 Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent, Google Antigravity 등 총 11개의 호스트를 연결합니다. 변경 로그에는 0.13.0 버전부터 Hermes Agent가 1등급 호스트로 등재되어 있으며, hermes과 antigravity은 고정된 릴리스에서 일반적인 --agents ID입니다. Claude Code는 가장 많은 기능을 지원합니다. .mcp.json의 MCP 서버 항목, 상태 표시줄, 편집 후 훅(post-edit hooks), .claude/ 하위의 스킬 파일이 포함됩니다. Codex는 AGENTS.md 섹션과 ~/.codex/ 하위의 시스템 전체 항목을 지원하며, graft init --no-global는 이를 건너뜁니다. Grok은 스킬 파일과 .grok/config.toml의 MCP 블록을 지원합니다. Hermes Agent와 Antigravity는 AGENTS.md 섹션을 읽으며, 다른 에이전트들은 규칙 또는 제어 파일을 전달받습니다. 다른 MCP 클라이언트는 npx -y @nanonets/graft@0.21.1 mcp 명령을 등록하여 서버를 직접 사용할 수 있습니다.