SDD · Spec-Driven Development · AI 编程新范式

🏠 返回 07-README ｜ ⬅️ 18-Agent-RL-Ops

定位：方法论层面论述 AI 编程语境下 Spec-Driven Development 是什么、为什么重要、主流形态、工具生态、标准流程与落地判断。与项目内 OpenSpec 实操指南（工具手册）和 AI 辅助开发（工具使用）形成方法论→工具→实操三层互补。

状态：Review 版 | 更新时间：2026-07-03

---

§0 面试前 Checklist

金句（90s）：「SDD 不是取消人，而是把人的判断前置到需求、边界和验收标准上，再让 AI 提升执行效率。核心是 spec → plan → tasks → implement → verify 的闭环，每次改动都能追溯到 spec 和 task。」

---

1 · 什么是 SDD

本文讨论的 SDD 是 Spec-Driven Development（规范/规格驱动开发），不是 Schema-Driven Development。

一句话概括：

SDD 是先把需求、约束、设计意图和验收标准结构化成 spec，再基于 spec 进行计划、实现、测试和评审的开发模式。

在 AI 编程语境下，SDD 的核心作用是给 AI Agent 和开发团队提供稳定边界：

• 明确本期要做什么。
• 明确本期不做什么。
• 明确功能如何验收。
• 明确接口、数据、权限、状态和兼容约束。
• 明确实现完成后如何证明没有跑偏。

当前主流落地不是"完全由 spec 自动生成生产代码"，而是：

Spec-first / Spec-anchored
+ AI Agent
+ 自动化测试
+ 人工 review
+ CI/CD 闸门

也就是说，SDD 不是取消人，而是把人的判断前置到需求、边界和验收标准上，再让 AI 提升执行效率。

2 · SDD 为什么出现

AI 编程让"生成代码"的成本大幅降低，但也放大了几个问题：

• 需求只存在聊天记录或 PRD 中，工程侧没有稳定事实源。
• AI 会根据上下文自行补规则，容易实现越界。
• 复杂需求里的权限、状态、异常、历史兼容、接口契约容易遗漏。
• 代码 diff 变大后，review 人很难判断哪些改动是必要的。
• 测试如果事后再补，容易只验证"代码现在做了什么"，而不是"需求本来应该是什么"。
• 需求变化后，文档、计划、测试和代码容易不同步。

SDD 试图把开发过程从：

模糊需求 -> 直接生成代码 -> 人工补救

变成：

明确意图 -> 结构化 spec -> 计划拆解 -> 实现 -> 验证 -> 更新 spec

它的本质是：先形成可评审、可追踪、可验证的需求表达，再进入代码实现。

3 · SDD 的核心原则

3.1 Spec 是开发输入

在 SDD 中，spec 不是代码完成后的说明文档，而是实现前的输入。它决定 AI 和开发者可以做什么、不能做什么。

一个有效的 spec 至少要回答：

• 为什么做。
• 做什么。
• 不做什么。
• 谁使用。
• 在什么条件下发生。
• 系统应该如何响应。
• 如何验收。
• 哪些既有行为必须保持不变。

3.2 Spec 必须可评审

Spec 不是写给 AI 自己看的。它必须能被产品、研发、测试、review 人理解和审核。

好的 spec 应该具备：

• 结构清楚。
• 范围明确。
• 场景可验收。
• 术语一致。
• 关键字段、接口、状态、权限使用稳定名称。
• 不确定点单独列出，不让 AI 猜。

3.3 Spec 必须可追踪

SDD 的关键能力是 traceability（可追踪）。

理想情况下，每个实现改动都能回答：

它对应哪条 spec？
它来自哪项 task？
哪个测试或验收场景证明它正确？
它是否修改了非目标范围？

如果一个改动无法追踪到 spec 或 task，它就需要解释；解释不清时，通常应视为越界改动。

3.4 Spec 不等于越详细越好

Spec 应该详细到足以防止误解，但不要细到替代代码。

好的 spec 写系统行为和约束，不写具体代码操作。例如：

• ✅ 好：用户未登录时，系统 SHALL 拒绝访问并引导登录。
• ❌ 不好：在某个文件第 42 行增加一个 if 判断。

实现细节应进入 design 或 plan，行为要求应留在 spec。

4 · 主流 SDD 形态

当前行业里常见的 SDD 可以分为五类。

4.1 Spec-first：轻量规范先行

Spec-first 是最容易开始的一层。团队先写一个轻量 spec.md、issue、PRD 摘要或验收标准，再让 AI Agent 或开发者实现。

适合：

• 个人或小团队。
• 短周期功能。
• 明确 bug fix。
• 中小复杂度业务需求。
• 希望比直接 prompt 写代码更稳，但不想引入重流程。

