서론 (Introduction)

"토큰을 낭비하는 것을 멈추고, 더 스마트하게 리뷰를 시작하세요."

이 글은 "하루에 하나의 오픈 소스 프로젝트 (One Open Source Project a Day)" 시리즈의 126번째 기사입니다. 오늘의 프로젝트는 code-review-graph입니다. 이 도구는 코드베이스의 지속적인 구조적 지도 (structural map)를 구축하고, MCP를 통해 AI 코딩 도구에 정밀한 컨텍스트 (context)를 전달하는 로컬 우선 (local-first) 도구입니다.

AI 코딩 에이전트들은 코드 리뷰 과정에서 숨겨진 비효율성을 가지고 있습니다. 그들은 "내가 이 함수를 변경하면, 다른 무엇이 망가질까?"라는 질문에 답을 알지 못합니다. 그래서 컨텍스트를 구축하기 위해 코드베이스의 방대한 부분을 읽거나, grep에 의존하며 운에 맡기곤 합니다. code-review-graph의 해결책은 다음과 같습니다. 구조적 그래프 (함수, 클래스, 호출 엣지 (call edges), 상속, 테스트 커버리지)를 미리 구축한 다음, 리뷰 시점에 그래프를 쿼리하여 변경 사항의 "영향 범위 (blast radius)"를 계산하고, 실제로 중요한 파일들만 AI에게 제공하는 것입니다.

벤치마크: 중앙값 기준 약 82배의 토큰 절감. 최상의 경우 528배 절감.

19,762 Stars. 2026년 2월 생성. 14개의 AI 코딩 플랫폼 지원.

학습 내용

• 영향 범위 (blast-radius) 분석의 작동 원리: 변경된 파일에서 호출자 (callers), 의존성 (dependents), 그리고 테스트로의 추적
• 전체 아키텍처: Tree-sitter AST → SQLite 그래프 → MCP 도구 체인
• 증분 업데이트 (incremental update) 메커니즘: 왜 2,900개의 파일이 있는 저장소가 2초 이내에 재인덱싱되는지
• 3단계 엣지 신뢰도 점수 (EXTRACTED/INFERRED/AMBIGUOUS) 및 그 의미
• 벤치마크 수치에 대한 정직한 해석: 528배는 최상의 경우이며, 중앙값이 아님

사전 요구 사항

• Claude Code 또는 기타 AI 코딩 도구에 대한 기본적인 경험
• MCP (Model Context Protocol)에 대한 익숙함
• 정적 분석 (static analysis) 및 호출 그래프 (call graphs)에 대한 기본 이해

프로젝트 배경 (Project Background)

개요 (Overview)

code-review-graph (CRG)는 네 가지 핵심 기능을 가진 로컬 우선 코드 인텔리전스 도구입니다:

1. Tree-sitter를 사용하여 코드베이스를 함수, 클래스, 임포트(import), 호출 관계(call relationships)의 그래프로 파싱(Parse)합니다.
2. 그래프를 .code-review-graph/ 내의 SQLite 파일로 저장합니다 — 네트워크 의존성이 전혀 없습니다.
3. 30개의 MCP 도구를 노출하여 AI 어시스턴트가 "이 변경 사항이 무엇에 영향을 미치는가?"라고 질의할 수 있게 합니다.
4. 증분 업데이트(incremental updates)를 지원합니다 — 변경 사항이 발생하면 수정된 파일만 다시 파싱합니다.

저자 / 팀 (Author / Team)

• 저자 (Author): tirth8205
• 언어 (Language): Python 3.10+
• 라이선스 (License): MIT
• 버전 (Version): v2.3.6
• 웹사이트 (Website): code-review-graph.com

프로젝트 통계 (Project Stats)

• ⭐ GitHub Stars: 19,762+
• 🍴 Forks: 2,107+
• 📄 라이선스 (License): MIT
• 📅 생성일 (Created): 2026년 2월 26일

기능 (Features)

빠른 시작 (Quick Start)

pip install code-review-graph        # 또는: pipx install code-review-graph
code-review-graph install            # 플랫폼 자동 감지 및 MCP 설정 작성
code-review-graph build              # 코드베이스 파싱 및 그래프 구축

세 가지 명령어로 충분합니다. install은 사용자의 머신에 있는 모든 AI 코딩 도구를 감지하고, 각 도구에 맞는 정확한 MCP 설정을 작성하며, 플랫폼 규칙 파일에 그래프 인식(graph-aware) 지침을 주입하고, 플랫폼 네이티브 훅(hooks)/스킬(skills)을 설치합니다. 에디터를 재시작한 후, AI에게 다음과 같이 요청하세요:

Build the code review graph for this project

초기 구축: 500개 파일 규모의 프로젝트 기준 약 10초 소요. 이후에는 증분 방식으로 진행됩니다.

플랫폼 지원 (Platform Support)

한 번의 설치로 14개 플랫폼을 지원합니다: Codex, Claude Code, CodeBuddy Code, Cursor, Windsurf, Zed, Continue, OpenCode, Antigravity, Gemini CLI, Qwen, Qoder, Kiro, GitHub Copilot.

