第一周
在一个真实工单上使用变更提案，并要求评审者在实现前挑战非目标。
SDD 文件链路
意图
spec.md在实现前写清目标、非目标、验收标准、边界条件和发布证据。版本化
specs/当规格需要进入 git、随 PR 评审，并和实现证据绑定时，把它作为 Spec as Code 管理。打开 Spec as Code 主题 Hub。设计
design.md记录架构选择、被拒绝方案、接口、上线顺序和运行约束。执行
tasks.md把工作拆成可评审任务，写明负责人、允许文件、验收链接和测试命令。证明
evidence.md把验收标准连接到测试、截图、日志、指标、手工检查和上线停止信号。为什么 SDD 能改善 AI 辅助交付
| 常见失败模式 | SDD 改变什么 | 评审信号 |
|---|---|---|
| 模糊提示词变成大 diff | 规格先写清非目标和允许行为。 | 规格外代码可以直接要求移除。 |
| 架构在生成过程中被发明 | 设计文档先写清接口、约束和被拒绝方案。 | 生成代码必须符合批准过的形状。 |
| 大 PR 难评审 | 任务按验收标准和文件归属拆开。 | 评审者可以检查更小的可测试切片。 |
| 把批准当成证明 | 证据日志把标准连接到测试、截图、指标和发布门禁。 | 合并评审有具体证据可看。 |
真实案例：退款重试但不能重复扣款
有价值的 SDD 包应该从真实交付问题开始。这个案例里，客服需要在支付渠道超时后重试退款。危险写法是一句话：“让退款可以重试”。这会把幂等、客服权限、渠道状态和上线证据都留给实现阶段自行决定。
SDD 写法会把决定拆到不同文件。spec.md 规定相同 idempotency key 必须返回已有 refund_id。design.md 选择 pending_provider_confirmation 状态，而不是在请求链路里同步重试。tasks.md 拆开存储、worker、客服 UI 和测试。evidence.md 记录重放测试、客服阻断状态截图，以及触发停止发布的指标。
| 产物 | 它负责的决定 | 评审者要问什么 |
|---|---|---|
spec.md | 退款重放必须幂等，并且只能发生在 90 天退款窗口内。 | 客服能否不用问工程，就解释渠道超时后发生什么？ |
design.md | 渠道确认放到 worker；请求链路只创建一条本地 pending 记录。 | 被拒绝的同步重试方案是否说清了重复退款风险？ |
tasks.md | 存储、worker、UI 和测试分成独立切片，并写明允许文件。 | 某个切片评审失败时，是否会拖垮整个计划？ |
evidence.md | 合并前必须附重放测试、客服阻断截图和重复退款告警。 | 发布负责人是否知道什么时候停止 rollout？ |
怎样采用 SDD，而不是增加仪式感
先从一个高风险真实工单开始，不要一上来改全公司流程。适合的第一批场景包括支付流程、公开 API、数据迁移、权限、通知发送，或任何“AI 生成大 diff 后很难评审”的改动。第一个规格包应该小到评审者十分钟内能看完。
采用规则很简单：只有当某个文件能减少歧义时才添加它。小的 UI 文案变更可能只需要 spec.md；公开 API 变更可能需要 design.md、tasks.md 和 evidence.md。如果一个文档不会改变决策、测试或发布门禁，它大概率只是仪式。
判断是否有效，可以看评审会不会更快暴露分歧。如果大家只是读完文档点头，说明内容还不够具体；如果评审者能指出一个非目标、一个证据缺口或一个需要拆分的任务，SDD 才真正发挥作用。
第二周
只在需要窄文件归属、多评审者或 AI 编码边界的工作上加入 tasks 文件。
第三周
对高风险变更加 evidence log，并对比新旧流程下的发布评审质量。
可复制的 SDD 模板
SDD、Spec-First、TDD 和 BDD
| 方法 | 核心问题 | 适合解决什么 |
|---|---|---|
| Spec-First Development | 写代码之前，应该先决定什么行为？ | 在实现前澄清产品和工程决策。 |
| Spec as Code | 规格应该放在哪里、如何评审？ | 把 spec.md 放进 git，让 PR、测试和发布证据引用同一个产物。 |
| Spec-Driven Development | 哪些仓库文件应该指导计划、编码和证据？ | 用可评审文件协调人工和 AI 代理。 |
| TDD | 哪些测试应该驱动实现？ | 在编码过程中保护单元、契约和回归。 |
| BDD | 哪些示例描述用户可见行为？ | 用业务可读语言写共享示例。 |
当前 SDD 工具带来的启发
OpenSpec 模式
先让变更意图可评审，再进入代码生成。有价值的是显式提案，而不是工具锁定。
Superpowers 模式
给编码代理持久技能和仓库规则，让重复工作遵循同一标准，而不是每次重新开聊天。
Spec Kit 模式
从 specification 到 plan 再到 task execution，让 AI 辅助实现拥有清晰决策轨迹。
FAQ
什么是 spec-driven development？
Spec-driven development 是一种先写可评审规格、约束、实现任务和验证证据，再进入主要代码改动的工作流。
SDD 和 spec-first development 有什么区别？
Spec-first 是先写行为再写代码的原则；SDD 更强调仓库里的文件链路，通常包括 spec、design、tasks 和 evidence。
SDD 会取代 TDD 或 BDD 吗？
不会。SDD 先决定行为和约束，TDD 和 BDD 可以继续用来编写测试和业务示例，证明规格被正确实现。
为什么 SDD 对 AI 编码重要？
AI 编码代理需要明确指令、非目标、允许文件和证据要求。SDD 在改代码之前提供一个可评审的事实来源。
最小可用的 SDD 包是什么？
最小 SDD 包可以是一个包含 spec.md、tasks.md 和 evidence.md 的文件夹；当架构选择需要评审时再加入 design.md。
先把 SDD 模板用在一个真实工单上。让它足够短，方便评审；也要足够具体，能阻止实现漂移。