gitnexus-guide

GitNexus ガイド

GitNexus のすべての MCP ツール、リソース、ナレッジグラフスキーマをすばやく参照できます。

まずここから始めてください

コードの理解、デバッグ、影響分析、リファクタリングに関するタスクでは、次の手順に従ってください。

1. リポジトリを一度だけバインドします — 確認済みのレジストリ名／パス、または設定済みのデフォルトを使用します。不明な場合は list_repos を呼び出してください。ホットツールの staleness を確認します。概要が必要な場合は gitnexus://repo/{name}/context を使用します。
2. タスクに合ったスキルを以下から選び、そのスキルファイルを読みます
3. スキルのワークフローとチェックリストに従います

手順 1 でインデックスが古いという警告が表示された場合は、まずターミナルで node .gitnexus/run.cjs analyze を実行してください。 query／context／impact／cypher を使用する前に、staleness.status と staleness.branch／lastCommit を確認してください。再分析が必要なのは behind または diverged の場合のみです。

スキル

タスク	読むスキル
アーキテクチャを理解する／「X はどのように動作しますか？」	gitnexus-exploring
影響範囲／「X を変更すると何が壊れますか？」	gitnexus-impact-analysis
バグを追跡する／「X が失敗するのはなぜですか？」	gitnexus-debugging
名前変更／抽出／分割／リファクタリング	gitnexus-refactoring
ツール、リソース、スキーマのリファレンス	gitnexus-guide（このファイル）
インデックス、ステータス、クリーン、Wiki の CLI コマンド	gitnexus-cli

ツールのリファレンス

ツール	提供される情報
query	プロセスごとにグループ化されたコードインテリジェンス — 概念に関連する実行フロー
context	シンボルの 360 度ビュー — 分類された参照と、参加しているプロセス
impact	シンボルの影響範囲 — 深さ 1／2／3 で何が壊れるかを信頼度とともに表示
trace	2 つのシンボル間の最短経路 — 1 回の呼び出しで「A はどのように B に到達しますか？」を確認
detect_changes	Git 差分の影響 — 現在の変更が何に影響するか
rename	セマンティックな名前変更：デフォルトではプレビューのみ（dry_run を省略、または true に設定）。dry_run: false とプレビューの plan_token を指定すると適用されます。適用状況と失敗を確認してください
cypher	生のグラフクエリ（最初に gitnexus://repo/{name}/schema を読んでください）
explain	永続化された汚染分析結果 — ソースからシンクへのデータフロー（analyze --pdg が必要）
pdg_query	制御／データ依存関係 — X を制御するもの（CDG）／Y が流れる先（REACHING_DEF）。analyze --pdg が必要
check	循環インポートなどのグラフ不変条件を確認
route_map	API ルートマップ — どのコンポーネント／フックがどのエンドポイントを取得するか、およびそれらを処理するハンドラーファイル
shape_check	レスポンス形式の差異 — 各ルートが返すキーと、利用側がアクセスするキーを比較（MISMATCH にフラグを設定）
api_impact	API ルートの変更前レポート — 利用側、ミドルウェア、形式の不一致、リスクレベル
tool_map	MCP／RPC ツールの定義と、それらを処理するファイル
group_list	設定済みの複数リポジトリグループ、または指定した 1 グループの設定を一覧表示
group_sync	グループの Contract Registry（リポジトリ間の HTTP 契約リンク）を再構築します。group.yaml の変更後、またはメンバーの再インデックス後に実行してください
list_repos	インデックス済みリポジトリを検出（ページネーション対応 — limit／offset）

焦点を絞った応答を選ぶ

接続先サーバーのスキーマを使用してください。古いサーバーでは、新しいフィルターが公開されない場合があります。以下のオプションはすべて明示的な指定です。省略すると既存の出力が維持されます。不要なセクションが大きい場合はフィルターを使用してください。もともと小さな応答では、メタデータの省略によって節約できるバイト数より、メタデータ自体のほうが大きくなることがあります。

質問	オプション
これを実装しているシンボルはどれですか？	query：limit: 3、max_symbols: 3、include_content: false、chain_depth: 0、response_sections: ["process_symbols", "definitions"]
どの実行フローが一致しますか？	query：response_sections で processes を維持します。id を process_symbols[].process_id に結合します
このシンボルを直接呼び出しているのはどれですか？	context：uid、response_sections: ["incoming"]、relationTypes: ["CALLS"]
これは何を呼び出しますか？ソースも含めて確認するには？	context：uid、include_content: true、response_sections: ["outgoing"]、relationTypes: ["CALLS"]
影響の概要は何ですか？	impact：direction: "upstream"、summaryOnly: true。リスク計算と合計は維持されます
調査が必要な影響対象のシンボルはどれですか？	impact：limit: 10、offset: 0。応答に示されるとおりにページを進めます
A はどのように B に到達しますか？	trace：from_uid、to_uid

