Knowledge Graph×MCPでAIコードレビューを8〜49倍圧縮

「AIコードレビューでトークンが8〜49倍削減された」というベンチ結果を私は以前書きました。数字だけ独り歩きしても再現できません。「どうやって同じ設計を組むか」の方が10倍問い合わせが来ます。本記事では、Knowledge Graph×MCPでレビュートークンを圧縮する 設計の3層 を分解して書きます。

前提として、Tree-sitter は2026年7月時点で306言語のプリコンパイル済み grammar が pack として利用可能で、Python/TypeScript/Go/Rust/Java/C/C++/Ruby/C#/PHP/Kotlin/Scala/Swift まで実務品質の対応が揃っています。「私のスタックには対応してない」で躓く可能性は、もう小さいです。

「全ファイル症候群」から Graph 前提へ

Claude Code に「リポジトリ全部読んでレビューして」と頼んだ夜、返ってきた指摘の8割はその PR で変更していないファイルの話でした。あるあるだと思います。AI に全部読ませると、AI は全部について語ります。

でも本当に必要なのは「変更された1行が、他のどこに波及するか」だけです。この問いに答えられれば、コンテキストは変更ファイル+呼び出し関係の周辺だけで済みます。ここで登場するのが Knowledge Graph です。

問題は「Knowledge Graph をどう組むか」です。設計次第で、レビュー時に AI に渡すトークンが 10倍以上変わります。私が使っている設計を3層に分けて紹介します。

第1層: 抽出層 — Tree-sitter で構造だけ取る

第1層は 決定論的な構造抽出 です。Tree-sitter で AST を舐めて、次の5種類のノードだけを取ります。

• File: パス、言語、行数
• Module: import 対象になる名前空間(Python の module、JS の package、Go の package)
• Class: クラス定義。名前、所属ファイル、行範囲
• Function: 関数・メソッド定義。名前、所属、シグネチャ、行範囲
• Variable: モジュールスコープの変数(関数内ローカルは含めない)

関数内ローカル変数まで全部ノード化する誘惑に負けないでください。ノード数が一桁増えるだけで、レビュー精度はほとんど変わりません。「必要になってから足す」を守ります。

エッジも6種類で十分です。CONTAINS、IMPORTS、CALLS、INHERITS、IMPLEMENTS、REFERENCES。全部 Tree-sitter が返す AST から機械的に引けます。ここまでは LLM を1回も呼びません。

30万行のリポジトリで、この第1層の処理は1回目のフルビルドで数十秒、以降の差分ビルドで数百ミリ秒。Tree-sitter がインクリメンタルに動くのでコストが線形にスケールしません。

第1層で引いたエッジには confidence: 1.0 のプロパティを付けます。これが第2層と決定的に効いてきます。

第2層: 推論層 — LLM は「動的呼び出し」だけに呼ぶ

Tree-sitter だけでは取れない情報が3つあります。

• 動的呼び出し — Python の getattr 経由呼び出し、JS の obj[method_name]()、Go の interface 経由
• 設計意図タグ — 「この関数はドメインでいう payment レイヤーに属する」といった意味的分類
• 暗黙のインターフェース — Duck typing で「同じ形」を実装しているクラス群

これらは LLM でしか推論できません。ただし、素朴に全関数を LLM に投げると、Claude Sonnet で数百ドル飛びます。ここでコストを効かせるのが「ホット/コールド戦略」です。

• コールド(全体): 第1層だけを1回走らせてベースラインのグラフを作る
• ホット(差分): 変更されたばかりの関数だけ、第2層で意図推論

第2層で LLM に渡すコンテキストも絞ります。ファイル全体を渡すと、第2層の中で再び「全ファイル症候群」が起きます。私が渡すのはこの4つだけです。

• 対象関数の本体(必須)
• 属するクラスやモジュールの docstring
• 呼び出し元 1-2 関数のシグネチャ
• 呼び出し先 1-2 関数のシグネチャ

これで第2層1回あたりの入力トークンは 200-800 トークンに収まります。周辺の情報は第1層で構築済みのグラフから瞬時に取れるので、LLM に「探させる」必要がありません。

第2層で引いたエッジには confidence: 0.0-0.9 を付けます。第1層と第2層をエッジのプロパティで区別できるようにしておくと、レビュー時のクエリで閾値を絞れます。

