Claude Codeの推測を排除する：ナレッジグラフによるAI開発の最適化

我々エンジニアがAIコーディングエージェント、特にClaude Codeのようなツールを実務で使い始めたとき、最初に直面する「壁」は、AIがコードの全体像を把握できていないことによる推測の連鎖だ。AIは質問のたびにファイルを読み込み、その場しのぎの文脈を組み立てる。これはまるで、スパゲッティコードの迷宮で地図を持たずに彷徨う新人のようなものだ。結果として、AIは「おそらくこうだろう」という推測に基づいた回答を生成し、我々はそれを修正するために貴重な時間を浪費する。この「推測」を排除し、確実な構造的理解をAIに与える唯一の解が、コードをナレッジグラフとして構造化することである。

今回紹介する手法は、code-review-graph、better-code-review-graph、Graphify、そしてSerenaという4つのOSSツールを組み合わせ、コードの依存関係をグラフ化してClaude Codeに渡すというものだ。これにより、AIはファイルを全読みすることなく、「verifyTokenはgetConnectionに依存している」といった構造的真実を即座に把握できる。これは単なる効率化ではない。AIの推論プロセスを「確率的な推測」から「グラフ探索による論理的な導出」へと昇華させるパラダイムシフトだ。我々が深夜の障害対応でデッドロックに頭を抱える際、AIが「どの関数がどのリソースをロックしているか」をグラフから正確に提示できれば、解決までの時間は劇的に短縮されるはずだ。

特筆すべきは、この手法がもたらすトークン消費の劇的な削減だ。実測データによれば、全文読み込み時に最大14万トークンを消費していたレビュー用コンテキストが、グラフ経由ではわずか70トークンにまで圧縮された。これは約2000分の1という驚異的な数値であり、コスト面だけでなく、AIのコンテキストウィンドウを汚染せず、より本質的なタスクに集中させるための極めて合理的なエンジニアリングであると私は考える。

複数のツールを導入した際、最大の懸念は「どのツールをいつ使うか」という判断のオーバーヘッドだ。しかし、CLAUDE.mdにルーティングルールを記述することで、この問題は驚くほどエレガントに解決される。質問の種類に応じて、AIは自律的に最適なツールを選択する。例えば、「認証の仕組みは？」という抽象的な問いにはGraphifyがコードと設計書を横断し、「NotificationChannelの定義元は？」という具体的な問いにはSerenaがLSP経由で正確な行番号を返す。このルーティングの精度は、もはや魔法に近い。ツール名を明示せずとも、質問の「形」から意図を汲み取り、適切なバックエンドへ振り分ける仕組みは、まさに我々が目指すべき自律的な開発環境の姿だ。

以下に、このシステムにおけるツール選択の基準を整理する。このテーブルは、単なる設定値ではなく、AIエージェントを指揮するための「指揮官の地図」である。

ただし、ここで注意すべきは「過信の排除」だ。セキュリティスキャンにおいて、内蔵のSemgrepルールだけではSQLインジェクションや秘密鍵の漏洩を完全に防ぐことはできない。グラフツールはあくまで「構造の可視化」に特化しており、静的解析の深さについてはSnyk等の専門ツールと併用するのがプロのエンジニアとしての矜持だろう。ツールを組み合わせることは、単に便利にするだけでなく、それぞれのツールの限界を理解し、多層防御的なアプローチをとることに他ならない。

セットアップは確かに手間がかかる。Python 3.13の環境構築、uvによるパッケージ管理、そしてCLAUDE.mdへのルーティング記述。しかし、この初期投資を惜しむエンジニアは、一生「AIの回答を疑い、ファイルをgrepし続ける」という無限ループから抜け出せない。一度この「聞けばわかる」環境を構築してしまえば、戻ることは不可能だ。なぜなら、我々の脳内にある「コードの地図」が、AIと完全に同期する感覚を一度味わえば、それが開発における標準（スタンダード）になるからだ。

最後に、我々エンジニアに突きつけられた問いを投げかけたい。AIがコードの構造を完全に理解し、影響範囲を瞬時に特定できるようになったとき、我々人間が担うべき「設計」の価値とは何だろうか？ 単なる実装の記述はAIに任せ、我々は「グラフのノード同士がどうあるべきか」という、より高次のアーキテクチャ設計に集中すべきではないか。この技術は、我々をコードの海から解放し、より創造的な領域へと押し上げるための強力なレバレッジである。

明日から取るべきアクションは明確だ。まずは小規模なプロジェクトでこの構成を試し、グラフが可視化する「密結合の箇所」を直視すること。そして、AIが提示する影響範囲分析と、自分の直感を照らし合わせること。もしAIの分析が自分の直感を超えたなら、その時こそが、あなたの開発スタイルがアップデートされた瞬間である。技術の進化をただ眺めるのではなく、自らの手で「推測」を排除し、確実な論理の上に開発を積み上げていく。それが、シニアエンジニアとして生き残るための唯一の道であると私は確信している。