spec-product

Spec Product

恒久的な機能について、持続的な what、why、および 証明すべき事項を定めるプロダクト仕様を作成します。

プロダクト仕様はスライスや設計より上流に位置します。後続のエージェントが変更の範囲を定め、実装設計を導き、正しさを検証し、意図の欠落を勝手に補わないために使用する、プロダクトの契約を定義します。

境界

対象が、永続的な機能、プロダクトの表面、ユーザー／システムのニーズ、または振る舞いのまとまりである場合は、プロダクト仕様を使用してください。

対象が単一の、範囲の明確な変更である場合は、プロダクト仕様を使用しないでください。代わりに /slice で変更の範囲を定めてください。

実装設計、アーキテクチャ、コード構造、アルゴリズム、ストレージのレイアウト、フェーズ計画は含めないでください。技術的な解決策の内容は /spec-tech または /design に記載してください。

標準構成

ユーザーが異なる標準テンプレートを明示的に指定しない限り、次の形式を使用してください。

# {{ref}}: {{title}}

## 1. Intent
Problem, value, and desired outcome.

## 2. Scope
In scope, out of scope, and boundaries.

## 3. Principles
Non-negotiable product/domain stances.

## 4. Requirements
Framing sentence plus constraints and invariants only. Functional/quality
requirements live as entities (synthesized below), never as prose rows.

## 5. Success Measures
Expected outcomes, metrics, signals, and acceptance gates.

## 6. Behaviour
Primary flows, alternate flows, edge cases, guards, and failure modes.

## 7. Verification
Verification approach in prose; no coverage table; cite durable REQ-NNN, not labels.

## 8. Open Questions
Unresolved decisions requiring exploration, judgement or further information.

作成ルール

1. 意図

次の内容を記述します。

• 解決する問題
• ユーザー、オペレーター、エージェント、またはシステムのニーズ
• その機能が重要である理由
• 目指す最終状態

プロダクトレベルにとどめてください。システムの構築方法は記述しないでください。

優れた意図は、ニーズとその結果を明確にします。弱い意図は、機能の名前を挙げるだけです。

2. 範囲

仕様が対象とするものと、意図的に対象外とするものを分けます。

次の内容を含めます。

• 対象範囲内の振る舞いや表面
• 対象範囲外の振る舞いや表面
• 境界条件
• 解釈を限定する前提

後続のエージェントが意図しない範囲拡大を却下できるよう、境界を明確にしてください。

3. 原則

プロダクトまたはドメインにおける、譲れない方針を示します。

原則は解釈を制約するものであるべきです。「シンプルにする」のような一般的な美徳は、具体的な帰結がない限り含めないでください。

推奨例：

• 「要件は、文章に埋め込まれるものではなく、独立したエンティティです。」
• 「標準要件が欠けている場合は、推測を許すのではなく、作業を停止します。」
• 「検証の失敗は、黙って修正せず、明示しなければなりません。」

避ける例：

• 「ユーザーフレンドリーにする。」
• 「保守しやすくする。」
• 「ベストプラクティスを使う。」

4. 要件

要件は、プロダクト仕様において機械的に重要な中核であり、文章の行ではなく、常にエンティティとして存在します。これがこのモデルの要点です。

§4 の本文に記載するのは、次の3つだけです。それ以外は記載しません。

1. 機能要件と品質要件は要件エンティティとして記録され、spec show が生成する「Requirements」セクションに表示されることを示す、短い導入文。
2. Constraints: の箇条書き。
3. Invariants: の箇条書き。

The functional and quality requirements this capability must satisfy are recorded
as requirement entities and appear under the synthesized Requirements section
below. This section carries only the constraints and invariants that bound every
valid implementation.

Constraints:

- The capability must respect ...
- The implementation must not require ...

Invariants:

- ... must always remain true.
- ... must never occur.

§4 の本文に「Functional Requirements」という小見出し、- FR-001 — … のような行、または品質要件の行を書かないでください。 機能要件と品質要件は、spec req add で作成する独立したエンティティです（構造規範を参照）。これらは生成された ## Requirements ブロックに表示されます。文章の行として列挙することは、このスキルが防ごうとしている誤りです。検索可能な構造化データを文章に重複させ、両者の食い違いを招きます。（ラベルは NF- です。従来の「NFR」形式ではありません。）

機能要件（FR- ラベル）は、観察可能な振る舞いを定義します。品質要件（NF- ラベル）は、信頼性、パフォーマンス、安全性、セキュリティ、プライバシー、アクセシビリティ、互換性、運用性、保守性、またはエージェントによる読み取りやすさの品質基準を定義します。どちらもエンティティであり、それぞれ --kind functional と --kind quality を指定します。