특정 타겟 설치:

code-review-graph install --platform claude-code
code-review-graph install --platform cursor
code-review-graph install --platform codex

토큰 절감 패널 (Token Savings Panel)

┌─────────────────────── Token Savings ────────────────────────┐
│ 전체 컨텍스트 (Full context) 예상:     12,921 tokens                     │
│ 사용된 그래프 컨텍스트 (Graph context used):           762 tokens                     │
...

detect-changes --brief 또는 update --brief로 출력되었습니다. OpenAI의 cl100k_base 토크나이저(tokenizer)와 교차 확인하려면 --verify를 추가하세요. 실제 토큰 수와 비교했을 때 추정치는 실무적으로 약 1% 이내의 오차를 유지합니다.

심층 분석 (Deep Dive)

핵심 아키텍처 (Core Architecture)

Repository
    │
    ▼ git ls-files (추적 중인 파일만 인덱싱됨)
...

그래프 노드 (Graph nodes): 함수 (functions), 클래스 (classes), 파일 (files), 모듈 (modules)
그래프 엣지 (Graph edges): 호출 관계 (call relationships), 임포트 관계 (import relationships), 상속 (inheritance), 테스트 커버리지 (test coverage)

영향 범위 분석 (Blast-Radius Analysis)

핵심 개념입니다. 파일이 변경될 때:

변경 된 파일 (예: auth/login.py 내의 login())
    ↓
그래프 쿼리: 어떤 함수가 login()을 직접 호출하는가?
...

AI는 전체 코드베이스를 스캔하는 대신, 이 최소한의 세트만을 읽습니다.

정확도 참고 사항 (README에서 매우 솔직하게 기술됨):

• 현재 재현율(recall)=1.0은 **그래프에서 도출된 상한선 (graph-derived upper bound)**입니다. 정답(ground truth)이 예측기가 탐색하는 것과 동일한 그래프 엣지에서 나오기 때문에, 측정 방식 자체가 순환적(circular)입니다.
• "공동 변경 모드 (Co-change mode)"는 작성자가 동일한 커밋에서 실제로 함께 편집한 파일들을 기준으로 평가합니다. 이는 그래프가 아닌 git 히스토리로부터 얻은 독립적인 증거이며, 이 경우 수치가 상당히 낮게 나타날 것입니다.
• 영향 범위 분석은 의도적으로 보수적입니다. 깨진 의존성(dependency)을 놓치는 것보다 추가적인 파일을 더 많이 식별하는 것이 낫기 때문입니다.

증분 업데이트 (Incremental Updates): 2초 미만

파일 저장 (hook 실행 / watch 모드 / crg-daemon)
    │
    ▼
...

3단계 엣지 신뢰도 (Three-Tier Edge Confidence)

그래프 엣지는 신뢰 수준을 포함합니다:

이를 통해 AI는 쿼리 시 신뢰도에 따라 필터링할 수 있으며, 동적 타이핑 (dynamically-typed) 코드에서 저품질 엣지로 인해 발생하는 잘못된 경고를 방지할 수 있습니다.

30개의 MCP 도구 (30 MCP Tools)

용도별로 구성되어 있습니다:

컨텍스트 검색 (코드 리뷰 핵심 기능)

• get_minimal_context_tool — 초소형 컨텍스트 (ultra-compact context), 약 100 토큰, 가장 먼저 호출할 것
• get_impact_radius_tool — 변경된 파일의 영향 범위 (blast radius)
• get_review_context_tool — 구조적 요약이 포함된 토큰 최적화 리뷰 컨텍스트 (token-optimized review context)
• detect_changes_tool — 위험 점수가 부여된 변경 영향 분석 (risk-scored change impact analysis)

그래프 쿼리 (Graph queries)

• query_graph_tool — 호출자 (callers), 피호출자 (callees), 테스트 (tests), 임포트 (imports), 상속 (inheritance) 쿼리
• traverse_graph_tool — 토큰 예산 내에서 임의의 노드로부터 자유 형식의 BFS/DFS 수행
• semantic_search_nodes_tool — 이름 또는 의미에 따른 코드 엔티티 검색 (선택적 임베딩 (embeddings) 필요)

아키텍처 분석 (Architecture analysis)

• get_architecture_overview_tool — 커뮤니티 구조로부터 자동 생성된 아키텍처 맵
• get_hub_nodes_tool — 가장 연결성이 높은 노드 (아키텍처 핫스팟)
• get_bridge_nodes_tool — 매개 중심성 (betweenness centrality)을 통한 병목 지점 (chokepoints)
• get_surprising_connections_tool — 예상치 못한 커뮤니티 간 결합 (cross-community coupling)
• get_knowledge_gaps_tool — 고립된 노드, 테스트되지 않은 핫스팟, 구조적 약점

기타 (Other)

• refactor_tool — 이름 변경 미리보기, 데드 코드 (dead code) 탐지
• generate_wiki_tool — 커뮤니티 구조를 기반으로 한 Markdown 위키 생성
• cross_repo_search_tool — 등록된 모든 리포지토리 (repos)에 걸친 검색

토큰이 제한된 환경에서는 필요한 것만 노출하세요:

