ナレッジグラフでClaude Codeのトークン消費を最大49倍削減する方法

はじめに

Claude Codeのヘビーユーザーなら誰もが直面する問題があります。トークン消費量とコストです。

Anthropicの公式データによると、Claude Codeの平均コストは1開発者あたり日6ドル、90%のユーザーは日12ドル以下に収まります。チーム利用（Sonnet 4.6）では月100〜200ドルが目安です（Manage costs effectively - Claude Code公式ドキュメント）。ヘビーユーザーはこの範囲を大きく超えます。

2026年3月、code-review-graphの開発者Tirth Kanani氏が、ナレッジグラフによるトークン削減効果を実測値付きで報告しました。レビュータスクで平均6.8倍、日常的なコーディングで最大49倍という削減率です（Medium記事）。

本記事では、なぜLLMがコンテキストを大量に消費するのかを技術的に解説し、ナレッジグラフによる解決策を具体的に説明します。

なぜLLMはコンテキストを大量に消費するのか

トークン消費の問題を理解するには、Transformerアーキテクチャの内部動作を知る必要があります。

Attentionの計算コスト：O(n^2)の壁

Transformerの中核であるSelf-Attention機構は、入力の各トークンが他のすべてのトークンとの関連度を計算します。Query(Q)とKey(K)の内積で注意重みを算出し、Value(V)に適用する処理です。

Attention(Q, K, V) = softmax(QK^T / sqrt(d_k)) V

この計算量はシーケンス長nに対してO(n^2)です。1,000トークンなら100万回、10,000トークンなら1億回の注意計算が走ります。不要なトークンを送るコストは線形ではなく二次関数的に増大します。

KVキャッシュとメモリコスト

推論時、各トークンのKeyとValueベクトルはKVキャッシュに保存されます。新しいトークン生成のたびに過去のすべてのK/Vを参照するためです。KVキャッシュサイズは 2 × レイヤー数 × ヘッド数 × シーケンス長 × ヘッド次元 で決まり、大規模モデルでは数十GBのGPUメモリを消費します（KV Caching Explained - Hugging Face）。これがAPI利用料金に直結し、不要なコードを送るほどコストが増加します。

Claude Codeにおける具体的なトークン消費

Claude Codeはリクエストのたびに以下をコンテキストとして送信します。

• CLAUDE.mdやルールファイル（プロジェクト設定）
• ツール定義（Read, Edit, Bash等の呼び出しスキーマ）
• 会話履歴全体
• ツール実行結果

これらだけで数千トークンを消費します。さらにコードレビューや修正時には、ファイル全体を読み込みます。1,000行のファイルで必要なのが1つの関数（20行）だけでも、残り980行分のトークンが無駄になります。セッションが長くなると会話履歴も積み上がり、auto-compactが走るまで全履歴がトークンとしてカウントされ続けます。

ナレッジグラフによる解決：必要な構造だけを取得する

ナレッジグラフは、コードベースの構造をノードとエッジのグラフとして表現する手法です。

• ノード：ファイル、関数、クラス、変数、インターフェース
• エッジ：import関係、関数呼び出し、クラス継承、テストカバレッジ

# 従来のアプローチ
Claude Code → ファイル全文を読む → 大量のトークン消費

# ナレッジグラフのアプローチ
Claude Code → グラフに問い合わせ → 必要な関数・依存関係だけ取得

ファイル全文を送る代わりに、関連するノードとエッジだけを送ります。不要なコードがコンテキストに入らないため、Attentionの二次関数的なコスト増を根本から抑制できます。

tree-sitterによるAST解析の仕組み

ナレッジグラフの構築にはtree-sitterが使われます。tree-sitterはGitHubが開発した増分パーサーで、ソースコードをAST（抽象構文木）に変換します。

処理の流れは、(1) 言語ごとの文法定義に基づきソースコードをパースしてAST生成、(2) ASTを走査して関数定義・クラス定義・import文などのノードを抽出、(3) ノード間の関係（呼び出し、継承、依存）をエッジとして記録、(4) SQLiteに永続化、です。

# tree-sitterによるAST解析のイメージ（簡略化）
import tree_sitter

