gitnexus-exploring

GitNexus でコードベースを調べる

使用する場面

• 「認証はどのように機能しますか？」
• 「プロジェクトの構成はどうなっていますか？」
• 「主要なコンポーネントを見せてください」
• 「データベースのロジックはどこにありますか？」
• これまで見たことのないコードを理解するとき

まずリポジトリをバインドする

確認済みのレジストリ名／パス、または設定済みの MCP デフォルトを使って、セッションごとに一度バインドしてください。その後は同じものを再利用します。対象がまだわからない場合に list_repos {} を呼び出してください。質問のたびに呼び出す必要はありません。チェックアウトディレクトリからレジストリ名を推測してはいけません。インデックス化されたリポジトリが1つの場合は、以下の例をそのまま使ってください。2つ以上ある場合は、呼び出しのたびに repo を指定してください。repo を省略すると通常はエラーになりますが、MCP ポリシーでデフォルトが設定されている場合は、エラーにならずにそのデフォルトが使われます。どのリポジトリを指しているのか判断できない場合は、作業を止めて確認してください。説明には、バインドしたリポジトリとインデックスの鮮度も併記してください。

list_repos の結果はページ分割されます。リポジトリが存在しないと結論づける前に、hasMore が false になるまで offset: pagination.nextOffset でページを取得してください。

ワークフロー

1. Bind the repository once; use hot-tool staleness on subsequent calls
2. If no symbol is known: query({search_query: "<concept>", limit: 3, max_symbols: 3})
3. context({uid: "<returned id>"})                → Inspect the selected symbol
4. Read a process resource only when its full trace answers an unresolved question

インデックスが古い場合 → ターミナルで node .gitnexus/run.cjs analyze を実行してください。 Hot-tool の staleness は、どのインデックスが応答したか（branch／lastCommit）と、その鮮度（status）を示します。再分析するのは behind または diverged の場合だけです。current は同一性を示し、unknown は測定できないことを示します。

必要な証拠だけを求める

接続済みサーバーが公開しているオプションを使用してください。response_sections とコンテキストの relationTypes は、単一のリポジトリに対するオプトインのビューであり、@group によるルーティングではありません。古いサーバーでは、既存の上限値と content／chain オプションを使ってください。不要なセクションが大きい場合はフィルターを使います。ただし、除外情報のメタデータにより、すでに小さいレスポンスがわずかに大きくなることがあります。 リポジトリのバインド後は、対象を絞った呼び出しを2～3回行うことを目安にしてください。質問に答えられたら終了します。ただし、証拠や必須の安全確認が不足している場合は、調査を広げてください。

query({search_query: "payment retry", repo: "my-app", limit: 3, max_symbols: 3,
       include_content: false, chain_depth: 0,
       response_sections: ["process_symbols", "definitions"]})
context({uid: "<id from query>", repo: "my-app", include_content: true,
         response_sections: ["incoming", "outgoing"], relationTypes: ["CALLS"]})
// Before editing, assess impact using the normal traversal and risk calculation:
impact({target: "<same id>", repo: "my-app", direction: "upstream", summaryOnly: true})

シンボルがすでにわかっている場合は、context から始めてください。曖昧な結果を避けるため、uid、または name と file_path／kind を使います。「これを呼び出しているのは誰か？」だけに答える場合は、response_sections: ["incoming"] と relationTypes: ["CALLS"] を指定し、include_content は false のままにしてください。質問がフローに関するものなら、シンボルのみのビューを要求するのではなく、クエリに processes を含めてください。

検索でヒットしたすべての項目について、ソースコードと複数ホップのチェーンを要求してはいけません。選択したシンボルのソースコードだけを取得してください。大きなクラス／ファイルの場合は、0始まりの startLine／endLine を小さく指定した read_file を使うのがおすすめです（グラフの行番号から1を引きます）。または、そのツールが利用可能なら、ファイル全体を読み込むために maxLines を使ってください。既知の A→B の経路には、context を何度も展開するのではなく trace を使ってください。

フィルターは、要求したセクション／カテゴリを保持し、その他を非表示にします。他の参照が存在しないことの証明にはならず、既存の上限付き検索を網羅的にするものでもありません。response_filter、warning、partial、truncated、epistemic、staleness を確認してください。より広い証拠が必要な場合は、フィルターを解除してください。maxTokens は最終手段となるバイト数の上限であり、JSON が途中で切れることがあります。切れたレスポンスを完全なものとみなさず、要求範囲を絞ってください。必須の影響確認を省略したり、UNKNOWN リスクを無視したりするために、フィルター済みの呼び出し元ビューを使ってはいけません。

チェックリスト

- [ ] Once per session: bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Check hot-tool staleness; read the overview only if needed
- [ ] Query for the concept only if the relevant symbol is not already known
- [ ] Review returned symbols; include processes when execution flow matters
- [ ] context on selected symbols; request only relevant sections/relations
- [ ] Read a process resource only if its full trace is needed
- [ ] Read targeted source only when implementation details are needed
- [ ] State the repository and index freshness with the explanation

リソース

リソース	得られる情報
gitnexus://repo/{name}/context	統計情報、鮮度に関する警告（約150トークン）
gitnexus://repo/{name}/clusters	凝集度スコア付きのすべての機能領域（約300トークン）
gitnexus://repo/{name}/cluster/{name}	ファイルパス付きの領域メンバー（約500トークン）
gitnexus://repo/{name}/process/{name}	ステップごとの実行トレース（約200トークン）

ツール

query — 概念に関連する実行フローを検索します。

query({search_query: "payment processing", repo: "my-app"})
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
→ Symbols grouped by flow with file locations

context — シンボルを360度の視点から表示します。

context({name: "validateUser", repo: "my-app"})
→ Incoming calls: loginHandler, apiMiddleware
→ Outgoing calls: checkToken, getUserById
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)

複数のリポジトリがインデックス化されている場合は、repo が必要です。1つだけの場合は省略できます。

例：「決済処理はどのように機能しますか？」

my-app がすでにバインドされ、インデックスが最新の状態である場合：

1. query({search_query: "payment processing", repo: "my-app", limit: 3, max_symbols: 3})
   → CheckoutFlow and RefundFlow, with symbol IDs and locations
2. context({uid: "<processPayment id>", repo: "my-app", include_content: true,
            response_sections: ["outgoing", "processes"]})
   → Selected source, callees, process participation and completeness diagnostics
3. Answer from that evidence; read one process resource only if its trace is still needed

説明とともに、リポジトリとインデックスの最新状態を報告してください。my-app がまだバインドされていない場合は、まず list_repos で一度検索してください。