Spec-Driven Development完全实战指南
前言
2025 年初,Andrej Karpathy 发了一条推文,创造了 Vibe Coding 这个词:
"我完全沉浸在 vibe 里,看到东西就说,说了就跑,跑完就复制粘贴,大部分都能用。遇到 bug 就把报错丢回去,不加任何评论。这不算真正的编程。"
这条推文引爆了整个 AI 编程社区。Vibe Coding 确实让所有人体验到了前所未有的编码速度——GitHub 的数据显示开发者完成任务快了约 55%。
但很快,一个残酷的现实浮出水面:三个月墙。
大量用 Vibe Coding 构建的项目在三个月后开始腐烂——没人理解生成的代码、修一个 bug 冒出三个新 bug、需求全散落在聊天记录里、重构率下降 60% 而复制粘贴率上升 48%。
于是,一种新的方法论开始在社区中成型:Spec-Driven Development(SDD)——不是让你放弃 AI 编程,而是让 AI 编程 真正可控、可维护、可协作。
如果用一句话概括:
SDD 的核心主张是:在 AI 编程时代,Spec(规格说明)而非代码,才是第一等公民。先写清楚要做什么,再让 Agent 去做。
1. 什么是 Spec-Driven Development
1.1 先说人话定义
Spec-Driven Development 是一种以 结构化规格说明 为核心驱动力的 AI 辅助开发方法论。
它的核心操作很简单:
在让 AI Agent 写任何一行代码之前,先把需求、设计、任务拆解写成可版本化的文档(Spec),然后让 Agent 按照 Spec 逐步实现、逐步验证。
这里的 Spec 不是传统意义上的"需求文档"——它是一份 Agent 可消费的、结构化的工作契约,通常包含:
- 问题陈述与目标
- 验收标准(什么算做完了)
- 架构决策与约束
- 任务拆解与依赖关系
- 每个任务的完成定义
1.2 SDD 的工作流
综合业界主流实践,SDD 的通用工作流可以归纳为五步:
Explore → Specify → Design → Implement → Verify
↑ |
└────────────── 迭代反馈 ←──────────────────┘
- Explore(探索):让 AI 先读代码、理解现状,不写任何东西
- Specify(定义规格):写清楚要做什么、为什么做、边界在哪里
- Design(架构设计):数据模型、接口设计、技术选型、边界 case
- Implement(逐步实现):按任务拆解逐个实现,每个任务范围小且明确
- Verify(验证):对照 Spec 验证输出,测试内建在任务列表中
1.3 Birgitta Bockeler 的三层模型
Thoughtworks 的 Birgitta Bockeler 在 Martin Fowler 的网站上发表了目前最有深度的 SDD 分析,她把 SDD 分为三个层次:
| 层次 | 含义 | 适用场景 |
|---|---|---|
| Spec-First | 先写 Spec,实现后可以丢弃 | 单次功能开发,不需要长期维护 Spec |
| Spec-Anchored | Spec 和代码一起维护,长期保持同步 | 团队协作项目,需要持续迭代 |
| Spec-as-Source | 只编辑 Spec,代码完全生成,人不碰代码 | 激进的全自动化场景(目前仍在探索中) |
大多数团队目前处于 Spec-First 到 Spec-Anchored 之间。
2. Vibe Coding vs SDD:不是对立,而是光谱
2.1 一张表看懂两种模式
| 维度 | Vibe Coding | Spec-Driven Development |
|---|---|---|
| 规划程度 | 几乎没有,边聊边做 | 充分的前期设计 |
| 核心制品 | 聊天记录(临时的、不可追溯) | 版本化的 Spec 文件(持久的、可 Review) |
| 速度曲线 | 前期极快,后期急剧下降 | 前期稍慢,后期稳定 |
| 适用周期 | < 3 个月的项目 | > 3 个月的项目 |
| 团队规模 | 一个人 | 多人协作 |
| 可维护性 | 差(三个月墙) | 好(Spec 保留上下文和决策) |
| 风险容忍度 | 高(原型、黑客松) | 低(生产环境、有审计要求) |
2.2 它们是互补的
业界共识正在收敛到一个务实的立场:Vibe Coding 和 SDD 不是非此即彼,而是同一条光谱上的两端。
最佳实践是:
- 用 Vibe Coding 去探索和验证:快速原型、验证想法、找到对的方向
- 用 SDD 去落地和维护:确定方向后,写 Spec、拆任务、严格实现
切换信号——当你发现以下情况时,是从 Vibe 切到 SDD 的时候了:
- 修一个 bug 冒出三个新 bug(上下文漂移)
- 回归测试开始频繁失败
- 团队开始超过一个人
- 准备上生产环境
Karpathy 自己的演进轨迹也印证了这一点——他在创造"Vibe Coding"一年后,转而倡导 Agentic Engineering,强调 "there is an art and science and expertise to it"。
3. 谁在用 SDD
3.1 关键人物
| 人物 | 身份 | 贡献 |
|---|---|---|
| Andrew Ng | DeepLearning.AI 创始人 | 与 JetBrains 合作推出 SDD 课程,将 SDD 推向主流视野 |
| Paul Everitt | JetBrains Developer Advocate | 教授 DeepLearning.AI 的 SDD 课程,定义了 Constitution → Specification → Implementation → Validation → Replanning 工作流 |
| Brian Madison | Extend 高级工程经理 | 创建 BMad Method,25+ 年经验(美国陆军、NASA、IoT)。在团队里做了两周实验——所有工程师只能用 Agent 模式开发,独立发现了 SDD 原则 |
| Birgitta Bockeler | Thoughtworks | 在 Martin Fowler 网站发表最深度的 SDD 工具分析,提出三层模型,也是目前最重要的批评声音 |
| Andrej Karpathy | 前 Tesla AI 总监 | 创造了 Vibe Coding 概念,一年后转向倡导 Agentic Engineering |
3.2 公司和组织
GitHub:开源了 Spec Kit,一套 SDD 工具包,GitHub Stars 超过 137K。通过 specify CLI 提供 Constitution → Specify → Plan → Tasks → Implement 完整工作流,创建 .specify/ 目录管理 spec.md、plan.md、tasks.md 等文件。兼容 Copilot、Claude Code、Cursor、Codex。
AWS/Amazon:发布了 Kiro,一个内建 SDD 工作流的 Agentic IDE。在 IDE 层面原生支持 Requirements → Design → Tasks 的流程,不需要额外框架。
JetBrains:与 DeepLearning.AI 合作推出 SDD 课程,博客上有针对 Junie(他们的 AI Agent)的 SDD 实践指南。
Thoughtworks:将 SDD 纳入技术雷达,发表了 "Beyond Vibe Coding: The Five Building Blocks of AI-Native Engineering"。
Tessl:构建 Spec-as-Source 框架,追求最激进的路线——代码完全由 Spec 生成,文件头标注 // GENERATED FROM SPEC - DO NOT EDIT。
3.3 SDD 框架对比
| 框架 | 创建者 | 最适合 | 核心特点 |
|---|---|---|---|
| Spec Kit | GitHub | 新项目 | Constitution + Slash Commands,Agent 无关 |
| BMad Method | Brian Madison | 有审计要求的项目 | 12+ AI Persona 多角色流水线,带审计追踪 |
| OpenSpec | Fission-AI | 老项目改造 | Delta 标记(ADDED/MODIFIED/REMOVED),77K+ npm 下载 |
| Kiro | AWS | 通用开发 | IDE 原生支持,不需要额外框架 |
| Tessl | Tessl | Spec-as-Source | tessl build 从 Spec 完全生成代码 |
| SPEQ | speq-ai | 通用开发 | 专注开发者体验 |
4. 实战:在 Claude Code 中做 SDD
4.1 四阶段工作流
这是目前 Claude Code 社区沉淀出的最佳实践:
阶段一:Explore(探索)
让 Claude 先理解现有代码,不写任何东西:
> 读一下 src/ 目录的代码结构,理解下现在的架构,不要改任何东西
可以用 subagent 并行探索不同模块(数据层、API 层、UI 层),加速理解。
阶段二:Specify(写 Spec)
切换到 Plan Mode(Shift+Tab),让 Claude 帮你起草 Spec:
> 我要给系统加一个 XXX 功能,帮我写一份 Spec,包含:
> 1. 问题陈述和目标
> 2. 验收标准
> 3. 架构设计
> 4. 任务拆解(每个任务不超过 3 个文件)
> 5. 每个任务的完成定义
> 保存到 docs/spec-xxx.md
关键技巧:让 Claude 反过来 interview 你——它会问出你没想到的边界 case 和需求盲区。
阶段三:Implement(逐步实现)
按任务列表逐个执行,每个任务用独立的对话窗口(/clear 清上下文):
> 参考 docs/spec-xxx.md 的 Task 1,开始实现。完成后提交。
每完成一个任务就 /clear,保持上下文干净。可以用 subagent 并行处理无依赖的任务。
阶段四:Verify(验证)
测试内建在任务列表中,不是事后补的:
> 按照 docs/spec-xxx.md 的验收标准,逐条验证当前实现
4.2 CLAUDE.md 的使用原则
- 保持在 ~100 行以内,只放全局信息
- 内容包括:项目技术栈、代码风格规则、架构概览、工作流提醒
- 功能细节不放 CLAUDE.md,放在各自的 Spec 文件里
- 当 Claude 重复犯同一个错时,在 CLAUDE.md 里加一条纠正规则——"让文件自己修正自己"
4.3 上下文管理
这是 Claude Code 做 SDD 的命脉:
- 任务之间用
/clear清上下文,不要让上下文膨胀 - 一个会话只做一个任务
- MCP Server 限制在 3-4 个以内
- 避免用
/compact(压缩可能丢失关键上下文) - Spec 文件就是跨会话的记忆——它替代了你的聊天历史
5. 实战:在 Cursor 中做 SDD
Cursor 社区沉淀出了一套基于 .cursor/rules/ 的四阶段规则文件方案:
| 规则文件 | 阶段 | 作用 |
|---|---|---|
@ears.mdc | Specification | AI 进入问答模式,追问范围、价值、边界 case,产出需求文档 |
@design.mdc | Design | 交互式设计研讨,覆盖架构、接口、数据流 |
@plan.mdc | Planning | 消费 Spec + Design,拆解 User Story 和 Backlog |
@execute.mdc | Execution | 逐个 Story 实现,带 lint 和测试 |
最佳实践:
- 阶段之间开新对话(避免上下文污染)
- Spec/Design/Planning 用强推理模型(如 o3)
- Execution 用编码模型(如 Claude Sonnet)
6. 实战:在 Codex 中做 SDD
OpenAI Codex 的 SDD 实践围绕 Backlog.md 展开:
- 在项目根目录维护一个
Backlog.md,列出所有待办任务 - 每个任务包含:描述、验收标准、涉及文件
- Codex Agent 从 Backlog 中取任务执行
- 社区工具
codex-spec提供了自动化的 SDD 工作流
7. SDD 的现实挑战
7.1 Spec Drift(规格漂移)
这是 SDD 最核心的未解问题:Agent 在实现过程中会做适应性调整,但 Spec 文件不会自动更新,逐渐变成"文学作品"而非实际情况。
各框架的应对策略:
- OpenSpec:提供
/opsx:sync命令同步 - Spec Kit:提供
/speckit.reconcile命令 - BMad Method:QA Agent 负责审查一致性
Bockeler 的结论是:最可靠的缓解方式仍然是 小步迭代。
7.2 过度规格化
Bockeler 在实测中发现,SDD 工具可能把一个简单的 bug fix 变成 4 个 User Story 配 16 条验收标准。她直言:
"I'd rather review code than all these markdown files."
解药:根据任务复杂度选择合适的规格深度。不是每件事都需要完整的 Spec-Design-Plan-Task 流水线。
7.3 "这不就是瀑布吗?"
社区中反复出现这个质疑。共识是:SDD 不等于瀑布,因为 Spec 被设计为可迭代的活文档。但 在实践中确实容易滑向瀑布——当团队过度投入前期规格而抗拒迭代时。
7.4 语义扩散
Bockeler 警告 SDD 这个词已经在经历"语义扩散"——不同人赋予它不同含义。有人把它等同于"写 PRD",有人等同于"用 TDD",有人等同于"Contract-First API 开发"。保持清晰的定义很重要。
8. 怎么选:一个决策框架
你的项目是原型/黑客松/一次性脚本吗?
→ 是:Vibe Coding,不要犹豫
→ 否 ↓
项目会活过三个月吗?
→ 不会:Vibe Coding + 轻量 Spec
→ 会 ↓
团队超过一个人吗?
→ 是:SDD(Spec-Anchored 级别)
→ 否 ↓
你需要上生产环境且有质量要求吗?
→ 是:SDD(至少 Spec-First 级别)
→ 否:Vibe Coding + 关键路径写 Spec
最务实的姿势:先 Vibe 出方向,再 Spec 落实现。
9. 核心参考资料
| 资料 | 来源 |
|---|---|
| Andrej Karpathy 的 Vibe Coding 原始推文 | Simon Willison 引用(2025.02) |
| DeepLearning.AI × JetBrains SDD 课程 | deeplearning.ai |
| SDD 工具深度分析(三层模型) | Birgitta Bockeler / Martin Fowler 网站 |
| GitHub Spec Kit | github.com/github/spec-kit |
| BMad Method(Tech Lead Journal #255) | techleadjournal.dev |
| AWS Kiro IDE | kiro.dev |
| Thoughtworks 技术雷达:SDD | thoughtworks.com |
| Beyond Vibe Coding: Five Building Blocks | Thoughtworks |
| Claude Code SDD 实战 | gahmed.com |
| Cursor Rules SDD 方案 | github.com/gertalot/cursor-rules |
| Codex SDD 工作流 | jettro.dev |
| Spec Kit vs BMad vs OpenSpec 对比 | dev.to/willtorber |
| Vibe Coding 技术债危机 | TechStartups |
| SDD 学术论文 | arXiv:2602.00180 |