why

理由

履歴上の証拠から、コードを形作った力を明らかにします。文書化された意図と、裏付けのある推論、妥当な仮説、未知の事項を区別します。

コードは仕組みを示す証拠であり、動機を示すものではありません。動機は、ソース履歴、レビュー、チケット、ドキュメント、チーム内の議論、インシデント、テレメトリー、プロダクトデータなどに記録されている可能性があります。

調査ワークフロー

1. 質問を明確にする

次の点を特定します。

• 対象となるコード、パターン、機能、または決定事項。
• ユーザーが知りたい具体的な理由。
• 質問に含まれている仮説。

曖昧な指示対象を解釈する際は、開いているファイル、最近の編集、会話の文脈を参考にします。解釈を明示し、ユーザーが訂正できるようにします。解釈が異なると調査内容に実質的な違いが生じる場合に限り、質問してください。

ユーザーが示した説明は、検証する仮説として扱います。

完了条件： 関連する証拠を定義できる程度に、対象と質問が明確であること。

2. コードの起点を作る

関連するパスと行、主要なシンボル、最後に変更したコミット、名前変更前の履歴、関連するレビューやチケットを記録します。次のコマンドなどから始めると便利です。

git blame -L <start>,<end> <file>
git log --follow -p -- <file>
git log --oneline -20 -- <file>
git log -1 --format=%B <commit>

利用可能なフォージクライアントまたは API を使って、レビューの説明と議論を読みます。特定のフォージやツールがインストールされているとは限りません。

ソースをまたいで再利用できるよう、パス、シンボル、コミット、レビュー ID、チケット ID、日付、作成者、検索語を記録します。

完了条件： 調査担当者が、質問の対象となるコードや期間を改めて探し直すことなく、別のシステムを検索できること。

3. カバレッジマップを作成する

現在のランタイムで利用できるリポジトリと、外部の読み取り専用コネクターを特定します。コネクターごとに台帳の項目を作成し、各項目を次の証拠カテゴリーに対応付けます。

1. ソース管理とコードレビュー。
2. 課題またはチケットの追跡。
3. 長文ドキュメント。
4. リアルタイムのチーム内議論。
5. インフラストラクチャーの可観測性とインシデント。
6. エラーまたは例外の追跡。
7. プロダクト分析またはデータウェアハウスデータ。

references/source-playbook.md を読み、利用可能なカテゴリーごとのプレイブックだけを読み込みます。ツール名とスキーマは、このスキルではなくランタイムから取得します。

既定では、異なる記録を保持している同一カテゴリー内の複数のコネクターも含め、利用可能なすべてのコネクターを検索します。各台帳項目に searched、unavailable、inaccessible、inapplicable のいずれかを記し、理由と対象範囲も記録します。対象が構造上そのカテゴリーに該当しない場合に限り、そのカテゴリーを該当なしとします。

完了条件： 発見されたすべてのコネクターに検索計画または具体的なステータスの理由があり、利用可能なコネクターがない場合も含めて、台帳に7つすべてのカテゴリーが記載されていること。

4. 各ソースを調査する

独立した読み取り専用エージェントが利用できる場合は、コネクターを並行して検索します。それ以外の場合は、順番に検索します。同じ記録とクエリ用語を扱う場合に限り、コネクターを組み合わせ、コネクターごとに範囲を限定したレーンを設けます。この手法は、特定のエージェントプロバイダー、モデル、ランナー設定に依存してはいけません。

レーンの契約として references/investigator-prompt.md を使用します。質問、コードの起点、カテゴリー別プレイブック、横断的なインシデントの観点があればそれも渡します。調査担当者は、質問への回答ではなく、証拠の収集を行います。

各ソースについて、次のことを行います。

• 幅広く検索してから、対象を絞り込みます。
• 関連する項目全体と、その議論を読みます。
• 表現が重要な場合は、安定した引用情報とともに正確な引用を記録します。
• クエリ、期間、検索結果なしの場合、矛盾、アクセス制限を記録します。
• 他のソースに関する手掛かりは、範囲を黙って変更せず、該当するカテゴリーに引き継ぎます。

検索結果なしという結果は、その結果をもたらした検索が記録されている場合にのみ、有用な証拠となります。

完了条件： 計画したすべてのカテゴリーについて、引用付きの証拠、記録された検索結果なし、または名前を明示したアクセス上の不足のいずれかが得られていること。

5. 確信度を適切に調整して統合する

references/epistemics.md と references/synthesizer-prompt.md を読みます。直接統合するか、すべての調査結果とコードアンカーにアクセスできる、読み取り専用のシンセサイザー 1 つに委任します。

各主張を分類します。

• 直接的： ソースが根拠を明示しています。
• 裏付けあり： 複数の間接的なソースが一致しています。
• 推論： 推論の連鎖が明確で、妥当な解釈です。
• 推測： もっともらしい仮説ですが、根拠が乏しい、または相反する証拠があります。
• 不明： 調査では質問に答えられませんでした。

提示する前に引用を抜き取り確認します。物語として整えるために矛盾を解消するのではなく、明らかにします。最終編集でも確信度を示す表現を保ちます。

完了条件： 根拠に関するすべての主張に確信度の区分があり、その区分に適した表現と、隣接する証拠または明示的な不足情報があります。

6. 調査の系譜を示す

次の構成を使用します。内容が本当にないセクションのみ省略します。

1. 質問
2. コードアンカー
3. 直接的および裏付けのある調査結果
4. 妥当な推論
5. 競合する仮説
6. 不明点と不足情報
7. 参照したソース
8. 確信度の要約

各ソースについて、何を検索し、何が見つかったかを、結果がなかった場合やスキップした理由も含めて記載します。読者が引用された主張をすばやく検証し、調査範囲を判断できるようにします。

調査がコード変更に先行する場合は、簡潔な制約セットを追加します。

• 維持： 証拠によって引き続き裏付けられる動作や根拠。
• 変更： 証拠により古くなったと示された前提。
• 回避： 失敗が引き続き当てはまるため、却下された方法。
• リスク： 計画で考慮すべき不足情報や不確実性。

完了条件： 回答が知見と推論を区別し、調査範囲を明らかにして、もっともらしい説明ではなく、検証可能な証拠をユーザーに示しています。