핵심 요약

• 무엇: Graft — tree-sitter 기반 코드 그래프를 만들어 Claude Code/Codex/Cursor/Gemini 등에 연결하는 컨텍스트 레이어 (MIT, npm @nanonets/graft)
• 누구에게: 큰 저장소에서 Claude Code/Codex를 매일 쓰는데 토큰·시간이 반복 탐색으로 낭비된 개발자
• 검증 결과: 임시 홈에 npm 0.16.0 설치·postinstall 점검·실제 홈 무결성 검증 완료(2026-09-07). 2026-10-08 갱신 때 0.21.1로 재설치해 postinstall·ARM64 동작을 다시 확인했다. 라즈베리파이(ARM64) 호스트에서는 여전히 네이티브 tree-sitter 미지원으로 CLI 실행 불가 — 이슈 #119 오픈 상태
• 보안: 익명 텔레메트리(모든 숫자 버킷 처리, DO_NOT_TRACK=1·graft telemetry disable·init 체크 해제 중 하나로 차단, CI에선 자동 off), ~/.codex/ 사용자 레벨 설정 기입(공개 문서화, --no-global로 회피), API 키 불필요(기본 그래프)
• 대체재: Serena(코드 내비게이션 MCP)·Graphify와 비교, LSP와는 보완 관계

Graft가 해결하는 반복 탐색 문제

Claude Code에 “인증 버그 고쳐줘”라고 하면 에이전트는 먼저 저장소를 탐색한다. grep으로 용어를 찾고, 파일을 열고, import를 따라가고, 다시 빠져나오는 과정을 반복한다. 한 시간 전에 만들었던 지도를 세션마다 버리고 다시 만드는 셈이다. Graft의 README는 이를 “에이전트는 매번 온보딩한다”고 표현한다.

Graft는 이 탐색을 한 번만 수행해 결과를 저장소 안 graft/ 폴더에 마크다운 노드 그래프로 저장한다. 구조 분석은 tree-sitter로 로컬에서 결정적으로 이뤄지며, 기본 그래프 빌드에는 API 키도 네트워크 호출도 없다. 이후 에이전트는 파일을 열어 읽듯 그래프를 읽어 탐색 비용을 건너뛴다.

작동 구조를 단순화하면 다음과 같다.

1. graft build — tree-sitter로 심볼·호출·의존 관계를 추출해 graft/ 폴더에 그래프 생성 (LLM 불필요, 무료)
2. graft init — Claude Code(.claude/), Codex(AGENTS.md), Cursor(.cursor/rules/) 등 각 에이전트의 네이티브 설정 파일에 연결
3. 세션 중 hooks — 프롬프트마다 관련 노드를 컨텍스트로 당기고, 편집 후 그래프를 자동 재동기화

검증 환경과 직접 확인한 사실 (2026-09-07 발행, 2026-10-08 갱신)

수치 표의 각 행에 조회일을 병기했다. 최초 검증은 2026-09-07, 갱신 재검증은 2026-10-08에 공식 저장소·npm·GitHub API에서 직접 수행했다.

임시 홈 격리 설치 검증. 실제 홈의 ~/.claude, ~/.codex, ~/.claude.json, ~/.claude/settings.json 해시를 설치 전후로 비교했다. 격리된 /tmp 홈에 npm 0.16.0 설치 후 네 개 경로 모두 무결성이 유지됐다(UNCHANGED 4/4). postinstall 스크립트(scripts/postinstall.mjs)를 직접 읽었고, 하는 일은 설치 이벤트 기록 한 건뿐임을 확인했다.

