code-review-graph로 Codex와 Claude Code 코드 리뷰 범위 줄이기

코드 리뷰에서 에이전트가 저장소 전체를 다시 읽기 시작하면 작은 변경도 대화 맥락을 크게 잡아먹습니다. code-review-graph는 Tree-sitter로 코드 구조를 그래프로 저장하고, 변경 파일의 호출자·의존성·테스트를 골라 MCP에 넘깁니다. 이 글은 Codex와 Claude Code 연결 뒤 detect-changes --brief로 검토 범위를 확인하는 경로를 다룹니다.

개요

code-review-graph는 로컬 저장소에 SQLite 그래프를 만들고, 함수·클래스·import·호출 관계를 보관하는 Python CLI입니다. README는 Codex, Claude Code, Cursor, Zed, GitHub Copilot 등 여러 클라이언트의 MCP 설정을 install 명령에서 감지한다고 안내합니다.

저는 단일 파일을 고치는 작업보다 PR에서 호출 관계와 테스트 범위를 함께 찾아야 할 때 이 도구를 먼저 보겠습니다. 앞선 OmniRoute 모델 라우터 구성처럼 모델 연결을 한곳에서 관리하는 도구와 달리, code-review-graph는 에이전트가 읽을 코드 범위를 줄이는 쪽에 집중합니다.

실제 문제 상황

grep과 IDE 검색은 심볼 하나를 찾는 데 빠릅니다. 다만 인증 함수나 공용 타입을 바꾼 PR은 직접 호출자, 간접 의존성, 관련 테스트까지 이어집니다. README의 blast-radius 분석은 이 연결을 그래프에서 추적해 검토 후보 파일을 좁힙니다.

공개 벤치마크의 6개 저장소 수치는 질문당 토큰 감소 중앙값을 약 82배로 제시합니다. 528배는 fastapi 한 저장소의 최대값입니다. 이게 전부 수치입니다. 작은 단일 파일 수정에서는 그래프 메타데이터가 원본 파일 읽기보다 커질 수 있다고 README가 함께 밝힙니다. 숫자는 저장소와 질문마다 달라지는 공개 평가값으로 봐야 합니다.

준비물

Python 3.10 이상과 Git 저장소가 필요합니다. uv가 있으면 MCP 설정은 uvx를 우선 사용하고, 없으면 설치한 CLI 명령을 사용합니다. 설치 명령은 PyPI 패키지 경로만 다룹니다.

pip install code-review-graph
cd <PROJECT_DIR>
code-review-graph install --platform codex
code-review-graph build

Claude Code만 연결할 때는 마지막 전 단계의 플랫폼 값을 claude-code로 바꾸면 됩니다. 여러 클라이언트를 함께 감지하려면 --platform 없이 code-review-graph install을 실행하면 됩니다.

사용 방법

build가 끝나면 저장소 루트에 .code-review-graph/ 데이터가 생깁니다. 작업 중 변경분만 다시 반영할 때는 update --brief, 이미 hook이나 watch가 그래프를 갱신했다면 읽기 전용 detect-changes --brief를 씁니다.

code-review-graph status
code-review-graph detect-changes --brief
code-review-graph update --brief

첫 명령에서 그래프 통계가 나오면 저장소 인덱스가 준비된 상태입니다. 두 번째 명령은 영향 함수, 흐름, 테스트 간격과 Token Savings 패널을 표시합니다. rebase 뒤나 큰 변경 직후에는 update --brief를 실행해주시면 됩니다.

적용 대상

• 여러 패키지와 테스트가 얽힌 PR을 Codex 또는 Claude Code로 검토하는 팀.
• 변경 파일 주변의 호출 관계를 MCP 도구로 확인하려는 개발자.
• 소스 코드를 외부 서비스에 보내지 않고 로컬 SQLite 그래프를 유지하려는 경우.

작은 저장소에서 한 파일만 수정하거나 일회성 심볼 검색만 한다면 grep과 LSP가 더 짧습니다. 언어별 심볼 정확도도 LSP가 더 세밀할 수 있습니다. README는 code-review-graph를 LSP 대체품이 아니라 언어를 가로지르는 구조 그래프로 설명합니다.

확인

아래 명령에서 등록한 플랫폼과 그래프 통계가 표시되면 설치와 인덱스 생성이 끝난 상태입니다.

code-review-graph status

변경분이 있는 저장소에서는 code-review-graph detect-changes --brief를 실행한 뒤 영향 파일과 Token Savings 패널이 나오면 검토 범위를 확인하시면 됩니다.