详解Spec-Driven Development(SDD)：Agent 时代的软件工程新范式

江畔柳前堤

267人浏览 · 2026-08-03 15:22:43

江畔柳前堤 · 2026-08-03 15:22:43 发布

Spec-Driven Development：AI 时代的软件工程新范式

一句话总结：先写清楚"做什么"，再让 AI 去实现"怎么做"。规范（Spec）不再是代码的附属品，而是整个开发流程的唯一事实来源。

一、从一个痛点说起

2025 年，Andrej Karpathy 创造了 “Vibe Coding”（氛围编程） 这个词——打开 AI 编辑器，凭感觉对话，代码唰唰地生成。很爽，对吧？

但很快，问题就来了：

你：帮我写一个用户注册功能
AI：好的，这是代码...（生成了 200 行）
你：不对，我要支持手机号注册
AI：好的，我改一下...（重写了 300 行，顺便改了你不想改的部分）
你：等等，接口格式不是这样的...
AI：抱歉，我重新来...（又重写了，之前的逻辑全丢了）

三轮对话之后，你发现自己在"调教"AI，而不是在"开发"软件。

这背后的根本问题是：

问题	表现
意图模糊	自然语言 prompt 碎片化，AI 大量"脑补"需求
上下文丢失	多轮对话后 AI “失忆”，前后矛盾
不可复现	同样的 prompt，不同时间产出完全不同的代码
架构漂移	多人/多轮迭代后，接口定义、数据结构悄悄变更
质量不可控	代码"能跑"但偏离业务诉求，隐性 bug 频发

实测数据显示：纯 Vibe Coding 模式下，AI 生成代码的一次通过率仅约 31%。

行业需要一种方法，把"凭感觉编程"升级为"按图纸施工"。

这就是 Spec-Driven Development 诞生的背景。

二、什么是 Spec-Driven Development？

2.1 定义

Spec-Driven Development（SDD，规范驱动开发） 是一种以 规范（Specification） 为核心驱动力的软件开发方法论。其核心思想是：

在编写任何代码之前，先编写一份结构化的规范文档（Spec）。规范成为人类开发者与 AI 共同的"唯一事实来源"（Single Source of Truth），代码是规范的最终实现产物。

用微软的话说，SDD 是 “思想的版本控制”——管理的重点从代码的演变历史，转向了决策的演变历史。

2.2 一个关键思维转变

传统开发：需求 → 代码（文档是代码的注释，写完即弃）
SDD 开发：需求 → Spec → 代码（Spec 是"预编译的源代码"，代码只是 Spec 的编译产物）

维度	传统模式	SDD 模式
核心工件	代码	规范（Spec）
文档地位	辅助性，写完就扔	驱动性，持续演进
AI 角色	代码补全工具	规范的"执行者"
人的角色	写代码	定义"做什么"
质量保障	事后测试	前置约束 + 自动验证

2.3 不是什么

SDD 不是：

❌ "多写一份文档"的形式主义
❌ 传统瀑布模型的回归
❌ 只适用于 AI 编程的专属方法（但 AI 让它真正落地）

SDD 是：

✅ 从 “Vibe Coding 的随机性” 走向 “Agentic Coding 的可控性” 的根本方法
✅ 将"定义做什么（WHAT）"与"实现怎么做（HOW）"彻底解耦
✅ 人类负责意图表达与决策，AI 负责工程实现

三、SDD 的核心原则

原则一：Spec First, Code Second

任何代码变更，必须先有对应的 Spec 变更。 没有 Spec 的代码是"无主代码"，不允许进入主干。

原则二：Single Source of Truth

规范是整个团队（人 + AI）的唯一事实来源。当代码与规范冲突时，以规范为准，修复代码。

原则三：Spec 必须可执行

Spec 不是模糊的需求描述，它必须足够精确、完整、结构化，能够：

被 AI 直接理解和执行
被自动化工具校验
生成可验证的验收标准

原则四：渐进式细化

Spec 不是一次性写完的大文档，而是随着开发推进逐步细化的：

Level 0: 愿景（Vision）      → 一句话说清楚要做什么
Level 1: 需求（Requirements） → 用户故事 + 验收标准
Level 2: 设计（Design）       → 架构决策 + 接口定义
Level 3: 任务（Tasks）        → 可执行的开发任务清单

原则五：人机各司其职

┌─────────────────────────────────────────┐
│              人类的职责                   │
│  • 定义业务意图和约束                     │
│  • 审查和批准 Spec                       │
│  • 做出架构决策                          │
│  • 验收最终交付物                        │
└─────────────────────────────────────────┘
                    ↓ Spec
