规范驱动开发实战：用 Spec-kit 让规范成为可执行的工程资产

规范驱动开发（SDD）最近在技术圈讨论度很高，Spec-kit 这个工程化工具也频繁出现在我的信息流里。做后端十几年，我见过太多“文档写一套、代码做一套”的项目，最后文档变成考古资料，代码靠老人传帮带。所以第一次看到 SDD 这个概念被做成可落地的工具时，我花了不少时间折腾 Spec-kit，手头一个用户中心模块正好拿来当试验田。这篇文章把我对 SDD 的理解、Spec-kit 的实操过程、踩过的坑、以及我本人对“规范作为工程资产”这件事的思考都写下来，给同样被代码和文档脱节问题折磨的团队一个参考。

1. SDD 到底是什么？为什么在这个时间点突然火起来

1.1 先写规范，再写实现

SDD 的全称是 Specification-Driven Development，规范驱动开发。它的核心逻辑朴素得不像一个“新方法论”：任何一次业务变更，第一步不是写代码，而是先把“这次需求到底要做什么、边界在哪、数据长什么样、失败怎么处理”这些问题用结构化形式写明白。规范落定之后，后续的代码实现、接口文档、测试用例、数据库模型设计，全部以这份规范为基准展开。

这和传统写需求文档有本质区别。传统需求文档是给人类读的散文，一段话描述一个行为，不同读者会产出不同理解。而 SDD 里的规范是机器可读的结构化资产，一个业务规则对应一条明确条目，字段、类型、约束、状态流转都定义清楚。开发照着规范写代码，测试照着规范写用例，review 也照着规范核对实现，三方有了同一把“尺子”。

我参与过的一个支付模块重构就是典型例子。需求文档两百多页，里面关于“退款”的定义散落在四五个章节，不同开发对“退款后订单状态到底怎么流转”的理解至少有三个版本。代码写出来后，光是对齐这个认知分歧，就开了四次评审会。如果当时把“退款流程”抽成结构化规范，每个状态转移一步一约束，这种分歧根本不会发生。

1.2 为什么传统流程管不住复杂项目

传统瀑布流的问题大家都清楚：需求文档和代码是两套体系，文档不更新，代码必然偏离。到了敏捷开发，虽然原则里写明“可工作的软件优先于详尽的文档”，但落地实践中文档往往更没人写了——冲刺排得满满当当，谁愿意停下来更新那个没人看的 Word 文档？

而这两年 AI 编程助手普及之后，这个问题变得更尖锐。AI 可以一分钟生成几百行代码，效率很高，但如果没有明确的规范约束给到生成上下文，AI 产出的代码在风格、边界处理、错误处理上可能各有各的“理解”。我以前带过的一个项目，三个人用同一个 AI 助手生成代码，两周后代码库里出现了三种不同风格的错误处理方式：有人返回 null，有人抛异常，有人用 Result 对象。代码能跑，但维护成本肉眼可见地飙升。

SDD 在这个时间点火起来，不是因为它是银弹，而是因为它恰好补上了 AI 时代最缺的那块拼图：给 AI 生成行为提供可执行的约束边界。没有规范时，AI 是自由发挥；有规范时，AI 是照着施工图施工。这是效率工具之外的另一层价值。

1.3 SDD 和 TDD、BDD、DDD 的边界在哪里

方法论的边界如果不理清楚，团队落地时会很混乱。我简单画一条线：

• TDD（测试驱动开发）：先写测试，再写实现，关注的是代码行为的自动化验证。它处理的是“实现是否正确”。
• BDD（行为驱动开发）：用 Given/When/Then 句式描述业务行为，关注的是业务场景的完整覆盖。它处理的是“场景是否明确”。
• DDD（领域驱动设计）：聚焦业务建模和领域语言，关注的是系统结构与业务认知的一致性。它处理的是“模型是否准确”。
• SDD（规范驱动开发）：先用结构化语言定义系统的契约和行为约束，再让代码、测试、文档围绕这个契约生成与执行。它处理的是“实现是否遵循约定”。

它们不是互斥关系，更像一条递进链路：DDD 定领域模型，SDD 定行为契约，BDD 定场景描述，TDD 验证行为正确性。Spec-kit 这类工具精准卡位在 SDD 这一段，把规范从“概念”变成“可执行的工程基线”。

2. Spec-kit 解决了什么问题：规范从文档变成可执行资产

2.1 传统规范的痛点：写归写、做归做

