コードグラフスキル

目的: コードグラフ(codebase-memory-mcp)を使用して、サブミリ秒単位でシンボル検索、関数検索、依存関係の分析、影響範囲検出を行います。これにより、コード内の単純なgrep検索やファイル読み込みの代わりになります。

---

コア原則

グラフが先、ファイルは次。 ファイルを読むかgrepする前に、必ずコードグラフにクエリを実行します。グラフが提供する情報以上の内容が必要な場合、または変更が必要な場合にのみ、ファイル全体を読み込みます。

計画段階でグラフを活用する。 機能追加、リファクタリング、バグ修正など、あらゆる変更を計画する際は、まずグラフにクエリを実行して、スコープ、依存関係、影響範囲を理解します。これは実装フェーズだけでなく、検討・計画フェーズにも適用されます。Grepは文字列リテラル、ログメッセージ、設定値、コード構造外に存在するコンテンツの検索に最適なツールです。

┌────────────────────────────────────────────────────────────────┐
│  グラフが先、ファイルは次                                       │
│  ─────────────────────────────────────────────────────────────│
│  コードグラフはコードベース全体をパーシステントナレッジグラフ   │
│  としてインデックス化します。Claudeはそれをmcpを介して        │
│  クエリし、数百のファイル読み込みの代わりに、シンボル検索、   │
│  依存関係チェーン、影響範囲をインスタントに取得できます。      │
│                                                                │
│  14 MCP ツール │ 64 言語 │ サブミリ秒クエリ │ 依存なし        │
│  ファイル読み込みによるナビゲーション比で約99%トークン削減    │
├────────────────────────────────────────────────────────────────┤
│  自動更新                                                      │
│  ─────────────────────────────────────────────────────────────│
│  ファイルウォッチャーがグラフを同期状態に保ちます。             │
│  コミット後フックで最新性を確保します。                        │
│  手動で再構築する必要はありません。                            │
└────────────────────────────────────────────────────────────────┘

---

グラフとダイレクト読み込みの使い分け

タスク	グラフツールを使用	ダイレクト読み込み
関数/クラス定義を検索	search_graph	いいえ
関数シグネチャ + ドキュメント取得	get_code_snippet	いいえ
関数の呼び出し元をすべて検索	trace_call_path	いいえ
依存関係チェーンを追跡	query_graph	いいえ
変更の影響範囲を判断	detect_changes	いいえ
プロジェクトアーキテクチャを理解	get_architecture	いいえ
コードパターンを検索	search_code	いいえ
完全な実装コードを読んで変更	search_graphで位置を特定、その後ファイル読み込み	はい
ビジネスロジックコンテキストを理解	get_code_snippetで概要確認、その後読み込み	はい

ルール: グラフツールが質問に答えられる場合は、グラフツールを使用します。編集のために完全なソースコードが必要な場合にのみファイルを開きます。

---

利用可能な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. 計画       → get_architecture + search_graph で計画前にスコープを理解
1. 位置特定   → search_graph でシンボルを検索
2. 理解       → get_code_snippet でコンテキストを取得
3. 影響範囲   → detect_changes で影響を評価
4. 追跡       → trace_call_path で影響を受けるすべての呼び出し元を検索
5. 変更       → ファイルを読み込み、編集を実施
6. 確認       → detect_changes を再度実行してスコープを確認

ステップ0はコーディングだけでなく計画にも適用されます。 ユーザーが機能計画、リファクタリング、修正を依頼する場合、まずグラフにクエリを実行して、何が存在し、何が何に依存し、スコープがどのようであるかを理解します。これにより、コードベースについての誤った仮定に基づいた計画を防ぎます。

ステップ3を決してスキップしないでください。 影響範囲分析により、共有コードへの変更によって予期しない問題が発生するのを防ぎます。

---

グラフデータと最新性

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

レイヤー	トリガー	実行内容
ファイルウォッチャー	ファイル保存時	codebase-memory-mcpが変更を検出し、影響を受けたファイルをリアルタイムで再インデックス
自動インデックス	セッション開始時	auto_index: trueによりClaudeコード起動時にグラフが最新
コミット後フック	git commit時	.code-graph/.needs-updateマーカーに接触 — ファイルウォッチャーが検出(約10ms、ノンブロッキング)

手動でのインデックス再構築は不要です。 ディレクトリ名の変更やブランチ切り替えによる大規模な変更がある場合のみ index_repository を実行し、その後は3つのレイヤーが最新性を保ちます。

• ストレージ: .code-graph/ディレクトリ(自動作成、gitignore)
• MCP設定: プロジェクトルートの.mcp.json(コミット、チーム間で共有)

---

MCP設定

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

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

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

---

判断フレームワーク

シンボル/関数を検索する必要がある場合
  → search_graph (サブミリ秒、構造化結果)
  → NOT: grep -r "functionName" (低速、非構造化)

依存関係を理解する必要がある場合
  → query_graph または trace_call_path (完全、トラバーサル可能)
  → NOT: インポートステートメントを手動で読む

変更の影響を評価する必要がある場合
  → detect_changes (包括的、インスタント)
  → NOT: ファイル全体でのUsage手動検索

アーキテクチャを理解する必要がある場合
  → get_architecture (高レベル概要)
  → NOT: すべてのディレクトリリストを読む

コードを読む/変更する必要がある場合
  → search_graph で位置特定、その後特定ファイルを読み込み
  → NOT: 全ディレクトリを読み込み検索

---

アンチパターン

アンチパターン	代わりにこうしてください
関数名をgrepで検索	search_graphに関数名を指定
シグネチャを見つけるために全ファイルを読み込み	特定のシンボルに対してget_code_snippetを使用
インポートチェーンを手動で追跡	trace_call_pathまたはquery_graphを使用
影響を確認せず変更を実施	共有コードを変更する前に毎回detect_changesを実行
ディレクトリ内のすべてのファイルを読み込み	構造はget_architectureで、詳細はsearch_graphで
グラフ陳腐化の警告を無視	index_statusを確認、必要に応じて再インデックス
クエリのたびに再インデックス	ファイルウォッチャーを信頼。大規模再構成後のみ手動再インデックス