常见产物：spec.md、issue 描述、PRD 摘要、验收标准、简单 task list。

优点：成本低、启动快、容易接入现有开发流程。

风险：实现完成后 spec 可能不再维护；spec 和代码容易脱节；没有测试和 review gate 时，仍然难防止 AI 越界。

4.2 Spec-anchored：规范作为长期资产

Spec-anchored 是复杂项目里更实用的一层。Spec 不只是实现前的临时提示词，而是和代码一起进入仓库，并在后续迭代中持续维护。

适合：

• 中大型业务系统。
• 存量系统。
• 多人协作。
• 涉及权限、状态、接口、数据迁移、兼容策略的需求。

常见产物：proposal.md、spec.md、design.md、tasks.md、接口契约、测试用例、变更记录。

优点：可追溯、方便 review、方便后续维护、适合沉淀团队知识。

风险：需要持续维护；如果实现后不更新 spec，文档会失真；如果 spec owner 不明确，容易无人负责。

4.3 Spec-as-source：规范即源码

Spec-as-source 是更激进的一层。人主要修改 spec，代码由工具持续生成或同步。

适合：DSL、低代码平台、表单/流程/规则引擎、API/SDK 生成、状态机和配置驱动系统、边界清晰且语义高度形式化的领域。

当前判断：在通用业务系统里还不是主流；对 spec 的形式化程度要求很高；如果 spec 不能完整表达行为，人仍然需要读代码、改代码和 review 代码。

4.4 Contract-first / API-first

Contract-first 是传统工程里最成熟、最容易落地的一类 SDD。它不一定叫 SDD，但本质是用契约驱动实现。

常见工具：OpenAPI、AsyncAPI、GraphQL SDL、protobuf/gRPC、JSON Schema、Pact、Schemathesis。

适合：前后端协作、微服务协作、SDK 生成、mock server、契约测试、接口变更治理。

典型流程：

先定义接口契约
-> 生成 mock 或 SDK
-> 并行开发
-> 契约测试校验兼容性
-> CI 阻止破坏性变更

4.5 Executable Spec：可执行规范

可执行规范把验收场景、单元测试、集成测试、端到端测试作为 spec 的验证形式。

常见工具：Cucumber、SpecFlow、Jest、pytest、RSpec、Playwright、Cypress。

AI 时代推荐做法：

Spec 写业务意图
-> Tests 锁住行为
-> Agent 实现代码
-> CI/Review 验证是否跑偏

可执行规范不是 SDD 的全部，但它是让 spec 变成工程闸门的关键。

5 · SDD 与相关概念的区别

概念	关注点	和 SDD 的关系
PRD	产品目标和用户价值	SDD 会把 PRD 转成工程可执行 spec
Design Doc	技术方案和取舍	SDD 的 design 阶段承接技术决策
TDD	测试先行	可作为 SDD 的验证手段，但不是 SDD 本身
BDD	行为描述和验收	可为 spec 提供结构化场景写法
API-first	接口契约	是 SDD 在接口协作领域的成熟形态
CI/CD	自动验证和发布	是 SDD 的落地闸门
Code Review	人工质量控制	根据 spec 审查实现是否符合范围

SDD 的变化在于：AI Agent 加入后，spec 不再只是人与人之间的沟通材料，也变成了约束 AI 行为的上下文和边界。

6 · 工具生态

不要把所有 SDD 工具混在一起看。它们通常处在不同层。

工具类别	代表工具	主要解决的问题
规范框架	Spec Kit、OpenSpec	生成和管理 spec/plan/tasks 等文档资产
AI IDE / Agent 工作流	Kiro、Qoder Quest、Trae Builder、CodeBuddy、Comate、Cursor、Windsurf	在 IDE 或云端完成需求理解、拆任务、编码和验证
工程纪律 / 方法论	Superpowers、BMAD、Agent OS	约束 AI 按澄清、计划、验证的流程工作
执行循环	Codex Goal、Claude Goal/Loop、Copilot coding agent	在 spec 和 plan 明确后持续执行、验证、修复
契约工具	OpenAPI、protobuf、GraphQL、Pact、Schemathesis	固定接口和服务契约
可执行规范	Jest、pytest、Playwright、Cucumber	把 spec 变成可重复验证的测试

6.1 Spec Kit

Spec Kit 更像完整的 SDD 脚手架。典型流程是 Spec → Plan → Tasks → Implement。它适合新项目、大功能、统一模板和把需求从一次性 prompt 变成可共享、可 review、可执行的 Markdown artifacts。

6.2 OpenSpec

OpenSpec 更偏 change 管理。它通常围绕一次变更组织 proposal.md、spec.md、design.md、tasks.md。它适合存量项目迭代、中等复杂需求、明确本期做什么和不做什么，并通过命令校验 spec artifacts。

