ln-021-codegraph

**パス：**ファイルパスは skills リポジトリのルートからの相対パスです。

Code Knowledge Graph

**タイプ：**スタンドアロンユーティリティ
**カテゴリ：**0XX 開発環境

コードベースをレイヤー化されたグラフ（tree-sitter AST → SQLite）にインデックス化し、MCP ツールを通じて依存関係の分析、パスの追跡、API の影響、参照、実装、診断、アーキテクチャの概要を提供します。

入力

入力	必須	ソース	説明
project_path	はい	args または CWD	インデックス化するプロジェクトのルート
command	いいえ	args	特定の操作：index、search、symbol、paths、refs、arch

使用するタイミング

• 不慣れなコードベースで作業を始めるとき → index + architecture
• 関数／クラスをリファクタリングする前 → find_symbols + inspect_symbol + trace_paths
• 呼び出しフローを把握するとき → trace_paths
• シンボルをすばやく見つけるとき → search

MCP の利用可否

ツールのポリシー：ホストの AGENTS.md に記載された MCP の設定に従ってください。ホストのポリシーがない場合、または MCP の動作が不明確な場合に限り、references/mcp_tool_preferences.md と references/mcp_integration_patterns.md を読み込んでください。

タスクがシンボルの同一性、参照、実装、アーキテクチャ、データフロー、編集の影響に関わる場合は、まず hex-graph を使用してください。利用可能な場合、対象を絞ったローカルコードの読み取りには、まず hex-line を使用してください。MCP を利用できない場合、未対応の場合、またはインデックス化されていない場合は、組み込みの Glob/Grep/Read/Bash を使って作業を続け、手動で確認した根拠をもとに回答してください。また、スキルの実行を中断するのではなく、確度が低下していることを明記してください。

ワークフロー

フェーズ 1：インデックス化

プロジェクトのルートにグラフが存在するか確認します（.hex-skills/codegraph/index.db）。

存在しない場合：

Call: index_project({ path: "{project_path}" })

存在する場合（必要に応じて再インデックス化）：

Call: index_project({ path: "{project_path}" })

冪等性があり、変更されていないファイルは自動的にスキップされます。

hex-graph を利用できない場合：Glob と対象を絞った Grep/Read でプロジェクトの手動マップを作成し、インデックス化を行わずに、最も近いクエリのワークフローへ進みます。

フェーズ 2：クエリ

ユーザーの意図に基づいて振り分けます。

