code-review-graph: 지식 그래프로 Claude Code 토큰을 줄이는 법

Claude Code를 대규모 코드베이스에서 사용할 때 급격히 증가하는 토큰 소비를 로컬 지식 그래프로 억제하는 code-review-graph 프로젝트가 실용적인 비용 절감 솔루션으로 주목받고 있다. 대형 레포지토리에서 코드 리뷰나 기능 구현을 요청할 때 Claude Code가 불필요하게 방대한 코드 컨텍스트를 매번 API에 전송하는 비효율 문제를, 로컬에서 미리 구축한 코드 의존성 그래프와 선택적 컨텍스트 검색으로 해결하는 접근 방식이다. 월 수십만 원에 달하는 Claude Code 비용을 고민하는 개발팀에게 즉각적인 실용 가치를 제공한다.

대형 레포에서 컨텍스트가 부풀어 오르는 방식

code-review-graph는 Claude Code(및 Claude API를 사용하는 코딩 에이전트)의 토큰 효율성을 높이기 위해 코드베이스를 사전에 그래프 구조로 인덱싱하고, 실제 요청 시 관련성 높은 코드 스니펫만 선택적으로 컨텍스트에 포함시키는 도구다. 핵심 아이디어는 단순하지만 강력하다. 특정 함수를 수정하거나 버그를 분석할 때 10만 줄짜리 코드베이스 전체를 컨텍스트에 넣는 대신, 해당 함수와 직접 관련된 의존성(호출하는 함수, 호출되는 함수, 공유 타입, 관련 테스트)만 정밀하게 추출해 제공하는 것이다.

프로젝트는 네 가지 목표를 명시한다. 불필요한 코드를 컨텍스트에서 제거해 API 비용을 절감하는 토큰 소비 60-80% 감소, 핵심 컨텍스트에 집중해 AI의 주의가 분산되지 않도록 하는 응답 품질 유지 또는 향상, 변경된 파일만 재인덱싱해 대형 레포지토리에서도 빠른 업데이트가 가능한 증분 업데이트, VSCode·JetBrains·Vim 등 편집기에 무관하게 CLI 도구로 동작하는 IDE 독립성이다.

Claude Code는 사용자 요청을 처리할 때 코드베이스의 관련 파일들을 자동으로 읽고 컨텍스트에 포함시키는데, 이 자동 컨텍스트 수집 기능이 대형 레포지토리에서는 두 가지 문제를 일으킨다고 프로젝트는 지적한다. 파일 탐색 전략이 보수적으로 설계되어 있어 실제 필요한 파일보다 훨씬 많은 파일을 컨텍스트에 포함하는 경향(예: 한 파일을 수정하는 단순한 요청에도 그 파일을 임포트하는 수십 개 파일이 모두 컨텍스트에 포함될 수 있다는 것)과, 특정 클래스의 메서드를 수정할 때 해당 클래스가 포함된 파일 전체가 컨텍스트에 들어가지만 실제 관련성 있는 부분은 전체 파일의 10-20%에 불과한 경우가 많다는 것이다. 또한 파일 시스템 탐색과 관련 파일 식별 과정이 매 요청마다 반복되며 토큰을 소비하는데, 이 정보는 코드가 변경되지 않는 한 동일하므로 로컬에 캐싱하면 반복 비용을 완전히 제거할 수 있다.

지식 그래프로 컨텍스트를 미리 구조화하기

지식 그래프는 엔티티(노드)와 엔티티 간의 관계(엣지)로 정보를 표현하는 구조다. 코드베이스 맥락에서는 함수, 클래스, 모듈, 파일이 노드가 되고, "호출한다", "임포트한다", "상속한다", "테스트한다" 등의 관계가 엣지가 된다.

⤢✕

이 구조를 로컬에 미리 구축해두면, 특정 함수를 수정해달라는 요청이 들어왔을 때 그래프 쿼리로 즉시 관련 노드를 식별하고 필요한 코드만 추출할 수 있다. code-review-graph는 코드베이스를 분석해 함수 호출 관계(정적 분석으로 직접 호출과 인터페이스를 통한 간접 호출을 구분), 임포트/의존성 관계(순환 의존성은 별도 플래그로 표시), 타입 관계(TypeScript/Python 타입 어노테이션 분석), 테스트 커버리지 관계(테스트 파일이 어떤 소스 파일/함수를 테스트하는지 매핑), 커밋 동시 변경 관계(Git 히스토리에서 자주 함께 변경되는 파일 쌍을 식별해 정적 분석으로 잡히지 않는 암묵적 결합을 파악)를 추출해 그래프에 저장한다.

인덱싱 파이프라인은 이렇게 돈다

⤢✕

파싱 레이어로는 tree-sitter를 채택해 Python, TypeScript, JavaScript, Go, Rust, Java 등 주요 언어를 지원한다. tree-sitter는 언어마다 문법 규칙을 정의하면 AST를 생성해주는 파서 라이브러리로, 코드가 불완전하거나 에러가 있어도 부분적으로 파싱이 가능한 오류 내성 특성을 갖는다. 의존성 추출 후에는 각 코드 섹션(함수, 클래스 메서드)에 대해 임베딩을 생성해 벡터 인덱스에도 저장하고, 그래프 기반 구조적 검색과 임베딩 기반 의미적 검색을 결합해 더 정확한 관련 코드 식별이 가능하다.

그래프 DB, 규모에 맞게 고르기

