write-spec

编写规格说明

如果你看到不熟悉的占位符，或需要确认已连接哪些工具，请参阅 CONNECTORS.md。

编写功能规格说明或产品需求文档（PRD）。

用法

/write-spec $ARGUMENTS

工作流

1. 了解功能

询问用户想要规划的内容。以下任一形式均可接受：

• 功能名称（“SSO 支持”）
• 问题陈述（“企业客户一直在要求集中式身份验证”）
• 用户请求（“用户希望将数据导出为 CSV”）
• 模糊的想法（“我们应该解决新手引导流失的问题”）

2. 收集上下文

向用户询问以下信息。保持对话式交流，不要一次性抛出所有问题。先问最重要的问题，并在交流过程中补全缺失信息：

• 用户问题：这个功能要解决什么问题？谁会遇到这个问题？
• 目标用户：这个功能服务于哪些用户群体？
• 成功指标：我们如何判断这项功能是否成功？
• 约束条件：技术约束、时间线、合规要求、依赖项
• 已有方案：此前是否尝试过？是否存在现有解决方案？

3. 从已连接的工具中获取上下文

如果已连接 ~~project tracker：

• 搜索相关的工单、史诗（epic）或功能项
• 提取已有的需求或验收标准
• 识别与其他工作项的依赖关系

如果已连接 ~~knowledge base：

• 搜索相关的研究文档、历史规格说明或设计文档
• 提取相关的用户研究结论
• 查找相关的会议纪要或决策记录

如果已连接 ~~design：

• 提取相关的原型图、线框图或设计探索稿
• 搜索与该功能相关的设计系统组件

如果这些工具未连接，则完全基于用户提供的信息开展工作。不要要求用户连接工具，直接使用现有信息继续即可。

4. 生成 PRD

按照以下章节生成结构化的 PRD。各章节应包含的具体内容请参阅下方的 PRD 结构。

• 问题陈述：用户问题、受影响的人群，以及不解决该问题的影响（2-3 句话）
• 目标：3-5 项具体、可衡量、与用户或业务指标挂钩的成果
• 非目标：3-5 项明确不在范围内的事项，并附上简要理由
• 用户故事：采用标准格式（“作为【用户类型】，我希望【能力】，以便【收益】”），按用户角色分组
• 需求：分为必须具备（P0）、最好具备（P1）和未来考虑（P2），每项均附验收标准
• 成功指标：领先指标（快速变化）和滞后指标（随时间变化），并给出具体目标值
• 待解决问题：尚未解决的问题，并标注需要回答的人员（工程、设计、法务、数据）
• 时间线考量：硬性截止日期、依赖关系与分期安排

5. 审阅与迭代

生成 PRD 后：

• 询问用户是否需要调整任何章节
• 主动提出对特定章节进行扩展说明
• 提议创建后续产出物（设计简报、工程工单拆分、利益相关方汇报材料）

PRD 结构

问题陈述

• 用 2-3 句话描述用户问题
• 谁会遇到这个问题，以及发生的频率
• 不解决该问题的代价（用户痛点、业务影响、竞争风险）
• 以证据为依据：用户研究、支持数据、指标或客户反馈

目标

• 3-5 项该功能应实现的具体、可衡量的成果
• 每个目标都应回答：“我们如何判断它成功了？”
• 区分用户目标（用户获得什么）与业务目标（公司获得什么）
• 目标应为成果而非产出物（“将首次获得价值的时间缩短 50%”，而非“构建新手引导向导”）

非目标

• 3-5 项本功能明确不会做的事情
• 本版本范围之外的相邻能力
• 对每个非目标，简要说明其超出范围的原因（影响不足、过于复杂、独立计划、时机尚早）
• 非目标可以防止实施过程中的范围蔓延，并为利益相关方设定预期

用户故事

按照标准格式编写用户故事："作为 [用户类型]，我希望 [能力]，以便 [收益]"

指南：

• 用户类型应足够具体，才有意义（例如"企业管理员"而不是仅仅"用户"）
• 能力应描述他们想完成什么，而不是如何完成
• 收益应解释"为什么"——这带来了什么价值
• 包含边界情况：错误状态、空状态、边界条件
• 如果功能服务于多种角色，请包含不同的用户类型
• 按优先级排序——最重要的故事放在最前面

示例：

• "作为团队管理员，我希望为我的组织配置 SSO，以便团队成员可以使用企业凭据登录"
• "作为团队成员，我希望自动跳转到公司的 SSO 登录页面，以便无需记住单独的密码"
• "作为团队管理员，我希望查看哪些成员通过 SSO 登录过，以便确认推广是否正常运作"

需求

必须具备（P0）：没有这些，功能无法发布。这些代表功能的最小可行版本。提问："如果去掉这项，功能是否仍能解决核心问题？"如果否，则它为 P0。

最好具备（P1）：能显著改善体验，但没有它们核心用例也能运行。这些通常会在上线后作为快速后续迭代推出。

未来考虑（P2）：明确不在 v1 范围内，但我们希望以支持其后续实现的方式进行设计。记录这些内容可以防止意外的架构决策使其日后难以实现。

对于每项需求：

• 清晰、无歧义地描述预期行为
• 包含验收标准（见下文）
• 记录任何技术考虑或约束
• 标明对其他团队或系统的依赖

待解决问题

• 需要在实施前或实施期间得到答案的问题
• 为每个问题标注应由谁回答（工程、设计、法务、数据、利益相关方）
• 区分阻塞性问题（开始前必须回答）与非阻塞性问题（可在实施期间解决）

