三个月从多耗时 30% 到节省 40%：SDD 落地真正卡在哪里

同一套 SDD 流程，第一个月让单接口端到端耗时增加 30%，第三个月却把耗时降低了 40%。如果只截取前半段，它是一次失败的流程改造；只展示后半段，它又像一篇过度漂亮的成功学。真正值得研究的，是中间那六周发生了什么。

我是老李。今天借宋振华的《3个月，从+30%到-40%：SDD落地踩坑实录》，把 SDD 从概念落到团队工程：为什么规范不是额外文档，为什么第六周最容易放弃，以及怎样让 Spec 真正进入测试、代码和变更管理。

01、第一月变慢，不代表方向错了

原文给出一个容易被误读的数据：第一个月新增耗时中，规范编写只占 40%，其余 60% 来自 Review 返工；同期返工率达到 40%。也就是说，痛苦的主要来源不是“多写了十几分钟”，而是团队第一次把过去藏在编码过程里的分歧提前暴露出来。

传统开发会把不清晰需求推迟到联调、测试甚至线上。表面上开工很快，成本却分散在返工里。SDD 把边界、异常和非目标集中到开工前，前期时间因此变得可见。迁移期若只看开发开始到提交代码的速度，必然会误判。

真正应该比较的是端到端周期：需求进入、规格确认、实现、评审、测试、返工到可发布。第一个月变慢可以接受，但必须能解释慢在哪里；如果三个月后仍在写长文档、测试没有复用规格，那才是流程设计失败。

02、SDD 不是文档驱动，而是可执行的意图管理

一份普通需求文档可以描述背景和愿景，一份有效 Spec 必须让人和 Agent 对“完成”达成相同判断。它至少回答：系统要实现什么、不实现什么；输入输出契约是什么；状态如何流转；异常怎样呈现；性能、安全和兼容边界在哪里；哪些条件可直接转成验收测试。

模糊需求 -> Spec -> Plan -> Tasks -> Code -> Tests
              ^                         |
              └──── 变更与缺陷回写 ─────┘

关键不是箭头向右走一次，而是任何需求变更和缺陷修复都先回写 Spec。否则下一次 Agent 根据旧规格生成代码时，已经修过的 Bug 会重新出现。代码是当前实现，Spec 是可持续的意图来源；两者发生冲突时，团队必须明确谁先被修订。

03、三个常见认知陷阱，会让团队在第六周退出

第一个陷阱是“我手写更快”。对一个熟悉接口也许成立，但团队要优化的是长期变更成本，不是首屏代码出现时间。第二个陷阱是“我不知道规格该写什么”，于是模板越做越大，最后所有人面对空表格发呆。第三个陷阱是“有了 Agent，工程师只负责审批”，结果把未完成的判断交给模型，再用 Review 承担全部返工。

第六周危险，是因为学习成本已经支付，收益却尚未稳定出现。原文中，拐点来自两件具体事件：团队形成第一版优秀规格参考库；成员开始复用已经验证过的结构。空白页成本下降后，规范编写从约 20 分钟降到 10 分钟，流程才从负担变成杠杆。

所以推动者不能只发布制度。每周要收集一份“写得好且上线有效”的 Spec，标出为什么好；同时收集一份返工案例，说明哪个缺失边界导致了什么成本。参考库不是模板仓库，而是判断案例库。

04、架构核心：三级规格，不让所有任务穿同一件衣服

原文把规格分为三级。L1 极简约 5 分钟，覆盖字段、基本校验和验收；L2 标准约 15 分钟，增加状态流转、异常码和 EARS 验收条件；L3 完整约 40 分钟，再加入性能、降级、安全与兼容边界。

任务风险与复杂度
      |
      +-- 单表/简单校验 ----------------> L1
      +-- 状态机/跨服务/明确异常 --------> L2
      +-- 核心链路/高并发/安全合规 ------> L3
      +-- 暂时判断不清 ------------------> L1 起步，发现风险即升级

分级解决的是边际收益问题。规范太少，Agent 靠猜；规范太多，模型每一步都遍历规则，团队也被维护成本拖慢。所谓“规约钟摆”，就是从简到繁后再回到恰好够用。级别不是按职位审批，而应由状态复杂度、故障影响面、不可逆性和合规要求共同决定。

每级都必须保留两个项目：Non-goals 明确本期不做什么；验收条件明确什么情况算完成。前者控制范围蔓延，后者连接测试。缺少任一项，规格都会退化成愿望清单。

05、从写规格到用规格：先扩、再裁、再冻结

“先扩再裁”是最实用的写法。第一步让 Agent 罗列边界、依赖、异常和反例，此时明确要求“先不要写代码”；第二步由工程师根据业务价值和风险删除过度设计；第三步把保留项写成可验证条款；第四步冻结当前版本，再进入 Plan。

验收条件可以采用 EARS 风格。例如：“当支付成功事件重复到达时，订单服务应保持已支付状态，并返回幂等处理结果。”这句话同时包含触发、对象、行为和结果，比“保证接口幂等”更容易转成测试。

Plan 负责把规格映射到架构和文件，Tasks 负责形成可独立验证的小步实现。每个阶段都设置人工确认：Spec 确认业务判断，Plan 确认技术取舍，Tasks 确认执行顺序。若等 Agent 写完 800 行代码才发现理解偏差，所谓自动化只是更快地产生返工。

一个有效的 PR 应同时包含 Spec 版本、对应任务、实现和测试证据。评审者不再凭经验浏览所有代码，而是逐条确认“实现是否满足条款、测试是否覆盖边界、是否出现未声明行为”。

