程序员这行，最折磨人的往往不是写代码本身，而是“改需求”。需求文档写一套，代码实现一套，最后测试又验证一套，三套逻辑在项目里互相打架。我在团队里抓过无数次这种“三体问题”：产品说我要A，代码里跑的是B，测试用例断言的是C，谁都没错，但合在一起就是灾难。直到我开始用Spec-kit这套基于SDD（规范驱动开发）的工程化工具链，才算是把这三条线真正拧成了一股绳。
SDD这个词最近在圈子里热度上升得很快，核心思路其实特别朴素：把“需求规格”当成软件开发的一等公民，先写规格，再让规格驱动代码生成和测试校验。Spec-kit就是围绕这套理念落地的工程化工具，它不是什么银弹，但绝对是一套能改变团队协作方式的工作流。这篇文章我会从SDD的理念源头讲起，把Spec-kit的设计思路、动手实操、团队落地和踩坑记录一次说清楚，如果你正在被需求变更和文档脱节折磨，或者想让AI更听话地帮你写代码，这篇文章值得看完。
1. SDD从哪里来，为什么偏偏是现在
1.1 从TDD到BDD，再到SDD的演进脉络
要理解SDD，得先看它之前的前辈们解决了什么、又留下了什么。
TDD（测试驱动开发）是老牌方法论了，核心是“先写测试，再写实现”。红-绿-重构这套节奏确实能让代码质量上一个台阶，但它有个天然的盲区：测试只验证“代码做得对不对”，没有办法验证“做的东西是不是用户要的”。你完全可以写出一套测试全绿、但产品经理看了想骂人的功能。
BDD（行为驱动开发）在TDD基础上往前走了一步，用Given-When-Then这种接近自然语言的格式描述行为，让产品、开发、测试能共用一套语言。这个想法很好，但落地的时候经常走样：BDD的feature文件往往在项目启动时写完，然后就躺在Git仓库里吃灰，代码越改越多，feature文件越来越旧，最后没人再愿意维护它。
SDD的站位很有意思，它把BDD里“规格即文档”这个点彻底放大：规格不是给测试当注释用的，它是整个开发流程的输入源。代码从规格生成，测试从规格推导，改动从规格追溯。规格变了，代码和测试跟着变，但反过来，代码怎么改都不该影响规格。这就让规格从“文档”变成了“契约”。
1.2 为什么现在的团队特别需要SDD
说白了，SDD火起来不是偶然，是两个趋势撞在一起的必然结果。
第一个趋势是AI编程的普及。现在团队里用AI辅助写代码已经是常态，但AI有个特性：你描述得越精确，输出越靠谱。如果你给AI的是一段模糊的自然语言需求，它还给你的就是一段“看起来差不多”的代码，而这恰恰是最危险的。SDD强制你先产出结构化的规格，这等于把AI的输入给格式化，输出的稳定性会大幅提升。我实测下来，有了规格作为上下文，AI生成代码的返工率至少降了一半。
第二个趋势是文档和代码脱节的老毛病越来越痛。现在的项目迭代节奏快得离谱，两周一个版本，文档更新永远追不上代码变更。SDD的思路是：不再维护独立的“需求文档”，规格本身就是活文档。团队里任何人想搞清楚某个功能到底怎么定义的，直接看规格文件就行，不用去翻文档库里不知道哪个版本的石器。
1.3 SDD不是银弹，但它是正确的约束
有一点必须提前说清楚：SDD不是万能的，它适合需求逻辑清晰的业务系统，但像算法攻坚、性能优化这种探索型任务，不适合用SDD硬套。SDD的本质是一种约束，它要求你在写代码之前先想清楚“到底要实现什么”，这是好事，但也意味着前期的时间投入会变多。对那种需求天天翻烧饼的项目，SDD同样救不了，因为规格本身也会天天变，但至少变起来比改代码成本低得多，这本身就是价值。
2. Spec-kit的设计拆解：它到底是怎么把SDD落到实处的
2.1 规格即代码：spec文件是怎么组织项目的
我第一次接触Spec-kit的时候，最直观的感受就是它把“信息架构”做得很舒服。整个项目的源头是一个存放规格的目录，规格的编写方式是Markdown加代码块的双重结构，简单说就是“人类可读、机器可执行”。
一个典型的spec文件会拆成两个层次：需求条目和实现细节。需求条目描述的是“用户需要什么能力”，用的是自然语言结合条件判断的语法，比如“作为一个用户，我能够提交RSVP，条件是姓名不能为空”，这种写法，产品经理能读懂，测试工具也能解析。实现细节则更精确，直接写测试断言级别的when/then条目，规定了具体的输入输出行为。
这种双层结构的妙处在于：顶层面向人和业务，底层面向机器和测试。不会出现“产品文档一套、技术文档另一套”的割裂，因为它们在同一个文件里，上层和下层一一对应。
2.2 Disco不是万能的，但它是AI时代最值得关注的生成模式
Spec-kit里有个组件叫Disco，它的定位是“从规格到代码的生成器”。很多朋友第一次听到这个会觉得，这不就是个代码生成器吗？Copilot不也能干这事？区别在姿势上。
Disco用的方式是“spec + 偏好 = 代码”。它会读取整个规格目录，再结合你在disco-prefs.md里声明的技术栈偏好，然后生成一套完整可运行的代码骨架，包括模块结构、函数定义、基础测试和类型签名。你可以反复运行disco命令，每次规格更新后重新生成，它会比对已有的代码结构，尽量做到不覆盖你手工修改过的部分。
这里必须说明，Disco生成的代码不是最终交付物，而是一个“符合规格的初始版本”，它的价值是把“从规格到代码的第一公里”跑完，后续你在这个基础上做二次开发。我个人的经验是，Disco生成代码的完成度大概在六到七成之间，剩下的三成是业务细节和边界条件，需要人工投入。但就算只是省掉那六成的机械劳动，这个工具的价值就已经实打实了。
2.3 测试是流水线的一部分，不是事后的保险
Spec-kit对测试的定位跟传统团队不太一样。传统团队的测试是开发完代码之后再去补的，而在SDD的流程里，测试是从规格推导出来的，它本身就是开发过程的产物。
具体来说，spec文件里的when/then条目可以被工具直接导出成测试用例。开发人员写完一块逻辑，跑一下测试，就知道自己的实现是不是符合规格的预期。这里的关键设计是“测试隔离”：a区测试直接来自规格，b区测试是开发者自定义的单元测试。两者分开存放，跑测试的时候一起执行，但严格来说，a区是规格的守护者，b区才是开发者自由发挥的空间。这个机制保证了规格变更和代码变更互不污染，后面我会细讲。
2.4 Gate机制：合并前那道不可逾越的红线
团队协作中，最怕的事情就是有人悄悄改坏了规格定义的行为，还浑然不知。Spec-kit里有个组件叫Gate，它就是一个“规格守护门禁”，允许你配置一条命令，在CI流程里运行，用来检查spec定义的test数量、覆盖范围、是否被意外跳过。
我把Gate理解成规格的测试。普通测试守护的是“代码符合逻辑”，Gate守护的是“代码没有偏离需求”。两者缺一不可。一般来说，Gate会在PR提交流程中作为必过的检查项，一旦发现规格中定义的测试没有被执行，或者有测试被标记跳过，CI直接失败，醒目地把问题暴露出来。
3. 实战操作：用Spec-kit从零搭建一个带完整规格的项目
3.1 环境准备：需要什么、不需要什么
Inspect kit的项目是Go写的，你只需要安装好Go环境和Node.js环境（前端部分要用），然后通过Go命令就可以很干净地安装Spec-kit。整个工具是单一二进制文件，不像某些脚手架工具那样要拖一卡车依赖。
安装完记得确认两个核心命令可用：一个是disco，负责规格生成代码和测试；一个是gate，负责规格守门。如果用的是最新版本，指令的默认入口就是项目根目录下的specs目录，路径约定很明确，团队协作时不会有歧义。
一个我实测下来的建议：在项目根目录创建规格目录时，一开始就分好业务域和通用能力的子目录。比如demo项目里，可以用invitations目录表示邀请相关的业务域，核心放用户故事和规则，用common目录放全局约定。这样后期规格多了不会乱，Gate检查也能针对子模块独立执行。
3.2 手把手写第一份规格文件：从想法到可执行的“用户故事”
很多人第一次接触规格驱动，不知道规格到底该长什么样。这里用RSVP邀请场景举个最典型的例子。
你可以在invitations目录里新建一个文件，内容是这个业务域的核心需求。最开头是用户故事描述，用三五行自然语言说明背景和核心目标，这部分是给人和AI看的上下文。紧接着是能力清单，一条条列出“系统应该能做什么”。然后是核心的细节规则区，每一段描述后面跟一个when/then代码块：
## RSVP提交规则 当收到一个RSVP请求时： - when 请求中的姓名是空字符串 - then 返回校验错误，错误码为VALIDATION_ERROR - when 请求中的日程编号不存在 - then 返回校验错误，错误码为EVENT_NOT_FOUND - when 请求合法且日程存在 - then 创建RSVP记录，状态为pending，并返回201状态码这里要特别注意一个细节：when/then条目里的内容是“能转换成测试断言的”，所以描述一定要具体到“返回什么状态码”“写入什么字段值”这种粒度，不能出现“合理处理”“适当校验”这种模糊词汇。规格写得越死，测试生成的校验力越强。这是从文档思维切换到契约思维的关键门槛，也是新手最常翻车的地方。
写完这份文件后，建议顺手配置测试命令的注册清单，把规格目录下的每一个业务域都登记成可执行的测试任务。这个动作是在为后面的Gate铺路。
3.3 跑一次Disco，看看代码是怎么“长出来”的
接下来就是见证奇迹的环节：在项目根目录运行规格生成命令。
运行完你会看到，原本空荡荡的目录里多出了一套完整的代码结构：核心逻辑模块是空的也不慌，这是预期的第一步。关键看两个层面的产出：一是接口和类型签名，它们直接对应规格里的能力清单，能保证你的代码结构从一开始就跟规格对齐；二是初步的测试目录，接口的测试文件已经根据when/then条目生成了对应的测试函数，这些测试现在跑是红的，因为实现还没写。
我在实际操作中发现，Disco生成的初始代码很有讲究：它不会一次性生成所有细节，而是把复杂的业务规则留白，只生成主干。比如它会给你的处理器定义好输入输出的类型结构，但内部如何校验姓名为空、如何判断日程不存在，这些逻辑会留出清晰的TODO标记。这其实是合理的，因为规格描述的是契约，而契约背后的业务算法才是开发者该花心思的地方。Disco负责把骨架搭好，你负责把血肉填上。
3.4 补实现、跑测试、过Gate：一个完整的迭代闭环
代码骨架有了，接下来的工作就是填肉。以RSVP为例，实现姓名校验、日程查询、落库逻辑，这些都是常规代码。一边写实现一边跑测试的感觉很特别：因为测试是从规格生成出来的，它的断言就是规格的定义，所以你的代码不是“写出来的”，而是“被规格逼出来的”。
补完核心逻辑，跑一次测试命令，作用域限定在邀请模块的测试任务ID上。正常情况下，测试应该从红变绿，如果哪条是红的，排查方式也很直接，不外乎两种情况：实现写错了，或者规格定义跟实际业务预期不符。前一种去改代码，后一种说明规格本身有问题。
全部测试通过之后，跑一下Gate命令做全局守门。Gate会检查规格中定义的每条规则是否都被对应的测试覆盖到。这一步之所以放在最后，是因为它能帮你找出“想当然以为测了，其实没测”的盲区。我记得第一次跑Gate，就抓到一个被遗漏的规格条目：规格里定义了一条“已删除的日程不能接收RSVP”，但我根本没给这个规则写测试，Gate立刻报警了。这种盲区在传统开发流程里，往往要等到线上出事故才会被发现。
3.5 从demo到真实项目：扩展和维护规格的节奏建议
很多刚接触SDD的团队会陷入一个误区：想一口气把整个业务的所有规格都写完再动工。这完全是反模式。
规格的粒度控制，我在实践中摸索出的原则是“跟着迭代走”。每个迭代开始前，花半天时间把本迭代的需求写成规格，技术方案评审直接评审规格，不再评审方案文档。代码开发阶段，规格就是你的任务清单。迭代结束时，规格加代码加测试，三者一起提交，形成一次完整的产物。这种节奏跑顺之后，团队里再也没人问“上次那个逻辑到底是咋定的”了——去翻规格就行了。
4. 团队落地和CI/CD集成：从个人玩具变成工程标准
4.1 让团队接受SDD：最有效的切入点不是理念，是流程
在团队里推SDD，最难的不是让大家学会写规格，而是改变工作习惯。我发现一个特别有效的切入点：从“代码评审”的变革开始。
过去代码评审看的是什么？看风格、看逻辑、看有没有低级错误。引入SDD之后，我强制要求每个PR必须带对应变更的规格diff。评审者先看规格diff，看这次需求的契约定义变没变，变了是否合理，然后再看代码实现。一旦养成这个习惯，你会发现评审效率大幅提升，因为规格diff比代码diff更容易暴露“你到底想干什么”。
另一个实用技巧是从最容易犯错的需求类型开始试点，比如支付金额计算、权限控制这种规则密集型场景。这种场景下SDD的优势体现得最明显，团队尝到甜头，后面推广阻力就小了。
4.2 在CI流水线里加入规格守护
Gate最大的价值在于集成到自动化流程里。以GitHub Actions为例，你可以在代码推送到远程后触发CI，CI里增加一步Gate检查：检查规格定义的测试是否全部执行，检查规格测试是否有被跳过的风险，如果失败就直接阻断合并。
这里有个细节要注意：Gate和跑的测试任务最好解耦。Gate负责检查“该测的测了没”，test命令负责“测出来的结果对不对”。先跑test，再跑Gate，逻辑上更完满。因为如果测试本身是红的，你去检查覆盖率没有意义，先把错误清掉，再回来谈守门。
4.3 团队协作中的规范约定：先谈命名，再谈分工
SDD能在团队里跑顺，有一批“隐形规则”必须提前定好，否则规格目录会变成第二个垃圾场。
我踩过最大的坑就是规格文件随意命名和随意放置。有人喜欢一个文件塞所有用户故事，有人喜欢把测试和规格分得七零八落。最终我们的约定是：规格目录结构跟业务域一一对应，一个业务域一个目录，一个业务域内的能力清单不超过10条，一旦超过就要考虑拆分子模块。这个约束能强制团队在规格层面做模块化，而不是把什么都堆在一起。
另一个约定是权限分离：产品经理和技术负责人是规格的唯一编辑者，开发人员默认不直接改规格，只能改代码。如果开发发现自己实现不了规格定义的行为，走变更流程，先让规格变更审批通过，然后再改代码。这听起来有点重，但对规范驱动开发来说，这是底线，规格一旦被随意改动，整个链条就崩塌了。
5. 常见问题与排查技巧实录
5.1 规格定义了那么多规则，测试却没生成出来
这是我最常被问到的坑，而且真的很常见。
排查思路很简单：Spec-kit的测试生成依赖when/then代码块可以正确解析。检查代码块的标注格式是否和文档要求的一致，很多新手会在代码块后面加一堆自然语言注释，或者代码块内部格式换行错乱，导致解析器直接跳过了这段规则。这个问题最隐蔽的地方在于，很多工具不会主动报错，它只会“安静地”跳过无法解析的规则。所以写完规格之后，先用检查命令看解析结果，确保所有规则都被注册了，再继续往下走。
5.2 测试变更了代码里面的实现，却把规格也弄乱了
这个问题的根因是没理解SDD里“规格隔离”的设计目标。规格和代码的关系是单向的：规格驱动代码，代码不反向影响规格。你改业务实现的时候，不应该去动规格文件里的when/then条目，除非业务需求本身变了。
如果你发现自己改代码的时候，顺手改了规格，停下来问问自己：“我真的在改需求吗？还是为了让测试过而改契约？”如果是后者，说明你的代码实现偏离了规格方向，要去改代码，不是去“校准”规格。我用一条硬性规则约束团队：规格文件只在需求讨论会上被修改，其他时间禁止动。
5.3 AI生成代码和手动代码混在一起，越改越乱怎么办
这是进入AI辅助开发时代最真实的痛点。Disco生成骨架之后，你在里面手写了很多业务逻辑，下次规格变更时重新运行生成命令，最怕的就是自己写的东西被覆盖。
这类工具的默认行为是保护手工代码的，但保护机制往往依赖注释标记或者代码块边界识别。我的经验是：手写代码务必写在明确的代码块内部，尽量不要在生成代码的注释区里塞自己的逻辑，给后续生成操作留出明确的识别边界。同时，在跑新生成之前，先把当前已通过测试的代码提交一个版本，就算抽风，你也可以随时回滚。
5.4 Gate正常通过，但需求没满足，这事怎么说
Gate检查的是“规格定义的规则有没有对应的测试执行”，它验证不了“需求本身是不是用户想要的”。规格本身可能就写错了，或者遗漏了业务条件。这是SDD实施中一个非常重要的认知边界：SDD保证的是“按规格实现”，不保证“规格就是对的”。
这个问题的解法分两层：第一层，规格评审必须邀请业务方参加，让规格定义在源头上对齐业务预期；第二层，建立规格变更的快速反馈机制，一旦线上发现预期偏差，第一时间反查规格是不是有错误定义，再通过修正规格来驱动代码修正。不要试图让Gate替你做需求分析，这不现实。
6. 写在最后的几点经验
整套Spec-kit和SDD的工作流，我用下来最深的感觉是：它没有提高“写代码”的速度，但它改变了“理解代码”的成本。代码变得次要了，规格成了主角。过去的代码是给人读的，现在是给机器读加给人读的，而通过规格，机器和人都读的是同一份东西。
我建议任何刚开始尝试这个工具的人，不要一上来就追求全流程落地。第一步，个人项目里，先跑一个业务模块的规格闭环，感受规格生成测试、规格驱动实现的节奏；第二步，团队试点，固定一个业务域，把规格审查加进评审流程；第三步，再把Gate挂到CI上，实现全自动化守门。一步一脚印，规格是强约束，约束要一步一步加，不然团队会被流程的陡增束缚直接劝退。
还有一个实用小技巧是，规格文件尽量写在版本控制系统里一个独立的变更流上。业务规格的变更历史独立于代码的变更历史，这样复盘的时候你能清晰地看到：哪些需求变了，对应合同的骨架经历了怎样的演进。这在快速迭代的团队里，是无比珍贵的一手资料。毕竟在软件工程这个行当，最贵的东西从来不是代码，而是“认知的一致性”。
