# 3个月，从+30%到-40%：SDD落地踩坑实录

3个月前，我们团队全面推行 SDD（规范驱动开发）。第一个月，单接口端到端耗时不降反升，比手写多了 30%；熬到第三个月，这个数字变成下降 40%。前两个月是爬坡期，第三个月才突然拐头——而第 6 周，是大多数人想放弃的节点。这不是理论布道，是我踩了一堆坑之后摸出来的实战总结。

## 认知转变：SDD 不是写文档，是前置思考

很多人把 SDD 理解成"多写一份文档"，这是第一道坎。传统写代码是增量思考——边写边想、错了再改；SDD 要求前置思考——写第一行代码前，就把边界、异常、约束全想清楚。反直觉，但过了这关，后面全是执行。

落地时最容易卡在三件事上：一是"手比脑子快"，需求一来手指自己就动了，先写代码再补规范，Review 反复被打回；二是"不会写规范"，打开模板大脑空白，坐半天写不出一个字；三是"担心被 AI 替代"，于是规范写得敷衍，AI 生成质量差，又用"AI 还是不行"给自己找理由不配合。

这三道坎本质上都是认知问题，不是技术问题。核心认知只有一句：**用流程倒逼思考**。把"想清楚"从写代码时挪到写代码前——IDE 里卡一道关，不写规范就提交不了代码，倒逼你先填完规范、确认验收条件都可测试了，再让 AI 动手。

## 怎么落地：3 级规格 + 两个必写项

### 为什么分级

写规范最大的障碍不是"不会写"，是"不知道从哪写"。我一开始把规范等同于长篇大论，对着空白模板发呆。后来想明白：好规范 = 结构化 + 可执行 + 边界清晰，不一定需要很多字。关键区别在于读者——传统文档写给人看，SDD 规范写给 AI Agent 看，它的结构必须让模型能引用、对照检查、在 session 切换时恢复上下文。

解法是按接口复杂度分三级，降低起步门槛：

- **L1 极简**——简单接口，输入输出字段 + 基本校验，5 分钟搞定
- **L2 标准**——业务逻辑接口，加状态流转、异常码、边界条件，15 分钟
- **L3 完整**——核心复杂模块，加性能约束、降级策略、安全要求，40 分钟

拿不准就先从 L1 写，写着发现需要补状态流转再升 L2。不要一上来奔 L3 去——那只会让你对着模板发呆。

### 同一主题三个级别的规格案例

下面三份规格都围绕"订单状态变更"，差别只在颗粒度，一眼就能看出 L1 到 L3 层层加了什么。

L1 极简（约 5 分钟，字段 + 基本验收）：

```markdown
## 接口：订单状态变更

### 输入
| 字段 | 类型 | 必填 | 校验规则 |
|------|------|------|----------|
| order_id | string | 是 | 订单ID，UUID格式 |
| target_status | enum | 是 | 取值：PAID / SHIPPED / CANCELLED |
| operator_id | string | 是 | 操作人ID |

### 输出
| 字段 | 类型 | 说明 |
|------|------|------|
| order_id | string | 订单ID |
| current_status | enum | 变更后状态 |
| updated_at | datetime | 变更时间（ISO 8601） |

### 验收条件
- [ ] 订单不存在时返回 404
- [ ] 状态变更成功返回最新状态
- [ ] 变更记录写入操作日志
```

L2 标准（约 15 分钟，在 L1 基础上加状态流转规则、异常码、EARS 验收条件）：

```markdown
## 接口：订单状态变更

### 状态流转规则
| 当前状态 | 允许流转到 | 不允许流转到 |
|----------|-----------|-------------|
| PENDING | PAID, CANCELLED | SHIPPED, DELIVERED |
| PAID | SHIPPED, CANCELLED | PENDING, DELIVERED |
| SHIPPED | DELIVERED | PENDING, PAID, CANCELLED |
| DELIVERED | （终态） | 任何状态 |
| CANCELLED | （终态） | 任何状态 |

### 异常码
| 错误码 | HTTP | 触发条件 | 返回信息 |
|--------|------|----------|----------|
| ORDER_NOT_FOUND | 404 | 订单ID不存在 | "订单不存在" |
| INVALID_TRANSITION | 409 | 不允许的状态流转 | "当前状态{current}不允许变更为{target}" |
| REASON_REQUIRED | 400 | 取消未填原因 | "取消订单必须填写原因" |

### 验收条件
- [ ] WHEN 状态流转合法 THEN THE SYSTEM SHALL 更新订单状态并记录流转日志
- [ ] IF 状态流转不合法 THEN THE SYSTEM SHALL 返回 409 + INVALID_TRANSITION
- [ ] WHEN 订单变更为 CANCELLED THEN THE SYSTEM SHALL 释放库存并触发退款流程
- [ ] IF 操作人无权限 THEN THE SYSTEM SHALL 返回 403

### 边界情况
- 并发变更：使用乐观锁（version字段），后到的返回 409
- 异步通知失败：重试3次后写入死信队列，不阻塞主流程
```

