规格驱动开发：AI 时代的软件工程新范式

先写规格，再写代码——这事变了

传统软件开发里，规格文档通常是写完代码后的补品，甚至根本不存在。需求来了，打开 IDE 就撸，边写边想边改，这是大部分程序员的真实工作流。

但 AI 编程工具改变了这个等式。当你给 Cursor、Copilot、Claude 一个模糊的需求，它给你一堆似是而非的代码；当你给它一份精确的规格说明，它输出的代码质量能飙升好几个档次。

于是”规格驱动开发”（Spec-Driven Development，简称 SDD）这个概念开始流行。核心想法很简单：把”想清楚要做什么”和”动手做”分成两步，前一步人主导，后一步 AI 主导。

SDD 到底是什么

SDD 不是什么全新的发明。它跟 TDD（测试驱动开发）、BDD（行为驱动开发）一脉相承——都是用某种”前置约束”来驱动编码。区别在于约束的形式：

方法	前置约束	验证方式
TDD	测试用例	跑测试
BDD	行为描述	场景验证
SDD	规格说明	规格对照

SDD 的规格比测试用例更广，比行为描述更具体。一份好的规格应该包含：

• 做什么：功能边界、输入输出、异常处理
• 不做什么：明确的排除项，防止 AI 过度发挥
• 约束条件：性能要求、兼容性、安全策略
• 接口契约：API 签名、数据结构、状态转换

说白了，SDD 就是把”脑子里的想法”变成”机器能读的规格”，然后让 AI 按规格干活。

为什么 AI 时代需要 SDD

1. AI 是执行者，不是决策者

当前的 AI 编程助手最擅长的是”理解意图并生成代码”，最不擅长的是”猜你到底想要什么”。模糊的需求 + 强大的执行 = 精确的错误。

SDD 把决策权留在人手里。你定好规格，AI 只负责实现。这比”让 AI 一边想一边写”靠谱得多。

2. 规格是可迭代的最小代价

改一份规格说明，几分钟。改一段跑了一半的代码，几小时。在 AI 辅助下，写代码的成本已经大幅下降，但修改已有代码的成本并没有等比例下降——因为你得理解 AI 写的代码，确认改动不会引入新问题。

先在规格层面迭代，确认无误后再让 AI 生成代码，整体效率更高。

3. 规格即上下文

AI 编程最大的瓶颈是上下文窗口。一份精炼的规格说明，比翻来覆去的对话记录有效得多。规格天然就是结构化的上下文——它告诉 AI 要做什么、不要做什么、边界在哪。

SDD 的工作流

一个典型的 SDD 循环长这样：

需求 → 写规格 → 规格评审 → AI生成代码 → 人工验收 → 补充规格 → 再生成

关键环节拆解：

第一步：写规格

这是 SDD 的核心，也是最难的部分。写规格不是写小说，要精确、无歧义、可验证。

一份 API 端点的规格可能长这样：

endpoint: POST /api/users
purpose: 创建新用户
input:
  - name: string, 必填, 2-50字符
  - email: string, 必填, 合法邮箱格式
  - role: enum[user, admin], 可选, 默认user
output:
  201: { id: string, name: string, email: string, role: string, createdAt: ISO8601 }
  400: { error: string, field: string }
  409: { error: "用户已存在" }
constraints:
  - 同一邮箱不能重复注册
  - name字段做HTML转义
  - 不发欢迎邮件（后续版本再做）

注意最后一条”不发欢迎邮件”——明确说”不做什么”和说”做什么”一样重要。AI 不写你不想让它写的东西。

第二步：规格评审

别跳过这步。自己读一遍，或者让另一个 AI 来审。检查：

• 有没有歧义？比如”处理错误”——具体处理什么错误？怎么处理？
• 有没有遗漏？异常路径、边界条件、并发情况
• 有没有矛盾？前后说法打架

第三步：AI 生成代码

把规格丢给 AI，让它写。这一步应该是最无痛的。如果规格写得好，AI 通常一次就能生成 80-90% 可用的代码。

第四步：人工验收

跑测试、看代码、试功能。发现问题不要直接改代码——先回到规格，看看是规格遗漏还是 AI 偏离。

• 规格遗漏 → 补规格，再让 AI 重新生成
• AI 偏离 → 修代码，但检查是否规格表述不够清晰

第五步：迭代

SDD 不是瀑布模型。规格可以改，应该改。但每次改规格是显式的决定，不是无意识的蔓延。

SDD 与现有开发方法的对比

SDD vs 敏捷

敏捷强调”响应变化胜过遵循计划”。SDD 并不反对变化——它要求变化先体现在规格上，再体现在代码上。这其实是更可控的敏捷：变化是显式的，不是隐式的。

敏捷的 user story 太粗，SDD 的规格更细。两者可以结合：用 user story 管需求，用规格驱动实现。

SDD vs 设计文档

设计文档通常是重量级的，写完就过时。SDD 的规格是轻量级的，跟代码同步迭代。

关键区别：设计文档是给人看的，SDD 规格是给 AI 看的（当然人也看）。给 AI 看的规格必须精确、无歧义，这反过来也帮了人——你被迫想清楚。

SDD vs Prompt Engineering

有人觉得 SDD 就是”写好 prompt”。有重叠，但不等同。

