ln-020-codegraph

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

コードナレッジグラフ

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

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

入力

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

使用する場面

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

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}" }
「差分／ワークツリーをレビューして」	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

推奨フロー： find_symbols は、実用上可能な範囲まで path を絞り込んでから使用します。返された 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
• 範囲が制限されたプロパティフローには、access_path と併せて property

精度の制御： 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 を提案します

対応言語

言語	拡張子	対応範囲
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