code-review-graph serve --tools query_graph_tool,detect_changes_tool,get_review_context_tool

언어 지원 범위 (Language Coverage)

40개 이상의 언어 및 형식 지원: Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Elixir, Zig, Vue/Svelte SFCs, Jupyter/Databricks notebooks (.ipynb), Terraform, Ansible 등.

지원되지 않는 언어의 경우, 포크(fork)나 코드 변경 없이 .code-review-graph/ 디렉토리에 languages.toml 파일을 추가하면 됩니다:

[languages.erlang]
extensions = [".erl"]
grammar = "erlang"
...

CI 통합: GitHub Action

on:
  pull_request:

...

그래프는 CI 러너(runner) 상에서 완전히 구축되고 쿼리됩니다. 어떠한 소스 코드도 외부 서비스로 전송되지 않습니다. 각 PR(Pull Request)에 위험 점수(risk-scored)가 포함된 고정 댓글을 게시하며, 푸시(push)가 발생할 때마다 해당 위치에서 업데이트됩니다. 선택 사항인 fail-on-risk 입력을 사용하면 리뷰를 머지 게이트(merge gate)로 전환할 수 있습니다.

멀티 레포 데몬 (Multi-Repo Daemon)

crg-daemon add ~/project-a --alias proj-a
crg-daemon add ~/project-b
crg-daemon start
...

훅(hooks)을 지원하지 않는 에디터(Cursor, OpenCode 등)를 위한 기능입니다. 백그라운드에서 여러 레포지토리(repository)를 감시하며, 30초마다 상태 체크(health-check)를 수행하고, 중단된 감시 프로세스를 자동으로 재시작합니다. 설정은 ~/.code-review-graph/watch.toml에 유지됩니다.

벤치마크 수치 — 솔직한 분석

README는 벤치마크 수치를 이례적일 정도로 솔직하게 다룹니다:

전체 코퍼스(whole-corpus) 기준선은 실제 에이전트(agent)가 지불하지 않는 상한선입니다. 유능한 에이전트라면 식별자(identifier)를 grep으로 검색하고 가장 잘 일치하는 파일만 읽을 것입니다. agent_baseline 벤치마크는 이 더 현실적인 기준선—순수 파이썬(pure-python) grep, 매칭 횟수 기준 상위 3개 파일—을 측정하며, 이 비교가 가장 솔직한 비교입니다.

작은 단일 파일 변경의 경우, 그래프 컨텍스트(graph context)가 단순 파일 읽기보다 더 클 수 있습니다(구조적 메타데이터 오버헤드가 파일 내용보다 더 큼). 실험 결과가 이를 보여줍니다. README는 이를 숨기지 않고 명시하고 있습니다.

관련 도구와의 비교

리소스 (Resources)

공식 링크 (Official Links)

리소스 (Resources)

공식 링크 (Official Links)

• 🌟 GitHub: tirth8205/code-review-graph
• 🌐 Website: code-review-graph.com
• 📦 PyPI: code-review-graph
• 📄 Benchmark reproduction: docs/REPRODUCING.md
• 💬 Discord: discord.gg/3p58KXqGFN

요약 (Summary)

code-review-graph는 코드베이스가 커질수록 문제가 심화되는 문제, 즉 AI 에이전트가 A를 변경하는 것이 B에 영향을 미친다는 사실을 모른다는 문제를 해결합니다. 따라서 너무 많은 파일을 읽거나 grep에 의존하게 됩니다. CRG는 '무엇이 무엇에 영향을 미치는지' 맵을 미리 구축하여 에이전트가 이를 직접 조회할 수 있게 합니다.

주목할 만한 세 가지 엔지니어링 결정 사항:

로컬 우선 및 제로 원격 측정 (Local-first with zero telemetry): 그래프는 SQLite에 저장되며, 클라우드 임베딩은 선택적(기본값 비활성화)이고, GitHub Action은 전적으로 사용자의 CI 러너에서 실행됩니다. 소스 코드는 사용자 기기에 남아 있습니다.

정직한 벤치마크 (Honest benchmarks): 528x는 '최상의 경우'로 표시되었고, 중앙값인 82x가 주요 수치입니다. recall=1.0은 순환적(그래프 기반의 Ground Truth)이라고 명시적으로 언급되었습니다. 작은 커밋에 대한 오버헤드는 숨기지 않고 인정했습니다. 이러한 수준의 투명성은 개발자 도구 분야에서 진정으로 드문 것입니다.

주요 경로로서 증분 업데이트 (Incremental updates as the primary path): 초기 빌드는 일회성 비용입니다. 2초 만에 완료되는 증분 업데이트는 사용자가 작업하는 동안, 또는 기억해서 재빌드할 때가 아니라 후크(hooks)와 워치 모드(watch mode)를 통해 그래프를 최신 상태로 유지할 수 있게 합니다.

수백 개에서 수천 개의 파일을 가진 중대형 코드베이스, 빈번한 코드 리뷰 워크플로우, 또는

더 많은 통찰력과 흥미로운 제품들을 확인하시려면 저의 개인 사이트를 방문해 주세요.