SDD 设计文档模板

当变更提案已经可评审后，再使用设计文档。它决定“如何实现”，同时保留规格中的行为边界和约束。

design.md

# Design Doc

Spec:
Owner:
Status: Draft | Review | Approved

## Context
- 链接已评审的规格或变更提案。

## Architecture Decision
- 选择的方案：
- 选择原因：
- 拒绝的方案：

## Interfaces
- API:
- Events:
- Database:
- UI states:

## Constraints
- Compatibility:
- Security:
- Performance:
- Operational limits:

## Rollout Plan
- Phase 1:
- Phase 2:
- Stop signal:
- Rollback:

什么时候使用这份模板

规格影响 API、数据库、队列、权限或发布顺序。
团队需要在编码前比较两个实现方案。
AI 生成代码需要更窄的架构边界。
评审者需要知道为什么拒绝某个方案。

填好后应该是什么样

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

## Architecture Decision
- 选择方案：退款创建保持同步，支付渠道确认放入异步 worker。
- 原因：客服需要立即看到 pending 状态，渠道超时可稍后确认。
- 拒绝方案：在请求链路内反复重试渠道调用，因为重复退款风险更高。

实现前先检查这些点

选定方案能回到已批准的规格。
接口列出明确的 endpoint、事件、表或 UI 状态。
被拒绝方案写出原因，而不是只写名字。
上线和回滚计划足够具体。

弱写法 vs 强写法

弱写法

使用 worker，并补测试。

强写法

退款请求链路保持幂等；先创建一条本地退款记录，再入队确认渠道状态。pending_provider_confirmation 期间阻止客服发起第二笔退款。

FAQ

每份规格都要设计文档吗？

不需要。只有当实现选择本身有风险时才需要。很小的 UI 文案修改可以跳过。

哪些内容放在这里？

产品行为放在规格；架构选择、权衡、约束、接口和上线顺序放在设计文档。

AI 代理怎么使用？

把规格和设计文档一起给代理，并要求代码变更映射到批准的接口和约束。

编辑说明

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

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

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