code-review-graph

Code Review Graph — MCP を使ったトークン効率の高いコードベースコンテキスト

すべてを読み込ませるのではなく、構造マップを AI に提供することで、大規模なコードベースでの AI のトークン使用量を大幅に削減できます。削減効果はコードベースの規模に応じて高まり、小規模なプロジェクトではわずかですが、モノレポでは大きくなります。

概要

code-review-graph は、Tree-sitter を使ってコードベースを解析し、SQLite に保存された AST グラフを作成する MCP サーバーです。AI アシスタントがタスクのコンテキストを必要とするとき、まずグラフを照会し、ディレクトリ内のすべてのファイルを読む代わりに、変更の影響範囲にあるファイルだけを取得します。

トークンへの影響（参考値 — コードベースによって異なります）：

コードベースの種類	傾向
大規模モノレポ（10K 以上のファイル）	最大の削減効果 — グラフが読み込むファイルはごく一部です
中規模アプリ（1～5K ファイル）	複数ファイルにわたる変更で大幅に削減できます
小規模プロジェクト（200 ファイル未満）	効果はわずかです — グラフのオーバーヘッドが削減量を上回る場合があります

品質面での利点： AI の対象を影響範囲に絞ることでノイズが減り、レビューに集中しやすくなります。固定の倍率をあてにせず、ご自身のリポジトリで測定してください。

ブートストラッププロトコル（オプトイン）

中規模から大規模なプロジェクトで /plan の実行中、または通常の使用中に呼び出された場合、グラフ分析を利用できるか確認してから使用してください。

1. ステップ 1： ツールがインストールされているか確認します：Get-Command code-review-graph（Windows）または which code-review-graph（macOS/Linux）。
2. ステップ 2： ワークスペースに .code-review-graph/ ディレクトリがあるか確認します。
3. ステップ 3： インストール済みでもインデックスがない場合は、code-review-graph build を実行する前にユーザーに確認します（プロジェクト全体をスキャンします）。
4. ステップ 4： インストールされておらず、プロジェクトが大規模な場合は、ユーザーに「このプロジェクトのトークン使用量を削減するために、pip install code-review-graph を実行してローカルマップを作成しますか？」と確認します。確認なしにインストールやビルドを実行しないでください。

---

使用する場合と見送る場合

✅ 次の場合はインストールしてください：

• コードベースが500 ファイル以上
• モジュール間の依存関係を伴う複数ファイルの変更を行う
• AI アシスタントのトークンに月額 20 ドル以上を費やしている
• モノレポ、マイクロサービス、またはパッケージをまたぐ TypeScript を扱う
• コスト削減に加えて、レビュー品質の向上も目指している

❌ 次の場合は見送ってください：

• 孤立した単一ファイルの変更が中心で、コードベースが約 200 ファイル未満
• 動的なパターン（リフレクション、実行時コード生成、動的インポート）を多用している
• メンテナンスを一切したくない — グラフを常に最新の状態に保つ必要があります
• チームで AI コーディングツールがまだ標準化されていない

⚠️ 次の場合はまず評価してください：

• コードベースが200～500 ファイル — 導入を決める前にベンチマークを実施してください
• 静的パターンと動的パターンが混在している — 代表的なコミットでテストしてください

---

仕組み（4 層）

Layer 1: PARSE    → Tree-sitter builds ASTs from 19 languages
Layer 2: STORE    → Nodes + edges saved in SQLite graph
Layer 3: TRACE    → BFS computes blast radius of changes
Layer 4: SERVE    → MCP exposes graph to AI assistants

グラフに含まれるもの

• ノード： ファイル、関数、メソッド、クラス、インポート、テスト
• エッジ： 「A が B を呼び出す」「X が Y をインポートする」「TestZ が FunctionW を対象とする」「ClassA が ClassB を継承する」
• メタデータ： ノードごとの名前、種類、ファイルパス、行の範囲
• プライバシー： 構造メタデータのみ — グラフにはソースコードの内容は含まれません

対応言語（19）

Python、TypeScript、JavaScript、Go、Rust、Java、C#、Ruby、Kotlin、Swift、PHP、C/C++、Vue SFC、Solidity、Dart、R、Perl、Lua、Jupyter/Databricks ノートブック。

---

インストール

前提条件

• Python 3.9+（python3 --version）
• pip または pipx がインストールされていること
• MCP 対応の AI クライアント（AG Kit、Claude Code、Cursor、Windsurf、Zed）
• Git で追跡されているコードベース（差分更新用）

ステップ 1：パッケージをインストールする

# Recommended: isolated environment
pipx install code-review-graph

# Alternative: fastest, no permanent install
uvx code-review-graph install

# Alternative: global pip
pip install code-review-graph

ステップ 2：MCP クライアントを設定する

# Auto-detect all supported tools
code-review-graph install

# Or target a specific platform
code-review-graph install --platform claude-code
code-review-graph install --platform cursor
code-review-graph install --platform windsurf

この手順の後、エディターを再起動してください。 MCP サーバーは再起動時に有効になります。

ステップ 3：初期グラフを作成する

cd /your/project
code-review-graph build

コードベースの規模	ビルド時間の目安
500 ファイル	10～30 秒
5,000 ファイル	2～5 分
27,000 ファイル	5～10 分

ステップ 4：ウォッチモードを有効にする（推奨）

# Keep graph current as you work
code-review-graph watch

増分更新は2 秒未満で完了します。手動で更新する場合は、次のようにします。

code-review-graph update

ステップ 5：統合を確認する

AI クライアントを開いて、MCP 接続を確認します。Claude Code の場合は、/mcp を実行し、code-review-graph が表示されることを確認します。

---

設定

無視ファイル

