product-requirement-document-authoring

プロダクト要件ドキュメントの作成

プロダクト要件ドキュメント、機能仕様書、計画ドキュメント、または課題の説明を作成・レビューする際は、この機能を使用してください。対象は、必要な内容と完了をどのように検証するかを記述する部分であり、実装方法ではありません。汎用的で自己完結しているため、コードベース、技術スタック、または適用先のデリバリーワークフローを問わず、あらゆる要件、仕様、RFC、計画に役立ちます。

このスキルでは、以下の順序で使用する標準ドキュメント構成を定めています。必須セクションはすべてのドキュメントに含めます。条件付きセクションは、適用条件を満たす場合に含め、適用されない場合も一行で理由を明記します。黙って省略してはいけません。

1. 概要 (必須) — 単独で成立する一段落。
2. ToDo (必須) — 成果物または変更対象を示す、静的で実行可能なリスト。
3. 背景 (必須) — 前提条件サブセクションを含めます。
4. 目標と非目標 (必須) — 一つのセクションとして記載します。通常は、冒頭の動詞で意図する成果と意図的な対象外を区別した、フラットなリストにします。
5. 機能要件 (条件付き) — UI デザイン (条件付き) と システム設計 (条件付き。妥当な競合案がある場合は 検討した代替案 を含む) をその下にネストします。
6. 非機能要件 (条件付き)。
7. 受け入れ基準 (必須)。
8. 検証戦略 (必須)。
9. 未解決の質問 (必須。「なし」でも可)。

このスキルは、仕様書が触れるすべての内容を扱うものではありません。ドキュメントの構成、問題の整理、スコープの境界、要件と基準の作成、そして UI デザインとシステム設計セクションの仕様レベルでの枠組み、つまり変更に求められる内容とその検証方法の記述を扱います。以下のような、記述の背後にある実装上の仕組みは対象外です。

• UI コンポーネントの構成、スタイル、マークアップ。 仕様書では階層、状態、アクセシビリティ、レスポンシブ対応の意図を示します。インターフェースの構築方法は、プロジェクト独自の UI およびコンポーネントの規約に委ねます。
• データフローの実装、ルーティング、ファイルツリー内でのモジュールの配置。 仕様書では、共有状態をどのモジュールまたはサービスが所有するかなど、システム設計上の判断を示します。それをどのように接続し、実際にどこへ配置するかは、プロジェクト独自のアーキテクチャおよび構成の規約に委ねます。
• テスト作成の仕組み（命名、構成、フィクスチャ、ロケーター）。 仕様書では、確認可能にするための対象範囲と検証手順を明記します。テストの記述方法は、プロジェクト独自のテスト規約に委ねます。

こうした仕組みを対象外にすることで、実装方法が変わってもドキュメントの安定性を保ち、レビューを成果に集中させることができます。

このドキュメントにおける「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119 に記載されているとおりに解釈してください。

受益者を軸とした表現

以下については、beneficiary-framing.md を参照してください。

• 実装の詳細に名前を付けると、そのドキュメントが評価すべき対象の仕事に従属してしまう理由
• 以下の受け入れ基準の例外を適用する方法。契約上のパスや識別子と、現時点の実装を反映しているだけのものを区別する具体例を含みます
• 以下のシステム設計における説明用スニペットの例外を適用する方法。説明図と命名違反を区別する具体例を含みます
• 観測可能な結果によって、具体性を損なわずに抽象度を高められる理由

以下はルールそのものであり、追加の読解を求めるものではありません。このスキルの対象範囲は仕様の各セクションの作成またはレビュー全体であるため、このルールはより狭い状況ではなく、すべてのセクションに適用されます。また、エージェントがまだ開いていない可能性のある参照先を示すのではなく、ここに直接記載しています。

仕様では、その変更を生み出すファイル、関数、行、コンポーネント、内部アルゴリズム、その他の実装手段ではなく、受益者が観測する変更を記述します。モジュールやサービス単位の所有権に関する記述は、System design のガイダンス自体が求めているものであり、このような実装手段には該当しません。受益者とは、その変更の恩恵を受ける人のことです。アプリケーションの機能であればエンドユーザー、開発環境の改善であれば開発者です。

ガイドライン：

