graft로 저장소 컨텍스트 탐색하기
graft는 저장소를 미리 인덱싱해 둔 컨텍스트 그래프입니다. 코드를 이해하거나, 어디서 무엇을 고쳐야 할지 찾거나, 변경의 영향 범위를 파악할 때 grep이나 파일을 직접 여는 대신 graft에 먼저 물어보면 훨씬 적은 토큰으로 정확한 file:line 위치를 얻을 수 있습니다.
- graft란 무엇이고 왜 필요한가
- grep/파일 읽기 대신 graft를 먼저 써야 하는 이유
- 핵심 명령어 5가지 (ask, grep, skeleton, callers, map)
- MCP 도구로 graft 사용하기 (지원 환경)
- 실전 워크플로우 예시
- 코드 변경 후 그래프 갱신하기
1. graft란 무엇인가
graft는 저장소를 스캔하여 파일마다 "이 파일이 뭘 하는지, 어떤 심볼을 정의하는지, 누가 호출하는지"를 정리한 작은 마크다운 노드들의 그래프를 만들어 두는 도구입니다. 이 그래프는 graft/ 디렉토리에 저장되며, 코드가 바뀔 때마다 git과 함께 갱신됩니다.
graft는 두 가지 방식으로 쓸 수 있습니다:
- CLI — 터미널에서
graft <subcommand>형태로 직접 실행 - MCP 도구 — 호스트(Claude Code 등)가
graft_find_code,graft_find_all,graft_trace_calls,graft_file_api,graft_repo_map같은 도구를 노출하는 경우, 같은 그래프를 도구 호출로 조회
2. 왜 grep 대신 graft인가
| 상황 | grep / 파일 직접 읽기 | graft |
|---|---|---|
| "이 기능이 어떻게 동작하지?" | 관련 파일을 추측해 여러 개 열어봐야 함 | graft ask가 코드 스니펫이 포함된 순위 결과를 즉시 반환 |
| "이 심볼을 누가 호출하지?" | 문자열 검색 + 수동 대조 (오탐 많음) | graft callers가 정확한 호출 관계를 그래프에서 바로 조회 |
| "이 패턴이 나오는 곳을 전부 찾아줘" | grep -rn으로 가능하지만 결과가 정리되지 않음 | graft grep이 감싸는 심볼별로 그룹화해서 보여줌 |
| "이 파일의 API 전체를 훑어보고 싶다" | 파일 전체를 읽어야 함 (토큰 소모 큼) | graft skeleton이 시그니처만 ~10배 저렴하게 제공 |
| "처음 보는 저장소, 어디서 시작하지?" | README를 읽고 폴더를 하나씩 열어봄 | graft map이 디렉토리 클러스터·허브·핫스팟을 토큰 예산 안에서 요약 |
3. 핵심 명령어
3.1 graft map — 낯선 저장소 오리엔테이션
처음 보는 저장소에서 가장 먼저 실행합니다. LLM 호출 없이(비용 $0) 디렉토리 구조, 허브 파일, 핫스팟을 토큰 예산 안에서 보여줍니다.
graft map주의: map은 그 자체로 오리엔테이션 답입니다. map이 언급한 모든 하위 시스템을 이어서 skeleton으로 훑는 것은 과도한 사용입니다.
3.2 graft ask — 이해하거나 수정할 위치 찾기
"이게 어떻게 동작하지?", "이 코드는 어디에 있지?" 같은 질문에 코드 스니펫이 포함된 순위 결과를 반환합니다.
graft ask "로그인 실패 시 재시도 로직이 어떻게 동작하나" --source--source— 각 결과에 핵심 코드(기본 8줄)를 함께 표시--full— 8줄로 부족할 때 전체 정의를 표시- 이해·수정 작업이면 1위 결과가 곧 답입니다.
covers:에 명시된 file:line을 인용하고--source결과에서 바로 수정하세요.
3.3 graft grep — 전수 검색
리터럴 문자열이나 심볼의 모든 출현 위치를, 이를 감싸는 심볼 단위로 그룹화하여 보여줍니다.
graft grep "processPayment"인덱싱되지 않은 파일까지 봐야 한다면 그때만 원시 grep -rn으로 보완합니다.
3.4 graft skeleton — 파일 API 한눈에 보기
파일 전체를 읽지 않고도 모든 정의의 시그니처와 위치를 ~10배 저렴하게 확인합니다. API 표면을 훑어볼 때 유용합니다.
graft skeleton src/services/payment.ts3.5 graft callers — 정확한 호출 관계 추적
어떤 심볼을 바꾸기 전에 그것을 누가 호출하는지(또는 그것이 무엇을 호출하는지) 정확하게 파악합니다. 리팩터링이나 이름 변경 전에는 반드시 실행하세요.
# 이 심볼을 호출하는 곳 (기본)
graft callers formatCurrency
# 이 심볼이 호출하는 것들
graft callers formatCurrency --direction out
# 전체 영향 범위 (연결된 모든 파일)
graft callers formatCurrency --depth allgraft callers <symbol> --depth all로 연결된 모든 파일을 먼저 지도화한 뒤 수정하세요.
4. MCP 도구로 사용하기
Claude Code 같은 호스트 환경에서는 같은 그래프를 CLI 대신 MCP 도구 호출로 조회할 수 있습니다. 대응 관계는 다음과 같습니다:
| CLI 명령어 | MCP 도구 |
|---|---|
graft ask | graft_find_code |
graft grep | graft_find_all |
graft callers | graft_trace_calls |
graft skeleton | graft_file_api |
graft map | graft_repo_map |
graft callers / graft_trace_calls가 이런 엣지를 읽는 유일한 방법입니다.
5. 실전 워크플로우
처음 접하는 프로젝트라면 graft map으로 전체 구조를 먼저 파악합니다.
이해·수정이면 ask --source, 전수 조사면 grep, API 훑기면 skeleton, 영향 범위 파악이면 callers를 씁니다.
ask --source가 반환한 file:line과 코드 스니펫을 그대로 인용하며 수정합니다. 결과가 잘려 있으면(+N more lines) 그 정확한 범위만 파일에서 열어 확인합니다.
코드를 크게 바꾼 뒤에는 graft build로 그래프를 최신 상태로 맞춥니다.
6. 그래프 갱신 (graft build)
graft 그래프는 결정론적으로 생성되며, LLM API 키 없이 무료로 갱신할 수 있습니다. 대규모 코드 변경(새 파일 추가, 대규모 리팩터링 등) 이후에는 그래프를 다시 빌드하여 최신 상태를 유지합니다.
graft buildnew-project.ts)는 스캐폴딩 과정에서 graft 그래프가 자동으로 빌드됩니다. 전역 설치된 graft 명령을 먼저 사용하고, 없으면 bunx로 대체 실행합니다. 즉 새로 만든 프로젝트는 처음부터 graft ask로 질문할 수 있습니다.