📎 项目内已有 OpenSpec 完整实操指南，涵盖安装、工作流、Slash Commands 与 20+ 工具集成。

6.3 Kiro / Qoder / Trae / CodeBuddy / Comate

这些更偏产品化 AI IDE 或 Agent 平台。

• Kiro：内置 specs 工作流，强调 requirements、design、tasks。
• Qoder Quest：支持 Spec 驱动场景，先对齐需求与约束，再执行并验收。
• Trae Builder：自主拆解需求并完成多轮编码任务。
• CodeBuddy：更偏产品、设计、开发、部署一体化。
• Comate：更偏 IDE 内自然语言需求到代码、代码库理解、企业知识库增强。

共同趋势是：从代码补全，到对话生成代码，再到需求澄清、计划、多文件实现和测试验证。

6.4 Superpowers / Loop / Goal 的定位

这类工具不是 SDD 本体，而是 SDD 的配套执行能力。

• Superpowers 更像 AI 编程纪律：要求先澄清、再计划、再验证。
• Loop / Goal 更像执行循环：在目标、计划和验证命令明确后，让 Agent 持续推进。

推荐理解：

SDD 定义要做什么和如何验收
Superpowers 等方法论约束 AI 如何工作
Loop / Goal 负责在明确边界内持续执行

7 · 国内外落地方式

7.1 国外常见路线

路线	代表	落地方式
GitHub / Microsoft 路线	GitHub Spec Kit、GitHub Copilot coding agent	用 spec/plan/tasks 驱动 Agent，实现后走 PR 和 CI
AWS 路线	Kiro	IDE 内生成 requirements、design、tasks，spec 作为 AI 执行护栏
Agent CLI 路线	Claude Code、Codex	先 explore/plan，再执行任务，通过测试、PR、CI 收口
小团队路线	Cursor、Windsurf、Linear、Notion、GitHub Issues	轻量 spec + agent 编码 + 测试 + review

国外落地共性：强调 spec 是实现和 review 的上下文；强调 human-in-the-loop；强调测试、CI、PR；复杂团队更需要 spec version、owner、review gate 和 traceability。

7.2 国内常见路线

路线	代表	落地方式
大厂 AI IDE / Agent	Qoder/通义灵码、Trae、CodeBuddy、Comate	在 IDE 或云端 Agent 中完成需求理解、拆分、编码、调试和验证
企业平台化治理	TAPD、禅道、飞书、语雀、钉钉 PRD + Git + CI + AI 工具	把 PRD、设计、代码、测试、发布串起来，AI 作为研发节点之一
小团队轻量实践	PRD 摘要 + markdown spec + AI 编码 + 人工 review	不引入重平台，靠模板和 checklist 控制风险

国内落地共性：更关注和现有研发流程融合；很多工具强调从需求到代码或端到端自主编程；存量业务系统里，真正难点不是生成代码，而是历史兼容、跨系统口径、权限、审批和多人 review。

7.3 成熟度判断

层级	成熟度	判断
Spec-first	已经比较普及	适合快速开始，成本低，但后续维护弱
Spec-anchored	正在成为复杂项目主流	适合存量系统和复杂业务迭代
Spec-as-source	仍偏实验或特定领域	适合 DSL、低代码、API/SDK、规则引擎

8 · 标准 SDD 流程

一个通用 SDD 流程可以拆成七个阶段：

输入材料
-> Spec
-> Design
-> Plan / Tasks
-> Implement
-> Verify
-> Sync / Archive

8.1 输入材料

目标：收集足够上下文，避免 AI 自行猜测。

常见输入：原始 PRD 或 issue、当前功能说明、设计稿或交互说明、当前接口字段权限状态数据结构、已知限制和非目标、真实样例和边界样例、历史兼容要求。

8.2 Spec

目标：把需求变成可验收行为。

Spec 应包含：背景和目标、本期范围、非目标、影响范围、Requirements、Scenarios、Open Questions。

推荐写法：

### Requirement: <能力名称>
系统 SHALL <具备某个可验收能力>。

#### Scenario: <场景名称>
- **WHEN** <条件或操作>
- **THEN** <系统响应>
- **AND** <补充约束>

8.3 Design

目标：确定实现方案，不让 AI 随机选择架构。

Design 应包含：技术方案、数据结构、接口契约、状态流转、权限规则、错误处理、兼容策略、迁移方案、风险和取舍。

8.4 Plan / Tasks

目标：把 design 拆成可执行、可 review、可验证的任务。

好的 task 应包含：任务编号、对应 spec scenario、允许修改的范围、需要补充的验证、完成证明和依赖关系。

