AIコードレビューのトークン爆発をcode-review-graphで抑える

AIコードレビューをClaude CodeやCursorに任せるとき、最初にぶつかる壁がトークンの爆発です。
PRの差分を渡すだけでは精度が出ない。
かといって関連しそうなファイルを手動で足していくと、あっという間にコンテキストが膨れ上がる。

依存グラフで「本当に関係するファイルだけ」を逆引きする code-review-graph を使えば、その両極端から抜け出せます。
インストールからClaude Code / Cursorへの接続、削減効果の確認まで、自分のリポジトリで再現できる状態を目指します。

AIコードレビューで「差分だけ渡す」が通用しない理由

PRの差分ファイルだけをAIに渡せば十分に思えますよね。
変更されたファイルさえ見れば、何が変わったかは分かるはずだ、と。

でも実際には、差分に映らない部分こそがレビューの精度を左右します。

具体的なシナリオで考えてみましょう。
共通ユーティリティ関数の引数の型を変えたとします。
差分ファイルはその関数定義が書かれた1ファイルだけです。
でも実際に影響を受けるのは、その関数を呼び出している10個のモジュール、それらのテストファイル、さらに継承関係にあるクラス群です。
AIが差分ファイルだけを見ていると「この変更は問題なさそう」と判断してしまう。
呼び出し元で型エラーが起きることに気づけないまま、レビューが終わります。

それを補おうとして「関連しそうなファイルも渡しておこう」と手動で追加し始めると、別の問題が起きます。
「関連しそう」という判断は人間の勘に頼るので、実際には無関係なファイルが大量に混入します。
500行のファイルを5個追加すれば、それだけで数千トークンが消えます。

Claude Codeはツールの出力を1回あたり25kトークンで打ち切ります。
さらに、複数ツールを連続して呼び出すセッションでは、各呼び出しの出力がコンテキストに積み重なっていきます。
Hacker Newsのスレッドでも指摘されていますが、Playwrightのスナップショット1回やgit logの出力1回で50kトークンを消費することがあり、3〜4回の連続呼び出しで100kトークンを超えることも珍しくありません。
コードレビューのセッションで複数ファイルを読み込みながらコメントを生成していくと、トークンの累積は想像以上に速いです。

差分だけ渡すと文脈が足りなくて精度が落ちる、全部渡すとトークンが爆発してセッションが死ぬ。
この二択から抜け出す第三の選択肢として、依存グラフによるアプローチがあります。

依存グラフが「本当に関係するファイル」を逆引きする仕組み

code-review-graphは、Tree-sitter ASTを使ってコードベース全体の構造グラフを構築します。
関数呼び出し・インポート・継承・テスト対象の関係を静的解析でマッピングし、SQLiteファイルとしてローカルに保存します。

PRのレビューを依頼するとき、ツールは差分ファイルのリストを受け取り、そのグラフを逆引きします。
「このファイルを呼び出しているのは誰か」「このクラスを継承しているのは誰か」「このモジュールのテストはどこにあるか」をグラフから辿り、 blast radius（変更の影響範囲）を特定します。
AIに渡すコンテキストは、その逆引きで得られたファイルだけです。
差分→依存グラフ→最小コンテキスト、という流れです。

ここで、似たようなツールとの違いを整理しておきます。

codebase-memory-mcp は「コードベース全体の記憶」を目的としたツールで、永続化はベクトル埋め込みベースです。セマンティック検索が得意な分、構造的な依存関係の追跡は苦手で、コードレビューに特化した機能（blast radiusの算出やリスクスコアリング）は持っていません。
graphify はコードベースをナレッジグラフに圧縮してAIに渡す用途で、BFS（幅優先探索）でアーキテクチャ全体を俯瞰するのが得意です。ただしコードレビューのワークフローに特化した機能はなく、ベンチマーク機能も持っていません。
code-review-graph はコードレビューに特化して設計されており、blast radiusの算出・リスクスコア付きの変更サマリ・ベンチマーク機能を持ちます。永続化はSQLiteでローカル完結、外部依存なしです。

筆者の判断基準を一言で言うと、PRレビューの文脈削減が目的なら code-review-graph 一択です。
アーキテクチャ全体を俯瞰したい・初見のコードベースを素早く理解したいという用途ならgraphifyが向いています。
セマンティック検索でコードを探したいなら codebase-memory-mcp やclaude-contextが適しています。
目的が違うので、組み合わせて使うのも合理的です。

セットアップ：インストールからMCP接続まで

3ステップで動きます。インストール、グラフ構築、MCP設定への追記です。

# インストール
pip install code-review-graph

# リポジトリのルートに移動してグラフを構築
cd /path/to/your/repo
crg build

ビルドが完了すると、リポジトリルートに .code-review-graph/ ディレクトリが作られ、その中にSQLiteファイルが生成されます。
テレメトリはゼロで、ネットワーク通信は一切ありません。
streamable-HTTPのMCPトランスポートはデフォルトでlocalhostにバインドされます（デフォルトポートはドキュメントで確認してください）。

