前の記事では、graphify がプロジェクトをナレッジグラフ化する仕組みを見ました。今回は「Claude Code を大規模コードベースで使うときに何が起きているか」を起点に、graphify がどうその問題に対処するかを解説します。

問題：ファイルを読み回るコスト

Claude Code に「認証フローを教えて」と聞いたとき、何が起きるでしょうか。

コンテキストに関連ファイルがなければ、Claude Code は探索を始めます。まず Glob でファイル一覧を取り、怪しそうなファイルを Read し、その中の関数呼び出し先を追ってまた Read する——という具合です。10 ファイル程度の小さなプロジェクトなら問題ありません。しかし数百ファイルのモノレポや長期運用プロジェクトになると話が変わります。

  • 「このモジュールはどこから呼ばれているか」の回答に 30 回の Read が走る
  • コンテキストウィンドウが埋まり、早い段階で古い会話が押し出される
  • API コストが膨らむ、応答が遅くなる

問題の本質は、コードベース全体の「地図」がないために、毎回一から探索しているところにあります。

アプローチ：グラフを地図として使う

graphify は /graphify . でプロジェクト全体のナレッジグラフを graph.json として出力します。このファイルには、ファイル・関数・モジュール・ドキュメント間のすべての接続情報が圧縮されています。

地図があれば目的地への最短経路だけ走れば済む、というのが発想の核心です。「認証フローはどこにあるか」をグラフへのクエリで先に絞り込み、関係するファイルだけを Read する。全探索を構造的なクエリに置き換えます。

PreToolUse フックの仕組み

graphify claude install を実行すると、2 箇所に設定が書き込まれます。

CLAUDE.md には「ファイルを読む前に graph.json を参照せよ」という指示が追記されます。Claude Code はプロジェクト全体のルールとして CLAUDE.md を読み込むため、この指示がセッション開始時から有効になります。

.claude/settings.json には PreToolUse フックが追加されます。PreToolUse フックは、ツール呼び出しの直前に発火する仕組みです。Claude Code が Read・Glob・Bash による検索を実行しようとした瞬間、フックが割り込んで graphify query を先に実行するよう誘導します。

Claude Code が Read を呼ぼうとする
     ↓
PreToolUse フックが発火
     ↓
graphify query で関連ノードを取得
     ↓
ヒットしたファイルだけ Read する

フックは「Read を禁止する」のではなく「まず地図を確認してから読む」という順序を強制します。必要なら全ファイルを読めますが、多くの問いはグラフへのクエリだけで解決します。

Before / After の対比

フックなしの場合

質問: 「認証フローを教えて」
→ Glob で src/ 配下を列挙（1 回）
→ auth.ts を Read（2 回目）
→ auth.ts が呼ぶ userService.ts を Read（3 回目）
→ userService.ts が使う db.ts を Read（4 回目）
→ db.ts の設定ファイルを Read（5 回目）
...（以降、依存を辿りながら続く）

フックありの場合

質問: 「認証フローを教えて」
→ PreToolUse フックが発火
→ graphify query "auth flow" を実行
→ 関連ノード: auth.ts, userService.ts, db.ts が返る
→ 3 ファイルだけ Read して回答

探索の起点がグラフのクエリ結果に変わるため、Read 回数が大幅に減ります。コンテキスト消費量の削減はそのまま API コストの削減と応答速度の向上につながります。

チームでの運用

graphify-out/ ディレクトリを git コミットしておけば、チーム全員が初日からグラフを使えます。新しいメンバーがリポジトリを clone した瞬間に、プロジェクト全体の構造情報が手元に揃います。

コミットのたびにグラフを最新化したい場合は graphify hook install を使います。git の pre-commit フックに AST 再構築が組み込まれ、コードが変わるたびにグラフが自動で更新されます。AST 解析はローカルで動くため、この自動更新に API コストはかかりません。

まとめ

  • 大規模コードベースでは Claude Code が grep → Read を繰り返し、コンテキストとコストを消費する
  • graphify は graph.json をプロジェクトの「地図」として使い、全探索を構造化クエリに置き換える
  • graphify claude install が CLAUDE.md と PreToolUse フックを設定し、Read 前にクエリを促す仕組みを自動で組み込む
  • グラフを git コミットすれば、チーム全員が即日使える
  • graphify hook install でコミットごとの自動再構築が可能（API コストなし）

次の記事では God nodes——コードベースの中で最も多くの依存を集める急所——を取り上げます。どのノードから読めば全体を最速で把握できるかを、グラフ構造から読み解いていきます。

出典