product-requirement-document-authoring

产品需求文档编写

每当你起草或审阅产品需求文档、功能规格说明、计划文档或问题描述时，都应使用此能力——这些文档描述的是需要做什么以及如何验证已完成，而不是如何实现。它通用且自成一体：无论对应什么代码库、技术栈或交付工作流，任何需求、规格说明、RFC 或计划都能从中受益。

此技能规定了一种唯一的规范文档结构，顺序如下。必需章节必须出现在每份文档中；有条件章节在满足触发条件时加入，只有在说明一行原因后才可省略，不得悄然删除。

1. 摘要 (必需) — 一个独立段落。
2. 待办事项 (必需) — 一份静态、可执行的交付项或变更范围清单。
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 的示例片段例外，并通过实例区分示例与命名违规
• 为什么可观察的结果能提升抽象层次，同时不降低具体性

以下内容是规则本身，而非额外的阅读要求：本技能的全部范围是起草或审查规范的各个章节，因此该规则约束每个章节，而非某个更狭窄的情形；规则也直接列于此处，而不是放在 Agent 可能尚未打开的链接之后。

规范描述的是其受益方所能观察到的变更，而不是产生该变更的文件、函数、行、组件、内部算法或其他实现载体——模块级或服务级的所有权声明并非此类载体，System design 自身的指南也要求采用此类声明。受益方是指变更所服务的对象：应用功能面向最终用户，开发环境改进则面向开发者。

指南：

• MUST 将规范的每个章节都描述为其受益方所能观察到的变更，并指出当前变更面向谁。
• MUST NOT 在规范中命名文件名、行号、函数名、组件、内部算法或其他实现载体。
• MUST 将以下两种情况视为该禁令的例外，而非违规：路径或标识符本身就是验收标准——例如必须存在于特定文件中的规则，或属于合同约定的导出名称；以及 System design 章节中的示例代码片段或图表，用于展示某种机制的形式（缓存键、签名、状态转换表），而非预先编写实现。
• MUST NOT 将上述任一例外用于仅反映当前实现位置的路径、标识符或代码片段；它们必须本身就是验收标准或示例。
• MUST NOT 援引此规则来为更含糊的需求辩护；如果移除某项实现细节后，章节变得更难检查，那么移除的就是错误内容，并未达到本规则的目的。

Summary、Todo 和 Background 的撰写

请参阅 problem-and-scope.md，了解：

• 如何撰写独立成段的 Summary
• 如何在静态 Todo 中列出交付物或变更范围，而不重复需求、验收标准或验证内容
• 如何将 Background 写成简洁的要点，并在图表有助于说明情况时加入图表
• 如何在 Background 下陈述假设，并将其与待解决问题区分开来
• 如何在一个扁平、以动词开头的列表中合并目标和明确的非目标
• 如何撰写末尾的 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 骨架
• 每个部分应包含的内容、每个条件章节的省略规则，以及控制篇幅的说明