response_sections は、単一リポジトリの MCP query または context でデータセクションを選択します（@group ルートでは使用できません）。query で選択できる項目：processes、process_symbols、definitions。context で選択できる項目：incoming、outgoing、processes、chain、routes、typed_properties。選択したシンボルは常に含まれます。context の relationTypes では、スキーマに公開されている大文字の関係名を指定でき、既存の incoming／outgoing カテゴリのみをフィルタリングします。ランキング、トラバーサル、ソースの保持、または候補／参照の上限付きウィンドウは変更されません。

フィルターを指定すると、選択内容と省略されたフィールド／カテゴリを含む response_filter が追加されます。警告、曖昧さ、古さ、完全性に関するメタデータは常に保持されます。フィルター適用後のビューが空でも、該当項目が存在しない証明にはなりません。表示範囲を広げるにはフィルターを省略してください。また、選択したカテゴリが空であっても、影響チェックを省略しないでください。maxTokens はページネーションではなくバイト数の上限であり、JSON が途中で切れる場合があります。これらのフィルター、小さな結果件数、そして大きな検索結果ではなく選択したシンボルのソース／チェーンの展開を優先してください。質問に答えるのに十分な証拠が得られたら終了し、デフォルトですべてのツールを実行しないでください。

list_repos のページネーション

list_repos は、大規模なレジストリが MCP／LLM のトークン制限によって切り詰められないよう、ページネーションに対応しています。省略可能な limit（デフォルトは 50、最大 200）と offset を受け取り、次の内容を返します。

{
  "repositories": [
    { "name": "...", "path": "...", "indexedAt": "...", "lastCommit": "...", "stats": { } }
  ],
  "pagination": {
    "total": 437,
    "limit": 50,
    "offset": 0,
    "returned": 50,
    "hasMore": true,
    "nextOffset": 50
  }
}

すべてのリポジトリを列挙するには、hasMore が false になるまで、offset に pagination.nextOffset を指定して呼び出し続けます。

list_repos {}               → repos 1–50,    nextOffset 50,  hasMore true
list_repos { offset: 50 }   → repos 51–100,  nextOffset 100, hasMore true
…
list_repos { offset: 400 }  → repos 401–437,                 hasMore false   (done)

注意：offset が total 以上の場合は、total は引き続き報告されますが、空のページが返されます。範囲外または形式が不正な limit／offset（整数以外、limit が [1, 200] の範囲外、offset < 0）は、明確なエラーとともに拒否されます。limit が上限を超える場合も、上限に合わせて黙って調整されるのではなく拒否されます。順序は決定的（小文字に変換した名前、その後にパス）なので、レジストリに変更がなければ、ページネーションによって項目が欠落したり重複したりすることはありません。

インラインの鮮度シグナル（query／context／impact／cypher）

この4つのホットリードツールは、すべての応答にブロッキングしない staleness フィールドを付加します。形式は { status, branch?, lastCommit, indexedAt, measuredAgainst, commitsBehind?, hint? } です。このフィールドは、「どのインデックスが応答したか」と「どれだけ新しいか」という2つの異なる問いに同時に答えます。何も問題がない場合でもこのフィールドが存在するのは、インデックスの識別情報を示すためです。ブランチに固定されたインデックスから計算された回答は、そうでなければデフォルトブランチから計算された回答と区別できません（#3291）。

{ /* …the tool's normal result… */
  "staleness": {
    "status": "current",
    "branch": "feature/checkout-v2",
    "lastCommit": "4f2a1c9e8b7d6a5c4e3f2a1b0c9d8e7f6a5b4c3d",
    "indexedAt": "2026-09-15T07:12:00.000Z",
    "measuredAgainst": "HEAD"
  }
}

ここでの status: "current" は、「このインデックスが、作成元のクローンの HEAD にある」という意味であり、デフォルトブランチの最新状態にあるという意味ではありません。measuredAgainst は、commitsBehind の基準となる対象を示します。これはそのクローンでチェックアウトされている HEAD であり、リモートではありません。branch はインデックスが表すブランチです。detached HEAD、Git リポジトリではないフォルダー、またはブランチを記録していないレガシーインデックスでは省略されるため、常に存在する識別子が必要な場合は lastCommit を確認してください。