做工程这么久，我深知“规范”这个词在多数团队里已经有点变味了。你问任何项目经理，他们都会说“我们有规范文档”，但细看实际情况通常是这样：规范写在 Confluence 上，写完靠大家自觉阅读；代码 review 的时候，没有任何机制自动检查实现是否符合规范条目；接口定义、数据库表结构、测试用例、前端类型定义，各写各的，同步全靠人工在群里吆喝。

最典型的一个痛点是“规范写了等于没写”。我见过某团队的数据字典文档写得非常完整，每个字段都标注了类型、长度、默认值、是否可空。但代码里照样出现 varchar(255) 存手机号、时间用字符串存储的“野生风格操作”，因为没有机制阻止这种偏离，文档变成了装饰品。

2.2 Spec-kit 的定位：把规范变成工作流的一等公民

Spec-kit 解决的核心问题，用一句话概括是：让规范直接参与工程的构建与校验过程，而不是躺在文档系统里当参考。它把规范文件作为整个开发工作流的一份输入，从这份输入里自动生成多种下游产物，同时反过来校验代码变更是否违背规范约束。

我实际用下来的感受是，它改变了开发节奏。以前写一个用户注册接口，流程是“查需求文档 → 问后端这个字段叫啥 → 问前端这个返回结构怎么定 → 写代码 → 联调时发现字段对不上 → 改文档”。用 Spec-kit 之后，流程变成了“改规范 → 自动生成接口定义和字段类型 → 前后端直接消费生成结果 → 写代码 → 自动校验一致”。看起来只是把顺序调整了一下，但实际省下了大量沟通成本，因为你沟通的对象从“人”变成了“规范”。

这种定位上的差异很微妙但很关键。传统工具里规范最多是个参考物，Spec-kit 这类工具则把规范提升为工作流中不可跳过的一环，谁跳过，谁就在 CI 阶段收到报错。

2.3 核心能力拆解：规范解析、双向追踪、变更影响分析

要把“规范驱动开发”这个思路变成工程事实，工具层面离不开三个核心能力，这也是 Spec-kit 内部设计的三个关键模块：

• 规范解析器：读取结构化的规范文件（如 YAML/JSON），转换为内部的规范模型。它要处理字段类型映射、约束解析、模块依赖关系等细节，是整个工具的地基。
• 代码生成器：基于规范模型生成下游产物。我用到的主要是 TypeScript 接口、OpenAPI 文档、Mock 数据、数据库迁移脚本骨架和测试用例骨架。这部分直接决定团队的“上手体感”——生成的东西好不好用，团队就愿不愿意用。
• 双向追踪与校验器：通过规范文件中的元数据标识（比如每个字段的 spec 来源标记）与源码建立映射，实现两个方向的追踪：从规范查实现（这个字段在哪些地方被引用）和从代码查规范（这个类到底对应哪条规范条目）。同时提供check命令，在代码变更时验证实现是否偏离规范。

另外还有一项很有用的能力是变更影响分析。规范文件里任何一处字段定义发生变化，工具能通过追踪关系自动列出受影响的服务、文件、测试用例。这个能力在多人协作时价值极大——以前改一个字段类型，全靠吼“用了这个接口的人都注意一下”，现在直接看工具生成的 impact list 就行。

3. 实操落地：用 Spec-kit 搭建规范驱动的工作流

3.1 环境准备与安装

我以 Node.js 生态为例（Spec-kit 目前对这套生态支持最好）。安装很简单，一个 npm 命令就能搞定。

npm install -g spec-kit

如果不想全局安装，也可以作为项目依赖引入：

npm install --save-dev spec-kit

安装完先确认版本：

spec-kit --version

我本地验证时用的是 1.4.2 版本，不同版本命令可能略有差异，但核心命令接口大同小异。项目根目录下执行初始化命令，工具会自动生成一套标准的工程结构：

spec-kit init

初始化后项目结构大致如下：

project-root/ ├── spec/ │ ├── user.yaml │ └── order.yaml ├── src/ │ ├── generated/ │ └── handlers/ ├── spec-kit.config.json └── package.json

如果你已经有存量项目，不建议直接 init 覆盖现有结构。我当时是手动创建了spec/目录，然后在spec-kit.config.json里配置生成目标的输出路径，这样可以把生成产物指到已有代码的旁边，不影响正在跑的服务。

提示：第一次使用别急着配全所有功能。先把“规范解析 + 接口代码生成”跑通，让团队看到可用的生成结果，再逐步把校验、追踪、CI 门禁这些环节加进来。