┌─────────────────────────────────────────┐
│              AI 的职责                    │
│  • 根据 Spec 生成实现代码                 │
│  • 根据 Spec 生成测试用例                 │
│  • 检查实现是否符合 Spec                  │
│  • 报告 Spec 中的歧义和冲突              │
└─────────────────────────────────────────┘

四、SDD 的工作流程

SDD 的最简工作流只有四步：

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Specify  │ →  │  Plan    │ →  │  Task    │ →  │Implement │
│ 定义规范  │    │ 制定计划  │    │ 拆分任务  │    │ 逐步实现  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
     ↑                                              │
     └──────────── 验证 & 迭代 ←────────────────────┘

Step 1: Specify（定义规范）

用结构化的方式描述：

做什么：功能需求、用户故事
不做什么：明确的边界和排除项
约束条件：性能要求、安全要求、技术栈限制
验收标准：怎样算"做完了"

Step 2: Plan（制定计划）

基于 Spec 进行架构设计：

技术选型及理由
模块划分与依赖关系
接口契约定义
复用已有代码的识别

Step 3: Task（拆分任务）

将计划拆解为小而有序的任务：

每个任务足够小，AI 可以一次完成
任务之间有明确的依赖顺序
每个任务有独立的验证标准

Step 4: Implement（逐步实现）

让 AI Agent 一次只实现一个任务：

每个任务实现后立即验证
验证通过才进入下一个任务
发现问题回到 Spec 层修正，而非在代码层"打补丁"

五、Spec 长什么样？

一个典型的 Spec 文件通常以 Markdown 格式存放在代码仓库中，包含以下核心部分：

# Feature: 用户注册模块

## 1. Overview（概述）
实现基于手机号的用户注册功能，支持验证码验证，
注册成功后自动创建用户档案。

## 2. Requirements（需求）
### 功能需求
- [ ] 用户输入手机号，获取短信验证码
- [ ] 验证码有效期 5 分钟，错误次数限制 3 次
- [ ] 注册成功后自动登录并跳转首页
- [ ] 支持"已注册用户"检测，引导登录

### 非功能需求
- 接口响应时间 < 200ms（P99）
- 验证码发送频率限制：同一手机号 60 秒内仅一次
- 密码使用 bcrypt 加密，cost factor ≥ 12

## 3. Existing Patterns to Reuse（复用模式）
- 复用 `src/services/sms.service.ts` 中的短信发送逻辑
- 复用 `src/middlewares/rate-limiter.ts` 进行频率限制
- 遵循 `src/modules/auth/` 下的现有模块结构

## 4. Architecture Decisions（架构决策）
| 决策项 | 选择 | 理由 |
|--------|------|------|
| 验证码存储 | Redis，TTL=300s | 自动过期，无需清理 |
| API 风格 | RESTful | 与现有接口保持一致 |
| 错误处理 | 统一 ErrorCode 枚举 | 前端统一处理 |