06、Bug 修复也必须经过 Spec

线上出现缺陷时，先问：这个场景是否已写进 Spec？若没有，先补条款和失败测试，再改实现；若已经写了但实现错误，说明执行或验证环节失守；若条款本身错误，则先完成业务决策。三种原因对应三种改法，不能都归结为“模型不够聪明”。

原文提出“两次失败原则”：同一任务连续修复两次仍失败，暂停改代码，检查 Spec 或 Plan。反复调提示词往往只是让模型围绕错误前提继续努力。失败次数是一个触发器，迫使团队从局部补丁回到上游意图。

还要建立双向追踪：条款能找到测试，测试能找到实现，线上告警能找到对应的性能或降级条款。没有追踪关系的 Spec 很快会变成过期文档；有追踪关系，它才是工程控制面。

07、用一组指标判断流程是否真的变好

不要只统计写了多少份 Spec。建议同时观察：端到端交付周期、首轮 Review 通过率、返工工时、需求澄清次数、缺陷逃逸率、规格编写时间、规格条款测试覆盖率、变更后 Spec 同步率，以及不同级别的采纳率。

原文第三个月的变化值得成组理解：端到端耗时从首月的增加 30% 变为减少 40%；规格编写时间从 20 分钟下降到 10 分钟；分级后 L1 采纳率超过 70%，L2 约 60%，L3 约 50%，整体约 62%。这说明效率不是靠“所有任务都写更多”，而是靠复用、分级和减少返工。

团队还应画周趋势而非只看月均值。如果规范时间下降、返工不降，说明条款不可执行；如果返工下降、交付仍慢，可能是审批门槛过多；如果低风险任务普遍进入 L3，说明分级机制失效。

不要只比较开发阶段的工时。SDD 的收益通常后移到评审、联调、验收和维护阶段，因此至少同时观察需求澄清耗时、规格评审轮次、编码耗时、返工比例、缺陷逃逸率、变更前置时间和线上回滚率。若编码快了但评审堆积，流程只是把瓶颈搬了位置；若文档数量增加却无法回答“为什么这样设计”，则团队增加的是库存，不是知识。

指标必须按任务复杂度分层。把改一行配置和跨服务状态迁移放进同一平均值，会掩盖真实变化。更稳妥的做法是记录基线区间，观察中位数与高分位，并为异常任务附一段解释。原实践中第六周出现转折，这个时间点不能照搬，但提醒管理者：试行期既要设止损条件，也要避免在学习成本刚暴露时过早宣判失败。

08、一套十二周的低风险推行路线

第 1～2 周只选一个中等复杂度服务，建立基线数据；第 3～4 周试行 L1/L2，积累五个正反案例；第 5～6 周引入 Non-goals、EARS 和参考库；第 7～8 周把 Spec 条款接入测试与 PR 模板；第 9～10 周扩展到 L3 核心链路，并演练降级；第 11～12 周根据指标删除无效规则，再决定是否扩大范围。

推行期间保留例外通道。生产事故可以先止血，但事后必须补 Spec 和回归；探索性原型可以轻量记录假设，进入正式开发再升级。流程的目的不是追求整齐，而是让重要判断可见、可复用、可验证。

角色边界也要提前写清。需求负责人确认目标与非目标，开发者补齐状态、依赖和失败路径，测试人员把验收条款转换为可重复验证的场景，技术负责人只对高风险分歧做裁决。不要把“写 Spec”永久交给某一位文档管理员，否则业务判断与实现约束会再次分离。评审会上也不应逐字润色，而应集中追问三类问题：哪条假设没有证据，哪种失败没有恢复路径，哪项验收无法自动或人工复现。

参考库需要版本与淘汰机制。模板、正例、反例和决策记录都标注适用系统、更新时间与维护人；连续两个季度无人使用的条目进入清理队列。若 AI 检索到旧规格，必须能看到它被哪份新决策替代。这样团队复用的是仍然有效的判断，而不是把历史文档当成不可质疑的事实。

负责人每两周做一次“规则清理”：哪些字段从未被使用，哪些条款无法测试，哪些模板只制造复制粘贴。SDD 的成熟标志不是文档越来越厚，而是团队越来越知道哪些内容值得写。

09、原文、概念与落地检查表

推荐原文：宋振华，《3个月，从+30%到-40%：SDD落地踩坑实录》，https://cloud.tencent.com/developer/article/2728455 。本文在其三个月数据、三级规格、先扩再裁和两次失败原则基础上，补充了团队治理与度量框架。

需要区分：SDD 管理可执行意图；TDD 用测试驱动设计反馈；BDD 用业务可读行为统一协作；DDD 处理复杂领域模型。它们不是互斥缩写，好的 Spec 可以用行为语言表达，并由测试验证，在领域边界内持续演进。

上线前检查五件事：级别是否与风险匹配；Non-goals 是否清楚；每个关键条款是否可验证；变更是否先更新 Spec；两次失败后是否回到上游。能持续回答这五问，SDD 才从写文档变成了工程系统。

┌──────────── SDD 的有效循环 ────────────┐
│ 先扩：穷举边界、异常、依赖             │
│  再裁：人决定价值、风险与非目标         │
│   分级：L1 / L2 / L3 匹配任务复杂度     │
│    执行：Spec → Plan → Tasks → Code     │
│     验证：条款 → 测试 → 指标            │
│      回写：变更和 Bug 先修正 Spec        │
└────────────────────────────────────────┘