• 仕様のすべてのセクションで、変更の受益者を明示したうえで、その受益者が観測する変更を記述しなければなりません。
• 仕様で、ファイル名、行番号、関数名、コンポーネント、内部アルゴリズム、その他の実装手段を挙げてはなりません。
• 次の2つのケースは、この禁止事項への違反ではなく例外として扱わなければなりません。特定のファイルに配置する必要があるルールや、契約の一部であるエクスポート名など、それ自体が受け入れ基準であるパスや識別子。そして、実装をあらかじめ記述するのではなく、機構（キャッシュキー、シグネチャ、遷移表など）の形を示す、システム設計セクションの説明用コードスニペットや図。
• 受益者が観測する結果が現時点で実装されている場所を反映しているだけで、受け入れ基準でも説明図そのものでもないパス、識別子、スニペットには、いずれの例外も適用してはなりません。
• 要件を曖昧にするためにこのルールを持ち出してはなりません。実装の詳細を取り除いたことで検証しにくくなるなら、取り除いたものが誤っており、ルールの目的を達成できていません。

Summary、Todo、Background の表現

以下については、problem-and-scope.md を参照してください。

• 単独で読める1段落の Summary の書き方
• 要件、受け入れ基準、検証内容を重複させず、成果物や変更対象を静的な Todo に列挙する方法
• Background を簡潔な箇条書きでまとめ、状況の理解に役立つ場合は図を使う方法
• Background の下に前提条件を記載し、未解決の質問と区別する方法
• 目標と明示的な対象外事項を、動詞で始める1つのフラットなリストにまとめる方法
• 既知のリスクとその軽減策を含め、最後に Open questions セクションを記述する方法
• 変更の規模と可逆性に応じてドキュメントの分量を調整する方法
• 曖昧な品質を表す形容詞を、具体的で検証可能な記述に置き換える方法

機能要件の作成

以下については、functional-requirements.md を参照してください。

• ユーザー視点の要件を「何をすべきか」ではなく「どうあるべきか」として記述する方法
• ガイドレベルの説明を、リファレンスレベルの詳細より先に配置する方法
• 主要なフローに加えて、関連する空の状態、エラー状態、境界状態を網羅する方法
• このセクションを適用するかどうかを判断し、適用しない場合は理由を明記する方法

UI デザインセクションの構成

以下を確認するには、ui-design-framing.md を参照してください。

• 仕様に UI デザインセクションが必要かどうか（ビューに影響する変更のみ）、また必要な場合はどの程度の詳細さにするか
• 実装ではなく仕様の観点から、階層とレイアウトの意図を説明する方法
• インタラクションの状態（デフォルト、無効、読み込み中、エラー、空）を列挙する方法
• テスト可能で、WCAG を参照した基準としてアクセシビリティの意図を示す方法
• レスポンシブな動作の意図と、コピー／マイクロコピーの制約を示す方法
• 作成したワイヤーフレームやモックアップへのリンクを含め、永続的なデザイン記録としてこのセクションを活用する方法

システム設計セクションの構成

以下を確認するには、system-design-framing.md を参照してください。

• 仕様にシステム設計セクションが必要となるケース――境界をまたぐ変更や元に戻しにくい変更、複雑でスコープの小さい仕組み
• 図や理解を助けるコードスニペットを用いて、仕様レベルでデータフローとモジュール境界を説明する方法
• 検討した代替案と、それらを却下した理由を記録する方法
• 非機能要件を測定可能な目標として示す方法

受け入れ基準の作成

以下を確認するには、acceptance-criteria.md を参照してください。

• レビュアーが実装コードを読まずに独立して検証できる基準の書き方
• 形容詞よりも、具体的で確認可能な表現を優先する方法
• 正常系、エッジケース／エラー／空の状態、および明示的な非影響を網羅する方法
• 影響を受けない基準は、機械的な代替指標ではなく、維持されるべき特性として表現する方法
• チェックリストを適切な規模にし、すべての基準を仕様の他の部分に結び付ける方法

検証戦略の作成

以下を確認するには、verification-strategy.md を参照してください。

• 検証戦略セクション、または外部検証を必要とする基準の作成やレビュー
• 作業が完了したことを示す順序付きの検証手順の作成。これには、変更サイクルを所有するプロジェクトが定める基準の指定について、その手法と証拠との対応付けも含みます
• バグ対応で、修正前と修正後の再現手順を示す方法
• プロジェクトで変更対象の範囲に必要な検証ゲートを明記する方法
• 追加または更新するテストカバレッジを明記する方法

計画ドキュメントのテンプレート

以下を確認するには、template.md を参照してください。

• ドキュメント全体の構造を示す、自己完結した注釈付き Markdown のひな形
• 各項目に記載する内容、条件付きセクションごとの省略ルール、および適切な規模にするための注意点