spec-writer

编写产品需求文档

这项技能会结合对话和代码仓库上下文，将已明确的想法转化为一份结构化的产品需求文档（PRD）。它假定主要歧义已充分梳理（例如使用 /grill-me），但也可以在需要时自行进行轻量澄清。

适用场景

当用户有以下需求时，使用这项技能：

• 要求“编写 PRD”“产品规格说明”“需求文档”“功能规格说明”等，或提出类似要求。
• 希望在实施之前，以结构化的方式记录新功能、变更或系统。
• 已经明确了想法，现在需要一份完整连贯的文档，可将其作为 issue 提交、分享给利益相关者，或提供给 /slice-the-spec。

如果想法仍然模糊或信息不足，建议先使用 /grill-me，然后再使用这项技能。

整体工作流程

如果某些步骤显然已完成，可以跳过或简化（例如，用户提供了详细的问题说明或用户故事列表）。

1. 收集详尽的问题描述

   • 请用户详细描述以下内容：
     • 想要解决的问题
     • 面向的用户
     • 现在解决这一问题的意义
     • 已有的初步解决方案构想或约束
   • 鼓励用户粘贴现有上下文（文档、工单、研究资料），而不是重新输入所有内容。

2. 探索代码仓库并验证假设

   • 检查代码库，了解当前行为、相关模块、数据模型和现有 API。
   • 交叉核对用户的陈述：记录代码仓库在哪些方面与之相符、相悖或未提及，并据此调整理解。
   • 记录与范围、边缘情况或实施约束相关的代码仓库事实。

3. 考虑替代方案

   • 询问用户是否考虑过其他解决方案或设计方向。
   • 简要列出 2–3 种可行方案及其权衡（复杂度、交付时间、风险、用户体验影响）。
   • 确认 PRD 应以哪种方案为主要方案。

4. 深入访谈实施细节（如有需要）

   • 如果需求仍较为宽泛，就功能的详细行为采访用户：流程、状态、输入／输出、失败模式、权限和性能预期。
   • 如果答案取决于现有行为，优先检查代码仓库，而不是猜测。
   • 明确列出假设并请求确认。

5. 敲定确切范围

   • 明确本 PRD 的范围内内容，并明确列出范围外内容（例如，延期处理的边缘情况、锦上添花的功能、后续事项）。
   • 明确目标发布范围（MVP 或完整功能），以及任何排序或第一阶段／第二阶段的区分。

6. 梳理模块和架构（轻量级）

   • 确定需要创建或修改的主要模块、服务或组件。
   • 指出可提取为深度、可测试模块的部分，以便单独验证（适用于后续 TDD 或使用 /tdd）。

7. 使用结构化模板编写 PRD

   • 按照清晰标注的章节起草完整 PRD（见下方模板）。
   • 使用适合工程师、产品经理和设计师阅读的朴实、准确的语言。

8. 将文档归档到合适的位置（可选）

   • 如有需要，按照代码仓库的惯例，将 PRD 整理为 GitHub issue 或 Markdown 文件。
   • 如果上下文中提供了相关信息，请添加标签、负责人以及相关 issue 或文档的链接。

PRD 模板

使用并按需调整此结构。对于明显不相关的章节可以省略，但建议尽量保留。

1. 摘要

• 用 2–3 句话说明我们要构建什么以及为什么。
• 说明目标用户群体和预期的主要成果。

2. 问题陈述

• 产品当前存在的痛点或缺口。
• 谁在什么情境下遇到了这个问题。
• 相关证据（指标、轶事、用户研究、支持工单），如有。

3. 目标与非目标

• 目标： 用简短的编号列表说明成功的标准。
• 非目标： 明确列出本 PRD 不会尝试实现的内容。

4. 用户故事

用较长的编号列表列出用户故事，涵盖所有重要行为。

每个用户故事应遵循以下格式：

1. 作为 <actor>，我希望 <feature>，以便 <benefit>
   • 如有帮助，可在行内补充验收说明或澄清。

尽量全面覆盖：核心流程、边缘情况、权限差异和失败场景。

5. 功能需求

• 详细描述各主要领域或流程的预期行为。
• 系统状态、状态转换，以及不同角色如何与该功能交互。
• 与正确性相关的验证规则、错误处理、重试、速率限制和约束。

6. 非功能需求

• 相关的性能、可扩展性和延迟预期。
• 可靠性、可用性和降级行为。
• 适用时的安全、隐私和合规考量。

7. 实现说明与架构

• 用文字形式描述高层架构或组件图。
• 列出需要修改或创建的模块／服务，以及它们如何交互。
• 关联当前代码库的说明（关键类、端点、表）。

8. 范围之外

• 明确列出本 PRD 不会涵盖的功能、流程、用户类型或边缘情况。
• 如已知，请提及可能的后续工作或未来迭代。

9. 风险与待解决问题

• 已知风险：技术、产品、用户体验或组织方面的风险。
• 实施或发布前必须解决的待定问题。
• 特别脆弱的假设。

10. 成功指标

• 说明如何判断这项工作是否成功（输入和输出指标）。
• 如果尚无精确数字，请描述预期趋势（例如，“显著减少关于 X 的支持工单”）。

行为与规则

1. 结构优先于大段文字：将内容拆分为清晰的章节和编号列表。
2. 尽可能使用代码库中的事实；能检查代码时，不要臆造 API 或数据模型。
3. 如果用户更看重速度而非全面性，请确认他们希望优先处理哪些章节，并尽量精简其余内容。
4. 如果需求过于模糊，请提出 1–3 个有针对性的澄清问题，而不是自行猜测。
5. 目标是编写一份工程师无需多次沟通即可据以实施的文档，而不是营销宣传单。