Code Review Graphとは｜Tree-sitter ASTのコード知識グラフでトークンを中央値65倍削減

Code Review Graphとは——コードレビューのトークン爆発をASTで根本解決

「このPRに影響を受けるファイルを教えてください」——その一言でAIコーディングツールがリポジトリ全体を読み込もうとしたとき、数万トークンが一瞬で消費される。数万ファイル規模のモノレポなら、対象は容易にその桁に届く。トークンコストは青天井になり、コンテキストウィンドウの上限にも達する。

Code Review Graphはこの問題を根本から解決するOSSツールだ。Tree-sitter ASTでコードベースの構造を解析し、ローカルSQLiteデータベースに知識グラフとして保存。AIが「本当に見るべきファイル」だけを特定することで、6リポジトリの実測で、1質問あたりのトークンを中央値65倍（範囲36〜376倍）削減する。

GitHub Stars 30,832（2026-08-26時点）を獲得したこのプロジェクトは、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段階で構成される。

ステップ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：ブラストラジウス分析

変更ファイルが特定されると、グラフトラバーサルで影響範囲を計算する。具体的には：

1. 変更されたノードの直接呼び出し元（callers）を特定
2. 依存している他のクラス・モジュール（dependents）を特定
3. そのノードをテストしているテストケースを特定
4. 再帰的に上位の依存関係を辿る

この分析は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-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はこれらを呼び出すことでコードベースを「見ずに理解する」ことができる。

コア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完全ガイドで解説している。

実測ベンチマーク：公称値は2026年5月に差し替えられている

現在の公称値は「6リポジトリ・5つのサンプル質問あたりのトークン削減」で、初出時の「コミット単位のレビュー」とは測っている対象そのものが違う。数値だけを新旧で並べても比較にならないので、指標の定義ごと置き換える。

トークン削減率（2026-08-02 再計測・crg 2.3.7・固定SHAのクリーンクローン）

この表の読み方で外してはいけない点が3つある。

・見出し数値は「中央値65倍」であって最大値ではない。 README自身が376倍について「最大のコーパスを持つfastapiでの最良ケースであり、典型的な結果ではない（not the headline）」と明記している
・分母の「ナイーブ」は、現実のエージェントが実際には払わないコスト。 README は whole-corpus baseline を「有能なエージェントは識別子をgrepして最良一致のファイルだけ読むので、誰も払わない上限値」と自認している。つまり65倍は上限どうしの比であって、実運用の削減率ではない
・再計測で数値は下がっている。 README の注記によれば、2026-05-25版より低い値になったのはノード埋め込みのテキストが充実してグラフ応答自体が長くなったため。このプロジェクトの公称値は上振れ方向に固定されていない——引用するときは必ず計測日を添えるべき種類の数値だ

精度の評価指標（同じ2026-08-02キャプチャ・13コミット）

再現率が全リポジトリで1.0なのは「影響を受けるファイルを見落とさない」ことを優先した設計の帰結で、その代わり適合率は0.546（＝拾ったファイルの約半分は不要）に留まる。見落としのコストのほうが高いという判断だ。

ただしこの再現率1.0は「グラフ由来の正解データ（graph-derived ground truth）」に対する上限値である点に注意がいる。READMEはより独立性の高い検証として、git履歴の同一コミットで実際に触られた他ファイルを正解に使う「co-change モード」も併設しているが、2026-08-02のキャプチャ時点で全採点コミットで predicted_files = 0 を返しており、測定として成立していないとREADME自身が認めている。つまり現時点で公開されている精度指標は、自己参照的な正解データに対するものだけだ。

対応言語23種とプラットフォーム自動検出

対応プログラミング言語（23種）

Tree-sitterの対応言語をフルに活用した23言語サポートは、PolyglotなチームやモノレポでCode Review Graphを使う上で重要だ。

自動検出される11のAIコーディングプラットフォーム

code-review-graph installを実行すると、以下のプラットフォームの設定ファイルを自動検出してMCPサーバー設定を追記する：

競合ツールとの比較：どのアプローチが何を解決するか

コードコンテキスト最適化のアプローチはCode Review Graph以外にも存在する。各手法の特性を整理する。

アプローチ別の詳細比較

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が最も効果を発揮する条件

Code Review Graphが示すAIコーディングの方向性

Code Review Graph（30,832★）が提起しているのは、AIコーディングツールにとって根本的な問いだ——「AIに渡す文脈の質をどう高めるか」。

より大きなコンテキストウィンドウ、より安いトークン単価も解決策のひとつだ。しかしCode Review Graphのアプローチは別の方向を向いている。コードベースの構造を機械的に理解し、必要な情報だけを数学的に特定することで、ウィンドウサイズやコストに依存せずスケールする解決策を提供する。

Tree-sitter ASTによるグラフ構築は、6リポジトリの実測で1質問あたり中央値65倍（範囲36〜376倍）のトークン削減を示している。グラフ由来の正解データに対しては再現率1.0（影響ファイルの見落としゼロ）を保ちながら、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コードレビューのトークン消費がどれだけ変わるかを試してみる価値がある。

参照ソース

• tirth8205/code-review-graph — GitHub公式リポジトリ
• Code Review Graph README — ベンチマークデータ・アーキテクチャ詳細
• tree-sitter/tree-sitter — Tree-sitter ASTパーサー公式リポジトリ
• Model Context Protocol (MCP) — 公式ドキュメント