code-graph

コードグラフスキル

目的： コードグラフ（codebase-memory-mcp）を使って、サブミリ秒のシンボル検索、関数検索、依存関係の分析、影響範囲の検出を行います。コードのナビゲーションにおいて、手当たり次第の grep やファイル読み込みに代わる方法です。

---

基本原則

まずグラフ、次にファイルです。 ファイルを読んだり grep したりする前に、コードグラフに問い合わせます。ファイル全体を読むのは、変更が必要な場合や、グラフから得られる情報だけでは文脈が足りない場合に限ります。

計画時にもグラフの利用を検討します。 機能追加、リファクタリング、バグ修正など、変更を計画する際は、まずグラフに問い合わせて、範囲、依存関係、影響範囲を把握します。これは実装時だけでなく、検討や計画の段階にも当てはまります。文字列リテラル、ログメッセージ、設定値、コード構造の外にあるコンテンツの検索には、引き続き grep が適切なツールです。

┌────────────────────────────────────────────────────────────────┐
│  GRAPH FIRST, FILE SECOND                                      │
│  ─────────────────────────────────────────────────────────────│
│  The code graph indexes your entire codebase as a persistent   │
│  knowledge graph. Claude queries it via MCP for instant         │
│  symbol lookup, dependency chains, and blast radius — instead   │
│  of reading hundreds of files.                                 │
│                                                                │
│  14 MCP tools │ 64 languages │ sub-ms queries │ zero deps      │
│  ~99% fewer tokens for navigation vs brute-force file reads    │
├────────────────────────────────────────────────────────────────┤
│  AUTO-UPDATED                                                  │
│  ─────────────────────────────────────────────────────────────│
│  File watcher keeps graph in sync. Post-commit hook ensures    │
│  freshness. No manual rebuild needed.                          │
└────────────────────────────────────────────────────────────────┘

---

グラフと直接読み込みの使い分け

タスク	使用するグラフツール	直接読み込みを使うか
関数／クラスの定義を探す	search_graph	いいえ
関数のシグネチャとドキュメントを取得する	get_code_snippet	いいえ
関数の呼び出し元をすべて探す	trace_call_path	いいえ
依存関係の連鎖をたどる	query_graph	いいえ
変更の影響範囲を特定する	detect_changes	いいえ
プロジェクトのアーキテクチャを把握する	get_architecture	いいえ
コードパターンを検索する	search_code	いいえ
変更のために実装全体を読む	search_graph で場所を特定し、その後 Read でファイルを読む	はい
ビジネスロジックの文脈を理解する	概要の取得に get_code_snippet を使い、その後 Read で読む	はい

ルール： グラフツールで質問に答えられる場合は、そのツールを使います。ファイルを開くのは、編集のためにソース全体が必要な場合に限ります。

---

利用可能な MCP ツール

インデックス作成とステータス

ツール	目的	使用するタイミング
index_repository	プロジェクトのグラフを構築／再構築する	初回セットアップ時、または大規模な再構成の後
index_status	グラフが最新かどうかを確認する	最新状態か不明な場合、問い合わせの前に使用
list_projects	インデックス済みのプロジェクトを一覧表示する	複数プロジェクト間のナビゲーション

問い合わせとナビゲーション

ツール	目的	使用するタイミング
search_graph	名前からシンボルを検索する（あいまい検索）	「認証関連の関数を探す」
search_code	インデックス済みのコードベース全体をテキスト検索する	「TODO コメントを探す」、パターンマッチング
get_code_snippet	特定のシンボルのソースコードを取得する	シグネチャ、ドックストリング、実装が必要な場合
get_graph_schema	グラフの構造と関係を把握する	利用可能なデータを調べる場合
query_graph	構造化されたグラフクエリを実行する	複雑な依存関係／関係性の問い合わせ

分析

ツール	目的	使用するタイミング
trace_call_path	呼び出し元／呼び出し先の連鎖をたどる	「sendEmail() を呼び出すのは誰か？」「init() は何を実行するか？」
detect_changes	変更されたファイルと影響範囲を特定する	コード変更の前後、PR レビュー
get_architecture	モジュール／パッケージの大まかな構成を把握する	オンボーディング、プロジェクト構成の理解