Prompt Engineering 关注的是怎么跟 AI 对话，偏技巧层面。SDD 关注的是怎么组织软件开发的思维过程，偏方法论层面。好的 SDD 规格可以转化为好的 prompt，但 SDD 不止于 prompt。

实践建议

规格写多细？

一个实用的判断标准：让一个不了解项目的程序员看了规格后，能写出正确的代码，而不需要问你任何问题。

如果达到这个标准，规格够细了。如果他还得来问你”这个字段什么意思””那个边界怎么处理”，说明规格不够。

但也不用过度。规格不是形式化证明，不用穷举每种可能。覆盖 80% 的主路径和 20% 的关键异常就够了。

用什么格式写规格？

没有标准答案。Markdown、YAML、甚至 JSON 都行。关键是：

• 结构化：AI 能解析，人能阅读
• 可版本控制：跟代码一起进 Git
• 可迭代：改起来方便

我推荐 Markdown + YAML 混合。用 YAML 写接口定义和数据结构，用 Markdown 写业务逻辑和约束说明。

规格放哪里？

跟代码放一起。每个模块一个 spec.md，或者用 .spec/ 目录集中管理。别放 Wiki 里——Wiki 和代码是两个世界，很快就会脱节。

什么时候写规格？

任何需要让 AI 写超过 50 行代码的时候。写个工具函数不用规格，但写一个 API 端点、一个数据流、一个组件，值得先写规格。

SDD 的局限

不吹不黑，SDD 也有它的问题：

写规格本身需要能力。 把模糊的想法变成精确的规格，这比写代码更难。很多程序员不擅长这个，也不是每个人都愿意学。

探索阶段不适用。 如果你在做原型、做 PoC、做技术验证，先写规格反而拖慢节奏。这时候快速试错比精确规划更有价值。

规格也会过时。 如果规格不跟着代码更新，它就成了谎言。需要纪律来维护规格和代码的同步。

不适合所有团队。 小团队、快速迭代的产品，SDD 可能显得重。大团队、需要协作的项目，SDD 的价值才明显。

工具生态

SDD 目前还在早期，工具不多，但已经有一些方向：

• Cursor Rules：用 .cursorrules 文件定义项目约束，本质上是轻量级规格
• Claude Specs：Anthropic 推荐的规格化开发方式
• OpenClaw Skills：用 SKILL.md 定义 AI 技能的行为规格
• Aider：支持从规格文件驱动代码生成
• SpecKit：社区尝试的规格管理工具

这些工具的共同思路：用文件（而非对话）来持久化 AI 的行为约束。

一个完整的 SDD 案例

假设要做一个”用户注册”功能，SDD 的流程：

1. 需求理解

用户注册，邮箱验证，基本信息填写。

2. 写规格

# 用户注册规格

## 功能
- 用户通过邮箱+密码注册
- 注册后发送验证邮件
- 验证链接24小时有效
- 验证后账户激活

## 接口
### POST /api/register
- input: { email, password, name }
- password: 8-128字符，至少包含数字和字母
- email: 合法邮箱格式，唯一
- 201: 注册成功，返回 { userId, status: "pending_verification" }
- 400: 参数校验失败
- 409: 邮箱已注册

### POST /api/verify
- input: { token }
- 200: 验证成功，返回 { userId, status: "active" }
- 400: token 无效
- 410: token 过期

## 不做的事
- 不支持手机号注册（V2再做）
- 不支持第三方OAuth（V2再做）
- 注册后不自动登录
- 不限制注册频率（V1先不做防刷）

## 数据模型
User {
  id: UUID
  email: string, unique
  passwordHash: string
  name: string
  status: enum[pending_verification, active, disabled]
  createdAt: timestamp
  verifiedAt: timestamp?
}

3. 把规格给 AI

“按照 spec.md 的规格实现用户注册功能，使用 Node.js + Express + PostgreSQL。”

4. AI 生成代码，你验收

检查 AI 生成的代码是否满足规格中的每一条。不满足的，回到规格看是遗漏还是 AI 的问题。

5. 迭代

发现需要支持密码强度提示 → 更新规格 → 让 AI 补充代码。

规格的演进

规格不是一成不变的。随着项目发展，规格会经历几个阶段：

1. 种子规格：刚开始只有核心功能的粗略描述
2. 工作规格：经过几轮迭代，覆盖了主要路径和关键异常
3. 活规格：跟代码持续同步，每次功能变更先改规格

目标是让规格始终处于”活”的状态。死规格比没规格更危险——它会误导。

小结

SDD 的核心主张：在 AI 能高效写代码的时代，人的价值在于定义”做什么”和”不做什么”，而不在于敲代码本身。

这不是说写代码不重要了。而是说，写代码这件事的性价比天平已经倾斜——花一小时写精确的规格，比花一小时调 AI 生成的代码，产出更高。

当然，SDD 不是银弹。它是一种适合 AI 编程时代的工作方式，尤其适合功能明确、边界清晰的项目。对于需要大量探索的工作，传统的方式可能更灵活。

试试看。下次让 AI 写代码之前，先花十分钟写个规格。你会发现，省下的不止十分钟。

---

参考：Anthropic - Building Effective Agents、Cursor Rules、OpenClaw Skills