インデックスがその HEAD より遅れている場合は、コミット数とヒントが付加されます。

{ /* …the tool's normal result… */
  "staleness": {
    "status": "behind", "commitsBehind": 3, "branch": "main",
    "lastCommit": "a0c945022d06b8815f93ffd8838df9ed5c08cbc0",
    "indexedAt": "2026-09-04T20:45:47.481Z", "measuredAgainst": "HEAD",
    "hint": "⚠️ Index is 3 commits behind HEAD. Run analyze tool to update."
  }
}

commitsBehind が含まれるのは、Git が差分を数えられた場合のみです。Git が差分を数えられなかったものの、HEAD がインデックスとは異なるコミットを指している場合（通常は、インデックス作成時のコミットがクローンの履歴に存在しなくなっている場合）、インデックスが HEAD にないことは確実ですが、数えられる差分がないため、数値は報告されません。

{ /* …the tool's normal result… */
  "staleness": {
    "status": "diverged", "branch": "main",
    "lastCommit": "a0c945022d06b8815f93ffd8838df9ed5c08cbc0",
    "indexedAt": "2026-09-04T20:45:47.481Z", "measuredAgainst": "HEAD",
    "hint": "⚠️ Index is not at HEAD and the commit gap could not be counted — the recorded commit may no longer be in this clone's history. Run analyze tool to update."
  }
}

つまり、commitsBehind を使う前に status を確認し、回答がどの参照を示すかを判断する前に branch／lastCommit を確認してください。status: "unknown" は、鮮度の確認自体を実行できなかったことを意味します（--skip-git フォルダーには測定可能な履歴がありません）。鮮度がわからなくても、どのインデックスが応答したかはわかるため、参照は引き続き報告されます。このフィールドが追加されるのはオブジェクト形式の結果だけです。raw-array 形式の cypher 出力とエラーエンベロープは変更されずに返されます。@group を対象とする呼び出しには付加されません（複数リポジトリにまたがる鮮度の定義は明確ではありません）。analyze を再実行するのは behind または diverged の場合のみです。これらは、インデックスがこのクローンの HEAD にないことを意味します。unknown は測定不能であり、古い状態ではありません。Git の履歴が存在しない限り、analyze を実行しても current にはなりません。

list_repos と HTTP のリポジトリルートに変更はありません。インデックスが最新の場合は staleness を完全に省略し、独自のトップレベルの branch／lastCommit／indexedAt フィールドを通じて参照を報告します。

汚染検出結果（explain）

explain は、gitnexus analyze --pdg によって記録された汚染検出結果を返します。これにはプロシージャー内の TAINTED エッジと、プロシージャー間の汚染フェーズで関数レベルのソース→シンクの連鎖が見つかった場合の、関数間をまたぐ TAINT_PATH ホップが含まれます。各検出結果には、シンクのカテゴリ（command-injection、code-injection、path-traversal、sql-injection、xss）、ソース／シンクの行、および各ホップで引き継がれる変数を含む、順序付けされたホップパスが含まれます。

• explain {} — リポジトリのすべての検出結果を列挙します（limit の範囲内で、決定的な順序）
• explain { target: "src/vuln.ts" } — ファイル内の検出結果（サフィックスによるパス一致も可能）
• explain { target: "runUserCommand" } — 関数内の検出結果（context と同様に解決され、曖昧な名前には順位付けされた候補が返されます）

--pdg なしでインデックス化されたリポジトリでは、「taint layer がありません」という明確な注記が返されます。注意点として、クロージャー／コールバック、プロパティ／フィールド、暗黙的なフローはモデル化されません。また、プロシージャー間の検出結果は関数レベルの TAINT_PATH ホップであり、文レベルで経路を証明するものではないため、検出結果がないことは、安全であることの証明には なりません。SANITIZES（サニタイザーによる除去）エッジは cypher でクエリできます。

制御とデータ依存関係（pdg_query）

pdg_query は、gitnexus analyze --pdg が記録する制御／データ依存関係レイヤー（CDG + REACHING_DEF、基本ブロック単位）を読み取ります。これは explain の制御／データに関する類似機能です。必ず対象を指定する必要があり（context と同様に解決される target のファイルパスまたはシンボル）、次の 2 つのモードがあります。

