功能 Spec 模板

模板使用路径

1. 把 Markdown 模板复制到 ticket、PR 或项目仓库。
2. 补齐负责人、非目标、验收标准、证据和回滚说明。
3. 让产品、研发和 QA 分别检查不同失败模式。
4. 实现行为发生变化时，在同一个变更里同步更新规格。

填完后应该长什么样

模板只有写入真实决策、责任人和证据后才有价值。上方空模板用于搭结构；进入实现前，建议至少写到下面这种具体程度。

## 退款重试行为
责任人：Billing platform

决策：
- 重试复用同一个 idempotency key

证据：
- 重复请求测试
- 支付渠道超时 fixture
- 客服后台截图

如果复制后的模板仍然缺责任人、证据或回滚字段，就先不要进入实现。

适用场景

• 新功能需求存在多角色协作（产品/研发/测试）。
• 改动可能影响 API、DB、UI 的一致性。
• 使用 AI 编码，需要强约束范围和验收标准。
• 历史上有“口头需求导致返工”的项目。

每个章节怎么写

• Goal：一句话写清用户价值或业务结果。
• Non-goals：明确这次“不做什么”。
• Acceptance：使用可验证的 Given/When/Then。
• Edge Cases：最少覆盖空值、重复、并发、权限。
• Deliverables：写清代码范围、测试项、回滚方案。

原则：让评审者在不追问的情况下，直接能设计测试用例。

常见误区

• 只写“要做什么”，不写“如何验收”。
• 出现“尽量、合理、优化”等不可验证措辞。
• 边界条件仅写标题，不写预期行为。
• 有状态变更却没有回滚步骤。

开发前评审清单

• 每条验收标准都有对应测试。
• 非目标已被团队确认，避免范围膨胀。
• API/DB 兼容性影响已记录。
• 上线与回滚条件可执行。

配套阅读：Spec 示例、评审清单。

弱写法和强写法对比

弱写法

“用户可以筛选订单，页面要好用，性能要合理。”这类描述看起来简洁，但研发和测试无法判断筛选字段、默认排序、空结果、权限和性能阈值。

强写法

“订单列表支持按状态、创建时间和客户邮箱筛选。默认展示最近 30 天订单，按创建时间倒序。无结果时展示空状态。没有 orders.read 权限时返回 403。P95 查询耗时低于 300ms。”

强写法不是更长而已，它把验收边界、权限条件和性能标准变成可以测试的约束。

团队如何使用这份模板

• 产品先填写目标、非目标和用户场景，避免评审时才发现范围不一致。
• 研发补充数据、接口、状态变更和回滚影响，尤其是跨服务或跨表改动。
• 测试把验收标准拆成用例，检查每条 Given/When/Then 是否能自动化或手动验证。
• 使用 AI 编码前，把模板作为上下文输入，并明确要求实现不得超出 Non-goals。

评审切片示例：订单筛选第一版

如果第一版订单筛选目标太大，可以先写一个可上线切片，让团队验证查询性能、权限和空结果行为。

第一版范围：
- 支持按订单状态和创建时间筛选
- 默认展示最近 30 天
- 无 orders.read 权限返回 403
- 空结果展示空状态，不自动扩大时间范围

暂不做：
- 客户邮箱模糊搜索
- 保存筛选条件
- 跨工作区批量导出

这种切片让产品看到可交付边界，也让研发和 QA 有明确的第一版完成标准。

落地时不要漏的三件事

• 负责人：写清谁批准范围变化，避免实现过程中每个人都能临时加需求。
• 证据：每条验收标准都要对应测试、截图、日志或手工验证记录。
• 更新：如果评审后调整了非目标、边界条件或发布策略，必须先更新 Spec，再继续开发。

功能规格的价值来自持续对齐，而不是第一次填写模板时的完整度。评审结束时，团队应该能回答三个问题：第一版到底交付什么，哪些内容明确延期，失败或回滚时由谁判断是否继续。如果这些答案仍然模糊，说明还不应该进入实现。

如果团队会把 Spec 交给 AI 编码工具，也建议在提示词里保留这些限制条件。这样生成结果更容易围绕已确认范围展开，而不是自动补出未经评审的字段、状态或交互细节。

怎样判断可以进入实现

一份功能 Spec 可以进入实现，通常意味着评审者能不参加原始会议，也能说清第一版交付什么、不交付什么、影响哪些角色、需要哪些测试证据，以及出现什么情况应该暂停或回滚。如果这些答案还依赖口头记忆，就应该继续留在评审阶段。

如果后续要交给 AI 编码工具，建议要求它把每个代码改动映射到目标、验收标准、边界条件或交付物。这样 PR 评审就不再只是主观判断，而是检查每个新增行为是否有规格依据。

常见问题

这个模板适合小改动吗？

适合需要多人理解的小改动。如果只是一次明显的文字替换，可以用更轻的清单；但只要涉及状态、权限、数据或用户可见行为，就值得写成短 Spec。

验收标准应该写几条？

通常 5 到 12 条足够。关键不是数量，而是覆盖正常路径、失败路径、边界条件、权限和回滚判断。

什么时候说明规格还没有准备好？

如果评审时仍有人无法说清第一版范围、非目标、失败路径或测试证据，说明规格还只是需求草稿。此时继续编码会把未解决的问题推到 PR、QA 或发布阶段。

准备好的规格应能让新加入的工程师在不参加原始会议的情况下理解交付边界。

如果新成员仍需要口头补课，说明文档缺少关键上下文，应在实现前补回目标、限制或验收证据。

这也是减少后续返工的核心价值。

发布后如何回看这份规格

功能上线后，建议把最终规格和实际结果放在一起复查：哪些验收标准直接变成了测试，哪些边界条件在实现中发生变化，哪些非目标后来被重新提出。这个回看能帮助团队判断模板是否需要增加字段或删掉无用章节。

如果一次发布出现返工，不要只在复盘里写“沟通不足”。应回到规格本身，找出缺失的决策：谁拥有范围、哪条失败路径没写、哪项证据没有在评审时出现。