L3 完整（约 40 分钟，在 L2 基础上加性能约束、降级策略、安全要求、兼容边界）：

```markdown
## 接口：订单状态变更（核心链路）

### Non-goals（本期不做什么）
- 不重构现有对账系统，仅通过事件推送数据给对账系统
- 不修改下游支付服务的接口契约
- 不支持批量状态变更

### 性能约束
| 指标 | 要求 | 说明 |
|------|------|------|
| 变更接口 P99 延迟 | <300ms | 含库存/通知调用 |
| 吞吐量 | >500 TPS | 大促峰值场景 |
| 数据库查询 | 单请求 <5次 | 避免N+1 |

### 降级策略
- 库存服务超时（>2s）：标记"释放中"，异步补偿，不阻塞主流程返回成功
- 通知服务不可用：写入重试队列，最多重试10次
- 数据库不可用：写入本地消息队列，恢复后补偿处理

### 安全要求
- 所有变更操作必须校验操作人权限（RBAC）
- 敏感操作（取消、退款触发）需二次确认
- 接口限流：单用户 10次/分钟
- 完整操作审计日志，保留90天

### 兼容边界（不允许改动）
- order_id 格式不变（已有外部系统依赖）
- 状态变更通知下游的消息格式不变
```

三份规格一摆出来，颗粒度差异不言自明：L1 只问"字段对不对、异常返回了没"；L2 多了"状态能不能流转、流转出错怎么报"；L3 还要回答"高并发扛不扛得住、下游挂了怎么办、谁有权限改"。

### 两个必写项

3 级模板解决了结构和复杂度，但还有两个必写项很多人会漏。

**第一个：非目标（Out of Scope）。** 多数人只写"要做什么"，不写"不做什么"。但 AI 天生爱"帮忙"——你让它做状态变更，它可能顺手帮你重构了查询接口、加了配置项。非目标就是刹车：

```markdown
Non-goals:
- 本期不支持批量状态变更
- 本期不改造现有订单查询接口
- 本期不支持自定义状态扩展
```

写了这三行，AI 就不会"顺手"帮你做这三件事。不写，你就等着返工。

**第二个：EARS 句式写验收条件。** EARS 源自航空安全领域，现在成了 SDD 的隐藏武器——因为每个 EARS 句式都能直接转成一条测试用例。两个最常用的句式：

- **WHEN...THE SYSTEM SHALL...**（事件驱动）："WHEN 状态流转合法 THEN THE SYSTEM SHALL 更新订单状态并记录流转日志"
- **IF...THEN THE SYSTEM SHALL...**（异常行为）："IF 凭据校验 60 秒内失败 3 次 THEN THE SYSTEM SHALL 锁定账户 15 分钟"

对比一下：写"处理异常"，AI 不知道做什么；写"IF 密码错误超过 5 次 THEN 锁定账户 30 分钟"，AI 能直接实现并写测试。把猜测空间变成决策空间。

### 何时选用哪一级

| 信号 | 选用级别 |
|------|----------|
| 输入输出清晰、无复杂业务逻辑的 CRUD | L1 |
| 有状态流转、多条件分支、需要异常码体系 | L2 |
| 涉及性能约束、降级策略、安全要求 | L3 |
| 拿不准 | 先从 L1 起步，需要再升级 |

这里有个"规约钟摆规律"值得注意：规范从简到繁，再从繁回到简。规则加载得越多，AI 每执行一步都要遍历所有规则做校验，思考被拉长；规范太细，AI 反而没了发挥空间。所以存在一个最优区间，越过那个点边际收益转负——这也是分级而非一刀切要求所有接口写 L3 的原因。

### 想清楚内容：先扩再裁

模板解决了"怎么写"，但内容从哪想出来？"先扩再裁"——先让 AI 帮你头脑风暴，列出所有可能的边界条件、异常场景、依赖关系；再由你做判断，哪些真正需要、哪些是过度设计，裁掉；裁完整理成规范，然后才写 plan、拆任务、生成代码。你不需要凭空想出所有边界条件，AI 帮你扩展视野，判断权在你手里。配合一个固定启动提示词，第一句就是"你先不要写代码"——强制 AI 先想再动手。Spec 确认后，再让 AI 出技术方案（Plan），Plan 确认后拆 Tasks，Tasks 确认后才 Implement——每个阶段边界都有人工确认。在 Plan 阶段发现一个错误，改一段话的事；等 AI 写了 800 行代码再发现，就是重写的事。

