1. 为什么SDD让不少程序员读起来像天书
第一次接触SDD这个词，很多人脑子里蹦出来的第一反应是“这不就是写文档吗”。我当初也是这么想的，直到被一个真实项目按在地上摩擦之后，才明白SDD和“写文档”之间差了十万八千里。SDD，全称Specification-Driven Development，规格驱动开发，核心思路是先把“要做什么”用一套结构化、可验证的规格描述清楚，再让代码去满足这套规格。听起来很朴素，但它真正难的地方在于：规格本身要足够精确，精确到机器能校验、人能读懂、后续能追溯。
为什么程序员读SDD相关材料会吃力？我观察下来有三个典型原因。第一，大部分资料一上来就讲形式化方法、讲谓词逻辑、讲契约式设计，把工程问题讲成了数学课，读者还没搞清楚这东西在项目里怎么落地就被劝退了。第二，SDD的实践案例往往来自航空、医疗、金融这类高可靠性领域，离日常写业务代码的场景太远，读者觉得“这跟我没关系”。第三，也是最要命的一点，很多团队把SDD做成了“先写一份没人看的规格文档，然后照旧写代码”，规格和实现两张皮，自然体会不到它的价值。
我写这篇东西的目的很明确：不跟你扯形式化验证的数学基础，也不吹SDD能解决一切问题。我想做的是把SDD拆成程序员能听懂的话，讲清楚它在实际项目里到底怎么用、哪些环节最容易翻车、以及一个普通业务团队要不要碰它。如果你之前看SDD的资料看得云里雾里，或者被“规格驱动”这四个字吓到过，那这篇就是写给你的。我会用大量类比和实际场景，把那些抽象概念翻译成你每天写代码时真正会遇到的东西。
先给一个最直白的类比。把SDD想象成装修房子之前的那份“施工图纸加验收标准”。传统开发模式像是跟装修队说“我要一个温馨的客厅”，然后边做边改，最后效果全凭运气和沟通。SDD则是先把客厅的面积、插座位置、承重墙能不能动、验收时用什么标准量，全部写清楚并双方确认，再动工。规格就是那份图纸加验收标准，代码只是施工过程。问题在于，写这份图纸比砌墙难多了，而且大部分程序员被训练成砌墙高手，没人教过怎么画图纸。
理解了这一点，你就能明白为什么SDD让人吃力：它要求的能力和日常写代码的能力不是同一套。写代码是“构造性”的，你一行行把逻辑搭出来；写规格是“描述性”和“约束性”的，你要先想清楚所有边界、所有非法状态、所有必须满足的条件，再用一种精确的语言表达出来。这两种思维模式之间的切换，才是真正的门槛。
2. 把SDD拆开看：规格到底在描述什么
2.1 规格不是需求文档的换皮
很多人把SDD理解成“把需求文档写得更细一点”，这是个危险的误解。需求文档描述的是“用户想要什么”，用的是自然语言，允许模糊、允许歧义、允许后续补充。规格描述的是“系统必须满足什么约束”，它要求精确、无歧义、可验证。举个具体例子，需求文档可能写“用户登录失败超过五次要锁定账户”。这句话人读没问题，但机器没法直接校验，因为“超过五次”是大于五还是大于等于五？“锁定”是锁定多久？锁定期间正确密码能不能解锁？
规格会把它写成类似这样的东西：给定一个账户，当连续失败尝试次数达到5次时，账户状态必须变为锁定；锁定状态下，即使输入正确凭证，认证结果也必须为失败；锁定状态在最后一次失败尝试后经过30分钟自动解除。你看，同样的业务规则，规格版本把每一个边界都钉死了。这不是吹毛求疵，因为代码实现时这些边界每一个都可能写错，而规格的作用就是让这些边界在写代码之前就被明确下来。
我刚开始接触时觉得这也太啰嗦了，后来在一个支付对账项目里吃了大亏。当时需求写的是“对账差异超过阈值要告警”，我们按“大于阈值”实现了，结果业务方期望的是“大于等于阈值”。上线后一批刚好等于阈值的差异没告警，财务那边炸了锅。如果当初有规格把“达到阈值”明确定义成大于等于，这个坑根本不会存在。这就是SDD最朴素的价值：把自然语言里的模糊地带提前消灭掉。
2.2 规格的三种常见形态
实际项目里，规格不会只有一种样子。我把它分成三类，理解这三类能帮你快速判断手头的场景该用哪种。
第一类是行为规格，描述系统在什么输入下应该产生什么输出。这类最常见，也最接近我们熟悉的单元测试。比如“给定一个空购物车，调用结算接口必须返回错误码CART_EMPTY”。行为规格的好处是它天然可以转成测试用例，写完规格基本等于写完了测试的骨架。
第二类是数据规格，描述数据的结构、约束和不变式。比如“订单金额字段必须为非负数，且精度不超过两位小数”“用户年龄字段取值范围为0到150”。数据规格往往通过类型系统、数据库约束或者校验层来落地。很多bug的根源就是数据规格没定清楚，导致脏数据在系统里到处流窜。
第三类是接口规格，描述模块之间、服务之间的契约。比如“订单服务调用库存服务扣减接口时，必须传入幂等键，且库存服务在收到重复幂等键时必须返回首次调用的结果”。接口规格在微服务架构里尤其重要，因为服务边界处的假设一旦不一致，联调时就是灾难。
这三类规格不是互斥的，一个完整的SDD实践通常会同时涉及。但你不必一上来就全都做，可以从行为规格入手，因为它最直观、最容易看到效果。我个人的经验是，先在一个模块里把行为规格写清楚，让团队尝到“少返工”的甜头，再逐步扩展到数据和接口规格。
2.3 规格和测试的关系：不是替代，是前置
这里要澄清一个高频误解：SDD不是让你用规格替代测试，而是让规格成为测试的来源。传统流程是“写代码，然后想测试用例”，SDD流程是“写规格，规格自动或半自动地生成测试用例，然后写代码让测试通过”。顺序变了，效果差别很大。
为什么顺序这么重要？因为人在写完代码之后写测试，会不自觉地被自己的实现带偏。你实现里怎么写的，测试就怎么测，那些你没想到的边界，测试里也不会有。而先写规格，你是站在“系统应该怎样”的角度思考，不受实现细节干扰。这跟测试驱动开发（TDD）的思路一脉相承，但SDD比TDD更强调规格的完整性和可追溯性，不只是“先写个会失败的测试”。
我自己的做法是，规格用结构化的自然语言加表格写，关键约束用类似断言的形式表达，然后人工或借助工具转成测试用例。这样规格既是沟通工具，又是测试来源，还是一份随代码演进的活文档。代码改了但规格没改，测试就会失败，逼着你去同步更新规格，文档过时的问题自然就缓解了。
3. 一个业务团队落地SDD的真实路径
3.1 选对第一个试点模块
SDD落地失败最常见的原因，是一上来就选了个太大、太核心、太复杂的模块。团队还没掌握写规格的方法，就被庞大的工作量压垮，最后草草收场。我的建议是，第一个试点模块要满足三个条件：业务逻辑相对独立、边界清晰、出错代价可控。
拿一个电商系统举例，别一上来就搞订单主流程，那牵扯太多。可以从“优惠券核销规则”这种相对独立的模块入手。它的输入输出明确，规则虽然多但都是纯逻辑，不依赖外部服务，写规格的难度适中，而且核销错了影响面有限，试错成本低。等团队在这个模块上跑通了“写规格、生成测试、实现、验证”的完整闭环，再往核心模块推广。
我见过一个团队从“用户注册时的密码强度校验”开始做SDD，听起来简单到不值一提，但正是这种简单模块让团队快速建立了信心和手感。他们在这个模块上踩的坑、总结的规格写法，后来直接复用到整个用户中心，效率提升非常明显。
3.2 规格的粒度怎么把握
粒度是SDD实践中最难拿捏的东西。写太粗，规格没有约束力，等于没写；写太细，规格变成伪代码，维护成本高得离谱，而且一旦实现调整规格就得跟着改，失去意义。
我的经验法则是：规格描述“可观察的行为”，不描述“内部实现步骤”。什么叫可观察的行为？就是站在调用方或者测试方的角度，能看到的输入输出和状态变化。比如“调用转账接口后，转出账户余额减少相应金额，转入账户余额增加相应金额，且两条账户流水记录被创建”，这是可观察行为。而“先查转出账户，再查转入账户，然后开启事务，更新两条记录”，这是内部实现步骤，不该写进规格。
为什么这条法则有效？因为可观察行为是稳定的，内部实现是易变的。你今天用关系数据库，明天可能换缓存，但“转账后余额变化”这个行为不会变。规格锚定在稳定层，才能长期有效。我见过有人把规格写得跟代码注释一样细，结果重构一次规格全废，团队从此对SDD深恶痛绝。这个教训值得每个人记住。
3.3 让规格成为团队共识而不是个人负担
SDD要真正发挥作用，规格必须是团队共识的产物，不能是某个人关起门来写完丢给其他人。我推荐的做法是，写规格时拉上产品、开发、测试三方一起过。产品负责确认业务规则没理解错，开发负责确认技术约束没遗漏，测试负责确认可验证性。这个过程本身就是一次高质量的需求澄清，很多歧义在写规格阶段就被消灭了。
有个实操技巧：用“例子映射”的方式写规格。不要一上来就写抽象规则，先让业务方给出几个具体例子，正例反例都要。比如优惠券规则，先给“满100减20，订单99元不能用，100元能用，101元能用”这几个例子，然后从例子里归纳出规则。这样写出来的规格接地气，业务方也能看懂并确认。抽象规则容易吵架，具体例子容易达成一致，这是我从多次需求评审里总结出来的经验。
4. 写规格时最容易翻车的几个地方
4.1 边界条件写成“等等”和“其他情况”
规格里最危险的词就是“等等”“其他情况”“以此类推”。这些词在自然语言里很自然，但在规格里就是定时炸弹。因为“其他情况”到底包含哪些，每个人理解不一样，实现时各写各的，最后对不上。
我踩过的一个坑：规格里写“用户输入非法字符时提示错误，其他情况正常处理”。结果实现时，有人把空字符串归到“非法字符”，有人归到“正常处理”，联调时发现同一个输入两个模块行为不一致。后来我们把“其他情况”全部展开，明确列出空字符串、纯空格、超长字符串、特殊符号各自怎么处理，问题才解决。
写规格时，遇到想写“等等”的地方，强迫自己停下来，把能想到的情况全部列出来。列不出来的，说明你还没想清楚，那就先别写规格，回去把场景想明白。这个习惯能帮你省下大量联调时间。
4.2 把实现细节混进规格
前面提过规格要描述可观察行为，但实际操作时很容易写着写着就滑向实现细节。比如写“查询用户接口”的规格，很容易写成“先查缓存，缓存没有查数据库，数据库没有返回空”。这就是实现细节，它把缓存策略这个易变的东西固化进了规格。
正确的写法是描述行为：“给定一个存在的用户ID，接口返回该用户信息；给定一个不存在的用户ID，接口返回空结果；接口的响应时间在正常负载下不超过200毫秒”。至于用不用缓存、怎么用缓存，那是实现自由。这样写，将来换缓存方案规格不用改，测试也不用改。
判断标准很简单：如果一句话描述的是“系统对外表现成什么样”，那是规格；如果描述的是“系统内部怎么一步步做”，那是实现。写规格时多问自己一句“这句话换个实现方式还成立吗”，不成立就说明写偏了。
4.3 规格写完就锁死，不随需求演进
规格不是刻在石头上的，需求变了规格就得变。但很多团队要么规格写完就不管了，代码改了规格还是老的；要么把规格当成不可更改的圣旨，需求变了也不敢动，导致实现和规格脱节。
健康的状态是：规格和代码同步演进，改代码必须改规格，改规格必须重新验证。这听起来增加了工作量，但实际上它防止了更可怕的后果——规格和实现不一致导致的隐性bug。我见过一个项目，规格文档停留在半年前，新来的同事照着规格理解系统，结果理解的全是过时逻辑，排查问题时被带偏了好几天。
实操上，我建议把规格文件和代码放在同一个仓库里，改代码的PR必须包含规格的相应修改，代码评审时一起看。这样规格不会掉队，新人也有一份可信的参考。工具上不需要多复杂，一个Markdown文件加版本控制就够了，关键是流程上把它当代码一样对待。
5. SDD和AI编程助手怎么配合
5.1 规格是给AI的最好提示词
现在用AI编程助手写代码越来越普遍，但很多人抱怨AI生成的代码“看着对，一跑就错”。根本原因往往是提示词太模糊，AI只能靠猜。而规格天然就是一份高质量的提示词，它把输入输出、边界条件、约束都写清楚了，AI拿着规格生成代码，准确率会高很多。
我实测下来的做法是：先把规格写清楚，然后把规格连同“请根据以下规格实现这个函数，不要添加规格之外的逻辑”一起丢给AI。这样生成的代码基本能直接跑，剩下的就是补测试和微调。相比直接说“帮我写个优惠券核销函数”，效果天差地别。因为后者AI不知道你的业务规则，只能写个通用模板，而前者AI有了明确的约束。
这里有个细节：规格里的边界条件对AI特别有用。AI最怕的就是模糊地带，你告诉它“金额为0时返回错误”，它就不会自作主张处理成正常。所以写规格时把边界写全，不仅对人有用，对AI同样有用。
5.2 用规格校验AI生成的代码
AI生成的代码不能盲信，但校验也需要依据。规格就是最好的校验依据。拿到AI生成的代码后，逐条对照规格检查：每条行为规格是否都有对应实现？每个边界条件是否都处理了？有没有实现规格之外的额外逻辑？这个检查过程比漫无目的地读代码高效得多。
我习惯把规格转成测试用例，然后拿AI生成的代码去跑这些测试。测试通过不代表完全正确，但测试不通过一定有问题。这种方式把“人工审查AI代码”这个痛苦的过程，变成了“跑测试看结果”的机械过程，效率提升非常明显。而且测试用例是规格生成的，覆盖了所有明确约束，比临时想的测试用例全面得多。
5.3 别让AI替你写规格
有一点必须强调：规格最好由人来写，至少由人来主导。原因很简单，规格的核心价值在于“想清楚”，而想清楚这件事AI替不了你。AI可以根据你的描述生成一份看起来很像样的规格，但那份规格里的业务规则是不是真的对、边界是不是真的全，只有人才能判断。
我试过让AI根据需求文档生成规格，结果它把很多模糊的地方用看似合理的假设填上了，表面看很完整，实际上那些假设全是错的。如果直接拿这份规格去实现，等于把错误固化进了代码。所以我的做法是：人先想清楚业务规则，写出规格草稿，可以让AI帮忙检查有没有遗漏、有没有表述不清，但规格的决策权必须留在人手里。
6. 从“读不懂”到“用起来”的心态转变
6.1 接受规格写不完美这件事
很多人读SDD资料吃力，深层原因是追求完美。看到资料里那些严谨到极致的规格示例，觉得自己写的规格差太远，于是要么不敢开始，要么写了又推翻。我的建议是：接受第一版规格一定不完美，先写出来，在用的过程中迭代。
规格的价值不在于一次写对，而在于它提供了一个可以讨论、可以修正的载体。你写的第一版规格可能有遗漏、有歧义，但把它拿给团队看，大家一讨论，问题就暴露出来了。这比在脑子里空想强一万倍。我自己的第一份规格现在回头看惨不忍睹，但正是那份惨不忍睹的规格让我和团队开始认真思考边界问题，后面的规格才越写越好。
6.2 把SDD当成沟通工具而不是考核指标
有些团队推行SDD时，把它变成了考核指标，要求每个人必须写多少条规格、规格覆盖率必须达到多少。这种做法往往适得其反，大家为了完成指标而写规格，写出来的规格没人看、没人用，纯粹是负担。
SDD的本质是沟通工具，它帮助产品、开发、测试在动手之前对齐认知。衡量它有没有用好，标准不是写了多少条，而是“因为规格而避免的返工有多少”“联调时因为理解不一致产生的bug减少了多少”。把注意力放在实际效果上，而不是形式指标上，SDD才能真正落地。我见过最成功的SDD实践，规格文件朴素得不行，但团队每次需求评审都围着它讨论，改代码必改规格，这就够了。
6.3 小步快跑，别搞大跃进
最后一点，也是我最想强调的：SDD落地要小步快跑。别想着一次性把整个项目的规格都补上，那是不现实的。选一个小模块，写几条规格，跑通闭环，看到效果，再扩大范围。这个过程可能需要几周甚至几个月，但每一步都是扎实的。
我见过太多团队雄心勃勃地启动SDD，制定了宏大的规格编写计划，结果两周后就没人提了。反而是那些从一个小功能开始、慢慢积累经验的团队，半年后回头看，规格已经覆盖了核心模块，而且团队已经形成了写规格的习惯。慢就是快，这句话在SDD落地上特别成立。
如果你现在读SDD资料还是觉得吃力，不妨先放下那些理论，找一个你熟悉的小功能，试着用规格的方式把它描述清楚。不用管格式对不对、完不完整，先写出来。写着写着你就会发现，那些之前看不懂的概念，突然就有了具体的落脚点。规格驱动开发不是什么高深的东西，它就是把“想清楚再动手”这件事，用结构化的方式固定下来。想清楚了，代码自然就好写了。