プロジェクトのルートに .code-review-graphignore を作成します（.gitignore の構文を使用）。

# Build artifacts
dist/**
.next/**
build/**

# Dependencies
node_modules/**
vendor/**

# Generated files
generated/**
*.generated.ts
*.min.js

# Test fixtures (if large)
__fixtures__/**

生成ファイルやビルド成果物を除外することが重要です。除外しないと、意味のないノードでグラフが膨らみます。

マルチリポジトリの設定

マイクロサービスアーキテクチャの場合：

# Register additional repos
code-review-graph register /path/to/other/repo

# List all registered repos
code-review-graph repos

MCP サーバーは、登録されているすべてのリポジトリを対象にコンテキストを提供します。

---

主なワークフロー

1. 影響範囲の分析（主な用途）

MCP サーバーがアクティブなときに自動的に実行されます。AI アシスタントはファイルを読む前にグラフを照会し、すべてではなく、影響を受けるファイルのみを取得します。

Without graph:  Changed auth/middleware.py → AI reads 200+ files → 8,200 tokens
With graph:     Changed auth/middleware.py → Graph returns 12 impacted files → 1,000 tokens

2. リスクスコア付き変更分析

code-review-graph detect-changes

未コミットの変更をリスクレベルごとにスコアリングします。

• 依存先の数
• テストカバレッジの不足
• 変更された関数がクリティカルパス上にあるかどうか
• レビューを依頼する前に高リスクの変更を検出

3. デッドコードの検出

グラフは入力エッジのないノード、つまり呼び出し元、インポーター、テストカバレッジがないノードを検出します。

# Surfaces functions/classes that are candidates for removal
# Useful on mature codebases to reduce cruft

4. リファクタリングのプレビュー

code-review-graph rename preview --from OldClassName --to NewClassName

名前変更によって影響を受けるすべてのファイルを表示し、静的解析では検出できないエッジケース（動的な文字列参照）にフラグを付けます。

5. アーキテクチャの可視化

code-review-graph visualize

コミュニティ検出（Leiden アルゴリズム）を使用して、モジュールのクラスターを示すインタラクティブな可視化を生成します。次の用途に役立ちます。

• 新しいコントリビューターのオンボーディング
• アーキテクチャの乖離の特定
• 過度に結合したモジュールの発見

6. Wiki の生成

code-review-graph wiki

コードベースの構造をまとめた Markdown Wiki を生成します。各モジュール、その公開 API、依存関係、テストカバレッジが含まれます。

---

既知の制限事項

制限事項	影響	軽減策
動的インポート（require(variable)、import(buildPath())）	パーサーから依存関係が見えない	.code-review-graphignore に手動で記載するか、過剰な予測を許容する
リフレクションベースの呼び出し（Django シグナル、getattr()、Java リフレクション）	グラフのエッジを見落とす	こうしたコードベースには Serena（LSP ベース）の方が適しています
実行時に生成されるコード（eval、テンプレートエンジン）	静的解析時には解析できない	制限を許容するか、グラフから除外する
言語間の境界（Python から TypeScript API を呼び出す場合）	言語ランタイム間にエッジがない	部分的な回避策としてマルチリポジトリ登録を使用する
古いグラフ（ウォッチモードを使用しない場合）	Claude が古い関係を照会する	タスクの前に必ず code-review-graph update を実行するか、ウォッチモードを使用する
TypeScript のパスエイリアス（@/components/...）	tsconfig の解決設定が必要な場合がある	tsconfig_resolver.py がご利用の設定に対応しているか確認する

---

代替ツールの比較

ツール	アプローチ	メリット	デメリット	最適な用途
code-review-graph	Tree-sitter + SQLite	高速、19 言語対応、ローカル、依存関係なし	静的解析のみ	一般的な用途、大規模なコードベース
Claudette	Go での書き換え	単一バイナリ、Python 不要	対応言語が少なく、よりシンプル	Python を避けたいチーム
Serena	LSP ベース	高精度なセマンティック解析、型解決	セットアップが大変、低速	ポリモーフィズムが多いコードベース
code-graph-rag	RAG + ベクトル検索	自然言語でのクエリ	複雑なセットアップ	コードベースの探索
IDE 標準のコンテキスト機能	エディター組み込み	セットアップ不要	影響範囲を明示しない	シンプルなプロジェクト

---

AG Kit との統合

補完的なスキル

AG Kit スキル	どのように補完するか
context-compression	グラフは入力コンテキストを削減し、圧縮は出力の冗長性を削減します
coordinator-mode	グラフを認識したワーカーを正確なファイルリストでディスパッチできます
verify-changes	グラフに基づくレビューの後、実行によって変更を検証します
batch-operations	グラフの影響範囲が、どのファイルにバッチ更新が必要かを示します

推奨されるセッションアーキテクチャ

1. Start fresh session for each distinct task
2. Graph pre-filters context → AI reads only blast radius
3. Context compression summarizes completed phases
4. Memory system saves key decisions for next session
5. Result: minimum tokens, maximum quality

---

ベストプラクティス

1. 開発中は常にウォッチモードを実行する — 古いグラフは古いコンテキストを生み出します
2. 生成されたファイルを除外する — それらはノイズでグラフを膨らませます
3. まずベンチマークを取る — 導入なしで1週間、導入ありで1週間、トークン使用量を測定します
4. 出力制約と組み合わせる — グラフは入力を削減し、プロンプトエンジニアリングは出力を削減します
5. ビルド成果物、node_modules、dist/ には .code-review-graphignore を使用する
6. セッションを短く保つ — 新しいセッション + グラフ = 最適なトークン効率
7. マイクロサービスアーキテクチャにはマルチリポジトリ登録を