spec-product

产品规范

编写产品规范：为一项长期有效的能力定义持久的是什么、为什么以及证明义务。

产品规范先于切片和设计。它定义产品契约，供后续 Agent 用于界定变更范围、推导实现设计、验证正确性，并避免臆造缺失的意图。

边界

当主题是一项持久能力、产品界面、用户／系统需求或行为类别时，使用产品规范。

当主题是一项范围明确的单次变更时，不要使用产品规范。改用 /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. 意图

说明：

• 要解决的问题
• 用户、运营人员、Agent 或系统的需求
• 这项能力的重要性
• 期望的最终状态

保持在产品层面。不要描述系统将如何构建。

好的意图会说明需求及其影响。薄弱的意图只会点出一项功能。

2. 范围

区分规范所涵盖的内容与刻意排除的内容。

包括：

• 范围内的行为或界面
• 范围外的行为或界面
• 边界条件
• 限制解释方式的假设

明确边界，使下游 Agent 能够拒绝意外扩大范围。

3. 原则

说明不可妥协的产品或领域立场。

原则应限制解释方式。不要写“让它简单”之类的泛泛优点，除非它们会带来具体后果。

优先采用：

• “需求是同级实体，而不是嵌入的散文。”
• “缺少规范需求时应停止，而不是自行推断。”
• “必须显式呈现验证失败，不得静默修复。”

避免采用：

• “以用户为先。”
• “保持可维护性。”
• “采用最佳实践。”

4. 需求

需求是产品规范中具有机制重要性的核心内容——它们应当以实体形式存在，绝不能写成散文条目。这正是该模型的全部意义。

§4 的散文正文只能包含以下三项，不得包含其他内容：

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- 标签）定义质量标准：可靠性、性能、安全、安保、隐私、无障碍性、兼容性、可运维性、可维护性或 Agent 可读性。两者都是实体，分别使用 --kind functional 和 --kind quality。

约束和不变量没有需求类型，应保留为 §4 的散文项目。约束限定有效的解决方案；不变量是在所有有效实现和未来切片中都必须成立的事实。不存在 CON-／INV- 实体——不要尝试通过 spec req add 添加它们。

也不要把功能或质量义务隐藏在叙述段落中：如果某项内容必须作为行为或质量标准实现、测试或强制执行，就应将其提升为需求实体，而不是写成散文句子。遵循你自己的代码库中产品规范的规范结构（spec show <PRD-ID>）。

5. 成功衡量标准

定义如何在产品层面识别成功。

包括适用的内容：

• 预期结果
• 验收门槛
• 行为信号
• 运营信号
• 定性验证
• 定量指标

成功衡量标准可以是理想目标，但验收门槛必须具体到足以进行评审。

避免仅以测试作为成功衡量标准。测试可以证明符合要求，但不一定能证明产品价值。

6. 行为

描述产品行为，但不要限定实现设计。

包括：

• 主要流程
• 替代流程
• 边缘情况
• 失败模式
• 防护措施
• 权限或策略边界
• 用户或 Agent 可见的结果

对于每个流程，明确触发条件、预期行为和最终状态。

如果行为取决于尚未解决的策略或产品判断，请在“开放问题”中记录这一空缺，而不是自行设定答案。

7. 验证

用文字描述验证方法：如何证明此功能履行其契约、保持其不变量并满足质量标准，同时不将规格绑定到特定实现。

不要编写逐项需求覆盖表。 以移动端 FR-/NF- 成员标签为索引的表格，会将可查询的数据重复写入文字，并在需求重新标记或排序时迅速过时。如检查必须引用特定义务，请引用持久化的需求实体（REQ-NNN），而不是成员标签。功能和质量需求的覆盖情况应针对这些实体进行跟踪，而不是在此处重复陈述。

验证说明仍应涵盖：

• 如何证明各项行为和不变量
• 验收门槛及满足门槛的信号
• 可观测性以及验证／评审义务

如果某项义务无法验证，请改写需求实体或记录一个开放问题。遵循你自己的代码库中产品规格的规范文字结构。

8. 开放问题

记录需要进一步探索、判断或补充信息的未决决定。

开放问题应用于真正未知的事项，而不是充当延期工作的堆积处。

每个问题都应说明其重要性或会阻碍什么工作。

建议写法：

• “OQ-1 — 归档的规格是否应在默认列表中保持可见？这会影响列表语义和验收测试。”

避免写法：

• “需要考虑 UX。”

结构规范

Doctrine 将规格作为一等实体管理。产品规格包含 三次协同写入——请参阅你自己的仓库中的产品规格（spec show <PRD-ID>），了解规范结构：

1. 身份 TOML（spec-NNN.toml）：包含 schema、version、id、slug、title、status = "draft"、kind = "product"、开放词汇的 category、tags 数组，以及由能力级陈述组成的 responsibilities[] 数组。使用 spec new product 创建脚手架。
2. 正文 MD（spec-NNN.md）：包含八个规范章节。§4 仅包含背景说明句以及 Constraints: 和 Invariants: 条目——不包含任何 FR-/NF- 行；§7 使用散文形式，不包含覆盖表。
3. 需求实体，通过 spec req add 添加：每项功能或质量需求都是一个同级 REQ-NNN 实体，在 spec show 中显示于合成的 ## Requirements 章节下，并带有 FR-/NF- 标签。

实际 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）：添加单行 description（可查询的陈述）和 acceptance_criteria 数组——没有对应的标志，这些内容需以 TOML 编写。

结构规则：

• 身份和扁平字段放在 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 中包含逐项需求的覆盖率表格，或正文引用移动端 FR-/NF- 标签，而非持久的 REQ-NNN
• FR- / NF-（功能与质量）混淆
• 错误地将约束或不变量提升为需求实体
• 将约束写成偏好
• 无法约束决策的原则
• 没有可观测信号的成功度量
• 成功度量与验证部分中的验收门槛不一致地重复
• 行为承诺了实现设计
• 没有验证途径的需求
• 本应阻止下游工作的开放问题
• 通过假设悄然回答未解决的问题

输出要求

从头起草时，按规范结构完整编写产品规格。

改进现有规格时，除非用户要求重构文档，否则保留其规范标题。

提供审查反馈时，按严重程度对发现的问题分组：

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

信息缺失时，不要捏造产品意图。应当：

• 写明清晰标注的占位内容，或
• 添加开放问题，或
• 如果用户要求尽力起草，则明确说明假设。

交接

确定后的产品规格应能支持下游工作。

确定后：

• 使用 /slice，从产品规格范围内定义一个连贯的变更
• 使用 /design 进行单项变更的技术设计
• 使用 /spec-tech 编写持久的技术规格

产品规格仍是产品意图、需求、成功度量、行为和验证义务的事实来源。