3.2 编写第一份可执行规范

Spec-kit 默认支持 YAML 和 JSON 两种规范格式。我更推荐 YAML，原因很简单：JSON 写复杂嵌套结构时，括号和逗号的噪音太大，尤其当你定义了十几个字段、四五个状态流转的契约时，YAML 的缩进层级读起来直观得多。

用注册用户这个业务来演示。在spec/目录下新建user.yaml：

version: 1.0 module: user entities: - name: User description: 系统用户实体 fields: - name: userId type: uuid constraints: [required, immutable] - name: email type: string constraints: [required, unique, email] - name: passwordHash type: string constraints: [required, minLength: 64] - name: status type: enum values: [active, inactive, banned] default: active - name: createdAt type: datetime constraints: [required] contracts: - name: registerUser description: 新用户注册 request: email: { type: string, constraints: [required, email] } password: { type: string, constraints: [required, minLength: 8] } response: userId: { type: uuid } status: { type: enum, values: [active] } errors: - code: EMAIL_EXISTS description: 邮箱已被注册 - code: INVALID_PASSWORD description: 密码不满足安全策略

每个部分都有它的作用。entities定义领域实体，后续生成的数据库迁移、TypeScript interface 都以这里为基础。contracts定义接口契约，包括请求参数、成功响应格式、错误码列表，这是前后端联调的唯一依据。version字段用来追踪规范本身的迭代历史，人员发生变动时，团队能从版本记录里看出业务定义是怎么演变过来的。

第一次写完规范文件后，立刻跑一遍解析验证：

spec-kit validate spec/user.yaml

这个命令只检查语法和结构正确性，比如字段重复定义、类型不在白名单、enum 值缺失等。我当时写完就遇到一个报错：constraints: [required, email]这种写法里把email当成自定义约束，但内建约束名列表里没有这一个，后来发现正确写法是用format: email来声明。这类细节看文档最快，但实际跑一遍记住更牢。

3.3 配置代码生成与自动校验

规范文件写好后，核心配置集中在spec-kit.config.json里。我贴一个典型的配置文件：

{ "specDir": "spec", "generators": { "typescript": { "output": "src/generated/types", "options": { "useEnums": true, "strictNullChecks": true } }, "openapi": { "output": "docs/openapi.json" }, "mock": { "output": "src/generated/mock", "options": { "locale": "zh-CN" } }, "db": { "dialect": "postgresql", "output": "src/generated/migrations" } }, "validation": { "enforceOnCommit": true, "ignorePatterns": ["src/legacy/**"] } }

生成器是 Spec-kit 的灵魂。我实际用得最多的是 typescript 和 openapi 两个。执行生成命令：

spec-kit generate

跑完后，在src/generated/types/user.ts里会看到由规范里User实体生成的 TypeScript 类型定义：

export type UserStatus = 'active' | 'inactive' | 'banned'; export interface User { userId: string; email: string; passwordHash: string; status: UserStatus; createdAt: string; } export interface RegisterUserRequest { email: string; password: string; } export interface RegisterUserResponse { userId: string; status: 'active'; }

这层代码不需要任何人去手写维护，改规范重新生成即可。团队里前后端联调的时候，直接把生成产物作为沟通基础，谁都不许在代码里手改生成的 interface——一旦改了，下次 generate 的时候必然冲突，这是设计上的强制约束。

校验命令同样简单：

spec-kit check

它会扫描src/下的代码，根据文件头部的元数据注释判断这个文件对应哪条规范，然后验证字段引用、类型使用、API 路径是否与规范一致。比如手写代码里出现了User类型不存在的字段，check 就会报错。

3.4 与 CI/CD 集成：让规范成为门禁

如果只在本地跑 check，靠个人自觉，SDD 的约束力就大打折扣。真正让规范从“建议”变成“纪律”的，是把校验动作嵌进 CI 流水线。我在项目的 GitHub Actions 工作流里加了这样一个 job：

name: spec-check on: [push, pull_request] jobs: spec: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm ci - run: npx spec-kit validate --all - run: npx spec-kit generate --check # 检查生成产物是否与规范一致 - run: npx spec-kit check # 检查代码实现是否偏离规范

三个命令分别处理三件事：规范文件本身是否合法、生成的产物是否最新、手写代码是否偏离规范。任何一个不过就直接把 PR 堵在门外。这个设计有个好处，它把“更新规范”和“更新代码”捆绑成一个原子操作——如果你的 PR 里有代码变更而没有对应的规范变更，check 就会提示你缺少规范条目。