## 从规范到代码：让 AI 一次做对

规范写好了，怎么让 AI 把它变成高质量代码？四条原则。

**给足上下文。** 只喂规范文件不够——AI 不知道项目的 naming 约定、安全约束、架构分层。规范文件 + 相关元模型 + AGENTS.md 一起喂。AGENTS.md 是放在仓库根目录的项目规则文件，回答三件事：怎么构建（启动命令、测试命令）、什么不能碰（不改哪些接口、不改哪些配置）、怎么验证（跑什么测试、做什么检查）。没有它，每个新功能 AI 都要重新猜你的技术栈和禁止事项——猜着就偏了。顺带一提，Spec-Kit、Superpowers 这些开源工具拿来就能和实际开发严丝合缝？事实是咬不上——企业自有规范越私有越细，公用标准越不适合。工具必须被重构，不是套用。

**小步生成。** 一次只让 AI 生成一个接口或一个模块，不要一次生成整页。出了问题容易回退和定位——改一个接口比重生成整个模块快得多。生成后立即拿验收条件逐条对照，花 2 分钟过一遍，快速发现 AI 遗漏的边界条件。

**迭代规范而非改代码。** AI 生成不符合预期时，先改规范再重新生成，不要直接改代码。直接改了代码，规范和代码就不一致了——下次 AI 拿这份过时规范生成，又会出错。

**重试环：错误写回 Spec。** 生成→测试→把错误信息写回规范（在对应验收条件后标注"AI 未通过此条件"）→基于更新后的 Spec 重新生成，通常 2-3 轮收敛到生产质量。关键在第三步——不只改代码，把错误场景写回规范，Spec 本身也在进化。最后让 AI 交付时回填一份 Delivery Report——列出哪些验收条件通过了、哪些没通过。AI 不能既当选手又当裁判，这份报告让你做裁判。

一个警惕：AI 生成的代码有"引力"——会不自觉地向训练数据的平均水平靠拢，Joshua Levy 管这叫 Slop Code。更糟的是 slop 会传染——你让一个坏模式溜过去了，下一个 Agent 看到这段代码会以为是项目标准，继续复制。应对方法是在 AGENTS.md 里写死禁止事项，规则越明确 slop 越少。

## 数据验证与效果

3 个月下来，这是真实数据：

| 指标 | 第1个月 | 第2个月 | 第3个月 |
|------|---------|---------|---------|
| 规范编写平均耗时 | 20分钟/接口 | 15分钟/接口 | 10分钟/接口 |
| AI 生成代码直接采纳率 | 35% | 48% | 62% |
| Review 返工率 | 40% | 28% | 18% |
| 单接口端到端总耗时 | +30% | +10% | -40% |

三个关键解读：

第一，第 1 个月耗时增加，但规范编写只占新增耗时的 40%——剩下 60% 是 Review 返工。第 1 个月返工率 40%，意味着近一半接口改了又改，这才是前期痛苦的真正来源，不是写规范本身。

第二，规范编写从 20 分钟降到 10 分钟，主要归功于 3 级模板——L1 把简单接口门槛压到 5 分钟，"先扩再裁"解决了"不知道写什么"的卡壳。分级采纳率上，L1 单项 70% 以上、L2 约 60%、L3 约 50%（需人工调优），整体平均 62%（因为含 L2/L3 偏低的接口拉低了平均值）。

第三，第 6 周是拐点。前 5 周我状态很差，好几次想放弃。第 6 周发生了两件事：团队发布了第一版规范参考库——平时 Review 同事代码时，碰到写得好的规范存下来，下次遇到类似接口直接参考，这些被复用的规范就是团队的"记忆层"；我发现"原来别人的规范可以直接拿来用"；我写的一份 L3 规范被同事复用了 3 次。强制了 6 周，开始尝到甜头——从"被迫"到"自愿"的临界点。外部团队实测数据也印证了这个趋势：引入 Spec 后 AI 生成代码一次通过率从 31% 提升到 89%，缺陷密度下降 76%。

坦诚补一个成本：团队月度 AI 费用上涨涨到近4倍。SDD 不只是省时间，也有真金白银的投入——这块心里要有数。

## 避坑指南

### 三个最容易踩的陷阱