制約と不変条件には要件の種別がなく、§4 の本文に箇条書きとして記載します。制約は有効な解決策を限定します。不変条件は、あらゆる有効な実装と将来のスライスにおいて成立しなければならない事実です。CON-／INV- エンティティはありません。これらを spec req add で追加しようとしないでください。

機能上または品質上の義務を、説明文の段落に埋め込まないでください。振る舞いや品質基準として実装、テスト、または適用が必要なものは、文章ではなく要件エンティティにしてください。自分のリポジトリのプロダクト仕様における標準形式（spec show <PRD-ID>）に合わせてください。

5. 成功指標

製品レベルで成功と判断する基準を定義します。

該当するものを含めます。

• 期待される成果
• 受け入れ基準
• 行動に関するシグナル
• 運用上のシグナル
• 定性的な検証
• 定量的な指標

成功指標は目標値でもかまいませんが、受け入れ基準はレビューに十分な具体性を持たせてください。

テストだけを唯一の成功指標にしないでください。テストは適合性を証明しますが、必ずしも製品価値を証明するものではありません。

6. 動作

実装設計を確定させずに、製品の動作を説明します。

以下を含めます。

• 主要なフロー
• 代替フロー
• エッジケース
• 失敗時の動作
• ガード
• 権限またはポリシーの境界
• ユーザーまたはエージェントに見える結果

各フローについて、トリガー条件、期待される動作、結果としての状態を特定します。

動作が未解決のポリシーや製品上の判断に依存する場合は、答えを推測せず、未解決の質問に記録します。

7. 検証

特定の実装に仕様を縛り付けることなく、この機能が契約を満たし、不変条件を守り、品質基準を満たすことをどのように証明するか、検証アプローチを文章で説明します。

要件ごとのカバレッジ表は作成しないでください。 モバイルのFR-／NF-メンバーシップラベルをキーにした表は、クエリ可能なデータを文章に重複して記載することになり、要件のラベルが変更されたり順序が入れ替わったりした時点で陳腐化します。特定の義務を明示する必要がある場合は、メンバーシップラベルではなく、**永続的な要件エンティティ（REQ-NNN）**を参照してください。機能要件と品質要件のカバレッジは、それらのエンティティに基づいて追跡し、ここで再掲しません。

検証に関する説明では、次の点も扱います。

• 動作と不変条件をどのように証明するか
• 受け入れ基準と、それを満たすシグナル
• 可観測性と検証／レビューの義務

義務を検証できない場合は、要件エンティティを書き直すか、未解決の質問として記録してください。自分のリポジトリにある製品仕様の標準的な文章構成に合わせてください。

8. 未解決の質問

調査、判断、または追加情報が必要な未解決の決定を記録します。

未解決の質問は、真に不明な点に使い、先送りした作業の置き場にしないでください。

各質問には、それが重要な理由、または妨げとなるものを説明します。

推奨例：

• 「OQ-1 — アーカイブ済みの仕様をデフォルトの一覧に表示すべきですか？一覧の意味と受け入れテストに影響します。」

避ける例：

• 「UXについて考える必要があります。」

構造に関する原則

Doctrine では、仕様を第一級のエンティティとして管理します。製品仕様は連携する3つの書き込みで構成されます。標準的な形式は、独自のリポジトリにある製品仕様（spec show <PRD-ID>）を参照してください。

1. ID TOML（spec-NNN.toml）：schema、version、id、slug、 title、status = "draft"、kind = "product"、自由に設定できる category、 tags 配列、および機能レベルの記述を並べる responsibilities[] 配列です。 spec new product でひな形を作成します。
2. 本文の文章（MD）（spec-NNN.md）：標準の8セクションです。§4 に含めるのは、 導入文と Constraints: および Invariants: の箇条書きのみです。FR-／NF- の 項目は含めません。§7 は、カバレッジ表を含まない文章です。
3. 要件エンティティ（spec req add 経由）：機能要件または品質要件は、それぞれ 独立した REQ-NNN エンティティです。spec show では、FR-／NF- ラベルを付けて、 合成された ## Requirements セクションに表示されます。

実際の CLI 操作は doctrine spec --help を参照してください（製品仕様のひな形作成、要件メンバーの req add、再構成した全体の show、コーパスの外部キー整合性を検証する validate、仕様の list）。動詞のモデルについては lib:reference/using-doctrine.md を参照してください。フラグを推測しないでください。