本地 Git 钩子也可以加一道快速反馈。我习惯在 pre-commit 阶段只跑spec-kit validate --all，因为 generate 和 check 在 CI 里跑就够，本地跑多了反而打断开发节奏。

3.5 团队协作规范：几条铁律

工具只是底座，团队协作的约定同样重要。我们试行时立了三条规矩：

• 改代码先改规范。任何涉及字段、接口、状态流转的变更，必须先更新 spec 文件，再动手写实现代码。评审时第一看 spec 变更，第二才看代码变更。
• 禁止手改生成产物。所有src/generated/目录下的文件都不允许人工修改，改动只能通过更新规范和重新 generate 完成。违反这个约束的人会收到代码 review 里最不留情面的 comment。
• 每条规范必须有 owner。每个模块的 spec 文件声明一个 owner，变更时 owner 必须在场参与评审。这样避免规范文件变成“人人都能改、人人都没责任”的死文档。

这三条规矩执行了一个多月，最大的变化是：新人接手一个模块时，不再需要追着老员工问“这个字段啥意思”，直接读 spec 文件，配合生成代码看，效率提升非常明显。

4. 常见问题与排错实录

4.1 规范文件写对了但生成不出来

这是我遇到频率最高的一类问题。表现是spec-kit validate通过，但spec-kit generate时某个模块的输出是空的，或者报错说找不到实体。

排查步骤按顺序来：

1. 确认配置文件里的specDir指向的目录与spec/实际路径一致。我遇到过大小写不一致的问题，在 macOS 上开发没感觉，CI 切到 Linux 就出问题。
2. 确认规范文件里module字段与generators下的模块过滤配置不冲突。如果配置了includeModules: ["user"]，而 YAML 里写的是module: users，那结果必然为空。
3. 确认实体定义里至少有一个字段带有required约束。我测试时发现一个场景：如果某个实体所有字段都没有约束，生成器会认为这个实体没有被正确建模，主动跳过并给出警告。

这类问题大多不是工具 bug，而是配置与规范写法之间的隐式约定没对齐。建议遇到空输出时先跑spec-kit debug --generators，它会打印出每个生成器实际读取到哪些实体，定位哪一步断了。

4.2 规范变更后旧代码校验失败

这是 SDD 工作流里最“正确”的一种失败：有人改了规范，但存量代码没跟上。它不意味着出故障了，而是意味着规范与实现之间的漂移被工具抓到了。

处理策略看变更类型。如果是新增字段，代码侧往往是安全兼容的，我会先让团队在代码里补上新字段的默认值处理，再合并规范变更。如果是删除字段或修改类型，属于破坏性变更，分三步走：

1. 在规范里给旧字段标deprecated: true，保留一段时间。
2. 代码侧把对这个字段的引用逐步清掉。
3. 某次迭代过去后，再在规范里彻底移除该字段，同时删除代码里的残留引用。

这套“先标记后删除”的流程和修线上问题时的灰度发布异曲同工，目的是不让规范变更成为一次爆炸性事件。我给团队的建议是：破坏性规范变更要单独发起 PR，不要混在业务代码里，否则单看代码完全看不出这个变更的意图。

4.3 多模块仓库怎么处理依赖顺序

中大型项目里模块之间往往有依赖关系，比如order模块的契约引用了user模块的实体。如果user规范还没解析就跑去生成order，就会报“引用的实体不存在”。

Spec-kit 里的解决方案是显式声明依赖。在order.yaml顶部加一段：

version: 1.0 module: order dependsOn: - user

生成器会自动按拓扑序处理模块，先跑user再跑order。如果模块之间存在循环依赖，工具会直接报错，这是合理的设计——规范层面的循环引用往往意味着领域模型没切干净，该拆解的还是得拆解。

我在一个订单 + 支付 + 退款三个模块的仓库里实测，声明依赖关系后生成时间多了不到两秒，但生成过程从“靠运气”变成了“确定性”，尤其当三个模块互相引用契约时，顺序稳定带来的收益非常大。

4.4 团队不接受 SDD 怎么办

工具好不等于团队愿意用。强制推行 SDD 最常见的反弹是——“写规范的时间不如多写两行代码”。我的处理方式是不争论、先试点。