**陷阱一：试图用 SDD 覆盖所有场景。** 小脚本、一次性原型、探索性 spike，用 Vibe Coding 更快。SDD 的甜区是有明确业务逻辑、需要可维护性、多人协作的场景。判断标准很简单：这段代码 3 个月后还要改吗？要→SDD；不要→随便写。

**陷阱二：过早定义过于详细的规范。** 需求还没清楚就强行写详尽规范，会产生"虚假的清晰度"——看着很完整，每个细节都是猜的，到实现阶段全部推翻。需求模糊时从 L1 起步，标明"待确认"项，不要硬填。

**陷阱三：忽略隐性知识。** 存量系统里有大量知识散落在老员工脑子里——"这个字段为什么这么命名""这个接口为什么不能改返回结构"——这些没法从代码自动提取。规范评审时拉上熟悉这块业务的人，把隐性知识外化到规范里，别让 AI 基于半截子理解去生成代码。

### Bug 修复：先问 Spec 再动手

功能上线，bug 来了。传统做法直接改代码——但在 SDD 里，先翻开 Spec 问一个问题：这个场景 Spec 里写了吗？因为如果直接改了代码但没改 Spec，下次 AI 基于旧 Spec 重新生成时，bug 又会回来——你修了个寂寞。SDD 的铁律是：需求变更时更新的是 Spec，不是代码。

翻开 Spec 一秒就能判断 bug 属于哪类，三类 bug 对应三种修法：

| Bug 类型 | Spec 里有没有 | 修复策略 |
|----------|-------------|----------|
| 实现偏离型 | 写了，但代码没照做 | 不改 Spec，基于 Spec 重新生成 |
| Spec 缺陷型 | 写了，但有歧义或写错 | 先改 Spec，再改测试，再重新生成 |
| Spec 遗漏型 | 压根没写这个场景 | 补 Spec 新增验收条件，再重新生成 |

一句话：Spec 写了但代码没照做→重新生成就行；Spec 没写或写错了→先补 Spec 再重新生成。决不能出现"所有 bug 都直接重生成"的偷懒做法。

还有一条"两次失败原则"快速带过：同一任务两次修复都失败，停下来，检查 Spec。重复失败通常说明问题不在代码，在 Spec 或 Plan——改 prompt 改得再勤也没用。跟代码死磕是 Vibe Coding 的习惯，SDD 要求你跟 Spec 较劲。

## 写在最后

三句话收尾。Microsoft 说：SDD 是思考的版本控制——传统版本控制管理代码的演变，SDD 管理的是思考的演变历史。圆桌讨论里说：把不确定性挤给人，把确定性交给机器。我自己的切身感受是：SDD 不是让工程师不写代码，是让你的手从键盘上慢下来，让脑子在前面多跑几步。

你也在推行 SDD 吗？踩过哪些坑、有什么不同做法？评论区聊聊。


**参考资源**：
- GitHub Spec-Kit：开源 SDD 脚手架，通过 `specify init` 初始化工程契约链
- Joshua Levy - speculate：独立 SDD 实践项目（与 Spec-Kit 不同），50 万行 Agent 生成代码的经验总结
- 腾讯云架构师同盟圆桌·AI 编程组织能力进化：十几位一线架构师的交叉印证
- SDD SOP（stel1os/ai-sdd-sop）：完整标准操作流程，含 Spec Amendment 协议
- 详解 SDD：Agent 时代的软件工程新范式，含 SDD vs TDD/BDD/DDD 对比


3个月前，我们团队全面推行 SDD（规范驱动开发）。第一个月，单接口端到端耗时不降反升，比手写多了 30%；熬到第三个月，这个数字变成下降 40%。前两个月是爬坡期，第三个月才突然拐头——而第 6 周，是大多数人想放弃的节点。这不是理论布道，是我踩了一堆坑之后摸出来的实战总结。

3个月，从+30%到-40%：SDD落地踩坑实录

腾讯先锋TDP成员

编程语言

开发工具

后端

3个月时间，SDD落地从效率下降30%逆转为提升40%，第6周是放弃与突破的分水岭。核心在于用流程倒逼前置思考，按接口复杂度分L1-L3三级编写规范，配合“非目标”与EARS验收句式两个必写项，让AI一次做对。经验证明：先扩再裁想清边界，迭代规范而非改代码，三类Bug各有对应修法。

消息队列

软件工程

代码解释

数据库

云架构

AI编程

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

3个月，从+30%到-40%：SDD落地踩坑实录-腾讯云开发者社区-腾讯云

3个月，从+30%到-40%：SDD落地踩坑实录

3个月，从+30%到-40%：SDD落地踩坑实录

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