product-question

product-question

コードベースの調査結果を、メール、Teams、Slack、プロダクトドキュメントにそのまま貼り付けられる、平易な英語のプロダクト向け回答にまとめます。

判断ツリー

ユーザーは何を尋ねていますか？

• プロダクト担当者、PM、ステークホルダー、サポートリード、またはエンジニアではない人が、アプリの動作について尋ねている このスキルを使います。コードを調査し、共有しやすいプロダクト向けの表現で回答します。

• ユーザーが「〜の場合どうなるか」「アプリが X をするのはなぜか」「この機能はどのように動作するか」「ユーザーには何が表示されるか」と尋ねている このスキルを使います。回答する前に、実際の動作、ルール、例外をたどって確認します。

• ユーザーが、コードに基づくアプリの動作について、転送、貼り付け、引用できる回答を求めている このスキルを使います。最終回答は、そのまま共有できるように仕上げます。文章を一般的に書き直したり共有したりする依頼だけでは、このスキルを使う理由にはなりません。

• ユーザーが実装の詳細、修正、レビュー、またはコードの変更を求めている プロダクト向けの説明も必要な場合を除き、このスキルは使い続けないでください。適切なコーディングまたはレビューのワークフローに切り替えます。

• 質問の範囲が広く、コードベースが大きい 対象となる機能、画面、顧客の操作、またはワークフローを推測できない場合に限り、簡潔な確認質問を 1 つだけします。

• 利用可能なファイルから動作を確認できない 確認した内容、未解明の点、判断に必要な証拠を伝えます。推測してはいけません。

クイックリファレンス

状況	対応
動作を見つける必要がある	references/discovery.md を読む
最終回答の形式を確認する必要がある	references/answer-contract.md を読むか、templates/product-answer.md から始める
よくある落とし穴を避ける必要がある	references/gotchas.md を読む
すばやく範囲を絞って回答する必要がある	ユーザーの機能に関する用語、ルート、ラベル、設定キー、テスト、ユーザー向けの文言を検索する
広範なワークフローに関する質問に答える必要がある	エントリーポイント、判断ルール、データの状態、ユーザーに見える結果、例外をたどる
このスキルパッケージを検証する必要がある	スキルのディレクトリから python3 scripts/validate.py . を実行する
パッケージングと評価のチェックが必要である	スキルのディレクトリから python3 scripts/test_skill.py . を実行する

デフォルトのワークフロー

1. プロダクトに関する質問を、機能、画面、ワークフロー、ユーザー操作、アカウントの状態、またはビジネスルールに具体化します。範囲を明確にする場合に限り、質問を言い換えます。
2. 既知の担当ファイルがあれば、そこから調査を始めます。なければ、ラベル、ルート名、ボタンの文言、設定名、イベント名、テスト名、ドキュメントなど、ユーザー向けの用語を検索します。信頼性を保てる最短の調査経路を選びます。
3. 名前が有望に見えるファイルだけでなく、実際の動作を定義するファイルを読みます。
4. ユーザーの操作またはシステムイベントから結果までの流れをたどります。入力、判断ルール、状態の変化、ユーザーに表示されるメッセージを把握します。
5. 例外を見つけるために、テスト、フィクスチャ、機能フラグ、権限、テナントやアカウントの条件、環境ごとの分岐を確認します。
6. 観察した動作と推論を区別します。確度の高い主張には、直接的な根拠を用います。
7. プロダクト担当者向けに、まず結果を示し、通常は平易な英語で回答します。対象読者や依頼内容に応じて、簡潔な技術用語やコードを含め、そのプロダクト上の意味を説明します。
8. 受け手がコードを読まずに回答を信頼するうえで役立つ場合に限り、「信頼度」または「確認済み」の簡潔な一文を加えます。

そのまま共有できる回答の基準

最終回答は、開発者向けのメモではなく、プロダクトの案内として書かれているように感じられるものにしてください。

次の構成は任意です。質問や対象者に合わせて、組み合わせたり、省略したり、順序を入れ替えたりしてください。

