SDD （Spec-Driven Development）规格驱动详解

SDD （Spec-Driven Development）规格驱动详解

一、什么是SDD？

AICoding大概率遇到过这个场景。

你跟 AI 说"帮我做个登录功能，邮箱密码那种"。两分钟它给你吐出来一个完整的页面加接口。你跑起来一看，数据库直连写在页面组件里了，密码哈希用的算法你们项目根本不允许，返回的 token 格式也不对。你说不对，改。它改完，旁边那个图片压缩的模块被改坏了。

这个问题不是模型笨。是你那句"邮箱密码那种"，在模型那边能解读出十几种意思。它选了一个最像答案的，然后一本帮你实现完了。

GitHub 自己总结过，AI 编程 Agent 的失败基本就三个模式。

1、意图漂移。 一句话需求，模型自己补了一堆默认值。你说"加个分享"，它不知道你要分享到哪、图片压不压缩、存不存云。它按网上最常见的写法整一套，跟你想的不是一回事。

2、上下文衰减。 项目大了之后，第三十次让它改东西，它已经忘了三周前你说过"这个模块不许加新三方库"。它很自信地给你加了个库，还告诉你这样更优雅。

3、输出不可验证。 没有验收标准，代码跑绿了，你也不知道它做的是不是你要的。评审只能逐行看，看完还怀疑漏了什么。

SDD，全称 Spec-Driven Development，规格驱动开发，就是奔着这三个问题来的。

二、以代码为准改为规格为准

以前我们的开发习惯是代码当爹。需求文档写完扔一边，代码跑起来之后文档没人更新。新人来了问"这个函数干嘛的"，老员工说"你看代码"。代码实际做了什么，就是真相。

SDD 把这个关系倒过来了。

规格文档是真相，代码是从规格生成出来的东西。改需求先改规格，再让 AI 按新规格改代码。代码跟规格对不上，说明代码写错了。调试的时候也是先看规格，看是规格写错了还是实现跑偏了。

GitHub 团队有句话说得挺准：我们不该把编程 Agent 当搜索引擎用，它更像一个字面意义的结对程序员。 你跟搜索引擎说"帮我做个登录"，它给你一堆链接。你跟结对程序员说话不能这么省，边界、规则、什么不能做，都得讲清楚。

一句话概括：代码是规格的实现细节，不是反过来。可以理解成需求文档抽象成md规格（约束，用户故事，计划，任务等）

三、规格不是越严越好，分四个等级

这里很多人有个误区，觉得 SDD 就是上来写几百页文档。是这个意思，但是没这么夸张。规格的严格程度是分档的，按项目情况选。

等级	规格地位	适合什么项目
Code-First	没有正式规格，代码先写	一次性脚本、临时验证
Spec-First	编码前写规格指导初始开发，之后可放着不管	个人项目、新功能快速起手
Spec-Anchored	规格跟代码长期同步维护，测试强制对齐	团队项目、长期维护的生产系统
Spec-as-Source	只改规格不碰代码，代码全量生成	受监管系统、接口 stub 生成这类成熟场景

拿我自己的项目举例。写个工具脚本批量改文件名，Code-First 就够了。做个新的图片压缩功能，Spec-First 起步，先花半小时把要什么写清楚再让 AI 写。公司那个要维护的鸿蒙端，必须 Spec-Anchored，规格改了代码不改 CI 直接挂。

Spec-as-Source 普通业务项目先别想。那个目前只有 OpenAPI 生成接口 stub、汽车行业 Simulink 生成认证代码这种特别成熟的领域用。

判断标准就一条：用能消除歧义的最低严格程度。 一个改按钮颜色的需求写两千字规格，那是给自己找活干。

四、SDD怎么用？

这是 SDD 最有技术含量的部分。你写一份 PRD 风格的规格，AI 照样会跑偏。关键是验收标准要写成 AI 没法钻空子的形式。

行业里现在流行用一套叫 EARS （Easy Approach to Requirements Syntax，简易需求语法）的写法，由 Alistair Mavin 等人在罗尔斯-罗伊斯于 2009 年创建，如今成为 SDD 的秘密武器------它产出的需求无歧义到 LLM 可以直接执行，五种句式。我用登录模块挨个举例。

恒真的规则，任何时候都成立：

系统应记录每一次登录尝试，成功和失败都要记。

事件触发的，发生某件事就执行：

当用户点击登录按钮，系统要拿表单凭证去认证服务校验。

状态持续的，处于某个状态期间一直生效：

当登录请求进行中，登录按钮要置灰，不能重复提交。

异常情况的，这个特别重要，大部分人写规格都漏掉：

如果一分钟内密码连续错误三次，账户锁定 15 分钟。

可选功能的，开启了某个特性才生效：

如果用户开启了两步验证，密码校验通过后必须跳转到验证码页。

这五种写法的好处是，每一条都能直接转成测试用例。AI 看完知道写什么，测试看完知道测什么。它没法说"我理解的不是这个意思"。

五、 spec.md 长什么样

我把之前那个图片压缩功能的规格摘一段，你感受一下结构。

## 功能：选图后自动压缩

### 用户故事
作为用户，我希望选完图片自动压缩到可接受大小，
这样我上传的时候不用自己开 PS 改尺寸。

### 验收标准
1. 用户选择图片后，自动压缩到最长边 1024px。
2. 压缩后文件大于 500KB 时，提示用户手动选择质量档位。
3. 压缩失败时，原图保留，弹出错误提示，不允许提交。
4. 压缩过程中，页面显示 loading，按钮置灰。

### Out of Scope
- 本期不做批量压缩。
- 本期不做滤镜和贴纸效果。
- 本期不做云端压缩，全部端侧完成。

看到最后那块 Out of Scope 了吗。这个比你想象的重要。你不写清楚不做什么，AI 就会自作主张。我上次没写，它给我加了个滤镜功能，我花了十分钟才让它删掉。

六、SDD 跟传统需求文档有啥区别

很多人会问，这不就是我们以前写的需求文档吗。

还真不一样。传统需求文档是给人看的，写完就漂了。第三个迭代就对不上代码了。SDD 的规格是给 AI 读的，结构化、有验收标准、跟代码一起版本控制，而且有测试去强制它跟代码对齐。

说白了，以前的文档是建议性的，你写了大家不一定照着做。SDD 的规格是强制性的，代码偏离规格，测试直接挂。

SDD 不是什么新方法论，TDD、BDD 玩的都是这套"先定行为再写代码"的思路。它之所以这两年火，就是因为 AI 编程 Agent 把这个需求放大了。以前你写不清楚需求，最多是返工。现在你写不清楚，AI 直接按它的理解给你生成一堆代码，返工成本更高。

核心就三句话：

1. 规格是真相，代码是生成物。
2. 用能消除歧义的最低严格程度，别上来就最重。
3. 验收标准写成 EARS 那种句式，AI 才能不跑偏。

并且现在有很多skills，可以直接转化需求文档为SDD需要的md。人工负责审核即可。