spec req add は、フィールドが未入力の REQ-NNN メンバーを予約します。**spec show で詳細に表示するには、要件エンティティの TOML（requirement-NNN.toml）を手動で拡充してください。**1行の description（検索可能な記述）と acceptance_criteria 配列を追加します。これらを指定するフラグはなく、TOML に記述します。

構造上のルール：

• ID とフラットフィールドは spec-NNN.toml に記述し、説明文は spec-NNN.md に記述します。
• 機能要件と品質要件は、それぞれ独立した REQ-NNN エンティティです。文章として 記述してはいけません。
• FR-／NF- は members.toml に記録される、固定された所属ラベルです （FR- は機能要件、NF- は品質要件）。ラベルは変更される可能性があるため、 文章ではラベルではなく、永続的な REQ-NNN を参照してください。
• 制約と不変条件にはエンティティ種別がありません。§4 の文章の箇条書きとして 記述します。
• レビューや改訂の前に doctrine spec show <PRD-ref> で再構成した全体を確認し、 構造を編集した後は doctrine spec validate を実行してください（「corpus clean」 と表示されることを確認します）。

機能要件や品質要件を文章に重複して記載してはいけません。それらは要件エンティティとして扱います。これは、エンティティモデルが適用を徹底する唯一の厳格なルールです。

作業手順

プロダクト仕様書を作成する場合：

1. 対象が恒久的な機能か、単一の変更かを判断します。
2. 単一の変更である場合は、/slice に誘導します。
3. プロダクトの意図、スコープの境界、譲れない原則を特定します。
4. 仕組み上拘束力のある動作や品質基準をすべて要件エンティティ（spec req add）に抽出し、§4 の本文には制約と不変条件のみを残します。
5. 機能要件（--kind functional）と品質要件（--kind quality）を分け、制約と不変条件は §4 の本文の箇条書きに記載します。
6. 成功指標と受け入れゲートを定義します。
7. プロダクトレベルで動作を記述します。
8. 検証方法は §7 の本文に記載し、カバレッジ表は作成しません。
9. 未解決の判断事項を未解決の質問として記録します。
10. 設計、実装、フェーズ計画に関する内容を削除します。

プロダクト仕様書を改訂する場合：

1. 明示的に置き換える場合を除き、既存の正規要件を維持します。
2. 本文に隠れている義務を要件に昇格させます。
3. 実装の詳細をプロダクト仕様書から除外します。
4. 曖昧な成功指標を、観測可能なシグナルまたはゲートへと明確化します。
5. すべての要件に検証方法があることを確認します。
6. プロダクトの意図が不足している場合は推測せず、未解決の質問を追加します。

プロダクト仕様書をレビューする場合：

次の欠陥がないか確認します。

• 意図が欠落している、または曖昧
• 動作に隠れたスコープ拡大がある
• 機能要件または品質要件が、要件エンティティではなく §4 の本文の行として記載されている
• §7 に要件ごとのカバレッジ表がある、または本文で永続性のある REQ-NNN ではなくモバイル向けの FR-／NF- ラベルを参照している
• FR-／NF-（機能要件と品質要件）の混同
• 制約や不変条件が誤って要件エンティティに昇格されている
• 制約が選好として記述されている
• 意思決定を制約しない原則
• 観測可能なシグナルがない成功指標
• 成功指標と検証の間で受け入れゲートが重複し、内容に一貫性がない
• 実装設計を確定する動作
• 検証方法のない要件
• 後続作業を妨げるべき未解決の質問
• 未解決の質問に対し、仮定によって暗黙のうちに回答している

出力に関する期待事項

ゼロから作成する場合は、正規の構成に従ってプロダクト仕様書を完全な形で作成します。

既存の仕様書を改善する場合は、文書の再構成を依頼されない限り、ユーザーが定めた正規の見出しを維持します。

レビューのフィードバックを行う場合は、重大度ごとに指摘をまとめます。

## Blocking
## Material
## Minor
## Suggested rewrite

情報が不足している場合、プロダクトの意図を捏造しないでください。次のいずれかを行います。

• 明確にプレースホルダーと示して記載する
• 未解決の質問を追加する
• 最善を尽くした草案を求められた場合は、仮定を明示する

引き継ぎ

確定したプロダクト仕様書は、後続作業を可能にするものである必要があります。

確定後：

• /slice を使って、プロダクト仕様書を基点とする一貫性のある変更の範囲を定めます
• /design を使って、変更ごとの技術設計を行います
• /spec-tech を使って、永続性のある技術仕様を作成します

プロダクト仕様書は、プロダクトの意図、要件、成功指標、動作、検証義務に関する信頼できる唯一の情報源であり続けます。