ARM64 실행 실패 — 이것이 이 글의 한계고, 0.21.1에서도 그대로다. 이 서버는 라즈베리파이(linux/arm64)다. 최초 검증(0.16.0)과 10-08 갱신 재검증(0.21.1) 모두 설치는 되지만 CLI 첫 실행에서 No native build was found for platform=linux arch=arm64 에러로 중단됐다. 의존성 tree-sitter@0.21.1의 prebuild가 darwin-arm64/darwin-x64/linux-x64/win32-x64만 제공하기 때문이다(이슈 #119 오픈 유지). WASM 폴백을 추가하던 PR #214는 2026-09-29 미머지로 종료됐고, 메인테이너는 문법별 격리 #337과 Windows/Kotlin 설치 수정 #325로 좁게 접근하기로 했다. 즉 linux ARM64 지원은 여전히 미정이다. 따라서 이 글은 설치·설정 파일 구조·제거 절차의 문서 검증까지이고, x64 머신에서의 실제 그래프 빌드·토큰 절감 A/B는 독자가 직접 수행해야 한다.

x64 사용자라면 이렇게 재현한다. 리눅스 x64·macOS·윈도우(WSL 포함)에서는 prebuild가 있어 이 단계가 정상 동작한다.

# 임시 디렉터리에서 먼저 확인 (실제 프로젝트에 영향 없음)
mkdir /tmp/graft-trial && cd /tmp/graft-trial
git init && echo 'console.log(1)' > index.js
DO_NOT_TRACK=1 npm install @nanonets/graft@0.21.1
DO_NOT_TRACK=1 ./node_modules/.bin/graft init --dry-run   # 변경될 파일 목록만 출력
DO_NOT_TRACK=1 ./node_modules/.bin/graft build            # 그래프 생성 (API 키 불필요)

Claude Code·Codex·Hermes 연결 방법

Claude Code (가장 깊은 통합). graft init을 실행하면 감지된 에이전트 목록이 뜨고, 선택한 에이전트의 설정 파일에 기입한다. Claude Code는 .claude/skills/graft/SKILL.md, 프로젝트 .mcp.json에 MCP 서버, statusline, hooks까지 설치된다. 기존 CLAUDE.md은 건드리지 않고 .claude/settings.json도 자기 블록만 병합한다고 문서화돼 있다.

Codex. AGENTS.md에 Graft 섹션을 추가하고, ~/.codex/가 있으면 사용자 레벨 config.toml([mcp_servers.graft]), hooks 파일에도 기입한다. 이 부분은 모든 저장소에 적용되는 machine-wide 변경이므로 --no-global 플래그로 프로젝트 한정으로 설치하는 편이 안전하다.

Hermes 포함 기타 에이전트. 표준 MCP 설정에 수동 등록하면 된다. 어떤 에이전트든 MCP 클라이언트라면 다음 JSON을 설정에 넣는다.

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

MCP로 노출되는 도구는 6개다: graft_find_code(질문→랭킹된 노드), graft_file_api(파일 시그니처만), graft_trace_calls(호출자 추적), graft_find_all(정규식 검색), graft_repo_map(저장소 지도), graft_check_freshness(그래프 신선도).

설치 시 실제로 바뀌는 경로 정리.

제거·원상복구 절차

Graft는 공식 제거 명령을 제공한다. 이 점이 검증 중 인상적이었던 부분이다.

graft uninstall          # 실제 삭제 전에 제거될 항목을 먼저 출력
graft uninstall -y       # 실제 삭제 (init의 역연산)
graft uninstall --no-global   # ~/.codex·~/.gemini 등 저장소 밖 파일은 유지
npm uninstall -g @nanonets/graft   # CLI 자체 제거

uninstall은 init이 기입한 모든 파일과 설정 항목을 역으로 제거한다. --keep-cache로 그래프 캐시만 남길 수도 있다. 임시 검증 환경에서는 rm -rf /tmp/graft-trial로 폴더째 삭제하면 끝난다.

보안·권한·텔레메트리: 숨기지 않는 정보

• 네트워크 호출 3종만 존재 (TELEMETRY.md 공식 계약): 사용자가 설정한 LLM 요청, 하루 1회 npm 버전 확인, 배치 처리된 사용 통계 1건. 코드·파일 경로·저장소명·심볼·쿼리는 전송하지 않으며, 모든 숫자는 버킷(예: “200-999 files”)으로만 전송된다. src/telemetry/contract.ts가 화이트리스트를 강제하고 미등록 속성은 전송 전 차단한다.
• 텔레메트리 차단: DO_NOT_TRACK=1 환경변수, graft telemetry disable 명령, 또는 graft init 프롬프트에서 체크 해제. CI 환경에서는 자동으로 꺼진다.
• postinstall: npm 설치 직후 익명 설치 이벤트 1건을 detached 프로세스로 보낸다. 스크립트 소스를 직접 읽어 확인했고, 설치 실패를 유발하지 않는 구조다.
• 권한 범위: 로컬 파일 읽기·그래프 쓰기가 전부. 데몬·서버 없음. --deep 모드에서만 사용자가 지정한 LLM 제공자로 코드 요약 요청이 나간다(자기 API 키 사용).
• machine-wide 변경 주의: Codex 선택 시 ~/.codex/ 전역 설정이 바뀐다. README가 이를 명시하고 --no-global 회피 경로를 제공하는 것은 투명한 태도다.
• 공급망: OpenSSF Scorecard 배지, TypeScript strict, 34개 npm 버전(10-08 기준), 기여자 다수. 악성코드 징후는 없었다.
• 비용: 도구 자체 무료(MIT). --deep 사용 시 자기 LLM 키 비용 발생.

Serena·Graphify·LSP와 비교: 어떤 관계인가

관계를 명확히 하면: Graft는 grep 반복 탐색에 대한 부분 직접 대체재이고, Serena는 시점 조회형 내비게이션이므로 목적이 겹치는 다른 하위 범주, LSP는 이미 심볼을 아는 경우의 도구라 보완 관계다. Graft 제작사가 HN 스레드에서 공개한 자체 비교로는 Graphify 대비 검색 정확도 MRR 0.73 vs 0.38 — 단 이 역시 자체 측정이다.

안전한 설치 프롬프트 (복사해서 붙여넣으세요)

아래 프롬프트를 Claude Code나 Codex에 붙여 넣으면 안전 절차를 따라 설치를 진행한다. 운영 프로젝트에서 바로 실행하지 말 것.

https://github.com/trailhq/Graft 문서를 읽고 다음 절차로 Graft를 설치해줘.

조건:
1. 버전 고정: @nanonets/graft@0.21.1 (npm 레지스트리에서 조회)
2. 먼저 임시 디렉터리(/tmp/graft-trial)에서 검증한다. 실제 프로젝트는 건드리지 마.
3. DO_NOT_TRACK=1 환경변수로 텔레메트리를 끄고 시작한다.
4. graft init --dry-run 출력을 먼저 보여주고, 내가 승인한 파일만 변경한다.
5. ~/.codex/ 전역 설정은 변경 금지 (--no-global 사용).
6. API 키 입력은 절대 요청하지 마. 기본 그래프 빌드만 수행한다.
7. graft build 결과와 graft check 출력을 보여줘.
8. 검증 후 graft uninstall -y와 npm uninstall로 /tmp/graft-trial을 완전히 정리하고,
   변경 전후 파일 목록을 비교해 원상복구를 확인해줘.

유용한 경우 vs 추천하지 않는 경우

도입을 검토할 만한 상황

• 수백~수천 파일 규모 저장소에서 Claude Code/Codex를 매일 사용한다
• 세션마다 반복 탐색으로 토큰이 급격히 소모된다
• 여러 팀원이 같은 저장소를 에이전트로 다룬다 (wiring만 커밋하면 각자 그래프 생성)
• linux x64·macOS 환경이다

추천하지 않는 상황

• 라즈베리파이 등 linux ARM64 환경 — 현재 실행 불가 (이슈 #119 오픈 중)
• 파일 몇 개짜리 소규모 프로젝트 — 탐색 비용 자체가 작아 이득이 없다
• 제작사 벤치마크 수치를 그대로 보증값으로 받아들이는 용도 — 어디까지나 자체 측정이다
• 텔레메트리가 자동으로 나가는 것이 원칙적으로 거부되는 환경 — 설치 후 즉시 비활성화 필요

설치 전 체크리스트

• [ ] 내 환경이 linux x64 / darwin / win32 인지 확인 (ARM64는 #119 해결 전 불가)
• [ ] git status로 커밋되지 않은 변경사항 정리 (백업)
• [ ] 임시 디렉터리에서 graft init --dry-run 먼저 실행
• [ ] DO_NOT_TRACK=1 설정 여부 확인
• [ ] Codex 전역 변경 원치 않으면 --no-global 플래그 사용
• [ ] --deep 사용 여부 결정 (LLM 키 비용 발생)
• [ ] graft uninstall 시나리오를 미리 dry-run으로 확인

발행 후 4주간 바뀐 것 (0.16.0 → 0.21.1)

CHANGELOG과 커밋 비교(v0.16.0…v0.21.1, 43커밋) 기준으로 핵심 변화만 정리한다. CLI 기본 흐름(설치→init→build→hooks)은 그대로다.

정리하면 로컬 그래프·보안 모델·텔레메트리 계약은 그대로이고, 확장은 대부분 제작사 호스팅 서비스 Trail 연동 쪽이다. Trail 없이 그래프만 쓰는 용법에는 영향이 없다.

직접 검증한 것과 검증하지 못한 것

직접 검증 완료

• npm 0.16.0 격리 설치, postinstall 소스 점검, 실제 홈 4개 경로 해시 무결성 (UNCHANGED 4/4) — 2026-09-07
• LICENSE(MIT), README(42KB), TELEMETRY.md 전문 읽기
• 릴리스 타임라인(0.9.0~0.21.1), 커밋 로그(2026-09-30까지), 이슈 활동 추이 — 2026-10-08 갱신
• 스타 증가 실측: 발행 시점 관측 +178/일 → 갱신 시점 9,704★ (+69%/4주)
• npm 다운로드 공개 API 조회: 월 23,499회 → 104,539회 (10-08)
• HN 토론(39pts/44댓글) 원문 확인, 제작자 응답 포함

검증하지 못한 것 (독자 과제)

• x64 환경에서의 실제 그래프 빌드·CLI 동작 (ARM64 호스트 한계)
• 토큰 42% 절감 재현 — 제작사 자체 벤치마크이므로 독자의 프로젝트에서 A/B 필요
• --deep 모드의 LLM 요약 품질과 비용
• 자체 저장소에서의 graft viz 시각화 품질

FAQ

Graft는 무료인가?

도구 자체는 MIT 라이선스 무료다. 기본 그래프 빌드는 API 키 없이 로컬에서 돈다. --deep 모드로 LLM 요약을 추가할 때만 자신의 API 키 비용이 발생한다.

정말 토큰이 42% 절감되나?

그 수치는 제작사가 162회 자체 벤치마크와 SWE-bench Verified 50케이스로 측정한 자체 발표 값이다. SWE-bench 결과(정확도 54%→66%)는 공식 채점기를 썼다고 명시하지만, 독립 검증은 아니다. 자기 프로젝트에서 같은 커밋·같은 작업으로 A/B 테스트하는 것이 가장 정확하다.

ARM64 맥(애플 실리콘)에서도 안 되나?

darwin-arm64 prebuild는 존재한다. 안 되는 것은 linux/arm64 조합뿐이다(라즈베리파이, ARM 리눅스 서버, ARM 도커 이미지). 단 WASM 폴백 PR #214는 09-29 미머지 종료됐고 후속(#337·#325)도 아직 열려 있으니, 해결 시점은 예약하지 않는 편이 맞다.

기존 CLAUDE.md이나 설정이 덮어써지진 않나?

README 명세상 Graft는 자체 섹션만 추가·갱신하고 기존 내용은 건드리지 않는다. statusLine도 Graft 것이 아닌 기존 설정은 그대로 둔다고 문서화돼 있다. 그래도 도입 전 git add로 백업하자.

Serena와 Graft 중 무엇을 쓰야 하나?

이미 심볼 이름을 알고 정의·참조를 추적한다면 Serena(LSP 기반)면 충분하다. “인증이 어디서 처리되나” 같은 개념 질의와 대형 저장소 오리엔테이션이 필요하면 Graft가 목적에 맞다. 둘은 경쟁보다 하위 범주가 다른 관계다.

이제 한국어 글도 많던데, 이 글의 차이는?

발행 당시엔 국내 소개 글이 없었지만 지금은 개념 소개·설치 안내 글이 여러 개 있다. 이 글의 차이는 셋이다. 임시 홈 격리 설치로 postinstall과 실제 홈 무결성을 직접 검증했다는 점, ARM64 미지원을 버전을 바꿔가며 두 번 재현했다는 점, 제작사 벤치마크를 자체 측정으로 명시하고 한계를 분리했다는 점이다.

제거는 깨끗한가?

graft uninstall -y가 init의 역연산을 수행한다. dry-run으로 삭제 목록을 먼저 볼 수 있어 안전하다. npm 전역 설치라면 npm uninstall -g @nanonets/graft로 마무리한다.

공식 참고자료

• Graft 저장소: https://github.com/trailhq/Graft
• npm 패키지: https://www.npmjs.com/package/@nanonets/graft
• 텔레메트리 문서(TELEMETRY.md): https://github.com/trailhq/Graft/blob/main/TELEMETRY.md
• ARM64 이슈 #119: https://github.com/trailhq/Graft/issues/119
• CHANGELOG (0.9.0~0.21.1): https://github.com/trailhq/Graft/blob/main/CHANGELOG.md
• HN 토론 원문: https://news.ycombinator.com/item?id=49299985
• Agent Skills 사양: https://agentskills.io/home

The post Claude Code가 매번 코드를 다시 읽는 문제, Graft로 끊기: 설치·보안·제거 직접 검증 appeared first on .