## 5. API Contract（接口契约）
### POST /api/v1/auth/register
Request:
```json
{
  "phone": "13800138000",
  "code": "123456",
  "password": "Str0ng!Pass"
}

Response (201):

{
  "userId": "uuid",
  "token": "jwt-token",
  "expiresAt": "2026-08-03T16:00:00Z"
}

6. Acceptance Criteria（验收标准）

正确手机号 + 正确验证码 → 注册成功，返回 201
错误验证码 → 返回 400，错误码 INVALID_CODE
已注册手机号 → 返回 409，错误码 USER_EXISTS
验证码过期 → 返回 400，错误码 CODE_EXPIRED
60 秒内重复请求验证码 → 返回 429

7. Out of Scope（明确排除）

本期不做邮箱注册
本期不做第三方 OAuth 登录
不做用户头像上传


> 💡 **关键洞察**：好的 Spec 不是"面面俱到的长文档"，而是 **"足够精确的短契约"**。它的核心价值在于消除歧义，让 AI 没有"脑补"的空间。

---

## 六、SDD vs 其他方法论

SDD 并非凭空出现，它站在前人肩膀上，但解决了不同的问题：

| 维度 | TDD | BDD | DDD | **SDD** |
|------|-----|-----|-----|---------|
| 驱动力 | 测试用例 | 用户行为场景 | 领域模型 | **规范文档** |
| 核心产物 | 测试代码 | Feature 文件 | 领域对象 | **Spec 文件** |
| 主要受众 | 开发者 | 开发+产品 | 架构师+开发 | **人 + AI** |
| 关注层次 | 函数/类级别 | 功能/场景级别 | 业务领域级别 | **全栈（意图→实现）** |
| AI 时代适配性 | 中 | 中 | 中 | **高** |
| 核心差异 | 先写测试再写代码 | 用自然语言描述行为 | 用领域语言建模 | **先写规范再让 AI 生成一切** |

**它们不是互斥的。** 在实际项目中：
- **DDD** 帮你定义领域边界 → 输入到 Spec 的架构决策中
- **BDD** 的 Given-When-Then → 可以成为 Spec 验收标准的格式
- **TDD** 的测试先行 → AI 可以根据 Spec 自动生成测试

SDD 更像是一个 **编排层**，把这些方法论的产出统一纳入 Spec 管理体系。

---

## 七、主流工具生态

2026 年是 SDD 工具全面爆发的一年。几乎所有主流 AI 编程工具都上线了自己的 SDD 方案：

### 7.1 GitHub Spec Kit

- **定位**：GitHub 官方开源的 SDD 工具包
- **仓库**：`github/spec-kit`（上线一个月 2.8 万 Star）
- **工作流**：`Constitution → Specify → Plan → Tasks → Implement`
- **特点**：
  - 规范、计划、任务以 Markdown 文件存储在代码仓库中
  - 支持 Claude Code、Copilot、Cursor、Gemini CLI 等多种 AI 工具
  - 提供 CLI 命令引导完整开发流程

```bash
# 安装
pip install specify-cli

# 初始化项目
speckit init

# 创建规范
speckit specify "实现用户注册功能"

# 生成计划
speckit plan

# 拆分任务
speckit tasks

# 开始实现（调用 AI Agent）
speckit implement

7.2 AWS Kiro

定位：AWS 推出的 AI-native IDE，原生内置 SDD 流程
特点：
- 在编码过程中，Kiro 会要求人类用户对其假设进行指导、确认或修正
- 自动生成三层文件：requirements.md → design.md → tasks.md
- 自主 Agent 可连续工作数日，始终遵循 Spec 约束

7.3 OpenSpec

定位：开源的 Spec 定义框架
特点：
- 用 JSON/YAML 定义服务名、端点、数据 Schema、约束和验证逻辑
- 更偏向 API 契约和机器可读格式
- 适合微服务架构下的接口规范管理

7.4 其他工具

工具	特点
BMAD-METHOD	多 Agent 协作框架，模拟产品经理、架构师、开发者角色
Tessl	将 Spec 视为"开发语言"，代码是"最后一公里"
Claude Code + CLAUDE.md	通过项目级 Markdown 文件定义规范和约束
Cursor + .cursorrules	在 IDE 层面嵌入项目规范

八、实战：用 SDD 开发一个功能

以一个真实场景演示完整的 SDD 流程：

场景：为电商系统添加"优惠券核销"功能

Step 1: 写 Spec

# Feature: 优惠券核销

## Overview
用户在下单时可以使用优惠券抵扣金额。
核销时需校验有效期、使用条件、库存。

## Business Rules
1. 每张优惠券只能使用一次
2. 优惠券有最低消费门槛（如满100减20）
3. 过期优惠券不可使用
4. 同一订单只能使用一张优惠券
5. 核销操作必须是原子性的（防并发超用）

## API Contract
### POST /api/v1/coupons/{couponId}/redeem
Request: { "orderId": "uuid", "orderAmount": 150.00 }
Response 200: { "discount": 20.00, "finalAmount": 130.00 }
Response 400: { "error": "COUPON_EXPIRED" | "BELOW_THRESHOLD" | "ALREADY_USED" }

## Technical Constraints
- 使用 Redis 分布式锁防止并发核销
- 核销记录写入数据库，支持审计追溯
- 接口幂等性：相同 orderId 重复调用返回相同结果

Step 2: 人类审查 Spec

✅ 业务规则是否完整？→ 补充：退款时优惠券不退还
✅ 接口设计是否合理？→ 确认
✅ 技术约束是否可行？→ 确认 Redis 集群可用

Step 3: AI 根据 Spec 生成代码

Prompt: 请根据 specs/coupon-redeem.md 实现优惠券核销功能。
       遵循 src/modules/ 下的现有模块结构。
       复用 src/services/redis-lock.service.ts。

Step 4: 自动验证

# AI 同时生成测试，运行验证
npm test -- --grep "coupon redeem"

