feature-discovery

機能の調査

機能調査では、既存の機能、モジュール、または動作の仕組みをたどり、根拠を引用しながらチャットで報告します。別のエンジニアが、その機能が何で、どのように動作し、どこで使われ、何がまだ不確かなのかを理解できる状態を目指します。

入力

受付内容は、Projects Affected: と What: ブロックを含む構造化された形式の場合も、自由形式の場合もあります。プロジェクトとトピックを推定してください。質問するのは作業を妨げる確認事項に限ります。ユーザーが不在の場合は、前提を明示して可能な範囲で続行してください。

ルール

• 帰属情報は一切含めないでください。 すべての出力に、共同著者、AI、またはツールの帰属情報を追加したり、残したりしないでください。
• 読み取り専用、チャットのみです。 調査中は、コード、設定、ドキュメント、ネイティブメモリ、ADR、プロンプト、Issue、生成アーティファクトを編集しないでください。GLOSSARY.md とアーティファクトの編集はステップ 7 の承認後に行います。docs/discovery/ ファイルは作成しないでください。また、ユーザーが指定しない限り、古くなるレガシーの調査ファイルを読まないでください。git fetch、git pull、インストール、マイグレーション、破壊的なコマンドは実行しないでください。
• 変更を伴わない検証を行ってください。 原則として静的検査を行います。ファイルやローカル／外部の状態を変更しないと確認できた場合に限り、プロジェクトやテストのコマンドを実行してください。それ以外の場合は、検証に合格したと報告せず、実行しなかった検査として報告してください。git status がクリーンなだけでは、無視対象のファイルやデータベースに変更がないことの証明にはなりません。
• 現在のコードを信頼できる情報源とします。 根拠の優先順位は、まず現在のコード、テスト、設定、次に ADR です。コードは実装済みの動作を示し、ADR と承認済み要件は意図された動作を記録します。両者が矛盾する場合は、両方を引用してください。実装との不一致は、承認済みルールの変更を意味しません。モック、フィクスチャ、スタブデータを使うパスは、実装済みの動作ではありません。その旨を明記してください。根拠と推論を分け、理由をでっち上げないでください。注意すべき兆候は、潜在的なバグに合わせてビジネスルールを書き換えることです。
• Git 履歴の確認はオプトインです。 調査中は決して読まないでください。レポートで確認を提案してください（ステップ 7）。
• シンボルだけでなく、動作をたどってください。 エントリーポイント、関連する条件、状態の変化、呼び出し元、下流への影響を、根拠を示すリンクまたは明示的な不足情報とともに結び付けてください。類似パス間でシームが再利用されている場合は指摘してください。注意すべき兆候は、使用箇所やユーザーに見える影響を示さないシンボルの羅列です。
• スコープを絞ってください。 受付内容が広範な場合は分割し、最初に調査する範囲と後回しにする範囲を明示してください。対象範囲の質問に答えるか、検証後に根拠の不足を報告した時点で終了してください。利用可能なコンテキストを超える未解決の作業には、スコープの分割または引き継ぎが必要です。注意すべき兆候は、明示的な方向転換なしにプロダクト調査や実験設計へと逸脱することです。
• レポートを提示したら終了してください。 次のスキルを提案しますが、呼び出したり、新たな依頼なしに実装を始めたりしないでください。質問で掘り下げられる不明点は、/feature-prompt または /grill-with-field で検討する未決定事項として残してください。「実際に触れる／見る必要がある」といった質問で掘り下げられない不明点は、/handoff と /prototype（インストール済みの場合。そうでなければ不確実性を明記）に回してください。行き先や未解決の質問がまだ曖昧な場合は、/feature-prompt ではなく /wayfinder を提案してください。方向性が曖昧なままでは、PR 単位のプロンプトを作成できません。
• 各フェーズの移行時に Stage / Found / Next / Needs user を出力してください。各項目は 1 行ずつ記載します。フェーズは、解析済み、コード追跡済み、検証済み、レポートです。
• サブエージェント：独立して進められる作業には、ローカルレーンを自動的に割り当ててください。クラウドエージェントは使用しないでください。割り当て時にレーン数を伝え、各レーンの完了時に報告してください。返すのは要約であり、逐語記録ではありません。統合はメインセッションで行います。

ワークフロー

1. 解析と場所の特定

回答する質問を列挙します。リポジトリ名、メタデータ、または README を使って、プロジェクトコードを Git ルートとパッケージ境界に対応付けます。確認したリビジョン／作業ツリーの状態と、開始時点の git status を記録し、既存の変更を保持してください。対応付けできないプロジェクトは明示的な不足情報として残し、範囲を絞った作業は続行します。

<artifacts-root> を解決します。*.code-workspace ディレクトリが存在する場合はそれを使い、そうでなければコンテキストごとのルート（リポジトリのルートにある GLOSSARY-MAP.md。レガシーの場合は CONTEXT-MAP.md）、それもなければリポジトリのルートを使います。

2. 現在のコードを追跡する

完全一致する用語を検索し、次に別名、ルート、コンポーネント、設定キー、環境変数、テーブル、ジョブ、フラグ、テストを検索します。コードベースの根拠を調べる際は、まず rg を使い、MCP より CLI を優先します。依存関係が不明な場合は、利用可能なソースまたは公式の上流ソースを読み取り専用で調べます。ダウンロードやインストールが必要でソースが存在しない場合は、未確認事項として報告し、次の対応を提案します。

3. ADR を読む

<artifacts-root> と対応するプロジェクトで、対象に関連する ADR（docs/adr/、docs/decisions/、または GLOSSARY.md やコードコメントで参照されているもの）を探します。各 ADR のステータス（accepted、superseded、proposed）と、現在のコードがその内容に一致しているかを記録します。見つからない場合は、検索した場所を明記します。