parser = tree_sitter.Parser()
parser.set_language(tree_sitter.Language("languages.so", "python"))
tree = parser.parse(source_code)

for node in walk_tree(tree.root_node):
    if node.type == "function_definition":
        name = node.child_by_field_name("name").text
        graph.add_node(name, type="function", file=filepath)
    elif node.type == "call":
        caller = get_enclosing_function(node)
        callee = node.child_by_field_name("function").text
        graph.add_edge(caller, callee, type="calls")

tree-sitterの増分パーシングにより、ファイル編集時は変更箇所のみを再パースします。これが差分更新の高速性を支えています。

実測データ：どの程度削減できるのか

code-review-graphのベンチマークレポートから、実測値を示します。

プロジェクト	ファイル数	レビュー時の削減率
httpx	125	26.2倍
FastAPI	2,915	8.1倍
Next.js	27,732	6.0倍
平均	-	6.8倍

日常的なコーディングタスクでは、Next.jsプロジェクトでレート制限ミドルウェアを追加するタスクにおいて49倍の削減が報告されています。27,000超のファイルからグラフが必要な15ファイルだけを特定し、約16,000ファイルの読み込みをスキップした結果です。

削減の原理を具体的な数値で示します。

# Next.jsプロジェクトで「レート制限ミドルウェアを追加する」タスクの場合

従来：関連ファイルの探索 + 全文読み込み ≒ 約739,000トークン
ナレッジグラフ：対象の15ファイルの関連構造のみ ≒ 約15,000トークン

削減率：739,000 / 15,000 ≒ 49倍

大規模コードベースほど「無関係なコード」の割合が増えるため、削減効果が大きくなります。

削減率はコードベースの構造に強く依存します。モジュール分割が明確なプロジェクトほど効果が高く、密結合なモノリシックコードでは効果が限定的です。

code-review-graphの導入

手軽な導入方法として、code-review-graphがあります。tree-sitterでASTを解析し、SQLiteにグラフを保存し、MCP経由でClaude Codeに提供するツールです。Python製で19以上の言語に対応しています。

インストールと設定

# pipでインストール（Python 3.10以上が必要）
pip install code-review-graph

# Claude Code用に自動設定（対応プラットフォームを自動検出）
code-review-graph install

# コードベースのグラフを構築
code-review-graph build

code-review-graph installは対応プラットフォームを自動検出して設定します。手動で特定のプラットフォームだけを設定する場合は--platform claude-codeオプションが使えます。

手動でMCP設定を行う場合は、.mcp.jsonに以下を追加します。

{
  "mcpServers": {
    "code-review-graph": {
      "command": "code-review-graph",
      "args": ["serve"]
    }
  }
}

初回ビルドは500ファイルのプロジェクトで約10秒です。以降はファイル編集やgit commitのたびにSHA-256ハッシュによる差分検出で増分更新されます。

動作の仕組み

設定後、Claude Codeは自動的にグラフを参照します。コードレビューを依頼すると、変更ファイルの影響範囲（blast radius）をグラフ上で計算し、呼び出し元、依存先、関連テストを含む必要最小限のコンテキストだけを取得します。

Codebase-Memoryとの比較

より高性能なアプローチとして、Codebase-Memoryがあります。2026年3月にarXivで発表された研究（arXiv:2603.27277、Martin Vogelら）に基づくツールです。

以下の比較表で両者の違いを整理します。

観点	code-review-graph	Codebase-Memory
アプローチ	Python製、グラフ + SQLite	静的バイナリ（C++）、グラフ + SQLite
対応言語	19言語以上	66言語
型解析	tree-sitter ASTベース	tree-sitter + LSP型ハイブリッド（Go, C, C++）
MCP機能	コードレビュー特化	14種類（検索、トレース、影響分析、デッドコード検出、Cypherクエリ等）
セットアップ	pip install + build	シングルバイナリ、依存関係なし
インデックス速度	500ファイルで約10秒	Linuxカーネル（2,800万行）を3分
クエリ応答	高速	サブミリ秒
可視化	なし	3DインタラクティブUI（オプション）
評価結果	レビューで平均6.8倍削減	ファイル探索比で120倍削減（構造クエリ5回で約3,400トークン vs 約412,000トークン）、回答品質83%（ファイル探索の92%比）
ライセンス	MIT	プロプライエタリ