# 验收标准逐条检查
✅ 正常核销 → 返回 200，金额正确
✅ 过期优惠券 → 返回 400 COUPON_EXPIRED
✅ 低于门槛 → 返回 400 BELOW_THRESHOLD
✅ 重复核销 → 返回 400 ALREADY_USED
✅ 并发请求 → 只有一个成功

Step 5: 迭代

如果验证失败，回到 Spec 层修正，而不是在代码里"打补丁"：

## Spec 修订记录
- v1.1 (2026-08-03): 增加规则"优惠券与满减活动不可叠加"

📊 效果对比：引入 Spec 后，AI 生成代码的一次通过率从 31% → 89%，缺陷密度下降 76%。

九、SDD 的优势与局限

✅ 优势

优势	说明
意图对齐	Spec 消除歧义，AI 不再"脑补"需求
可追溯性	每行代码都能追溯到 Spec 中的某条规则
可复现性	同一份 Spec，不同时间、不同 AI 产出一致
团队协作	Spec 是人和 AI 的"共同语言"，降低沟通成本
质量前置	在实现前发现问题，减少返工
知识沉淀	Spec 持续演进，成为团队的活文档
AI 可控性	给 AI 戴上"紧箍咒"，约束其行为边界

⚠️ 局限与挑战

挑战	说明
Spec 编写成本	前期需要投入时间写高质量 Spec
学习曲线	团队需要学习"如何写好的 Spec"
过度规范化风险	小功能/原型不需要重型 Spec 流程
Spec 维护负担	Spec 需要与代码同步演进，否则会成为"过期文档"
语义鸿沟	自然语言 Spec 仍可能有歧义，形式化程度有限
工具碎片化	各工具生态尚未统一标准

💡 实践建议

小改动/原型：不需要完整 SDD 流程，轻量 prompt 即可
中等功能：写一份简明 Spec（1 页以内），重点写清验收标准
复杂系统/多人协作：完整 SDD 流程，Spec 纳入版本管理和 Code Review
黄金法则：Spec 的粒度应该匹配任务的复杂度

十、未来展望

10.1 从"辅助"到"原生"

软件工程正在从 AI-Assisted（AI 辅助）走向 AI-Native（AI 原生）。SDD 是这一转变的关键桥梁：

2023: AI 补全代码（Copilot 时代）
2024: AI 生成函数（Chat 时代）
2025: Vibe Coding（凭感觉编程）
2026: Spec-Driven Development（规范驱动）  ← 我们在这里
2027+: Long-Running Agents（AI 自主交付）

10.2 Spec 即代码

未来的趋势是 Spec 本身成为"源代码"，而 Python/Java/TypeScript 等具体实现只是 Spec 的"编译产物"：

“In this new world, maintaining software means evolving specifications. The lingua franca of development moves to a higher level, and code is the last-mile approach.”
—— GitHub Spec Kit 团队

10.3 开发者的角色演变

过去：开发者 = 写代码的人
现在：开发者 = 定义 Spec + 审查 AI 产出的人
未来：开发者 = 系统意图的架构师 + AI 团队的"技术总监"

编码能力依然重要——你需要读懂 AI 生成的代码、判断架构决策的合理性、编写精确的 Spec。但你不再需要手动敲每一行代码。

10.4 标准化趋势

随着 SDD 工具的爆发，行业正在走向标准化：

Spec 的格式和结构将逐步统一
Spec 的验证和测试工具将成熟
Spec 与 CI/CD 管道的集成将成为标配

总结

Spec-Driven Development 的本质，是把软件工程中"从意图到实现"的鸿沟，用一份结构化的规范文档填平。

它不是一种新发明，而是"设计先行"、"契约优先"这些经典工程思想在 AI 时代的自然演进。当 AI 成为主要的代码生产者，人类的核心竞争力就从"写代码"转向了"定义正确的规范"。

记住这句话：

输入质量决定输出质量。Spec 的质量，直接决定了 AI 产出的质量。

如果你还在用"帮我写一个 XXX"的方式和 AI 对话，不妨试试先花 10 分钟写一份 Spec。你会发现，AI 突然变得"听话"了。

本文写于 2026 年 8 月。SDD 生态仍在快速演进中，建议关注 GitHub Spec Kit、AWS Kiro 等项目的最新动态。

参考资料：

GitHub Spec Kit 官方仓库
Microsoft Developer Blog: Spec-Driven Development: A Spec-First Approach to AI-Native Engineering
Thoughtworks Technology Podcast: What is Spec-Driven Development?
AWS Kiro 官方文档