第3層: 露出層 — MCP ツールは「1ツール1質問パターン」

第3層は Claude Code や Cursor に対して MCP ツールとして露出する層です。ここで設計を誤ると、AI が「どのツールを呼ぶか」で迷い、余計な往復が発生してトークンが焼けます。

先行 OSS の CodeGraph は22種類のツール、Code Pathfinder は6種類のツールを露出しています。この22という数字は、4軸(構造/依存/検索/メトリクス)×各軸5-6ツールから来ています。

私が最小構成として推奨するのは、この5ツールです。

1. get_function(name) — シグネチャ、行範囲、所属クラスを返す
2. get_callers(name, max_hops=1) — 直接の呼び出し元
3. blast_radius(name, max_hops=3, min_confidence=0.8) — 影響範囲(閾値で第1層のみに絞れる)
4. search_symbols(query, type="function|class") — シンボル検索
5. get_file_summary(path) — ファイル単位のサマリ

粒度の原則は 1ツール1質問パターン です。get_callers と blast_radius は機能が重なって見えますが、別ツールとして立てます。前者は「直接の呼び出し元1階層」を返してレビュー時に多用され応答が軽い、後者は「Hop ごとの呼び出し元集合」を返して設計判断に使い応答がやや重い。命名で意図を分けるとトークン効率が良くなります。

ツールの description も雑に書くと事故ります。3行構成で書きます。

1. 何を返すかを簡潔に
2. 返り値の形を具体的に
3. いつ使うか / 似たツールとの使い分け

「似たツールとの使い分け」があると、AI が blast_radius と get_callers のどちらを呼ぶべきか迷いません。ないと両方呼んで重複したり、間違った方を選んで再度別のツールを呼びなおしたりします。この往復が地味にトークンを焼きます。

3層構成でトークンが8〜49倍削減される内訳

削減の幅が広いのは、質問の性質で圧縮率が変わるからです。

• 狭いスコープの質問(「この関数のシグネチャは?」): 全ファイル読み 240万トークン → get_function 1回 300トークン → 8000倍削減 (これは外れ値なので上限として置いています)
• 中程度のスコープ(「この関数を変えたら何が壊れる?」): 240万トークン → blast_radius(max_hops=3) 5-10 ツール呼び出し合計 5万トークン → 49倍削減
• 広いスコープ(「このモジュール全体の設計を教えて」): 240万トークン → 検索+要約系ツール10回合計 30万トークン → 8倍削減

「広いスコープでも8倍以上は縮む」というのがこの設計の実務価値です。減らすほど質問の解像度が下がるトレードオフはないんですね。むしろ AI が「関係ある部分だけ」を見るので、指摘の精度が上がります。

サイバーエージェント社の Developers Blog が「Cursor、Claude Code、Codex 導入でコミット数が約2倍に増えたが、レビュー側がボトルネックになった」と報告しています。生産性向上のボトルネックは「コードを書く」から「コードを理解する」に移りました。理解の効率は AI に何を渡すかで決まります。全ファイルか、変更の影響範囲だけか。この分岐で3層構成が効きます。

MCP 2026 spec との整合

Model Context Protocol は2025年後半に resources / tools / prompts の3プリミティブに整理され、2026年時点でも基本構造は維持されています。上の設計は tools プリミティブに Knowledge Graph のクエリを載せる形なので、spec に素直に乗ります。

resources プリミティブに「ファイルの中身」を露出する誘惑もありますが、私は基本的に使いません。ファイルの中身を AI が読む時点で「全ファイル症候群」に戻るからです。露出するのは Knowledge Graph 経由の要約と関数単位のスライスだけに絞る、というのがこの設計の一貫した思想です。

今日から試せる最小構成

第1層と第3層の最小5ツールから始めるのを勧めます。第2層は「動的呼び出しがレビュー精度に効く」と確信してから足しても遅くありません。多くのプロジェクトは、第1層だけで実測10倍以上のトークン削減が出ます。

段階的に足すと、どの層がどれだけ効いているか計測できるので、あとから「第2層は要らなかった」と分かることもあります。それは失敗ではなく、正しい判断です。

3層設計の全体像(Kuzu vs Neo4j のグラフDB選定、Pass1/Pass2 の実装コード、22ツールへの拡張パス)は Knowledge Graph 実装ガイド にまとめています。本記事は入口です。