code-review-graphはOSSの手軽さが強みで、日常的なコードレビューのトークン削減に適しています。Codebase-Memoryは性能と機能の幅が突出しており、大規模コードベースでの高度な分析に力を発揮します。ただし回答品質はファイル探索エージェントの92%に対して83%で、構造的な情報で十分なケースに最適化されています。

コンテキスト最適化の他の手法との組み合わせ

ナレッジグラフは単独でも効果的ですが、他の手法と組み合わせると効果が最大化します。

• サブエージェント委譲：調査タスクを独立したコンテキストで実行し、メインセッションには結果の要約だけを返す。グラフと併用すればサブエージェント側のコンテキストも最小化される
• 戦略的compact：auto-compactを待たず、タスクのフェーズ切替時に手動/compactを実行する。会話履歴が要約され、以降のKVキャッシュ消費が大幅に減る
• MCP result persistence：Claude Code v2.1.91で追加された機能（リリースノート）。MCPツールの大きな返却結果をディスクに永続化し、_meta["anthropic/maxResultSizeChars"]で最大500,000文字まで許容できる。グラフのクエリ結果を永続化すれば再取得コストを削減できる
• RAGとの補完：RAGはベクトル類似度による意味検索が得意だが、コードの構造的依存関係の把握には向かない。構造クエリはグラフ、意味クエリはRAGと使い分けることで精度の高いコンテキスト取得が実現する

組み合わせの全体像

1. ナレッジグラフ  → 構造的に必要なコードだけを取得（トークン削減の核）
2. サブエージェント → 調査タスクを分離してメインコンテキストを保護
3. 戦略的compact   → フェーズ切替時に会話履歴を圧縮
4. MCP永続化       → 大きなツール結果の再取得を回避
5. RAG             → 意味的な検索でグラフの補完

ナレッジグラフで入力を最小化し、compactで履歴を圧縮し、サブエージェントで並列処理を分離する。この三層構造がトークン消費の総合的な抑制を実現します。

効果が出る条件と限界

効果が大きいケース

• ファイル数が1,000以上の大規模プロジェクト
• モジュール分割が明確（マイクロサービス、クリーンアーキテクチャ等）
• コードレビューや既存コードの修正が主な用途

効果が限定的なケース

• ファイル数が100以下の小規模プロジェクト
• 密結合でファイル間の依存が広範囲に及ぶコード
• 新規ファイルの作成が主な作業（グラフにまだ情報がない）

オーバーヘッド

グラフの構築・維持にもコストがかかります。

• 初回ビルド：500ファイルで約10秒（code-review-graph）、2,800万行で3分（Codebase-Memory）
• 差分更新：数ファイル変更で2秒以下
• ディスク容量：プロジェクトサイズの数%

大規模プロジェクトではこのオーバーヘッドはトークン削減効果に対して十分にペイします。

まとめ

ナレッジグラフは、Claude Codeのトークン消費問題に対する構造的な解決策です。TransformerのAttention計算がO(n^2)である以上、不要なトークンを送るコストは線形ではなく二次関数的に増大します。「ファイル全体を読む」から「必要な構造だけを取得する」への転換が、この根本的な問題を解決します。

導入のステップは以下の通りです。

1. pip install code-review-graphでインストール
2. code-review-graph installでClaude Code用に設定
3. code-review-graph buildでグラフを構築

より高度な分析が必要なら、Codebase-Memoryの66言語対応と14種類のMCPツールも検討してください。

トークン節約は単一の手法では限界があります。ナレッジグラフ、サブエージェント委譲、戦略的compact、MCP result persistence、RAGといった複数の手法を重ねることで、コスト削減と応答品質の両立が実現します。

参考リンク

• code-review-graph（GitHub）
• I Built a Knowledge Graph That Cuts Claude Code's Token Usage by 49x（Medium）
• Codebase-Memory（GitHub） / arXiv:2603.27277
• Manage costs effectively（Claude Code公式）
• Claude Code v2.1.91 リリースノート
• KV Caching Explained（Hugging Face）