code-review-graph는 기본 백엔드로 Kuzu를 사용한다. Kuzu는 임베디드 그래프 데이터베이스로, 별도 서버 프로세스 없이 로컬 파일로 동작한다. SQLite의 그래프 버전으로 이해할 수 있으며, 설치와 운용이 단순하다. 대규모 엔터프라이즈 코드베이스의 경우 Neo4j 백엔드도 지원하며, 이 경우 Docker Compose로 로컬에 Neo4j 인스턴스를 실행해 연결한다.

백엔드	적합한 규모	설정 복잡도	쿼리 성능
Kuzu (기본)	100만 줄 이하	낮음	중간
Neo4j	100만 줄 이상	높음	높음
SQLite (경량)	10만 줄 이하	매우 낮음	낮음

요청이 들어오면 컨텍스트를 찾는 순서

요청이 들어오면 code-review-graph는 다음 순서로 관련 컨텍스트를 수집한다. 먼저 요청에 언급된 함수명, 클래스명, 파일명을 식별해 그래프에서 해당 노드를 조회하는 직접 참조 노드 수집이 일어나고, 직접 참조 노드와 엣지 하나로 연결된 노드들(호출하는 함수, 호출되는 함수, 사용되는 타입 등)을 수집하는 1-hop 의존성 확장이 이어진다. 이후 수집된 노드들에 대해 요청 텍스트와의 의미적 유사도(임베딩 거리), 그래프 중심성(PageRank 변형), 최근 수정 여부를 종합해 관련성 점수를 계산하고, 마지막으로 토큰 예산(기본 32K 토큰)을 설정해 관련성 점수가 높은 코드 섹션부터 예산이 소진될 때까지 컨텍스트에 포함시키는 컨텍스트 예산 할당이 이뤄진다.

Claude Code와 연결하는 방식

code-review-graph는 Claude Code와 두 가지 방식으로 통합된다. MCP 서버 모드는 code-review-graph를 MCP 서버로 실행하면 Claude Code가 컨텍스트 검색 도구를 직접 호출할 수 있게 하는 방식으로, Claude Code가 파일 탐색을 시작하기 전에 code-review-graph의 search_context 도구를 먼저 사용해 관련 코드를 가져오도록 CLAUDE.md에 지시를 추가하는 방식으로 동작한다. 프록시 모드는 Claude API 호출을 가로채는 프록시 서버로 실행해, 요청에 포함된 컨텍스트를 자동으로 최적화한 후 실제 API에 전달한다. 이 방식은 Claude Code의 설정 변경 없이 투명하게 동작한다.

기본 사용 흐름은 다음과 같다. 프로젝트 루트에서 crg index 명령을 실행하면 코드베이스 전체를 분석해 .crg/ 디렉토리에 그래프 인덱스를 생성하며, 100만 줄 규모의 코드베이스 기준으로 초기 인덱싱은 약 10-20분이 소요된다. Git pre-commit 훅이나 파일 감시 데몬을 통해 변경된 파일만 자동으로 재인덱싱하는 증분 업데이트는 일반적인 커밋 기준으로 수 초 이내에 완료된다. CLAUDE.md에는 다음과 같은 지시를 추가해 Claude Code가 code-review-graph를 우선 활용하도록 안내한다.

코드 관련 작업 시작 전에 반드시 crg_search 도구를 사용하여
관련 컨텍스트를 먼저 수집한 후 작업하세요.
불필요한 파일 전체 읽기를 최소화하세요.

실측 효과: 토큰이 얼마나 줄었나

프로젝트 GitHub에서 공개한 벤치마크에 따르면, 50만 줄 이상의 대형 레포지토리에서 코드 리뷰 요청은 평균 입력 토큰 68% 감소, 버그 분석 요청은 71% 감소, 기능 구현 요청은 54% 감소(새로운 패턴 도입이 필요한 경우 감소폭 축소)라는 개선이 확인되었다. 비용 절감 효과는 코드베이스 규모에 따라 크게 차이난다. 10만 줄 미만의 소형 프로젝트에서는 효과가 제한적이지만, 50만 줄 이상의 대형 레포지토리에서는 Claude API 비용을 50% 이상 절감하는 사례가 보고되고 있다.

토큰 감소와 함께 응답 품질도 개선되는 경향이 관찰된다. 불필요한 코드가 컨텍스트에 없을 때 Claude가 관련 코드에 더 집중해 더 정확한 수정안을 제안한다는 것이 사용자들의 공통된 피드백이다. 특히 복잡한 의존성이 있는 리팩토링 작업에서 컨텍스트 품질 향상의 효과가 두드러진다.

한계와 주의사항

Python, JavaScript 등 동적 언어에서는 정적 분석만으로 모든 의존성을 정확히 파악하기 어렵다. 덕 타이핑, 동적 임포트, 메타프로그래밍 등을 사용하는 코드에서 일부 관계가 누락될 수 있다. 코드가 자주 변경되는 활발한 개발 중에는 인덱스가 일시적으로 부정확해질 수 있어 증분 업데이트 주기를 적절히 설정하여 인덱스 신선도를 유지해야 한다. 도구 설치, 초기 인덱싱, Claude Code 연동 설정에도 일정 시간이 필요해, 소규모 단기 프로젝트보다는 장기적으로 유지되는 대형 프로젝트에서 ROI가 높다.

code-review-graph는 Claude Code의 토큰 소비 최적화를 위한 실용적인 접근으로, 대형 코드베이스를 다루는 개발팀에게 의미 있는 비용 절감과 응답 품질 향상을 제공한다. 로컬 지식 그래프라는 검증된 기술을 AI 코딩 도구에 연결하는 방식은 단순하지만 효과적이며, Claude Code 비용이 부담으로 느껴지기 시작하는 팀이라면 도입을 검토할 가치가 있다.