code-review-graph: AI 코드 리뷰를 더 정확하게, 더 적은 토큰으로

code-review-graph는 AI 코딩 어시스턴트를 위한 오픈소스 도구입니다. 먼저 로컬에서 코드베이스에 대해 구조화된 '지식 그래프(Knowledge Graph)'를 구축한 다음, 실제로 관련된 컨텍스트만 AI에 전달하여 매 작업마다 전체 리포지토리를 풀 스캔하지 않도록 합니다. Tree-sitter를 기반으로 AST를 파싱하여 함수, 클래스, 임포트, 호출 관계 및 테스트 관계를 그래프 구조로 구성하고, MCP를 통해 Claude Code, Codex, Cursor 등 도구에 제공합니다.

해결하는 문제

현재 많은 AI 코딩 도구들이 코드 리뷰, 영향 범위 파악 또는 변경 사항 이해를 위해 전체 코드베이스를 반복적으로 읽어들이는데, 이는 상당한 토큰 낭비와 비용 증가를 초래합니다. 수백 개의 파일이 있는 리포지토리에서 함수 하나만 수정해도 AI가 많은 관련 없는 파일을 다시 스캔해야 하므로 속도가 느려지고 컨텍스트 노이즈가 증가하며 비용이 높아집니다.

code-review-graph의 접근 방식은 '코드 의존 관계'를 미리 모델링하여 AI가 리뷰 시 변경 사항에 실제로 영향을 받는 파일만 읽도록 하고, 추측에 기반한 풀 스캔을 피하는 것입니다. 공식 문서에서는 이 기능을 blast-radius analysis라고 부르며, 즉 '폭발 반경 분석'입니다. 특정 파일이 변경되면 도구는 호출, 상속, 의존성 및 테스트 체인을 따라 추적하여 영향을 받을 수 있는 모든 코드를 찾아냅니다.

작동 방식

도구는 먼저 Tree-sitter를 사용하여 리포지토리를 AST로 파싱하고, 함수, 클래스, 임포트, 호출 지점, 상속 관계 및 테스트 커버리지 등의 구조 정보를 추출한 다음 로컬 SQLite 그래프 데이터베이스에 저장합니다. 리뷰 단계에서 AI는 더 이상 전체 프로젝트를 직접 읽지 않고, 먼저 그래프를 조회하여 최소 컨텍스트 집합을 얻은 후 현재 문제와 직접 관련된 파일과 노드만 읽습니다.
또한 증분 업데이트를 지원합니다. 공식 설명에 따르면 이후 업데이트는 변경된 파일만 다시 파싱하고, 해시 및 의존성 추적을 통해 관련 노드를 갱신합니다. 약 2,900개 파일의 프로젝트에서 재인덱싱은 2초 이내로 제어할 수 있습니다. 이러한 방식은 수만 개의 파일 중에서 실제로 읽어야 할 파일을十几个으로 줄여주기 때문에 monorepo와 같은 대규모 리포지토리에 특히 유용합니다.

지원 플랫폼 및 도구

code-review-graph는 MCP를 통해 다양한 AI 코딩 플랫폼에 통합됩니다. 공식 퀵스타트 및 플랫폼 설명에 나열된 지원 대상은 Claude Code, Codex, Cursor, Windsurf, Zed, Continue, Kiro, OpenCode, Antigravity, Qwen 및 Qoder입니다. 이는 특정 AI 편집기에 국한되지 않고 가능한 많은 코딩 에이전트 또는 AI IDE에 '그래프 컨텍스트' 기능을 연결하는 것을 목표로 합니다.

특정 플랫폼에만 설치하려면 플랫폼 이름을 명시적으로 지정할 수도 있습니다. 예: code-review-graph install --platform codex, code-review-graph install --platform cursor, code-review-graph install --platform claude-code 또는 code-review-graph install --platform kiro.

사용 방법

가장 기본적인 사용 흐름은 간단합니다. 먼저 설치하고, AI 도구에 MCP 구성을 작성한 후, 실제 프로젝트로 돌아와 그래프를 구축합니다.

pip install code-review-graph
code-review-graph install
cd /path/to/your/project
code-review-graph build

여기서 매우 중요하고 혼동하기 쉬운 점이 있습니다. code-review-graph install 은(는) 프로젝트 루트에서 실행하는 '프로젝트 초기화 명령'이 아니라, 본질적으로 전역 구성 명령입니다. 공식 문서에 명확히 나와 있듯이, 이 명령은 사용자 컴퓨터에 설치된 AI 코딩 도구를 자동으로 감지하여 해당 MCP 구성을 작성하고, 그래프 관련 지침을 해당 플랫폼의 규칙 구성에 주입합니다. 실행 후에는 해당 편집기 또는 도구를 다시 시작해야 합니다.