时间线考虑

• 硬性截止日期（合同承诺、活动、合规日期）
• 对其他团队工作或发布的依赖
• 如果功能过大无法一次发布，建议的分阶段计划

用户故事编写

好的用户故事应当是：

• 独立的：可以单独开发和交付
• 可协商的：细节可以讨论，故事不是合同
• 有价值的：为用户（而不仅是团队）带来价值
• 可估算的：团队可以大致估算工作量
• 小的：可在一个 Sprint/迭代内完成
• 可测试的：有明确的方法验证其是否可行

用户故事的常见错误

• 过于模糊："作为用户，我希望产品更快" —— 具体应该哪里更快？
• 指定解决方案："作为用户，我希望有一个下拉菜单" —— 描述需求，而不是 UI 控件
• 没有收益："作为用户，我希望点击一个按钮" —— 为什么？它能完成什么？
• 过于庞大："作为用户，我希望管理我的团队" —— 将其拆分为具体能力
• 内部视角："作为工程团队，我们希望重构数据库" —— 这是任务，而不是用户故事

需求分类

MoSCoW 框架

• 必须有（Must have）：没有这些，功能不可行。不可协商。
• 应该有（Should have）：重要但对上线并非关键。高优先级的快速后续迭代。
• 可以有（Could have）：时间允许时可以实现。如被砍掉也不会延误交付。
• 本次不做（Won't have (this time)）：明确超出范围。未来版本可能重新考虑。

分类提示

• 对 P0 要严格把关。必做清单越精简，交付和学习就越快。
• 如果所有需求都是 P0，那就没有真正的 P0。逐条质疑每个必做项："如果没有这个，我们真的不能发布吗？"
• P1 应该是你确信很快就会构建的事项，而不是愿望清单。
• P2 是架构层面的保险，即使当前不构建，也能指导设计决策。

成功指标定义

领先指标

发布后变化较快的指标（数天到数周）：

• 采用率：尝试该功能的符合条件用户的百分比
• 激活率：完成核心操作的用户百分比
• 任务完成率：成功达成目标的用户百分比
• 完成耗时：核心工作流所需的时间
• 错误率：用户遇到错误或死路的频率
• 功能使用频率：用户回到该功能使用的频率

滞后指标

需要较长时间才能显现的指标（数周到数月）：

• 留存影响：该功能是否提升用户留存？
• 收入影响：该功能是否带动升级、扩展或新增收入？
• NPS / 满意度变化：该功能是否改善用户对产品的感受？
• 支持工单减少：该功能是否减轻支持负担？
• 竞争赢单率：该功能是否帮助赢得更多订单？

设定目标

• 目标应当具体，例如"30 天内采用率达到 50%"，而不是"采用率高"
• 目标应基于同类功能、行业基准或明确的假设
• 设定一个"成功"阈值和一个"挑战"目标
• 明确衡量方法：使用什么工具、什么查询、什么时间窗口
• 指定评估时间：发布后 1 周、1 个月或 1 个季度

验收标准

以 Given/When/Then 格式或清单形式撰写验收标准：

Given/When/Then：

• Given [前置条件或上下文]
• When [用户采取的操作]
• Then [预期结果]

示例：

• Given 管理员已为其组织配置 SSO
• When 团队成员访问登录页面
• Then 系统自动将其重定向至组织的 SSO 提供方

清单格式：

• 管理员可以在组织设置中输入 SSO 提供方 URL
• 团队成员在登录页面上看到"使用 SSO 登录"按钮
• 如果账户不存在，SSO 登录会创建新账户
• 如果邮箱匹配，SSO 登录会关联到已有账户
• SSO 登录失败时显示清晰的错误信息

验收标准撰写提示

• 覆盖正常流程、错误情况和边界情况
• 描述预期行为，而非实现方式
• 包含不应发生的情况（反向测试用例）
• 每条标准都应可独立测试
• 避免模糊用词，如"快速"、"用户友好"、"直观"，应具体定义其含义

范围管理

识别范围蔓延

范围蔓延通常发生在以下情况：

• 规格说明获得批准后，仍不断有新需求加入
• "小"的增加不断累积，最终变成规模大得多的项目
• 团队在构建没有用户要求的功能（"顺便……"）
• 上线日期不断推迟，却没有明确的重新定义范围
• 利益相关方不断添加需求，却不删除任何内容

预防范围蔓延

• 在每份规格说明中明确写出非目标
• 要求任何范围新增都必须伴随范围削减或时间表延长
• 在规格说明中清楚区分"v1"与"v2"
• 对照最初的问题陈述审视规格说明：每项内容是否都服务于该问题？
• 为调研设定时间上限："如果我们在 2 天内无法弄清 X，就砍掉它"
• 为好想法建立"待办池"，存放不在当前范围内的想法

输出格式

使用带有清晰标题的 Markdown。保持文档便于快速浏览：忙碌的利益相关方应当只读标题和加粗文字，就能掌握要点。

提示

• 对范围要有明确主张。一份边界清晰、定义明确的规格，比一份宽泛模糊的规格更好。
• 如果用户的想法对于一份规格来说太大，建议将其拆分为多个阶段，并为第一阶段编写规格。
• 成功指标应当具体且可衡量，而不是模糊的表述（例如“改善用户体验”）。
• 非目标与目标同样重要。它们可以防止实现过程中出现范围蔓延。
• 待定问题应当确实悬而未决，不要包含那些可以从上下文中得出答案的问题。