目录
一、什么是 SDD？
二、为什么 AI 时代更需要 SDD？
三、SDD 的核心理念
（一）规范是单一事实来源
（二）规范应当可测试
（三）规范应当可拆解
（四）规范应当随代码演进
四、SDD 的标准流程
（一）第一步：意图澄清
（二）第二步：需求规范
（三）第三步：技术设计
（四）第四步：任务拆解
（五）第五步：实现编码
（六）第六步：验证与演进
五、SDD 的核心制品
（一）Proposal：变更提案
（二）Requirements：需求规范
（三）Design：设计规范
（四）Tasks：任务计划
（五）Tests：验证规范
（六）Traceability：追踪关系
六、SDD端到端一致性与可追踪性
（一）SDD 与 TDD、BDD、Agile 的关系
（二）SDD 的最大价值：可追踪性
七、如何在团队中落地 SDD？
（一）从一个功能开始，不要全量重构
（二）把规范放进代码仓库
（三）为规范建立模板
（四）让代码评审检查规范
（五）让 AI 使用规范，而不是只使用提示词
（六）建立漂移门禁
九、SDD 的常见误区与适用场景
（一）常见误区说明
误区一：SDD 就是写很多文档
误区二：SDD 会降低开发速度
误区三：有了 SDD 就不需要产品沟通
误区四：SDD 只适合大公司
（二）SDD 适合哪些场景？
（三）一个最小可行的 SDD 模板
十、结语：未来的软件资产不只是代码
参考资料与延伸阅读
一、SDD 与 AI 辅助开发
二、SDD 研究与理论背景
三、需求工程与规范标准
四、可追踪性、契约与验证
五、TDD、BDD 与验收规范
六、Docs-as-Code、架构规范与 API-first
七、敏捷、持续交付与演进式架构
干货分享，感谢您的阅读！
在 AI 辅助编程快速普及之后，很多团队发现一个矛盾：代码生成速度变快了，但需求偏差、设计漂移、上下文丢失、测试不足、返工变多的问题也更明显了。传统开发中，需求文档、设计文档、任务拆解、代码、测试往往分散在不同工具里；AI 时代又进一步放大了这种割裂，因为很多关键决策只存在于聊天记录、提示词、临时笔记或某个开发者的大脑中。
SDD，Spec-Driven Development，规范驱动开发，正是为了解决这个问题而出现的一种开发方法。它的核心思想很直接：不要让代码成为唯一的事实来源，而是让规范成为需求、设计、实现、测试和 AI 协作的共同中心。 GitHub Spec Kit 的官方文档也将 SDD 描述为把 specifications 放在 AI 辅助软件开发中心的方法：先描述要构建什么，经过结构化阶段细化，再让 AI 编码代理实现。
一、什么是 SDD？
SDD 不是简单地“先写需求文档再写代码”，也不是把瀑布模型换个名字。它强调的是：规范是可维护、可追踪、可执行、可验证的工程资产。
在 SDD 中，规范通常包含以下内容：
需求规范：说明用户是谁、要解决什么问题、业务规则是什么、验收标准是什么。 设计规范：说明系统如何实现这些需求，包括架构、接口、数据模型、安全约束、异常流程等。 任务规范：把设计拆成可执行任务，明确依赖关系、完成定义和交付顺序。 验证规范：把验收标准转化为测试用例、质量门禁、安全检查和回归策略。 实现关联：将代码、PR、测试、接口文档、运行日志与规范项绑定起来。
因此，SDD 的重点不是“文档变多”，而是让文档不再是一次性说明书，而成为软件持续演进的控制面板。GitHub 的 Spec Kit 仓库明确提出，SDD 改变了过去“规范只是脚手架、代码才是国王”的习惯，使规范能够直接生成或驱动工作实现。
二、为什么 AI 时代更需要 SDD？
过去，团队依赖人的经验来弥补需求不清、设计不全、任务不细的问题。资深工程师会在脑中自动补全边界条件，测试人员会发现不合理流程，产品经理会通过反复沟通纠偏。但 AI 编码代理并不真正“知道”组织里的隐含规则，它只能根据当前上下文推断。
这会带来几个典型问题。
- 第一，需求歧义被快速固化成代码。如果一条需求没有明确边界，AI 可能会生成看似合理但方向错误的实现。速度越快，错误扩散越快。
- 第二，聊天上下文不能替代工程资产。一次 AI 对话中达成的结论，如果没有沉淀到仓库里的规范文件，后续开发者、测试人员和另一个 AI Agent 都可能无法复用。
- 第三，代码和意图容易漂移。功能上线后，代码被修改了，需求文档没更新；测试补充了，设计没同步；接口变了，任务说明还停留在旧版本。时间一长，团队不知道系统“应该怎样”，只能猜测“代码现在怎样”。
- 第四，AI 生成代码需要更强的边界条件。没有规范时，AI 很容易优先满足表面功能；有规范时，它至少可以围绕验收标准、接口契约、安全要求和测试门禁来工作。Kiro 的官方文档也把 Feature Specs 描述为引导需求收集、技术设计和实现规划的结构化过程。
三、SDD 的核心理念
（一）规范是单一事实来源
在 SDD 中，需求、设计、任务、测试和代码都应指向同一组规范。规范不是附属品，而是团队判断“这个功能到底应该怎么做”的依据。
例如，一个“用户重置密码”的功能，不应只在某个 issue 里写一句“支持重置密码”。它应该至少包含：
- 用户在什么情况下可以重置密码；
- 重置链接多久过期；
- 同一链接能否重复使用；
- 失败次数是否有限制；
- 是否需要防止账户枚举；
- 邮件发送失败如何处理；
- 如何测试过期链接、重复提交、非法 token 等场景。
这些内容如果不进入规范，就会变成每个人的猜测。
（二）规范应当可测试
一条好的规范不是“系统要好用”，而是“当用户输入有效邮箱并通过验证码验证后，系统应在 5 分钟内发送一次性重置链接；该链接 30 分钟后失效，且成功使用一次后立即作废”。
前者是愿望，后者才可以转化为测试。
（三）规范应当可拆解
SDD 不希望规范停留在宏大的产品描述上。它要求把规范拆成任务，并让每个任务都有清晰的输入、输出、依赖和完成定义。这样无论是人类工程师还是 AI Agent，都能按任务执行。
（四）规范应当随代码演进
很多团队失败不是因为没有文档，而是因为文档失效。SDD 要求规范与代码同仓库、同版本、同评审。当代码改变了系统行为，相关规范也必须更新。
四、SDD 的标准流程
一个典型的 SDD 流程可以分为六步。
（一）第一步：意图澄清
在真正写规范之前，团队要先明确问题本身。这个阶段要回答：
- 为什么要做这个功能？
- 目标用户是谁？
- 业务成功指标是什么？
- 不做哪些事情？
- 有哪些合规、安全、性能、成本约束？
这一步的产物可以是简短的 proposal、feature brief 或 change request。OpenSpec 的官方说明中，也强调在写代码前先生成 proposal、任务、技术设计决策和 spec deltas，以便提前审查和发现不一致。
（二）第二步：需求规范
需求规范的重点是“系统应该表现出什么行为”。常见写法包括用户故事、场景描述、验收标准、业务规则、异常路径、权限边界等。
一个较好的需求规范片段可以这样写：
需求 ID：REQ-LOGIN-003 标题：连续登录失败后的账户保护 描述：当同一账户在 10 分钟内连续 5 次登录失败，系统应临时限制该账户继续尝试登录。 验收标准：
这类规范不仅产品、研发能读懂，也能直接转成测试用例。
（三）第三步：技术设计
技术设计回答“如何实现”。它可以包括：
- 系统架构；
- 模块边界；
- API 契约；
- 数据库表结构；
- 缓存策略；
- 错误码；
- 安全设计；
- 性能指标；
- 兼容性方案；
- 回滚策略。
对于 AI 辅助开发来说，设计规范尤其关键。没有设计约束，AI 可能会选择与现有架构不一致的实现方式，甚至重复造轮子。
（四）第四步：任务拆解
任务规范把需求和设计转化为可执行工作。一个任务应当足够小，能被明确完成、评审和验证。
例如：
TASK-LOGIN-003A：新增登录失败计数表。 TASK-LOGIN-003B：实现失败计数与保护期判断逻辑。 TASK-LOGIN-003C：补充账户保护提示文案。 TASK-LOGIN-003D：增加单元测试和集成测试。 TASK-LOGIN-003E：增加管理员后台事件查询。
每个任务都应关联需求 ID、设计章节和测试项。
（五）第五步：实现编码
在实现阶段，开发者可以手写代码，也可以让 AI 生成代码。但无论哪种方式，代码都不应脱离规范。理想状态是：AI Agent 根据需求规范、设计规范和任务规范生成代码；开发者审查代码是否满足规范；测试验证规范是否被正确实现。
AWS 中文官方博客对 Kiro 的介绍也体现了类似思路：把多轮对话和零散需求收敛成 requirements、design、tasks 等结构化规范，再在这些规范约束下规划、编写和重构代码。
（六）第六步：验证与演进
验证阶段不仅要看测试是否通过，还要检查规范、代码、测试是否一致。常见做法包括：
- 需求验收测试；
- 单元测试和集成测试；
- 安全扫描；
- 架构规则检查；
- API 契约测试；
- 规范漂移检查；
- 代码评审时强制关联需求 ID。
如果测试发现需求遗漏，就更新需求规范；如果实现改变了设计，就更新设计规范；如果任务拆解不合理，就更新任务规范。
五、SDD 的核心制品
SDD 的制品不一定固定，但成熟实践通常包含以下几类。
（一）Proposal：变更提案
用于说明为什么要做某个变更。它关注动机、范围、收益、风险和替代方案。Proposal 不需要很长，但必须让团队知道“为什么要做”。
（二）Requirements：需求规范
这是 SDD 的基础，描述系统应当满足的用户行为和业务规则。需求规范最重要的要求是清晰、可测试、可追踪。
（三）Design：设计规范
设计规范承接需求，说明系统如何实现。它既要让开发者理解方案，也要让 AI Agent 有足够上下文遵守架构约束。
（四）Tasks：任务计划
任务计划把设计拆成可执行步骤。优秀的任务计划不是简单 todo list，而是包含依赖、验收标准、影响范围和风险提示的执行地图。
（五）Tests：验证规范
测试不应只是实现后的补丁，而应来自需求本身。每个重要需求都应该有对应测试项。
（六）Traceability：追踪关系
这是 SDD 与普通文档驱动的关键区别。每个需求最好能追踪到设计、任务、测试、代码和发布记录。
六、SDD端到端一致性与可追踪性
（一）SDD 与 TDD、BDD、Agile 的关系
SDD 不是要替代 TDD、BDD 或敏捷开发，而是可以与它们结合。
- TDD，测试驱动开发，强调先写测试，再写实现。它关注“代码是否满足测试”。SDD 可以为 TDD 提供更上游的需求和验收依据。
- BDD，行为驱动开发，强调用业务可读的行为场景描述系统行为。BDD 可以看作 SDD 在需求和验收层的一种优秀表达方式。
- Agile，敏捷开发，强调快速迭代、持续反馈和团队协作。SDD 并不反对迭代，它反对的是没有规范沉淀的混乱迭代。
更准确地说：敏捷解决节奏问题，TDD 解决验证问题，BDD 解决业务行为表达问题，SDD 解决从意图到实现的端到端一致性问题。
（二）SDD 的最大价值：可追踪性
软件开发最昂贵的成本之一，是后期没人知道某段代码为什么存在。SDD 通过追踪链路降低这种成本。
例如：
REQ-021：用户可以重置密码。 DES-021：使用一次性 token，30 分钟过期。 TASK-021A：实现重置密码 API。 TEST-021：验证过期 token、重复提交、非法 token。 PR-058：提交 reset-password 相关代码。 Release-1.4.0：上线该功能。
当线上出现问题时，团队可以快速回答：
这段代码对应哪个需求？ 需求是否仍然有效？ 设计有没有被修改？ 测试是否覆盖了这个场景？ 这次变更影响哪些功能？ 如果要回滚，需要回滚哪些任务？
这就是 SDD 的工程价值：它让软件系统不只是“能跑”，还“能解释、能验证、能演进”。
七、如何在团队中落地 SDD？
（一）从一个功能开始，不要全量重构
很多团队一开始就想为整个系统补齐所有规范，结果很快失败。更现实的做法是：选择一个即将开发的新功能，用 SDD 完整走一遍。
（二）把规范放进代码仓库
规范最好与代码同仓库管理，例如：
/specs
/password-reset
requirements.md
design.md
tasks.md
tests.md
这样每次代码变更都可以和规范一起提交、评审和回溯。
（三）为规范建立模板
模板可以降低执行成本。例如 requirements.md 可以固定包含：
背景； 目标； 非目标； 用户故事； 验收标准； 边界情况； 权限规则； 追踪关系。
（四）让代码评审检查规范
PR 模板中可以加入：
关联需求 ID； 是否更新 design.md； 是否完成 tasks.md； 是否补充测试； 是否存在规范与代码漂移。
（五）让 AI 使用规范，而不是只使用提示词
使用 AI 辅助开发时，不要只说“帮我实现登录功能”。更好的方式是把 requirements.md、design.md、tasks.md 作为上下文，让 AI 按任务实现，并要求它说明每个改动满足了哪条规范。
（六）建立漂移门禁
当代码改变了用户可见行为，但规范未更新时，应视为风险。轻量团队可以在 PR 评审中人工检查；成熟团队可以通过脚本、CI、代码所有者规则、提交模板或 AI 审查来辅助检查。
九、SDD 的常见误区与适用场景
（一）常见误区说明
误区一：SDD 就是写很多文档
不是。SDD 要的是有效规范，不是文档数量。一个短而准确、能驱动测试和实现的规范，比几十页没人维护的文档更有价值。
误区二：SDD 会降低开发速度
短期看，写规范需要时间；长期看，它减少返工、减少沟通成本、减少 AI 误生成、减少后期维护成本。对于复杂业务、多人协作、长期演进系统，SDD 通常会提升整体速度。
误区三：有了 SDD 就不需要产品沟通
SDD 不替代沟通，而是把沟通结果沉淀下来。它让口头共识变成可审查、可追踪、可执行的工程资产。
误区四：SDD 只适合大公司
个人开发者和小团队也可以使用轻量 SDD。只要保留 requirements、design、tasks 三类最小制品，就能显著改善 AI 协作质量。
（二）SDD 适合哪些场景？
SDD 特别适合：
- 业务规则复杂的系统；
- 金融、医疗、政企、教育等高合规场景；
- 多人协作项目；
- 长期维护项目；
- AI 参与编码较多的项目；
- 需要清晰验收和审计记录的项目；
- 接口、权限、数据一致性要求高的系统。
不太适合：
- 一次性脚本；
- 极小型验证 Demo；
- 生命周期很短的原型；
- 需求本身还没有探索清楚、且暂时不追求稳定交付的实验。
但即便是原型项目，也可以采用轻量 SDD：至少写清楚目标、非目标和验收标准。
（三）一个最小可行的 SDD 模板
对于刚开始的团队，可以采用下面这个最小模板。
/specs/{feature-name}/requirements.md
1. 背景
2. 目标
3. 非目标
4. 用户故事
5. 验收标准
6. 边界情况
7. 权限与安全要求
/specs/{feature-name}/design.md
1. 总体方案
2. 模块边界
3. API 设计
4. 数据模型
5. 异常流程
6. 安全与性能考虑
7. 回滚方案
/specs/{feature-name}/tasks.md
1. 任务列表
2. 任务依赖
3. 每个任务的完成定义
4. 测试要求
5. 关联需求 ID
这套模板不复杂，但足以让团队从“想到哪写到哪”变成“按规范推进”。
十、结语：未来的软件资产不只是代码
SDD 的价值，不在于给开发增加流程，而在于让软件开发回到一个基本原则：先明确要什么，再决定怎么做，最后验证是否真的做到了。
在 AI 时代，代码会越来越容易生成，但正确的系统不会自动出现。真正稀缺的是清晰的意图、稳定的约束、可执行的设计、可追踪的决策和持续更新的工程知识。
因此，SDD 可以被理解为一种新的工程分工方式：
- 人类负责澄清目标、判断取舍、审查规范和承担责任；
- AI 负责基于规范生成候选方案、拆解任务、实现代码和辅助验证；
- 规范负责把人、AI、代码、测试和业务目标连接在一起。
当团队真正把规范当成一等资产，开发就不再只是“写代码”，而是围绕规范持续经营一个可以理解、可以验证、可以演进的软件系统。
参考资料与延伸阅读
一、SDD 与 AI 辅助开发
二、SDD 研究与理论背景
三、需求工程与规范标准
四、可追踪性、契约与验证
五、TDD、BDD 与验收规范
六、Docs-as-Code、架构规范与 API-first
七、敏捷、持续交付与演进式架构
以上资料可作为进一步理解 SDD、AI 辅助开发、需求工程、可追踪性、契约测试和规范化工程实践的延伸阅读。