管理

ツール	目的	使用するタイミング
delete_project	グラフからプロジェクトを削除する	クリーンアップ、プロジェクトの再構成
manage_adr	アーキテクチャ決定記録を管理する	アーキテクチャ上の決定を記録する
ingest_traces	実行時トレースをインポートする	パフォーマンス分析、デッドコードの検出

---

ワークフロー：コードを変更する前に

0. PLAN       → get_architecture + search_graph to understand scope before planning
1. LOCATE     → search_graph to find the symbol
2. UNDERSTAND → get_code_snippet for context
3. BLAST      → detect_changes to assess impact
4. TRACE      → trace_call_path to find all affected callers
5. CHANGE     → Read file, make edit
6. VERIFY     → detect_changes again to confirm scope

ステップ 0 はコーディング時だけでなく、計画時にも適用されます。 ユーザーから機能追加、リファクタリング、修正の計画を依頼されたら、まずグラフに問い合わせて、何が存在するか、何が何に依存しているか、対象範囲がどの程度かを把握します。これにより、コードベースについての誤った前提に基づく計画を防げます。

ステップ 3 を絶対に省略しないでください。 影響範囲の分析によって、共有コードの変更による予期しない破損を防げます。

---

グラフデータと最新性

グラフは3つのレイヤーを通じて自動的に最新の状態に保たれるため、手動で再構築する必要はありません。

レイヤー	トリガー	動作
ファイルウォッチャー	ファイルを保存するたび	codebase-memory-mcp が変更を検出し、影響を受けたファイルをリアルタイムで再インデックスします
自動インデックス	セッション開始時	auto_index: true により、Claude Code の起動時にグラフが最新の状態になります
コミット後フック	git commit のたび	.code-graph/.needs-update マーカーに触れます。ファイルウォッチャーがこれを検出します（約10ms、ノンブロッキング）。

大規模な再構成（ディレクトリ全体の名前変更、大量の差分を伴うブランチ切り替えなど）を行わない限り、手動で再インデックスする必要はありません。その場合は、index_repository を一度実行すれば、その後は3つのレイヤーが最新の状態を保ちます。

• ストレージ：.code-graph/ ディレクトリ（自動作成、Git の追跡対象外）
• MCP 設定：プロジェクトルートの .mcp.json（コミットされ、チームで共有）

---

MCP の設定

コードグラフ MCP サーバーは、プロジェクトルートの .mcp.json で設定します。

{
  "mcpServers": {
    "codebase-memory": {
      "command": "codebase-memory-mcp",
      "args": []
    }
  }
}

インストール： ~/.claude/install-graph-tools.sh

---

判断のフレームワーク

Need to find a symbol/function?
  → search_graph (sub-ms, structured result)
  → NOT: grep -r "functionName" (slow, unstructured)

Need to understand dependencies?
  → query_graph or trace_call_path (complete, traversable)
  → NOT: manually reading import statements

Need to assess change impact?
  → detect_changes (comprehensive, instant)
  → NOT: searching for usages manually across files

Need to understand architecture?
  → get_architecture (high-level overview)
  → NOT: reading every directory listing

Need to read/modify code?
  → search_graph to locate, then Read the specific file
  → NOT: reading entire directories hoping to find it

---

アンチパターン

アンチパターン	代わりに行うこと
関数名を grep で検索する	関数名を指定して search_graph を使います
シグネチャを探すためにファイル全体を読む	対象のシンボルに対して get_code_snippet を使います
インポートの連鎖を手動で追跡する	trace_call_path または query_graph を使います
影響を確認せずに変更する	共有コードを編集する前に必ず detect_changes を実行します
ディレクトリ内のファイルをすべて読む	構造の確認には get_architecture、詳細の確認には search_graph を使います
グラフが古いという警告を無視する	index_status を確認し、必要に応じて再インデックスします
クエリのたびに再インデックスする	ファイルウォッチャーに任せます。手動での再インデックスは、大規模な再構成の後にのみ行います