聊一个最近圈子里越来越热、但真正讲清楚的资料却很少的话题SDDSpecification-Driven Development规范驱动开发。先交代下背景。过去一年AI 辅助编码工具席卷了整个行业“氛围编程”Vibe Coding这个词也随之火了起来——你只需要用自然语言描述需求AI 就能生成一整套代码你“感觉”它差不多能用就提交上线。这种方式在原型验证、个人小工具、快速 Demo 场景下确实爽但一旦业务逻辑复杂、多人协作、系统需要长期维护纯粹靠“氛围”写出来的代码往往会变成一锅粥接口没有稳定契约数据校验靠运气业务规则散落在各个函数里改一个字段要翻遍十几个文件。我自己的感受是AI 把“写代码”的成本拉到了地板但“写对代码”的成本反而更高了。原因很简单代码生成得越快越需要一个明确的标准来判断“对不对”。没有标准快速生成就等于快速制造混乱。SDD 就是这么一套做法先把“做什么、做到什么程度算完成”写清楚写成可执行、可校验的规范再让人或 AI 按规范去实现。它不是新的银弹也不是学院派概念而是把很多成熟实践契约测试、验收测试驱动开发、API 先行、状态机建模收拢成一条清晰的开发主线。这篇文章我会把自己在实际项目里用 SDD 的完整思路、步骤、踩过的坑都摊开讲适合正在被 AI 生成代码质量折磨的团队也适合那些觉得“氛围编程”不对劲、想找回工程秩序感的开发者。1. 为什么“氛围编程”越来越不靠谱了先说个我亲历的场景。上个月帮朋友团队救火他们的项目不大不小一个订单管理系统代码几乎全是 AI 生成。需求变更时开发者就把 Prompt 一改AI 把相关文件重写一遍。当时看起来功能都在但有个隐藏的超级 Bug退款接口在“重复退款”场景下居然能多次扣减库存。为什么因为业务规则“一个订单只能全额退款一次、部分退款累计不可超过订单金额”没有任何地方落成了规范AI 只负责让单个接口看起来正常跨接口、跨状态的一致性它根本管不着。这就是“氛围编程”的核心问题它优化的是“单次的代码生成体验”而不是“系统的长期一致性”。换句话说你让 AI 帮你画一张桌子它会给你一张看起来不错的桌子但如果你没给它桌子的承重标准、尺寸公差、材料等级它今天画的桌子能放花瓶明天改个参数生成的桌子可能放本书就塌了。用装修来类比可能更好懂。氛围编程是“只看效果图施工”SDD 是“先出施工图、再定验收标准、最后动工”。效果图再漂亮没有施工图就无法知道墙里埋的线怎么走、承重墙在哪没有验收标准住进去才发现漏水砸墙重来的成本是双倍的。代码也一样需求文档 AI 生成本质上是“效果图 感觉差不多”一旦出问题排查成本远比一次闭环规范要高。还有一个被很多人忽略的问题团队协作中的“隐性知识”。人跟人沟通需求时习惯说“这里做个幂等处理”“这个状态不能乱跳”但这些约束只存在于某一个人的脑子里或者某一次群聊记录里。氛围编程模式下这些约束几乎不会变成代码层面的防线因为它们太细、太业务化了AI 也猜不到。SDD 的出发点就是把这些隐性知识变成显性的、机器可校验的规范。当然我不是说氛围编程一无是处。探索原型、黑客松、写一次性脚本时它效率极高。但只要是“要活半年以上”“要多人维护”“要承载真实业务资金或用户数据”的系统必须在某个阶段切换到 SDD 的路线上来。2. SDD 到底在解决什么问题很多人一听 SDD 第一个反应是这不就是 TDD测试驱动开发换个新名字还真不是。TDD 的重点是“先写测试、再写实现”测试描述的是代码行为SDD 的重点是“先定规范、再写实现”规范描述的是系统契约范围更大。我习惯把 SDD 的规范拆成三层接口层契约系统内外之间如何交互入参出参长什么样错误怎么返回。对应 OpenAPI、gRPC Proto、TypeScript 类型定义等。数据层契约数据长什么样、允许什么值、状态怎么流转。对应 JSON Schema、Zod schema、数据库约束、状态机定义。行为层契约业务场景下系统应该表现出什么行为尤其是边界情况。对应 GherkinGiven/When/Then验收测试、业务规则清单。这三层契约合在一起回答了一个根本问题“什么叫‘做完了’”没有 SDD你说做完了我说没做完需求方看不懂代码开发之间互相信任全靠眼神。有了 SDD“做完了”的定义就变成了所有规范描述的场景全部通过校验所有契约被实现代码满足。SDD 和很多企业里“写文档”最大的区别是规范必须是可执行的。你写一百页 Word 文档说“退款需要校验订单状态”计算机不理解等于没写但如果你把这条规则写成一条 Gherkin 用例或者一个 JSON Schema 定义再把它接入 CI让每次代码提交都自动跑一遍这条规则才真正成了系统的防线。这正是 SDD 对“文档”和“代码”的调和文档从“给人看的摆设”变成了“人机共读的契约”。还有一个维度是业务侧非常受益的。传统开发流程里业务需求翻译成技术方案的时候会失真技术方案翻译成代码又会失真。SDD 用接近自然语言的规范比如 Gherkin 描述业务场景作为中间层业务方看懂了大半开发又可以直接把它变成自动化验收用例。两层“翻译衰减”被明显压缩这是 SDD 在协作效率上最直接的回报。3. 一套可落地的 SDD 实施路径理论说完了讲点实的。我目前的团队已经用这套流程跑了大半年整体收益非常明显尤其是配合 AI 工具之后需求的交付周期反而比“氛围编程”时代更稳定。整套流程分成五个阶段每个阶段都有明确输入输出。3.1 需求澄清把“氛围”翻译成业务规则SDD 的第一步不是写代码甚至不是写测试而是把需求里的业务规则一条一条地挖出来。这个阶段最忌讳的就是拿着一张产品原型图就开干。原型只表达“界面长什么样”但表达不了“这个按钮在什么条件下可点、点了之后发生什么、发生失败怎么提示”。做法上我强烈建议用业务规则清单这个工具。拿到一个需求先别管界面和接口只回答四个问题这个功能涉及哪些实体订单、用户、退款单实体之间是什么关系每个实体上有哪些业务规则约束条件这些业务规则在每个生命周期阶段分别有什么表现拿退款功能举例业务规则清单可能是R1只有状态为“已支付”的订单可以发起退款。R2退款金额必须大于 0且小于等于订单可退金额。R3一个订单的累计退款金额不可超过订单实付金额。R4退款审批通过后订单状态变更为“已退款”部分退款时订单状态保持“已支付”但可退金额减少。R5退款单创建后 24 小时内未审批系统自动取消。这些规则听起来简单但现实中相当多的系统是没有把它们落成明确清单的。规则缺失的直接后果就是 AI 或初级开发者在写代码时“自由发挥”最常见的 Bug 就是加了 R2 忘了 R3导致累计退款超过实付金额。3.2 定义可执行的规范契约业务规则清单是给人看的接下来一步是把它们翻译成机器能校验的“契约”。这一步的输出物按系统类型不同会有不同侧重但大体上是三件套API 契约推荐用 OpenAPI 3.x 定义所有对外接口。重点是明确请求参数、响应结构、错误码枚举。这一步做扎实了前端、后端、AI 生成代码都能基于同一份契约对齐不会你等我我等你。数据契约推荐用 JSON Schema 或各语言的 Schema 库TypeScript 用 ZodPython 用 Pydantic。它负责在运行时校验数据形状让协约不只是一纸文档。状态机契约这是很多人忽略但极其重要的一块。凡是生命周期复杂的实体订单、工单、审批流先定义状态机和允许的迁移路径再写代码。状态机这块我给个例子。订单状态机定义状态待支付 → 已支付 → 已退款 / 已关闭合法迁移待支付→已支付、待支付→已关闭、已支付→已退款非法迁移待支付→已退款、已关闭→已支付、已退款→已支付这个定义看起来简单但它能一票否决掉大量荒谬的“氛围编程产物”。我在项目里见过 AI 生成的代码里出现“已关闭→已退款”的状态跳转如果状态机契约在 CI 阶段被扫描这种问题在合入前就会被抓住。3.3 将规范转成自动验收测试有了契约第三步是把业务规则变成 Gherkin 场景再把场景变成自动化测试。这部分是 SDD 里“兜底最硬”的一环也是整个流程里投入产出比最高的一环。Gherkin 的好处是“人话 机器可执行”。一条典型的退款用例长这样场景对已支付订单发起部分退款 假如 订单状态为“已支付” 并且 订单实付金额为 100 元 并且 当前可退金额为 100 元 当 用户申请部分退款 30 元 那么 退款申请创建成功 并且 订单当前可退金额变为 70 元 并且 订单状态仍为“已支付” 场景对同一订单重复全额退款 假如 订单状态为“已退款” 并且 当前可退金额为 0 元 当 用户再次申请退款 100 元 那么 退款申请被拒绝 并且 错误码为“ORDER_NOT_REFUNDABLE”这些用例写完之后测试代码只是把它们逐句翻译成 API 调用和响应断言。这个翻译过程现在的 AI 工具已经做得很好真正费脑子的反而是场景设计——什么是正常路径、什么是边界、什么是异常这三类场景必须覆盖全。3.4 让人或 AI 基于规范实现代码规范、契约、测试都齐了才到“写实现”这一步。这一点和传统开发顺序完全是反过来的也是很多开发者不适应的地方我代码一行没写先把测试写了会不会很浪费时间实际跑下来恰恰相反。规范先行会把实现阶段的时间压缩得极其明显。因为规矩都定好了写代码变成了纯粹的“填空”。而且这阶段还有个巨大的红利AI 生成代码的成功率会指数级上升。你不再用模糊的 Prompt 说“帮我写一个退款接口”而是把 OpenAPI 契约 Zod Schema Gherkin 用例一起喂给 AI告诉它“实现这个规范并跑通所有验收测试”。AI 生成的代码会第一次具备“可验证的正确性”而不是“感觉上正确”。在我实测中有规范约束的 AI 生成代码一次通过验收测试的概率几乎翻倍后续修改的返工率也大幅下降。原因很好理解AI 本质上是“概率化地预测代码”你的规范越确定它的预测空间就越窄命中率自然越高。3.5 持续守规范把契约和用例接入 CI最后一步也是很多团队做 SDD 虎头蛇尾的原因——规范没接进自动化流程。你写了 OpenAPI、写了 Zod、写了 20 条 Gherkin结果每次代码提交靠人肉提醒“记得跑一下”那这套规范和不存在没区别。我们团队现在的做法是所有 API 契约文件提交到仓库用 CI 任务做“契约校验”确保实现代码声明的路由、参数、响应结构与契约一致所有 Gherkin 用例通过 Cucumber / CodeceptJS / Pytest-BDD 等框架接入自动化流水线每次 PR 强制跑通Zod / Pydantic 这类 Schema 直接作为运行时校验器和 API 层的数据守卫从源头挡住不合法数据状态机契约用自定义的静态扫描器检查保证领域模型里没有非法迁移路径。这个过程确实要花一点时间搭但只要搭好后面每次提交都会自动告诉你“规范有没有被破坏”。这种反馈循环才是 SDD 保持长期效果的引擎。4. 一个不抽象的真实案例订单退款全流程光讲方法论不给案例就是耍流氓。我拿一个团队真实的“订单退款全流程”重构来拆解你能更清楚地看到 SDD 每一步长什么样以及在 AI 辅助下这套流程能跑多顺。4.1 背景与痛点我们的业务是一个电商小程序订单退款逻辑是历史遗留的“胶水代码”三个接口各自校验一部分逻辑互相重叠又互不完整。最大的事故是有一次并发请求同时打到退款接口同一笔订单被退了两次资金损失不说用户信任也受影响。团队决定重构这一块并且这次强制走 SDD 流程。4.2 规范定义阶段我们产出的东西需求澄清之后我们定义了以下核心规范第一退款单实体的数据结构。用 TypeScript Zod 描述约束每个字段的类型和边界import { z } from zod; export const RefundStatusEnum z.enum([ PENDING, APPROVED, REJECTED, CANCELLED, ]); export const RefundOrderSchema z.object({ refundId: z.string().uuid(), orderId: z.string().uuid(), amount: z.number().positive().multipleOf(0.01), reason: z.string().min(1).max(500), status: RefundStatusEnum, createdAt: z.string().datetime(), reviewedAt: z.string().datetime().nullable(), });第二订单状态机关于退款的合法迁移路径PENDING待支付→ 不允许退款PAID已支付→ 可创建退款单创建后订单可退金额减少PARTIALLY_REFUNDED部分退款→ 可继续创建退款单FULLY_REFUNDED已全额退款→ 不允许再退款第三Gherkin 场景集。退款相关的核心用例我们写了 15 条覆盖正常流程、金额边界、状态边界、重复请求场景超过可退金额的退款被拒绝 假如 订单实付金额为 100 元 并且 当前可退金额为 60 元 当 用户申请退款 61 元 那么 退款申请被拒绝 并且 错误码为“AMOUNT_EXCEEDS_AVAILABLE” 并且 订单当前可退金额仍为 60 元 场景并发重复退款只有一个成功 假如 订单实付金额为 100 元 并且 当前可退金额为 100 元 当 两个并发退款请求同时申请全额退款 100 元 那么 其中一个退款申请成功 并且 另一个退款申请被拒绝 并且 错误码为“BALANCE_INSUFFICIENT”4.3 实现阶段怎么用 AI 提速规范齐了之后我们把这个“三件套”OpenAPI Zod Schema Gherkin直接喂给 AI 编码助手要求它实现一套符合上述规范的退款领域服务。输入里包含状态机的合法/非法迁移表Zod Schema 定义的退款单结构15 条 Gherkin 场景对接口行为的要求数据库层要求用事务保证并发一致性退款金额变动必须加锁。AI 生成的初版代码质量明显比“一句话需求”模式高出一大截。比如“AMOUNT_EXCEEDS_AVAILABLE”的错误分支、并发情况下的事务隔离处理它都考虑到了。原因很简单——规范里写清楚了它不用猜。当然它也不可能一次就全对有两条边界场景跑挂了一条涉及“部分退款后再全额退款”的累计金额校验另一条是状态机里 PARTIALLY_REFUNDED 到 FULLY_REFUNDED 的迁移判定。我们根据 CI 里测试的失败信息把对应 Gherkin 场景补充得更精确然后重新让 AI 修改来回两次就全绿了。4.4 这个案例带来的直接收益重构上线后最直观的数据是退款相关 Bug 工单从之前的平均每周 3 个降到了两个月 0 个。并发场景被事务和状态机双重防线挡住代码评审的时间也大幅缩短——因为评审人不再需要逐行读业务逻辑只需要对照规范检查是否遗漏场景。这个案例还证明了 SDD 和 AI 编程不是对立关系而是互补关系。AI 负责“快”SDD 负责“准”。“快”如果不配上“准”在复杂业务面前等于灾难“准”如果不配上“快”在交付压力面前等于空谈。5. 全套工具链选择与避坑指南工具选型是 SDD 落地里非常容易被低估的一环。规范本身写得好不好一半看方法论另一半看能不能落到合适的工具链上。下面是我的推荐组合以及每个环节的常见坑。5.1 工具链选型从需求到 CI 的闭环业务规则管理轻量场景用 Confluence / Notion 里维护“业务规则清单”重度场景可以用专门的规则管理工具但中小团队我不建议上太重的东西一份维护良好的 Markdown 表格足够。API 契约OpenAPI 3.x Swagger Editor 或直接写 YAML。后端代码生成用 openapi-generatorTypeScript 前端可以用 openapi-typescript 直接生成类型。数据契约TypeScript 生态首选 ZodPython 生态首选 PydanticJava 生态可用 Bean Validation MapStruct。重点是让 Schema 既是运行时校验器又是类型定义源一份定义多处使用。行为契约Gherkin 语言 Cucumber 系列JS 用 cucumber/cucumberJava 用 Cucumber-JVMPython 用 Pytest-BDD。如果团队没接触过 BDD一开始不要贪多挑核心业务流写 10 条左右用例就够了。状态机可以用 XState 这样的可视化状态机库但如果不希望引入额外运行时依赖也可以只定义一份 TypeScript 枚举和迁移表然后用一个几十行的静态扫描函数去校验。CI 集成GitHub Actions / GitLab CI 都行。核心是在流水线里加“契约校验”和“验收测试”两道门跑挂直接阻断合并。这块的优先级比代码覆盖率还要高。5.2 常见工具链陷阱先说一个最常见的坑把 OpenAPI 契约写出来就扔一边。我们接过的项目里有一半以上都有 OpenAPI 文档但代码实现和文档早已脱节。原因是文档和代码没有形成联动。解决的办法一是把 openapi-generator 生成的校验器直接用在路由层保证入参出参严格遵守契约二是 CI 里加一个 contract drift 检测任务检测契约描述与实际路由的差异。第二个坑是Zod Schema 写得太粗。很多人只校验类型不校验业务边界比如金额字段只用z.number()没有.positive()没有限制小数位。这样一来schema 只是“形状守卫”不是“业务守卫”。SDD 强调的规范要包含业务边界所以 Schema 里尽量把枚举、范围、格式都约束到位。第三个坑是状态机没有和数据库约束配合。单纯在应用层做状态迁移校验并发请求仍然可能绕过。我建议数据库中状态字段加 CHECK 约束或者采用带乐观锁的版本号机制让状态迁移在数据库层也有一道防线。规范不能只在内存里生效。第四个坑是行为契约用例“假通过”。不少团队把 Gherkin 用例跑通当成目标但用例本身写得软弱无力断言只检查“接口返回 200”不检查业务结果是否正确。比如退款接口只断言“退款成功”却没有断言订单可退金额确实减少了、退款单状态确实是 APPROVED。这种用例会给团队虚假的安全感比没有用例更危险。5.3 一个加速踩坑排查的小技巧Gherkin 用例如果只靠手写批量生产很慢也容易漏场景。这里有个我用了觉得效率很高的方式让 AI 基于规则清单生成候选场景集开发再逐条审查。先把你整理的业务规则清单喂给 AI让它给出 Gherkin 场景草案然后开发的重点工作从“凭空设计场景”变成“审查和补漏”。这比一次性凭空想 15 条场景轻松太多。但审查环节不能省。AI 生成的场景最大的问题是很平庸——正常路径覆盖得很好异常路径和边界条件往往漏得厉害。我自己的审查清单每个“不能”的规则是否都有对应的拒绝场景每个金额计算的地方有没有“少一分钱”“多一分钱”的边界用例每个状态流转有没有反向非法用例6. 从传统开发切换到 SDD渐进式引入的实用建议最后聊一下怎么把 SDD 引进一个已经跑了好几年的老项目。很多人听完觉得有道理但犹豫的是“我们是一堆遗留代码怎么搞”。确实像“一切从头开始写一份巨细无遗规范”这种搞法在存量项目里几乎不可能落地。但渐进式的做法是存在的而且效果也很明显。6.1 不要在存量系统上搞“一步到位”大爆炸式重构基本是自杀式做法。规范没沉淀清楚代码又改了业务还要继续跑两边同时出问题的时候团队很容易回到看一眼改一下的老路。正确的做法是从某个独立业务模块开始试点沉淀出标准套路再复制到其他模块。选第一个试点模块有讲究。最好满足以下条件业务规则相对清晰订单、支付、退款比“个性化推荐策略”这种模糊领域好做得多边界较清晰依赖相对少方便把规范边界画清楚已经有明显的 Bug 史痛点足够团队才有动力坚持流程。6.2 从“下一个新需求”开始不回头补规范老代码的历史债务不要急着还。我的建议是存量逻辑先冻结从下一个新需求开始走 SDD 流程。新需求来了先写规则清单、契约、验收用例再写实现。如果新需求恰好碰到存量代码的痛点就顺带把那一块逻辑的规范补上并且用新规范写“基线测试”覆盖现有行为。这种“只在新代码里守规矩”的策略能让团队在第一个月内不增加太多额外负担但慢慢地新代码的规范边界会和老代码形成鲜明对比——老代码越看越揪心新代码越看越舒服。等团队对 SDD 有了真实的体感和信心再回头切老模块阻力会小很多。6.3 警惕“规范焦虑”不是所有模块都值得强规范最后要泼一盆冷水SDD 不是万能的也不是所有模块都适合。一些高度探索性的功能比如算法效果还在验证的推荐策略、营销玩法的 A/B 实验公路上的规则还定不明白强行写规范只会把团队拖入“形式主义”规范写得飞快代码实现和规范对不上最后规范被弃置。真正的 SDD 强调的“可执行规范”只有在业务规则已经稳定、可以被明确描述的地方才有高杠杆。另一个不该用强规范的场景是一次性脚本、Demo、黑客松原型。这些场景下氛围编程的效率优势远大于规范带来的确定性收益。我一直跟团队说用 SDD 判断什么不该用 SDD本身就是 SDD 思维的一部分——先把“是否值得规范”这条元规则定下来。停在最后的几句实在话我个人实际用了大半年 SDD 之后最大的变化不是 Bug 率降了多少——虽然它确实降了——而是整个团队的沟通方式变了。以前评审会上大家在讨论“你觉得这代码对不对”现在讨论的是“你能不能举出这个场景对应的 Gherkin 用例”。讨论的锚点从人的感觉变成了白纸黑字、机器可执行的标准。这个转变的价值在团队扩张、人员流动、AI 参与度变高时会越来越凸显出来。最后再分享一个小技巧。如果你今天回去只能做一件事不用铺那么大的摊子就挑最近要改的一个核心模块把里面“当前代码其实是默认成立、但从来没写下来”的业务规则列出来用 Gherkin 写三条最痛的场景再落到测试里。就这三条很可能已经能拦住下一次线上事故了。规范不需要宏大它只需要精确且被遵守。