writing-product-specs

撰写产品规格说明书

概述

撰写全面的产品规格说明书，清楚传达我们要构建什么、为什么要构建，以及如何判断项目是否成功。记录利益相关方需要了解的所有内容：问题背景、目标受众、需求、成功标准和权衡取舍。让他们全面了解该功能或项目。

假设读者是经验丰富的产品人员或工程师，但对这个具体功能或问题领域一无所知。假设他们需要清晰的背景信息，才能理解这项工作的“为什么”。

开始时宣布：“我正在使用 writing-product-specs 技能来创建产品规格说明书。”

适用场景：设计新功能或规划项目，且需要清晰的需求文档时。

将规格说明书保存为名为 spec--MM-DD-YYYY.md 的文件（或按用户要求命名）。

核心原则： 产品规格说明书详细描述产品的功能与特性，用于向开发团队传达产品需求。

何时使用此技能

在以下情况使用此技能：

• 用户明确要求撰写产品规格说明书、产品规格或 PRD（产品需求文档）
• 用户要求设计新功能，并需要在实施前记录需求
• 用户正在规划项目，需要明确要构建什么以及原因
• 需要向利益相关方、工程师或设计师传达产品需求
• 需要将功能请求扩展为包含背景、需求和成功标准的详细规格说明书
• 用户要求在进入实施阶段前记录产品决策的“内容”和“原因”

撰写产品规格说明书的流程

遵循此流程，收集必要信息并撰写全面的产品规格说明书。

步骤 1：了解所请求的功能或项目

通过提问了解该功能或项目。收集以下信息：

• 这是什么？ 我们正在构建什么功能或项目？它有什么作用？
• 目标受众是谁？ 我们要为哪些人解决问题？他们的角色、用户画像或特征是什么？
• 他们面临什么问题？ 目标受众遇到哪些具体痛点或挑战？有什么功能无法正常使用或缺失？
• 此功能/项目将如何解决这些问题？ 提出的解决方案是什么？它如何解决这些问题？
• 他们将获得什么益处？具体益处是什么？ 这会带来什么价值？用户将获得哪些成果或体验到哪些改善？
• 我们如何判断是否成功？ 成功指标、验证标准或可观察到的结果是什么？
• 我们如何判断是否失败？ 哪些情况表明项目失败？有哪些失败模式或负面信号？
• 我们不会做什么？ 明确不在范围内的内容是什么？哪些相关功能或能力不包含在内？

继续提问，直到掌握足够信息来起草完整的规格说明书。除非已清楚回答这些核心问题，否则不要开始起草。

步骤 2：起草规格说明书

根据收集到的信息，按照 产品规格说明书格式 一节中概述的文档结构，起草产品规格说明书。向用户展示完整草稿。

步骤 3：根据反馈迭代

展示草稿后：

• 询问用户需要修改、澄清或补充的内容
• 找出规格说明书中的缺漏，并提出有针对性的问题以补充信息
• 根据反馈修订规格说明书
• 持续迭代，直到用户确认规格说明书完整且准确

步骤 4：定稿并保存

用户确认规格说明书符合要求后：

• 对照 产品规格说明书格式 中的文档结构检查最终稿
• 将文件保存为 spec-<feature-name>-MM-DD-YYYY.md（或按用户要求命名）

产品规格格式

以下是产品规格的格式。每个部分都应提供清晰、可执行的指导。

[项目 / 功能标题]

说明： 用简短的描述介绍我们要构建的内容（最多 1–2 句话）。这是一段概述，应在几句话内说明整个项目及其优势。读者仅凭标题和描述就应能理解其核心价值主张。

应包含的内容：

• 清晰且具有描述性的标题，体现该功能 / 项目
• 用一到两句话概述要构建的内容
• 该项目带来的主要优势或价值

背景

背景情况

说明： 从宏观层面描述问题所处的环境以及问题本身。说明这项工作为何重要。解释当前状况、市场或用户工作流中的变化，以及该问题为何出现或为何在当下变得重要。

应包含的内容：

• 当前的环境 / 工作流 / 系统状况
• 该问题存在或变得重要的原因
• 相关趋势、限制或外部因素
• 当前状况与期望状况之间的差距

目标受众

说明： 明确我们要为哪些人解决这个问题。具体说明用户画像、角色或用户类型。尽可能对应常见的用户画像（例如，文档撰写者、产品工程师、DevOps / IT 人员、客户的客户 / 文档读者等）。如果有多个受众，请列出他们，并说明各自能获得哪些益处。

应包含的内容：

• 受影响的主要用户画像或角色
• 适用时列出次要受众
• 解决方案如何惠及各类受众
• 重要的具体用户特征或需求

问题陈述

说明： 列出我们要解决的具体问题。使用项目符号，每个项目符号对应一个问题。表述简洁直接——背景部分已说明相关情境。每条问题陈述都应清晰、具体且可执行。

应包含的内容：

• 每个问题单独列为一个项目符号
• 具体明确的问题（避免含糊表述）
• 解决方案能够直接解决的问题
• 聚焦于用户痛点或业务需求

假设

说明： 解释为什么我们认为解决这些问题能够帮助客户实现目标。这是“做什么”背后的“为什么”——说明问题与拟议解决方案之间的逻辑关系。阐明预期结果及其依据。

应包含的内容：

• 问题解决后预期实现的结果
• 问题与解决方案之间的逻辑联系
• 此方法有效的原因
• 所作出的假设（如有）

成功标准

说明： 定义我们如何判断问题已得到解决。成功标准应是可衡量、可测试或可观察的指标。既要包含定量指标（如适用），也要包含定性验证步骤。

应包含的内容：

• 具体、可衡量的指标（例如，采用率、性能提升、用户满意度评分）
• QA / 验证步骤或验收标准
• 表明成功的可观察行为或结果
• 成功所需的时间范围或阈值（如相关）

需求

说明： 列出解决该问题所需构建的内容。具体说明功能需求、技术需求和限制。如有帮助，可按优先级或类别组织。每项需求都应足够清晰，以便工程师了解需要构建什么。

应包含的内容：

• 功能需求（系统 / 功能必须实现的内容）
• 技术需求（性能、可扩展性、兼容性要求）
• 用户体验需求（如适用）
• 集成或依赖要求
• 优先级（必须具备与锦上添花）——如相关

非目标

说明： 明确说明我们不做什么、哪些内容不在范围内，以及哪些工作无需完成。这可以避免范围蔓延，并划定清晰的边界。请具体说明哪些看似相关的功能或能力被明确排除。

包含内容：

• 明确不在范围内的功能或能力
• 我们不解决的相关问题
• 可能看似相关但不属于本规范的未来工作
• 关于无需构建哪些内容的假设

权衡与顾虑

说明： 编写本节时，只需将下方占位内容设为斜体。

尤其从工程角度来看，要实现此解决方案，我们必须做出哪些艰难的决策？由于我们选择实现此方案，未来可能需要解决哪些问题？