4. 範囲を限定して課題を読む。それ以外は読まない

ユーザーが指定した課題、または重要な未確認事項の解消に役立つ課題を読みます。課題が指定されておらず、ローカルの根拠で質問に回答できる場合は、トラッカーの確認は不要と記載します。広範な検索の承認を求めてはいけません。範囲を限定した課題と、そのコメントをすべて読みます。範囲を限定した検索には、完全一致する用語または信頼できるラベルを使います。各検索は、対応するリポジトリ／トラッカーの範囲内で行います（既定では gh issue view <n> --comments を使用します。ワークスペースのトラッカーマッピングがある場合は、そちらを優先します）。重要な未確認事項の解消に範囲を限定しない検索が必要な場合は、必要なコストを説明し、事前に確認を求めます。承認されない場合、利用できない場合、または返答がない場合は、その検索を行わず、制限事項を明記して、利用可能な範囲の作業を続けます。

5. 候補となるコンテキスト用語を追跡する

見つかったドメイン用語を GLOSSARY.md（<artifacts-root> 内、なければ近くのプロジェクトドキュメント内）と比較し、欠落、古さ、名称変更、意味の多重化、曖昧さがある用語にフラグを立てます。候補がある場合に限り、選定、提示、承認の手順を確認するために references/context-terms.md を読み込みます。候補がない場合は、その旨を1行で報告します。

6. 2回検証する

パス1：各回答を、使用したコード、テスト、設定、コンテキストと照合します。パス2：別名と逆引き検索を使って、矛盾する経路がないか調べます。コードが未使用と判断する前に、関連する間接的な登録、ルート、リスナー、フラグ、インポートパスのエイリアス、動的に構築される名前（テンプレート文字列の URL、連結されたキー）を確認します。生成物またはビルド出力（dist/、build/、生成されたクライアント）にのみ一致が見つかった場合、それはソースの根拠にはなりません。また、一致が見つからなかった場合に言えるのは、検索した範囲では見つからなかったということだけです。用語を、実装済みの動作および意図された動作と照合し、所有者、テスト、根拠に関する不足を明記します。依頼された質問すべてについて、根拠を示して回答するか、不足している根拠を明示して未解決とするか、この範囲外として明示的に保留します。

7. レポートを提示して終了する

ステップ2で「なぜ」または「いつ」に関する質問が残った場合、セクション8の末尾で、質問、追跡したファイル、直近2か月の期間を含む履歴確認の提案をします。新たに明確な承認を得た場合に限り、読み取り専用（git log、git show、git blame。より古い根拠が必要な場合は、対象を絞った検索を拡張）で確認し、追跡したファイルに繰り返し発生する修正コミットがあったかも記載した短い補足として回答します。

レポート提示後に GLOSSARY.md またはその他の成果物を更新する場合は、対象パス、提案する文面、理由をそれぞれ提示します。明示的な承認を待ってから、references/context-terms.md の 承認済みの更新の適用 に従います（承認が得られない場合：返答がなければ編集せず、候補はレポートに残します）。

出力

以下の番号付き構成を使用し、各セクションは箇条書き3項目以内にしてください。回答や但し書きを省かず、約550語を目安にしてください。Quick traceは、重要な分岐、候補コンテキスト、競合がない単純な単一プロジェクトの回答に使用します。質問で1つのシンボルが挙げられているだけでは該当しません。最初にQuick traceであることを明記し、セクション1～3、5、9を使用します（5は1行）。他のセクションには「該当なし」と記載します。求められた使用方法と根拠はセクション1～3に含めてください。それ以外の場合は完全なレポートを使用し、複数プロジェクトの調査を決して省略しないでください。

セクションの順序：1 概要 · 2 機能 · 3 仕組み · 4 使用箇所 · 5 ADR · 6 必要とされた理由／背景 · 7 GLOSSARY.mdの用語候補 · 8 リスク、ギャップ、推奨される次の確認事項 · 9 実施した検証 · 10 推奨される次のスキル（任意、1～3）。完全なレポートではreferences/report-template.mdを読み込みます。Quick traceでは、完全なテンプレートを読み込まず、対象となる上記のセクションを使用します。

エビデンスの形式。 file:line、またはファイル名とシンボルおよびその役割を引用します。複数プロジェクトにまたがるレポートでは、パスにPROJECT-CODEを付け、issueにはリポジトリまたはトラッカーを付けます。#123だけの記載は避けてください。コミットにはリポジトリ、短縮ハッシュ、日付を記載します。調査したソース、調査したテスト、実行したチェック、実行時の観察結果、ADRの記述、推論を区別します。ソースの既定値だけでは、デプロイ済みの構成を証明できません。実際に実行したコマンドから、決定的な出力のみを引用してください。否定的な主張をする場合は、省略したチェックと検索範囲を明記します。

完了基準

• セクション1～9のすべての事実に、エビデンスの形式に従った引用がある
• 求められた質問すべてに、エビデンスに基づく回答、明示されたエビデンスのギャップ、または明示的な対象範囲の保留がある
• 開始時と終了時のgit statusを比較し、既存の変更を保持し、実行したコマンドが変更禁止ルールを満たしている（承認済みのステップ7の更新を除く）
• ユーザーがセクション8の提案を承諾する前に、git履歴を調べるコマンドを実行していない
• 完全なレポートは番号順に従っている（セクション10は任意）。または、対象となるQuick traceにセクション1～3、5、9が含まれている
• セクション7を含める場合、4つの選択肢からなる承認依頼、または候補がない旨の行で終わっている
• レポートの作成後にセッションを終了している — スキルを呼び出さず、実装も開始していない