code-review-graph：AIコードレビューを高精度に、トークン消費を削減

code-review-graph は、AI コーディングアシスタント向けのオープンソースツールで、まずローカルでコードベースの構造化「知識グラフ」を構築し、本当に関連するコンテキストだけを AI に渡すことで、毎回のタスクでリポジトリ全体をフルスキャンするのを避けます。Tree-sitter を使って AST を解析し、関数、クラス、インポート、呼び出し関係、テスト関係をグラフ構造に整理し、MCP を介して Claude Code、Codex、Cursor などのツールに提供します。

解決する問題

現在、多くの AI コーディングツールはコードレビュー、影響範囲の特定、変更の理解を行う際に、コードベース全体を繰り返し読み込むため、明らかな Token の無駄とコスト増加を引き起こします。数百ファイルのリポジトリで、たった一つの関数を変更しただけでも、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 は現在のリポジトリに対して実際にグラフを構築します。

読者の混乱を避けるために、2つのコマンドの役割を対照表で明確に示します。

エディタが 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 回のコミットで評価され、グラフモードはナイーブなフル読み取りと比較して、平均で Token 消費量を約 8 分の 1、全体で 8.2 倍削減できることが示されました。公開データによると、リポジトリによって効果にばらつきはあるものの、ほとんどの大中規模プロジェクトで顕著な減少が見られます。

もう一つの重要な指標は影響分析の精度です。公式結果では再現率が 100%、平均 F1 が 0.54、平均適合率が 0.38 でした。これは、戦略としてやや保守的であることを示しています。つまり、「影響を受ける可能性がある」ファイルを多めに提示することを優先し、実際の変更に波及する依存関係を見逃さないようにしています。

ただし、この方法がすべてのシナリオで有利とは限りません。公式でも、規模が小さく変更が非常に局所的なプロジェクトでは、グラフメタデータ自体のコンテキストオーバーヘッドがファイルを直接読み取るコストを上回る可能性があると明言しています。たとえば、express の単一ファイル変更テストでは削減率が 0.7× にとどまりました。そのため、最も適したシナリオは、やはり中大規模プロジェクト、複数ファイルの変更、複雑な依存関係、高頻度の AI レビューワークフローです。

適したチーム

チームがすでに Claude Code、Codex、Cursor、または類似のツールを日常の開発フローに取り入れており、プロジェクト規模が大きく、モジュール間の関係が複雑で、PR レビューが頻繁に行われている場合、code-review-graph の価値は直接的です。これはコードレビューを代替するものではなく、AI が「何を読むべきか」を正しく判断できるように支援し、その後のレビュー、デバッグ、アーキテクチャ分析、オンボーディングをより正確なコンテキストに基づいて行えるようにするものです。

個人プロジェクト、非常に小規模なリポジトリ、または偶発的な単純な変更の場合、必ずしも明確な利益が得られるとは限りません。しかし、システム的に AI コーディングコストを削減し、コンテキストノイズを減らし、コードレビューのヒット率を向上させたいチームにとっては、非常に実用的な効果を示しています。