8.5 Implement

目标：严格按 tasks 执行，不越界实现。

推荐规则：

• 一个 task 一个小循环。
• 只实现 spec 和 tasks 内的内容。
• 发现 spec 外问题先停下来说明。
• 每完成一个 task 更新任务状态。

8.6 Verify

目标：证明实现符合 spec。

验证方式包括：自动化测试、契约测试、人工验收、diff 范围检查、spec 对照检查。

8.7 Sync / Archive

目标：保证 spec 和实现长期一致。

收尾时判断：实现是否改变了 spec、spec 是否需要同步到长期文档、变更是否可以归档、是否有后续 follow-up。

9 · SDD 中的关键产物

产物	作用
proposal.md	说明为什么做、做什么、不做什么
spec.md	说明系统应该如何表现
design.md	说明技术方案和取舍
tasks.md	说明执行顺序和验证方式
测试用例	把 spec 变成可执行验证
变更记录	记录 spec 和代码的演进

10 · 团队落地分级

不建议所有事情都走同样重的 SDD 流程。可以按复杂度分级。

等级	场景	推荐方式
L0	文案、日志、样式、小脚本	不需要完整 SDD，PR 说明即可
L1	明确单点 bug、小范围修复	轻量 spec + 验证
L2	中等需求、业务规则变化、接口变化	OpenSpec 或轻量 change spec
L3	大功能、跨模块、复杂协作	Spec Kit / 完整 SDD
L4	契约或平台级能力	Spec-anchored + Contract-first + CI gate

简单判断：

不改变行为：L0/L1
改变业务行为：至少 L2
跨模块、跨角色、影响数据和架构：L3 起步

11 · 常见误区

11.1 把 PRD 当 spec

PRD 通常描述产品目标和业务价值，但工程实现还需要权限、状态、异常、接口、数据、兼容、验收标准。SDD 不是复制 PRD，而是把 PRD 转成工程可执行规范。

11.2 Spec 写得太虚

“优化体验”“支持配置”"完善流程"都不是好 spec，因为无法验收。好的 spec 应该明确条件和结果。

11.3 只写 spec，不做验证

没有验证的 spec 很难防回归。AI 可以按 spec 写出第一版，但后续改动仍可能破坏行为。

11.4 在 spec 不清楚时启动执行循环

Loop/Goal 会放大执行效率，也会放大错误方向。先澄清 spec，再让 Agent 循环执行。

11.5 实现后不更新 spec

如果代码变了但 spec 不变，spec 很快失去可信度。SDD 的长期价值来自 spec 和实现持续同步。

12 · 推荐组合

轻量组合

Markdown spec
+ AI Agent
+ 自动化验证
+ 人工 review

存量项目组合

OpenSpec
+ AI Agent
+ 自动化测试
+ CI
+ 变更记录

新项目或大功能组合

Spec Kit
+ Contract-first
+ 自动化测试
+ AI Agent
+ CI/CD gate

接口密集型组合

OpenAPI / protobuf / GraphQL
+ mock server
+ contract test
+ SDK generation
+ CI gate

13 · 项目内交叉索引

本文在知识庄园中的位置与关联：

关联内容	路径	关系
OpenSpec 实操指南	openspec-guide.md	本文的方法论 → 该指南的工具实操
AI 辅助开发工具	01-AI辅助开发-Cursor-Copilot与Claude-Code.md	本文的方法论 → 该文的三大形态 / Agent 模式
传统设计方法论	05-architecture/design-methodology/	SDD vs 传统设计方法论对照
Spec-Driven Delivery Skill	skills/core/speckit/SKILL.md	Spec-Driven Delivery 骨架 Skill 定义

14 · 参考资料

• Martin Fowler: Understanding Spec-Driven-Development: Kiro, Spec Kit, and Tessl
  • https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
• GitHub Spec Kit
  • https://github.com/github/spec-kit
  • https://github.github.com/spec-kit/
• GitHub Blog: Spec-driven development with AI
  • https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• OpenSpec
  • https://github.com/Fission-AI/openspec
• Kiro Specs
  • https://kiro.dev/docs/specs/
• AWS Blog: From spec to production
  • https://aws.amazon.com/blogs/industries/from-spec-to-production-a-three-week-drug-discovery-agent-using-kiro/
• Qoder Quest: Spec-driven development
  • https://docs.qoder.com/user-guide/quest/spec-driven
  • https://help.aliyun.com/zh/lingma/qoder-cn/user-guide/lingma-quest-spec
• Trae Builder
  • https://www.trae.cn/plugin
• CodeBuddy
  • https://www.codebuddy.ai/docs/zh/ide/Best-practice/best-practice
• Baidu Comate
  • https://comate.baidu.com/zh