Code Review Graphとは——コードレビューのトークン爆発をASTで根本解決
「このPRに影響を受けるファイルを教えてください」——その一言でAIコーディングツールがリポジトリ全体を読み込もうとしたとき、数万トークンが一瞬で消費される。大規模なNext.jsモノレポなら27,732ファイルが対象になることもある。トークンコストは青天井になり、コンテキストウィンドウの上限にも達する。
Code Review Graphはこの問題を根本から解決するOSSツールだ。Tree-sitter ASTでコードベースの構造を解析し、ローカルSQLiteデータベースに知識グラフとして保存。AIが「本当に見るべきファイル」だけを特定することで、同じNext.jsモノレポの分析を27,732ファイルから約15ファイルに圧縮、49倍のトークン削減を実現した。
GitHub Stars 12,519を獲得したこのプロジェクトは、Tirth Patelが「Stop burning tokens. Start reviewing smarter.」というコンセプトで開発した。28のMCPツールを通じてClaude Code・Cursor・Windsurf等11のAIコーディングプラットフォームに自動統合できる。Python 3.10以上で動作し、MIT ライセンスで公開されている。
このツールが解決しようとしている問題を理解するために、まずAIコードレビューにおけるトークン消費の構造から見ていこう。
なぜAIコードレビューでトークンが爆発するのか：問題の構造
AIにコードレビューを依頼するとき、開発者が直面する現実的な問題は「どのファイルをAIに渡すか」という文脈選択の困難さだ。
ナイーブなアプローチは「すべてのファイルを渡す」ことだが、これは即座に破綻する。変更されたファイルだけを渡すと、そのファイルが依存する関数・クラス・テストの文脈が欠落し、AIは的外れなレビューしかできない。逆に関連ファイルを丸ごと渡すと、トークンが爆発する。
この問題の核心はソフトウェアの依存関係がグラフ構造を持つという点にある。あるファイルを変更すると、それを呼び出す関数、テストスイート、継承しているクラス、インポートしている他のモジュールが連鎖的に影響を受ける可能性がある。この「影響の波及範囲」を正確に特定するには、コードの構造を機械的に解析する必要がある。
従来の解決策はいくつか存在した。gitの差分だけを渡す方法は高速だが文脈が不足する。エディタのファイルツリーをそのまま渡す方法はトークンの無駄遣いになる。手動でファイルを選ぶ方法は開発者の認知負荷が高い。RAGによるベクトル検索は意味的類似性は捉えられるが、「このクラスを継承しているすべてのファイル」といった構造的な依存関係は苦手だ。
LLMのコンテキストウィンドウとトークン効率の基礎知識については、LLM完全ガイドで詳しく解説している。
Code Review Graphのアプローチは異なる。Tree-sitterという実績のあるASTパーサーでコード全体を構造的に解析し、関数・クラス・インポートをノードとして、呼び出し・継承・テスト関係をエッジとしてグラフに格納する。変更ファイルからグラフを辿ることで、最小限の「ブラストラジウス（影響範囲）」を数学的に特定できる。
Tree-sitter ASTからSQLiteグラフへ：アーキテクチャの詳細
Code Review Graphのパイプラインは5段階で構成される。
（差分検出）"] --> B["Tree-sitter
ASTパーサー"] B --> C["ノード抽出
（関数・クラス・
インポート）"] C --> D["エッジ構築
（呼び出し・継承・
テスト関係）"] D --> E["SQLiteグラフDB
（.code-review-graph/）"] E --> F["ブラストラジウス
分析"] F --> G["最小レビューセット
（AIへ送信）"]
ステップ1：差分検出とSHA-256ハッシュ比較
ファイルの変更検出はSHA-256ハッシュで行う。gitのコミット差分または保存時のファイル変更を検知し、変更されたファイルのみを再解析対象とする。このインクリメンタル更新により、2,900ファイル以上の大規模プロジェクトでも2秒以内の再インデックスを実現している。
ステップ2：Tree-sitter ASTパース
Tree-sitterはGitHub製の高速ASTパーサーで、23言語に対応する。各ファイルのASTから以下の要素を抽出する：
- ノード: 関数定義、クラス定義、インポート文、モジュール
- エッジ: 関数呼び出し、クラス継承、テスト対象、インポート依存
Tree-sitterがコードの構文構造を正確に理解するため、コメントや文字列リテラルに混入した偽陽性の参照を除外できる。正規表現によるテキストマッチングとは根本的に異なる。
ステップ3：SQLiteグラフデータベース
抽出されたグラフはローカルの.code-review-graph/ディレクトリにSQLiteデータベースとして保存される。外部データベースサーバーは不要で、クラウドへのデータ送信も発生しない。各ノードには関数シグネチャ（約10トークン）のみが格納されており、ストレージ効率が高い。
FastAPIリポジトリ（1,122ファイル）では6,285ノードが生成され、検索レイテンシは1.5ms。Flaskリポジトリ（83ファイル）では1,446ノード、検索レイテンシ0.7msだ。
ステップ4：ブラストラジウス分析
変更ファイルが特定されると、グラフトラバーサルで影響範囲を計算する。具体的には：
- 変更されたノードの直接呼び出し元（callers）を特定
- 依存している他のクラス・モジュール（dependents）を特定
- そのノードをテストしているテストケースを特定
- 再帰的に上位の依存関係を辿る
この分析は100%のリコール（影響ファイルを見落とさない）を達成している。F1スコアは0.54と保守的な設計になっており、これは意図的な判断だ——「関係ないかもしれないが念のため」というファイルも含めることで、AIが重要な変更を見逃すリスクを最小化する。
ステップ5：コミュニティ検出（Leidenアルゴリズム）
グラフ全体からコミュニティ（密に結合したコードのクラスター）を検出するためにLeidenアルゴリズムを使用する。クラスターが大きくなりすぎた場合は自動分割される。これにより「このモジュールはどの機能領域に属するか」という高次の構造理解が可能になる。
インストールと初期設定：3コマンドで動く
Code Review Graphのセットアップは3つのコマンドで完結する。
# 1. インストール
pip install code-review-graph
# 2. プラットフォームへの自動統合
code-review-graph install
# 3. 初回インデックス構築（500ファイルで約10秒）
code-review-graph build
code-review-graph installコマンドはClaude Code・Cursor・Windsurf等の設定ファイルを自動検出し、MCPサーバーとして登録する。特定のプラットフォームを指定したい場合は：
# Claude Codeに明示的に統合
code-review-graph install --platform claude-code
# Cursorに統合
code-review-graph install --platform cursor
主要CLIコマンド一覧
| コマンド | 用途 |
|---|---|
code-review-graph build |
全ファイルをフルスキャンしてグラフ構築 |
code-review-graph update |
変更ファイルのみインクリメンタル更新 |
code-review-graph visualize |
インタラクティブHTMLグラフを生成 |
code-review-graph detect-changes |
リスクスコア付きの変更影響分析 |
code-review-graph wiki |
リポジトリのMarkdownドキュメントを自動生成 |
除外ファイルの設定
自動生成ファイルやベンダーコードをインデックス対象から除外するには、.code-review-graphignoreを作成する：
generated/**
*.generated.ts
vendor/**
node_modules/**
dist/**
デフォルトではgit ls-filesでトラッキングされているファイルのみがインデックスされる。つまり.gitignoreで除外済みのファイルは自動的にスキップされる。
セマンティック検索の有効化（オプション）
コア機能はSQLiteのみで動作するが、セマンティック検索を有効にする場合はエンベディングモデルを追加インストールできる：
# ローカルエンベディングモデル（all-MiniLM-L6-v2）を使用
pip install code-review-graph[embeddings]
# すべてのオプション機能を含む
pip install code-review-graph[all]
外部のエンベディングAPIを使用する場合は環境変数で設定する：
export CRG_EMBEDDING_MODEL=all-MiniLM-L6-v2
export CRG_OPENAI_BASE_URL=http://127.0.0.1:3000/v1
export CRG_OPENAI_API_KEY=sk-...
export CRG_OPENAI_MODEL=text-embedding-3-small
マルチリポジトリデーモンの設定
複数のプロジェクトを常時監視するデーモンモードも提供されている：
# リポジトリをデーモンに登録
crg-daemon add ~/project-a --alias proj-a
crg-daemon add ~/project-b --alias proj-b
# デーモン起動
crg-daemon start
# 状態確認
crg-daemon status
# 停止
crg-daemon stop
28のMCPツール：AIエージェントとのシームレスな統合
Code Review Graphの最大の特徴のひとつが、MCPプロトコルを通じたAIエージェントとの統合だ。28種類のMCPツールが提供されており、AIはこれらを呼び出すことでコードベースを「見ずに理解する」ことができる。
Claude Code / Cursor etc."] -->|MCPプロトコル| B["Code Review Graph
MCPサーバー"] B --> C["コアツール群"] B --> D["分析ツール群"] B --> E["ナレッジツール群"] C --> C1["get_minimal_context_tool
（~100トークンで文脈取得）"] C --> C2["get_impact_radius_tool
（ブラストラジウス）"] C --> C3["detect_changes_tool
（リスクスコア付き変更検出）"] C --> C4["query_graph_tool
（呼び出し元/先・テスト検索）"] D --> D1["get_hub_nodes_tool
（アーキテクチャのホットスポット）"] D --> D2["get_bridge_nodes_tool
（依存関係のチョークポイント）"] D --> D3["get_knowledge_gaps_tool
（構造的弱点の特定）"] E --> E1["semantic_search_nodes_tool
（セマンティック検索）"] E --> E2["list_communities_tool
（コードコミュニティ一覧）"] E --> E3["generate_wiki_tool
（ドキュメント自動生成）"]
コアMCPツール：日常的なコードレビューに使う4つ
get_minimal_context_tool
最も重要なツールだ。変更されたファイルを入力として受け取り、AIがレビューに必要な最小限のコンテキストを約100トークンで返す。全ファイルを読み込む「ナイーブ」アプローチと比較して、フラスコ（44,751トークン → 4,252トークン、9.1倍削減）やGin（21,972トークン → 1,153トークン、16.4倍削減）といった実績がある。
get_impact_radius_tool
特定のファイルや関数が変更されたとき、影響を受ける可能性のあるすべてのコンポーネントを返す。直接の呼び出し元だけでなく、テストケース、継承クラス、依存モジュールも含めて列挙する。
detect_changes_tool
gitの差分情報を入力として受け取り、変更のリスクスコアを計算して返す。「この変更は低リスク（1ファイルのみ影響）」「この変更は高リスク（37ファイルに波及の可能性）」といった情報を提供する。
query_graph_tool
任意のノード（関数・クラス）に対して、呼び出し元（callers）、呼び出し先（callees）、テストコード、インポート関係を直接クエリできる。「この関数を呼んでいるすべての場所はどこか」という質問に即答する。
分析ツール：コードベース全体の健全性を把握する
get_hub_nodes_tool
コードベース内で多くのファイルから参照されているハブノードを特定する。「最もリスクの高い変更場所」「アーキテクチャ上の単一障害点」を可視化できる。
get_bridge_nodes_tool
異なるコミュニティ（モジュール群）を繋ぐブリッジノードを検出する。これらのノードを変更すると、複数の独立したモジュールに連鎖影響が出る可能性がある。
get_knowledge_gaps_tool
テストが不足している関数、ドキュメントが欠けているクラス、複雑度が高い未リファクタリング箇所といった「構造的弱点」を特定する。技術的負債の可視化に使える。
get_surprising_connections_tool
本来疎結合であるべき2つのモジュール間に予想外の依存関係が存在することを検出する。アーキテクチャ的な設計問題の発見に役立つ。
ナレッジツール：チームのオンボーディングと文書化
generate_wiki_toolとtraverse_graph_toolを組み合わせることで、コードベースの自動ドキュメント生成が可能だ。新しいメンバーが「このリポジトリはどう構成されているか」を素早く理解するためのWikiをMarkdown形式で出力できる。
semantic_search_nodes_toolはエンベディングを使った意味的検索を提供する。「ユーザー認証に関係する関数」「データベース接続を処理するクラス」といった自然言語クエリでグラフを検索できる（エンベディングオプション有効時）。
Claude CodeのMCP統合とエージェント設計の詳細は、Claude Code完全ガイドで解説している。
実測ベンチマーク：6リポジトリ13コミットの検証データ
Code Review Graphの効果は、実際の有名OSSリポジトリを使った実測データで裏付けられている。6リポジトリ、13コミット、合計175,286トークン（ナイーブアプローチ）と9,983トークン（グラフアプローチ）の比較だ。
トークン削減率の比較表
| リポジトリ | コミット数 | ナイーブトークン | グラフトークン | 削減率 |
|---|---|---|---|---|
| Flask（83ファイル） | 2 | 44,751 | 4,252 | 9.1倍 |
| Gin（Go製） | 3 | 21,972 | 1,153 | 16.4倍 |
| httpx | 2 | 12,044 | 1,728 | 6.9倍 |
| Next.js（モノレポ） | 2 | 9,882 | 1,249 | 8.0倍 |
| FastAPI | 2 | 4,944 | 614 | 8.1倍 |
| Express | 2 | 693 | 983 | 0.7倍 |
| 平均 | — | — | — | 8.2倍 |
Expressの0.7倍という数値に注目してほしい。小規模パッケージの単一ファイル変更では、グラフ構造のメタデータ（ノード情報など）が生ファイルサイズを上回ることがある。Code Review Graphが最も効果を発揮するのは、大規模リポジトリや多くのファイルにまたがる変更だ。
49倍削減の実態：Next.jsモノレポの解析
ベンチマーク表のNext.jsは8倍だが、「49倍」という数値はどこから来るか。これはNext.jsモノレポの全体スキャン実験で記録された。27,732ファイルのリポジトリで変更の影響を分析したとき、グラフが最終的に「この変更に関係するのは約15ファイルだけ」と特定した結果だ。
計算すると：27,732 ÷ 15 ≈ 1,849倍の「ファイル数削減」だが、各ファイルのサイズや必要なシグネチャ情報も加味した実際のトークン削減率が49倍になる。
精度の評価指標
- リコール：1.0（100%） — 影響を受けるファイルを見落とすことはない
- 平均F1スコア：0.54 — 保守的に多めに含める設計
- 誤ったポジティブ（不要なファイルを含む）あり — これは意図的。見落としのほうがコストが高い
ビルドパフォーマンスは実用レベルだ。FastAPI（1,122ファイル）でフロー検出128ms、検索レイテンシ1.5ms。Flask（83ファイル）でフロー検出95ms、検索レイテンシ0.7ms。
対応言語23種とプラットフォーム自動検出
対応プログラミング言語（23種）
Tree-sitterの対応言語をフルに活用した23言語サポートは、PolyglotなチームやモノレポでCode Review Graphを使う上で重要だ。
| カテゴリ | 対応言語 |
|---|---|
| Web/フロントエンド | TypeScript、JavaScript、Vue、Svelte |
| バックエンド主要言語 | Python、Go、Java、Ruby、PHP、Kotlin、Scala、C# |
| システム言語 | Rust、C、C++、Zig |
| モバイル | Swift、Dart |
| データサイエンス | R、Julia、Jupyter/Databricks Notebook |
| その他 | Solidity（スマートコントラクト）、Perl、Lua、PowerShell |
自動検出される11のAIコーディングプラットフォーム
code-review-graph installを実行すると、以下のプラットフォームの設定ファイルを自動検出してMCPサーバー設定を追記する：
| プラットフォーム | 検出方法 |
|---|---|
| Claude Code | .claude/ ディレクトリ設定 |
| Cursor | .cursor/ ディレクトリ設定 |
| Windsurf | .windsurf/ ディレクトリ設定 |
| Zed | ~/.config/zed/ 設定 |
| Continue | .continue/ 設定 |
| Codex | OpenAI Codex設定 |
| OpenCode | OpenCode設定ファイル |
| Antigravity | Antigravity設定 |
| Qwen | Qwen Coder設定 |
| Qoder | Qoder設定 |
| Kiro | Kiro設定 |
競合ツールとの比較：どのアプローチが何を解決するか
コードコンテキスト最適化のアプローチはCode Review Graph以外にも存在する。各手法の特性を整理する。
アプローチの比較"] --> B["AST/グラフベース
Code Review Graph"] A --> C["ベクトル検索ベース
RAGシステム"] A --> D["ファイルツリー
要約アプローチ"] A --> E["手動コンテキスト
選択"] B --> B1["構造的依存関係を追跡
100%リコール
追加設定が必要"] C --> C1["意味的類似性に強い
継承・呼び出しは苦手
エンベディングコスト発生"] D --> D1["シンプルで即効性あり
精度は低い
大規模リポジトリで限界"] E --> E1["最高精度
開発者の認知負荷が高い
スケールしない"]
アプローチ別の詳細比較
| 比較軸 | Code Review Graph | RAGベースのコード検索 | 手動ファイル選択 | ファイルツリー要約 |
|---|---|---|---|---|
| 構造的依存関係の追跡 | 完全（AST解析） | 限定的（意味的のみ） | 人間の判断に依存 | 不可 |
| セットアップ負荷 | 中（初回ビルド必要） | 高（エンベディング必須） | なし | なし |
| トークン削減率 | 平均8.2倍（最大49倍） | 可変（文書検索型に近い） | 開発者スキルに依存 | 低 |
| リコール | 1.0（見落としなし） | 0.7〜0.9程度 | 人間の主観に依存 | 低 |
| 動的コード（eval等） | 苦手 | 苦手 | 対応可 | 不可 |
| 大規模リポジトリ | 非常に得意 | 得意 | 非現実的 | 困難 |
| ローカル完結 | 完全（SQLiteのみ） | 一般的にクラウド依存 | 完全 | 完全 |
RAGベースのコード検索と比較したとき、Code Review Graphが明確に優位なのは「このクラスを継承しているすべてのファイル」「この関数を呼んでいるすべての呼び出し元」「この変更が影響するテストケース」といった、構造的な依存関係の追跡だ。意味的な類似性ではなく、コードの構文構造に基づいた依存関係を辿る。
一方、「ユーザー認証に関連するコードを探す」「このバグに似たパターンを持つファイル」といった意味的な検索は、RAGシステムが得意とする領域だ。Code Review Graphはオプションのエンベディングサポートでこの点も補完しているが、主戦場は構造的解析にある。
RAGシステムの構築と知識グラフの組み合わせについては、RAG完全ガイド2026も参照してほしい。
既知の制限と実運用での注意点
Code Review Graphは強力なツールだが、すべてのシナリオで効果を発揮するわけではない。公式READMEに明記されている制限を理解した上で導入を検討することが重要だ。
制限1：単一ファイル・小規模パッケージでのオーバーヘッド
ベンチマークのExpressリポジトリが示すように、小さなパッケージで単一ファイルのみを変更した場合、グラフのメタデータが生ファイルサイズを上回り、ナイーブアプローチよりトークンが増える場合がある（効率 < 1.0）。モノリスや大規模リポジトリでの利用が最も費用対効果が高い。
制限2：キーワード検索の精度
セマンティック検索のMRR（Mean Reciprocal Rank）は0.35で、正しい結果がトップ4に入る程度の精度だ。「完全に正確なファイル特定」ではなく「候補セットの絞り込み」として使うのが適切な利用法だ。
制限3：実行フロー検出の限界
detect_changes_toolのフロー検出リコールは33%だ。PythonのFlask・FastAPIといったフレームワークパターンでは信頼性が高いが、動的な呼び出し（eval()、getattr()、依存性注入フレームワーク）、メタプログラミング、実行時に変わるパターンは追跡できない。静的解析の限界だ。
制限4：フロントエンド・バックエンド横断の依存関係
Tree-sitterはファイル内とファイル間の同言語依存関係を追跡するが、APIエンドポイント経由のフロントエンド→バックエンドの依存関係、データベーススキーマとORM間の関係、設定ファイルとコードの関係は追跡対象外だ。
制限5：初回ビルドのコスト
初回のcode-review-graph buildは500ファイルで約10秒、大規模なモノレポではそれ以上かかる場合がある。CI/CDパイプラインでのコールドスタートには注意が必要だ。ただしインクリメンタル更新は2秒以内なので、開発中の日常利用は快適だ。
ベストプラクティス：Code Review Graphが最も効果を発揮する条件
- 1,000ファイル以上の大規模・中規模リポジトリでのコードレビュー
- 複数ファイルにまたがるリファクタリングの影響分析
- 「このクラスを継承しているすべてのコードを確認したい」という構造的クエリ
- チームの新メンバーへのWiki自動生成によるオンボーディング支援
- モノリスのアーキテクチャ上のホットスポット・リスクポイントの可視化
- 100ファイル未満の小規模プロジェクト（オーバーヘッドの方が大きい）
- 動的型付けやメタプログラミングを多用するコードベース
- 単一ファイルへの孤立した変更（依存関係がないケース）
- マイクロサービス間のAPIコントラクト横断の依存関係追跡
Code Review Graphが示すAIコーディングの方向性
Code Review Graph（12,519★）が提起しているのは、AIコーディングツールにとって根本的な問いだ——「AIに渡す文脈の質をどう高めるか」。
より大きなコンテキストウィンドウ、より安いトークン単価も解決策のひとつだ。しかしCode Review Graphのアプローチは別の方向を向いている。コードベースの構造を機械的に理解し、必要な情報だけを数学的に特定することで、ウィンドウサイズやコストに依存せずスケールする解決策を提供する。
Tree-sitter ASTによるグラフ構築は、平均8.2倍のトークン削減を実現し、最大ケースでは49倍の効率化を達成した。100%のリコール（影響ファイルの見落としゼロ）を保ちながら、2秒以内のインクリメンタル更新で実開発のワークフローに組み込める。
28のMCPツールと11プラットフォームへの自動統合により、Claude CodeやCursorなどのAIコーディングツールが既存の設定ファイルを通じてCode Review Graphを即座に利用できる。追加のプロンプトエンジニアリングなしに、AIが「必要なファイルだけ」を自律的に参照する仕組みが整う。
Claude Code ベストプラクティスガイドでは、Code Review Graphのようなコンテキスト最適化ツールをClaude Codeのワークフローに組み込む方法を詳しく解説している。
制限も明確だ——小規模プロジェクト、動的コード、フロー検出精度33%。しかし大規模リポジトリでのコードレビュー効率化という課題に対しては、Tree-sitter ASTグラフアプローチは現時点で最も実績のある解決策のひとつだ。
pip install code-review-graphからはじまる3コマンドのセットアップで、AIコードレビューのトークン消費がどれだけ変わるかを試してみる価値がある。