반면에 code-review-graph build 는 프로젝트 루트 에서 실행해야 하는 명령입니다. 공식 설명은 'Then open your project', 즉 AI 어시스턴트가 '이 프로젝트'에 대한 코드 리뷰 그래프를 구축하도록 하는 것입니다. 또한 도구의 무시 파일인 .code-review-graphignore 는 리포지토리 루트에 두어야 하며, 로컬 그래프 데이터는 프로젝트의 .code-review-graph/ 디렉토리에 저장됩니다. 즉, install 은(는) AI 도구에 기능을 연결하는 역할을 하고, build 는 현재 리포지토리에 대해 실제로 그래프를 구축합니다.

독자의 혼란을 방지하기 위해 두 명령의 역할을 직접 대조하여 명확히 설명하겠습니다.

편집기 자체가 hooks를 지원하지 않거나 백그라운드에서 그래프를 최신 상태로 유지하려면 데몬 모드를 사용할 수도 있습니다. 공식 문서에서는 crg-daemon add, crg-daemon start, crg-daemon status 등의 명령을 제공하여 여러 리포지토리를 등록하고 파일 변경을 자동으로 모니터링할 수 있습니다.

자주 사용하는 명령

설치 및 그래프 구축 외에도 공식 문서에서는 비교적 완전한 CLI 기능을 제공합니다.

Slash Commands를 지원하는 도구에서는 다음 명령을 직접 사용하여 해당 워크플로를 호출할 수도 있습니다: /code-review-graph:build-graph, /code-review-graph:review-delta, /code-review-graph:review-pr.

효과

공식 벤치마크는 6개의 실제 오픈소스 리포지토리, 13개의 커밋을 기반으로 평가되었으며, 결과에 따르면 그래프 모드는 naive한 전체 읽기 방식에 비해 토큰 소비를 평균 약 8.2배(1/8 수준)로 줄였습니다. 공개 데이터에서 볼 수 있듯이 리포지토리별 이점이 동일하지는 않지만, 대부분의 중대형 프로젝트에서 상당한 감소폭을 보입니다.

또 다른 주요 지표는 영향 분석 정확도입니다. 공식 결과는 재현율(Recall) 100%, 평균 F1 0.54, 평균 정밀도(Precision) 0.38입니다. 이는 전략적으로 보수적임을 의미합니다. 즉, '영향을 받을 수 있는' 파일을 더 많이 알려주는 방식을 취하여 실제로 변경에 영향을 받는 의존성을 놓치지 않도록 합니다.

하지만 이 방식이 모든 시나리오에서 우세한 것은 아닙니다. 공식 문서는 규모가 작고 변경 사항이 매우 국소적인 프로젝트에서는 그래프 메타데이터 자체의 컨텍스트 오버헤드가 파일을 직접 읽는 비용보다 오히려 클 수 있다고 명시합니다. 예를 들어 express의 단일 파일 변경 테스트에서는 reduction이 0.7x에 불과했습니다. 따라서 가장 적합한 시나리오는 여전히 중대형 프로젝트, 여러 파일 변경, 복잡한 의존 관계 및 빈번한 AI 리뷰 워크플로입니다.

적합한 팀

팀에서 이미 Claude Code, Codex, Cursor 또는 유사한 도구를 일상 개발 프로세스에 통합하고 있고, 프로젝트 규모가 크며 모듈 관계가 복잡하고 PR 리뷰가 빈번하다면 code-review-graph의 가치는 매우 직접적입니다. 이는 본질적으로 코드 리뷰를 대체하는 것이 아니라, AI가 '무엇을 읽어야 하는지'를 먼저 정확하게 파악하도록 도와 이후의 리뷰, 디버깅, 아키텍처 분석 및 온보딩이 더 정확한 컨텍스트 위에서 이루어지도록 하는 것입니다.

개인 프로젝트, 아주 작은 리포지토리 또는 간헐적인 단순 변경의 경우 항상 큰 이점이 있는 것은 아닙니다. 하지만 AI 코딩 비용을 체계적으로 줄이고, 컨텍스트 노이즈를 줄이며, 코드 리뷰의 정확도를 높이려는 팀에게는 이미 실용적인 효과를 보여주고 있습니다.