1. 簡潔な回答 - 質問に直接答える1〜2文。
2. ユーザーにとっての意味 - ユーザーに見える動作、判断、または制限。
3. ルールと例外 - 回答を左右する権限、機能フラグ、アカウントの状態、タイミング、データ条件、エッジケース。
4. 根拠 - ファイル名や領域名を記載した簡潔な「確認済み」の行。コードをそのまま貼り付けないでください。
5. 確信度 - 根拠が不完全、推論に基づく、または環境に依存する場合にのみ記載してください。

次の点を意識してください。

• そのまま共有できること
• 平易な表現であること
• 動作を具体的に説明すること
• 不確実性について誠実であること
• ファイル名や専門用語を控えめにすること
• コードブロックは、動作を明確にする場合や依頼を満たす場合に使い、調査内容をそのまま並べるためには使わないこと

根拠に関するルール

技術的な項目の羅列より、プロダクトに関係する根拠を優先してください。

• 良い例：「アクティブなサブスクリプションの読み込み後にのみ、アプリに解約オプションが表示されます。」
• あまり有用でない例：「useSubscriptionQuery が結果を返した後、SubscriptionActions コンポーネントが条件付きで CancelButton を描画します。」

信頼性を高めたり、回答の検証を可能にしたりする場合にのみ、ファイル名を記載してください。「確認済み」の行は次のように簡潔にしてください。

Checked: subscription settings screen, billing API route, and subscription status tests.

主張が推論に基づく場合は、その旨を明示してください。

Confidence: high for the web flow; I did not find mobile-specific handling in the available code.

共有しやすい回答で簡潔な引用を用いる場合でも、重要な主張は、調査したファイル、テスト、または設定までたどれるようにしてください。コードが示すのは、このチェックアウトでの動作であり、未確認のデプロイ環境や外部サービスの現在の動作ではありません。

情報源とメンテナンス

コードに基づく動作の説明と、不確実性に対する誠実さを、変わらない基本原則としてください。ローカルのガイダンスが不十分、古い、または外部依存関係の動作と矛盾する場合は、日常的なブラウジングを行ったり、アプリの根拠をプロバイダーのドキュメントで置き換えたりせず、該当バージョンの関連する公式ドキュメントまたは信頼できる一次情報源を確認してください。検証上の制約を報告し、例や回帰テストケースを添えて、情報源に基づくスキルの修正案を提示してください。メンテナンスが作業範囲に含まれる場合に限り、正本のスキルを編集してください。インストール済みのコピーを黙って更新してはいけません。

トーンに関する約束

• 前置きとして「コードベースを調査しました」と言わないでください。まず回答を述べてください。
• フレームワーク、サービス、フック、リデューサー、マイグレーション、APIについて過度に説明しないでください。
• 技術的な仕組みをプロダクト上の意味につなげ、読み手の助けになる場合は簡潔な技術的詳細を残してください。
• 比較が必要な場合を除き、長い箇条書きより短い段落を使ってください。
• 内部分析を削除しなくても、ユーザーが回答を簡単に転送できるようにしてください。

読み方ガイド

必要な情報	参照先
調査ワークフロー、検索対象、確信度ラベル	references/discovery.md
そのまま共有できる回答の構成と例	references/answer-contract.md
よくある失敗と復旧パターン	references/gotchas.md
コピーして使える最終回答のひな形	templates/product-answer.md

注意点

1. 実装上の接続とプロダクトの動作を混同しないでください。プロダクトの利用者が知りたいのは、通常、何が起こるか、誰に表示されるか、何によって結果が変わるかです。
2. 根拠以上に確実な回答をしないでください。推測した動作に基づくプロダクト上の判断には大きなコストがかかります。
3. 本文にファイルパスを羅列しないでください。ユーザーが技術的な追跡情報を求めている場合を除き、簡潔な根拠の行を使ってください。
4. テストだけ、またはUIの文言だけを根拠に回答しないでください。テストは意図された動作を示すことがあり、UIの文言には隠れたルールが示されていないことがあります。
5. プロセスの説明で回答の要点を埋もれさせないでください。最初の文で質問に答えてください。