次に、MCPサーバーとして登録します。
Claude Codeの場合、プロジェクトルートの .mcp.json に以下を追記します。

{
  "mcpServers": {
    "code-review-graph": {
      "type": "streamable-http",
      "url": "http://localhost/mcp"
    }
  }
}

Cursorの場合はstdioトランスポートを使うのが一般的です。
CursorのMCP設定ファイルのパスはバージョンによって異なる場合があるため、Cursorの公式ドキュメントで確認してください。
設定の中身はこのようなかたちになります。

{
  "mcpServers": {
    "code-review-graph": {
      "command": "crg",
      "args": ["mcp", "serve", "--transport", "stdio"]
    }
  }
}

streamable-HTTPはサーバーを別プロセスで常駐させる方式で、stdioはCursorがプロセスを直接起動する方式です。
Claude Codeはstreamable-HTTPとstdioの両方をサポートしていますが、常駐させておきたい場合はstreamable-HTTPが安定します。

MCPサーバーをstreamable-HTTPモードで起動するには、別ターミナルで以下を実行します。

crg mcp serve

ここで一つ注意点があります。
Windows環境（特にWindows 11 + Codex CLI）では、2462ファイル規模のリポジトリでMCPバックエンドが内部でgit diffを実行する際に2分のタイムアウトに達するケースが報告されています（Issue #262）。
この問題に当たった場合、差分ファイルを手動で取得してCLI経由で渡す回避策が有効です。

# 差分ファイルを手動で取得してCLI経由でレビュー（Windows環境での回避策）
git diff --name-only HEAD~1

Issue #262の報告では、Codex CLIのエージェント自身がこの方法を自力で見つけて回避していたという記録があります。
MCPパスが遅い場合でも、CLIのグラフ操作は高速に動作することが確認されているので、Windows環境ではまずCLIで動作を確認してからMCP接続に移行するのが安全です。

削減効果の確認と、グラフを腐らせないための運用

セットアップが終わったら、まず削減効果を自分の目で確認することをおすすめします。
code-review-graphにはベンチマーク機能が組み込まれており、差分ファイルを渡したときに「グラフなし」と「グラフあり」でどれだけ参照ファイル数とトークン数が変わるかを比較できます。

# ベンチマークを実行
crg benchmark

出力には、参照ファイル数とおおよそのトークン推定値が「グラフなし（全ファイル渡し）」と「グラフあり（blast radius絞り込み後）」の両方で表示されます。
オプションの詳細はドキュメントを参照してください。

数値の読み方としては、参照ファイル数の削減率よりもトークン数の削減率を重視してください。
ファイル数が半分になっても、残ったファイルが大きければトークン削減効果は限定的です。
逆に、小さくて頻繁に参照されるファイルを除外できると、トークン削減率は大きく跳ね上がります。

グラフを構築して終わり、にしてしまうと運用上の問題が起きます。
コードベースは毎日変わるので、グラフが古くなると誤った依存関係を返すようになります。
「このファイルはもう削除されているのに、グラフには残っている」という状態が積み重なると、AIが存在しないファイルを参照しようとして混乱します。

グラフの更新はデーモンを使うのが楽です。

# デーモンを起動してリポジトリの変更を自動監視
code-review-graph daemon start

# デーモンの状態確認と停止
code-review-graph daemon status
code-review-graph daemon stop

デーモンはリポジトリをウォッチして、変更があれば自動的にグラフを更新します。
複数リポジトリを登録しておけば、それぞれのグラフを並行して最新に保てます。

モノレポや多言語リポジトリでの挙動については、Tree-sitterのウォーカーが汎用的に設計されているため、標準でサポートされていない言語もカスタム言語定義（docs/CUSTOM_LANGUAGES.md に仕様があります）を追加することで対応できます。
言語定義を追加してもビルトイン言語の挙動は変わらないので、既存の解析結果に影響しません。

CI/CDへの組み込みも自然な拡張です。
PRが作られるたびにグラフを最新に保つ運用は難しくありませんが、その詳細は別の機会に譲ります。

ツールを入れた直後はグラフが新鮮なので効果を実感しやすいですが、数週間後に「なんか精度落ちたな」と感じたらグラフの鮮度を疑ってみてください。
依存グラフは育てるものです。
構築して終わりではなく、コードベースと一緒に更新し続けることで、はじめて「本当に関係するファイルだけを渡す」という状態が維持できます。

株式会社ホコサキは山口県宇部を拠点に、AIコーディングツールの導入支援やDX推進に取り組んでいます。
code-review-graphのようなツールを実際のプロジェクトに組み込む際には、リポジトリの構造や開発フローに合わせた調整が必要になることも多く、そのあたりの知見は現場で積み重ねてきました。
コンテキスト管理の改善や導入相談は、お問い合わせページからお気軽にどうぞ。