AI 에이전트의 토큰 소모를 90% 줄이는 코드 그래프: trailhq/Graft 가이드

Q: 기존 AI 코딩 도구와 어떻게 통합하나요?

Claude Code, Cursor 등의 에이전트 설정 문서(AGENTS.md 또는 CLAUDE.md)에 Graft 탐색 수칙을 정의해 두면 에이전트가 탐색 시 자동으로 graft ask 명령어를 활용합니다.

💡 요약

trailhq/Graft는 AI 코딩 에이전트가 코드 전체를 무작위로 검색하며 토큰을 낭비하는 현상을 막아주는 코드베이스 컨텍스트 그래프(Context Graph) 도구입니다. tree-sitter 기반 심볼 파싱과 연결 노드를 통해 에이전트가 단 몇 줄의 핀포인트 정보만으로 원하는 코드를 정확히 찾아 수정하게 돕습니다.

항목	내용
프로젝트명	trailhq/Graft
개발 조직	trailhq (Prime Radiant 팀 지원)
주요 역할	소스 코드 구조·심볼·호출 관계의 사전 인덱싱 및 컨텍스트 제공
특징	100% 로컬 구동 ($0 비용, API Key 불필요), Fail-soft 안전 설계
저장소 주소	https://github.com/trailhq/Graft

1. 기존 AI 탐색 방식의 한계와 Graft의 필요성

대규모 코드베이스에서 AI 코딩 에이전트(Claude Code, Cursor 등)에게 기능을 구현하거나 버그를 수정하도록 요청하면, 에이전트는 파일 목록을 계속 열어보거나 넓은 범위의 Grep 검색을 반복합니다.

토큰 과다 소비: 파일 전체를 읽느라 수십만 토큰이 허무하게 낭비됩니다.
시간 지연: 원하는 함수 위치를 찾을 때까지 수십 차례 툴 호출이 반복됩니다.
파급 효과 파악 불가: A 함수를 수정했을 때 B, C 파일에서 발생하는 파생 영향(Blast Radius)을 미리 알기 어렵습니다.

Graft는 프로젝트의 소스 코드를 사전 분석하여 graft/ 폴더에 경량화된 마크다운 인덱스 노드를 구축합니다. 에이전트는 파일 전체를 열지 않고도 이 그래프 노드를 읽어 필요한 코드 위치와 호출 관계를 즉시 파악합니다.

2. Graft 동작 구조 및 작동 원리

Graft가 프로젝트의 구조를 분석하고 에이전트에게 정보를 전달하는 과정은 아래와 같습니다.

1) 구문 분석 (Parsing)

Tree-sitter를 이용해 소스 코드 내의 함수, 클래스, 구조체 간의 의존 관계와 호출 네트워크를 정밀 분석합니다.

2) 인덱스 생성 (`graft/`)

프로젝트 폴더 내에 graft/ 디렉토리를 생성하고, 코드의 핵심 위치와 줄 번호(file:line span)가 담긴 연결 마크다운 노드를 만듭니다.

3) 핀포인트 검색 명령어 제공

AI 에이전트는 무작위 Grep 대신 아래와 같은 Graft 명령어를 실행하여 필요한 정보만 바로 얻습니다:

graft ask "<질문>": 연관성이 가장 높은 코드의 8줄 핵심(Crux)만 가져옵니다.
graft callers <함수명>: 해당 함수를 호출하는 모든 상위 코드 위치를 추적합니다.
graft skeleton <파일명>: 파일 전체를 읽지 않고 함수 시그니처 구조만 빠르게 파악합니다.

3. 핵심 명령어 및 활용 가이드

프로젝트 루트에 Graft를 설치한 후 에이전트 지침(AGENTS.md)에 규칙을 추가하여 사용합니다.

그래프 인덱스 구축 및 갱신

# 초기 그래프 인덱스 구축 (API 키 불필요, 100% 로컬)
graft build

에이전트 명령어 검색 예시

# 특정 질문에 대한 핵심 코드 위치와 맥락 검색
graft ask "로그인 처리 함수 위치와 호출 구조 알려줘" --source

# 특정 심볼을 호출하는 모든 상위 코드 탐색 (파급 효과 파악)
graft callers handleLogin --direction in

4. 실무 적용 팁

📍 경로 그래프 노드 파일 위치: 프로젝트의 graft/INDEX.md 및 graft/nodes/ 폴더에 색인 데이터가 기록됩니다.

💡 꿀팁 비용 $0로 토큰 절감: 외부 LLM API를 호출하지 않고 로컬 머신에서 정적으로 그래프를 빌드하므로 인덱싱 비용이 발생하지 않습니다.

⚠️ 경고 코드 대규모 변경 후 갱신: 신규 파일 추가나 큰 리팩토링 후에는 graft build를 실행하여 그래프 색인을 최신 상태로 유지합니다.

✅ 체크리스트: Graft 도입 시 점검 항목

graft build 명령어로 프로젝트 인덱싱 수행 확인
AGENTS.md 또는 프로젝트 규칙 문서에 Graft 사용 수칙 포함 여부 확인
graft/ 폴더를 .gitignore에 등록하여 인덱스 파일 중복 관리 방지

자주 묻는 질문 (FAQ)

Q1. Graft는 특정 언어나 프레임워크에 한정되나요?

Tree-sitter를 기반으로 작동하므로 TypeScript, JavaScript, Python, Go, Rust, C/C++ 등 다양한 주요 프로그래밍 언어를 지원합니다.

Q2. 기존 AI 코딩 도구와 어떻게 통합하나요?

Claude Code, Cursor 등의 에이전트 설정 문서(AGENTS.md 또는 CLAUDE.md)에 Graft 탐색 수칙을 정의해 두면 에이전트가 탐색 시 자동으로 graft ask 명령어를 활용합니다.