选一个稳定的业务模块（比如用户中心）作为试点，限定一个月时间，把规范文件、生成代码、校验流程全部配置好。试点期间不开大会，只做一件事：每次需求变更，先改 spec，再改代码。一个月后看两个指标：联调阶段的字段不匹配问题数量、新人上手理解业务的时间。试点模块的数据通常都会明显好于非试点模块，到这一步，团队内部的推动力就自己出现了。

还有一个软性技巧：把“规范变更”和“代码变更”在 PR 模板里绑定。我在 PR 模板里加了一个必填项“本次变更对应的 spec 条目”，填不出来的人说明没有按 SDD 流程操作。这一栏的存在让流程约束变得看得见摸得着。

4.5 与 AI 助手的协作模式

有人担心 SDD 会增加工作量，但配合 AI 编程助手使用时，SDD 反而能显著提升 AI 生成代码的可靠性。我自己常用的模式有两种：

第一种是把规范文件直接作为上下文输入给 AI。用 Cursor 或 Copilot 的时候，spec/user.yaml文件被明确引用后，生成代码时 AI 会参考字段约束和契约定义，生成的代码在结构上与规范保持一致的命中率明显提高。这本质上是在给大模型提供一个“施工图”，让它不要自由发挥。

第二种是把spec-kit check作为 AI 生成代码的自动门禁。AI 生成代码后不直接合并，先跑一遍校验，不通过就让 AI 根据报错信息自行修正。我用这个闭环处理过几个需求，AI 生成的代码从“能跑的版本”变成了“符合契约的版本”，review 成本大幅下降。

注意：AI 生成代码时如果引用了规范文件，请确认引用的是当前最新版本。我遇到过 AI 根据缓存中的旧规范生成代码，导致 check 全挂的情况。建议在大模型对话中每次重新引用或粘贴规范内容，别依赖模型记忆。

5. 我对 Spec-kit 深入使用后的个人心得

5.1 规范即文档：让 Spec 成为团队的单一事实来源

以前团队的知识库有三个地方描述同一个接口：需求文档、接口文档、代码注释。三处描述经常不一致，谁对谁错只能靠猜。Spec-kit 落地后，我强制要求所有下游文档都从规范生成或者以规范为准，手动维护的文档一律作废。这个做法落地后最直观的成果是：团队里关于“某一个字段到底存什么格式”的争执消失了，答案就在 spec 文件里，谁有疑问直接去看。

从“写文档给人看”到“写规范给机器执行”，这是一次思维方式的转换。人看的文档会被忽视，机器执行的规范不会被忽视，因为 CI 会拿着它卡你。这个心智转变，比选哪个工具更重要。

5.2 对 AI 生成代码的质量控制：LLM 时代的护栏

现在 AI 辅助编码已经是大势所趋，但 AI 写出来的代码质量充满不确定性。Spec-kit 的价值在于它给 AI 生成行为提供了一道“护栏”：规范先行约束 + AI 自主生成 + 自动化校验，形成闭环。规范在生成前就限定了字段和类型，校验在生成后拦截不匹配的部分，AI 在反馈中迭代修正。

我实测的感受是，没有护栏时让 AI 写业务代码，大约有五成概率要返工修类型和边界问题；有规范约束后，返工率明显降低，因为大多数类型错误在 check 阶段就被拦住了。作为一个对代码质量有执念的老工程师，这个改进让我对 AI 协作的态度从“警惕”变成了“可控地使用”。

5.3 什么项目适合 SDD、什么项目不适合

SDD 不是银弹，我的判断标准是看项目的稳定性和协作复杂度。

适合上 SDD 的项目：中大型业务系统，多人协作，领域模型相对稳定，需要长期维护，有对外 API 契约。比如电商系统的订单、支付、用户模块，这类模块的生命周期以年计算，规范带来的约束收益会随时间累积越来越大。

不适合上 SDD 的项目：快速原型、探索性项目、一次性脚本。这类项目需求本身就随时在变，规范制定成本大于收益，强制套 SDD 反而拖慢验证速度。

如果你正被“代码和文档脱节”这个问题折磨，我个人建议是：不用急着全面铺开，先挑一个稳定的模块试用 Spec-kit 或同类工具，跑通 规范 — 生成 — 校验 这条最小闭环，再根据团队体感决定是否推广。如果只让我留一条经验，那就是——别把规范当成一个文档任务，要把它当成一个工程资产。规范写清楚之后，代码反而简单了，因为大多数“这个需求到底什么意思”的争论，在写规范的阶段就已经被解决掉了。