ユーザーの発言	ツール	パラメーター
「依存関係を表示して」／「X を使用しているものは？」	trace_paths	{ name: "X", file: "...", path_kind: "mixed", direction: "reverse", path: "{project_path}" }
「X を呼び出しているのは？」／「X は何を呼び出す？」	trace_paths	{ name: "X", file: "...", path_kind: "calls", direction: "reverse"|"forward", path: "{project_path}" }
「X について教えて」／「X のコンテキスト」	inspect_symbol	{ name: "X", file: "...", path: "{project_path}" }
「プロジェクト構造」／「アーキテクチャ」	analyze_architecture	{ path: "{project_path}", scope?: "src/" }
「シンボル X を検索」	find_symbols	{ path: "{project_path}", query: "X" }
「app.get(...)／router.use(...)／server.registerTool(...) のパターンを検索」	grep_search	`{ path: "{project_path}", pattern: "app\.get\(
「重複コード／ホットスポット／未使用のエクスポートを検索」	audit_workspace	{ path: "{project_path}", scope?: "src/", verbosity: "minimal", limit: 5, clone_member_limit: 3 }
「循環依存／モジュール結合」	analyze_architecture	{ path: "{project_path}", verbosity: "full" }
「実装／オーバーライド」	find_implementations	{ name: "X", file: "...", path: "{project_path}" }
「データフロー／伝播」	trace_dataflow	{ source: { symbol: { name: "X", file: "..." }, anchor: { kind: "param", name: "input" } }, sink?: { symbol: { name: "X", file: "..." }, anchor: { kind: "return" } }, path: "{project_path}" }
「API ルート／レスポンス契約への影響」	api_impact	{ path: "{project_path}", route: "/api/users", limit: 10 }
「グラフの健全性／欠落しているオーバーレイ情報」	diagnose_graph	{ path: "{project_path}" }
「差分／ワークツリーをレビュー」	analyze_changes	{ path: "{project_path}", base_ref: "origin/main" }
「この範囲を編集すると何に影響するか確認」	analyze_edit_region	{ path: "{project_path}", file: "src/file.ts", line_start: 10, line_end: 40 }

標準セレクターのルール： セマンティックツールで指定できるセレクターは、次のうち 1 つだけです。

• symbol_id
• workspace_qualified_name
• qualified_name
• name + file

推奨フロー： まず path を可能な限り絞り込んでから find_symbols を使用し、返された workspace_qualified_name を inspect_symbol、trace_paths、find_references、または find_implementations に渡して、正確な追加クエリを実行します。

クエリ境界のルール： find_symbols は名前ベースの検出にのみ使用します。export function のようなコード断片や、解決されていない app.get(...) のようなメンバー呼び出しパターンには、シンボルとして扱わず grep_search を使用します。

曖昧さのルール： find_symbols が partial ... truncated=1 を返す場合、または返された行数よりも結果の総数が多い場合は、グラフクエリの範囲を広げず、path、続いて name + file または workspace_qualified_name を使って絞り込みます。

パスのルール： path には、インデックス化されたプロジェクトのルート、またはそのプロジェクト内の任意のファイル／サブディレクトリを指定できます。

データフローのアンカー： trace_dataflow では source.anchor と、任意の sink.anchor が必要です。次を使用します。

• param：関数パラメーター
• local：ローカル変数
• return：関数の戻り値
• property と access_path：範囲を限定したプロパティフロー

精度の制御： 呼び出し元が信頼度の低いパーサーのみの情報を抑制したい場合、inspect_symbol、trace_paths、find_references では min_confidence（low、inferred、exact、precise）を指定できます。

フェーズ 3：結果を提示する

1. MCP ツールの出力が利用可能な場合はそのまま表示します。利用できない場合は手動で調査した結果を提示し、フォールバック推論であることを明記します
2. 結果で参照するコードスニペットには、利用可能な場合は hex-line read_file と行範囲を使用します。利用できない場合は組み込みの Read を使用します
3. 結果に基づいて、次のクエリを提案します：

• find_symbols で明確な最上位の候補が見つかった場合 → workspace_qualified_name を指定して inspect_symbol を提案します
• find_symbols の結果が partial ... truncated=1 の場合 → より詳細なグラフツールを使用する前に、path を絞り込むか、name + file に切り替えることを提案します
• inspect_symbol の後 → リファクタリングの場合は trace_paths を提案します
• trace_paths の後 → シンボルの種類に応じて find_references または find_implementations を提案します
• 広範囲またはモジュールレベルのセレクターで trace_paths の結果が空の場合 → 依存関係がないと決めつけず、inspect_symbol または analyze_architecture を提案します
• api_impact の結果にルートがない場合、またはオーバーレイの情報が不足している場合 → diagnose_graph を提案します

対応言語

言語	拡張子	対応範囲
JavaScript	.js, .mjs, .cjs, .jsx	最も強力なセマンティック対応
TypeScript / TSX	.ts, .tsx	最も強力なセマンティック対応
Python	.py	ワークスペース対応の定義、呼び出し、インポート、未使用のエクスポート。プロバイダーがインストールされている場合は、オプションで高精度なオーバーレイにも対応
C#	.cs	ワークスペース対応の定義、呼び出し、プロジェクト／名前空間の所有関係、型の関係。プロバイダーがインストールされている場合は、オプションで高精度なオーバーレイにも対応
PHP	.php	ワークスペース対応の定義、呼び出し、PSR-4 名前空間のインポート、未使用のエクスポート。プロバイダーがインストールされている場合は、オプションで高精度なオーバーレイにも対応

MCP サーバーのセットアップ

.mcp.json に追加します：

{
  "mcpServers": {
    "hex-graph": {
      "command": "node",
      "args": ["{skills_repo}/mcp/hex-graph-mcp/server.mjs"]
    }
  }
}

完了の定義

• プロジェクトのインデックスを作成、または手動のフォールバックマップを構築済み
• クエリ結果をユーザーに表示済み
• 次のステップの提案を提示済み
• MCP を利用できなかった場合は、フォールバック手順を明記済み

---

バージョン： 0.1.0 最終更新日： 2026-03-20