SDD 变更提案模板

当一个需求不能只靠一句话交给开发，但还没到写实现细节的时候，用这份模板先把行为、边界、负责人和评审证据写清楚。

spec.md

# Change Proposal

Owner:
Status: Draft | Review | Approved
Date:

## Problem
- 现在什么行为不清楚、缺失或需要改变？

## Goal
- 这次上线后，用户或系统必须发生什么变化？

## Non-goals
- 本次明确不做什么？

## Acceptance Criteria
- Given ...
  When ...
  Then ...

## Open Questions
- [ ] ...

## Evidence Required
- Test:
- Log or metric:
- Manual check:
- Rollback signal:

什么时候使用这份模板

需求会影响多个页面、服务或角色。
产品或负责人需要工程在开工前确认范围。
AI 编码代理需要一个可追溯的上下文包。
评审者需要先看到非目标，避免实现阶段扩范围。

填好后应该是什么样

模板只有在写入真实决策、负责人和证据后才有价值。下面是一个可评审的片段。

## Goal
- 90 天内可退款的已捕获支付，不会产生重复退款。

## Non-goals
- 本次不更换支付渠道。
- 不做批量退款。

## Acceptance Criteria
- Given 同一个 idempotency key 被重复提交
  When 退款接口再次收到请求
  Then 返回已有 refund_id，且不发送第二条事件。

实现前先检查这些点

目标是一个行为结果，而不是任务清单。
非目标至少阻止一个常见的范围扩张。
每条验收标准都能被测试或观察。
证据写明测试、日志、指标、截图或手工检查。

弱写法 vs 强写法

弱写法

允许用户退款，并确保不会重复退款。

强写法

已捕获支付在 90 天内允许退款。相同 idempotency key 的重放请求返回已有 refund_id，不创建第二行记录，也不发送第二条 refund_requested 事件。

FAQ

它和 PRD 有什么不同？

PRD 说明产品意图；变更提案把意图转成工程行为、验收标准和证据。

应该写多长？

多数提案一页就够。如果需要架构权衡，链接设计文档，不要把这份模板无限加长。

什么时候可以进入实现？

当评审者对范围、非目标、影响系统和合并前证据达成一致时。

编辑说明

这份模板面向 spec-driven development 工作流，示例用于展示结构，不代表特定公司的内部流程。

作者: Daniel Marsh
编辑政策: 我们如何审阅和更新内容

建议把它放在仓库的 /docs/specs/ 或 /.specs/ 下，并在实现过程中持续更新。最后更新：2026 年 5 月 11 日。