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资料还是觉得吃力不妨先放下那些理论找一个你熟悉的小功能试着用规格的方式把它描述清楚。不用管格式对不对、完不完整先写出来。写着写着你就会发现那些之前看不懂的概念突然就有了具体的落脚点。规格驱动开发不是什么高深的东西它就是把“想清楚再动手”这件事用结构化的方式固定下来。想清楚了代码自然就好写了。