• pdg_query { mode: "controls", target: "..." } — CDG：「X はどの条件下で実行されるか？」各エッジは、制御する述語ブロック → 依存するブロックを示し、分岐の方向（'T'／'F'）は reason に記録されます。早期の return／throw へのエッジには guard: true が設定されます（ガード節の検出。方向は述語によって異なるため、固定ラベルでガードをフィルターしないでください）。
• pdg_query { mode: "flows", target: "...", variable?: "..." } — 関数内の REACHING_DEF 定義→使用エッジです。1 つのバインディングを追跡するには variable を指定します。

--pdg なしでインデックス化されたリポジトリでは、「PDG レイヤーなし」という注記が返されます（レイヤーを確認できない場合は「ステータス不明」）。関数内のみが対象です。関数をまたぐフローは taint の領域です（explain）。生の CDG／REACHING_DEF エッジも cypher でクエリできます。クエリの全容については gitnexus-pdg-query スキルを参照してください。

2 つのシンボル間の最短経路（trace）

trace は、「A はどのように B に到達するか？」を 1 回の呼び出しで回答します。context／impact を手動で 3～8 回つなげる代わりに、CALLS（および HAS_METHOD。クラスを起点とするトレースではそのメソッドへ降りていきます）上の最短有向経路を検索します。

• trace { from: "validateUser", to: "executeQuery" } — 2 つのシンボル間の最短経路です。
• よくある名前の曖昧さを解消するには、from_uid／to_uid（曖昧さなし）または from_file／to_file を指定します。名前が曖昧な場合は、順位付けされた候補が返されます。
• maxDepth（デフォルトは 10、最大は 30）で検索の深さを制限します。includeTests（デフォルトは false）を指定すると、テストファイルのシンボルを経由するトラバーサルが可能になります。

順序付きの hops（各要素は { name, filePath, startLine }）と、対応する { relType, confidence } の edges[] が返されます。これにより、呼び出しのホップと包含（HAS_METHOD）のホップを区別できます。経路が存在しない場合は、到達可能な最遠のノード（チェーンが途切れる場所）が報告され、トラバーサル上限に先に達した場合は truncated: true が設定されます。すべての結果には status が含まれます。値は ok／no_path／ambiguous／not_found／error のいずれかです。

リポジトリ間（実験的）：repo: "@groupName" を指定すると、グループのメンバーリポジトリをまたいでトレースできます。経路は 1 つの ContractLink 境界をまたぐ場合があります（crossings[] 内のブリッジされたコントラクトを含む CONTRACT_LINK ホップとして報告されます）。to を省略すると、from からの送信 HTTP 呼び出しをたどり、到達するプロバイダーのエンドポイントを特定します。グループは group_list／group_sync で設定します。

リソースリファレンス

ナビゲーション向けの軽量な読み取り（約 100～500 トークン）：

リソース	内容
gitnexus://repo/{name}/context	統計情報、古さの確認
gitnexus://repo/{name}/clusters	凝集度スコア付きのすべての機能領域
gitnexus://repo/{name}/cluster/{clusterName}	領域のメンバー
gitnexus://repo/{name}/processes	すべての実行フロー
gitnexus://repo/{name}/process/{processName}	ステップごとのトレース
gitnexus://repo/{name}/schema	Cypher 用グラフスキーマ

グラフスキーマ

ノード： File、Folder、Function、Class、Interface、Method、CodeElement、Community、Process、Route、Toolに加え、言語固有の型（Struct、Enum、Trait、Impl、Namespace、Moduleなど）とBasicBlock（--pdgインデックスのみ）。ノードの完全な一覧はgitnexus://repo/{name}/schemaにあります。 エッジ（CodeRelation.type経由）： CALLS、IMPORTS、EXTENDS、IMPLEMENTS、DEFINES、CONTAINS、MEMBER_OF、HAS_METHOD、HAS_PROPERTY、ACCESSES、METHOD_OVERRIDES、METHOD_IMPLEMENTS、STEP_IN_PROCESS、HANDLES_ROUTE、FETCHES、HANDLES_TOOL、ENTRY_POINT_OF、WRAPS、QUERIES、INJECTSに加え、--pdg専用の型（CFG、REACHING_DEF、TAINTED、SANITIZES、TAINT_PATH、CDG。デフォルトのインデックスでは行数はゼロです）。

Cypherを記述する前にgitnexus://repo/{name}/schemaを読み込んでください。これは、インデックス化されたリポジトリの正式なスキーマです。

MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
RETURN caller.name, caller.filePath