规范驱动开发Spec-Driven Development简称 SDD这两年被提得越来越多但真正把它落到工程实践里的团队并不多。大部分情况是规范写了一份又一份最后躺在 Confluence 里吃灰代码该乱还是乱。Spec-kit 这个工具想解决的就是这个断层——它把规范从文档变成了可执行、可校验、可追溯的工程资产。我最近花了两周时间把它从零跑通中间踩了不少坑也摸清了一些门道。这篇就把整个实践过程拆开讲从它到底解决什么问题到 CLI 怎么装、规范怎么组织、怎么和现有工作流接上尽量说透。1. 先搞清楚 Spec-kit 到底在解决什么断层1.1 规范文档和代码之间的翻译损耗做过中大型项目的人都有体会需求评审时大家点头规范文档写得漂漂亮亮但到了编码阶段规范就变成了参考材料。开发看着文档写代码测试看着文档写用例运维看着文档配环境三拨人理解出来的东西经常对不上。问题不在于谁不认真而在于规范是自然语言写的、静态的、和代码分离的它没有强制约束力。Spec-kit 的核心思路是把规范变成结构化的、机器可读的、和代码同源管理的东西。它定义了一套规范的组织格式和校验规则让规范不再是给人看的散文而是给工具链消费的结构化数据。这样一来规范里的字段、约束、接口定义可以直接被校验、被生成、被追踪。翻译损耗就降下来了。我举个具体的例子。以前我们写接口规范就是一段文字描述用户登录接口接收用户名和密码返回 token。Spec-kit 里你得把它拆成结构化的字段输入参数的类型、必填性、约束输出的结构错误码的枚举。拆的过程本身就是一次强制澄清——很多模糊地带在这个阶段就暴露了。1.2 SDD 和传统 TDD、DDD 的区别在哪很多人第一次听到 SDD 会问这跟 TDD测试驱动开发、DDD领域驱动开发有什么区别我的理解是这样TDD驱动的是实现细节你先写测试测试定义了函数级别的行为。DDD驱动的是领域模型你先把业务概念和边界划清楚。SDD驱动的是规范契约它处在比 TDD 更上游、比 DDD 更偏工程落地的位置。三者不冲突反而可以叠加。Spec-kit 的定位就是给 SDD 提供工程化支撑——它不替代你的测试框架也不替代你的领域建模它管的是规范怎么被结构化地表达、校验和追踪。1.3 什么样的团队适合上 Spec-kit不是所有项目都值得引入。我的判断标准是三条接口/契约多且变更频繁比如微服务架构服务间接口几十上百个改一个字段牵一发动全身。多人协作、跨团队对接前后端、上下游团队之间靠规范对齐口头沟通成本高。有合规或审计要求需要证明代码确实按规范实现了规范变更要有迹可循。如果是一个人写的小工具或者需求极其稳定的老系统上 Spec-kit 的收益不明显反而增加维护负担。这一点要想清楚再动手。2. 把 Spec-kit 的 CLI 装起来并跑通第一条规范2.1 环境准备里最容易被忽略的两个前提Spec-kit 的 CLI 本身不复杂但它对运行环境有两个隐性要求我第一次装的时候就在这卡了半天。第一个是Node.js 版本。Spec-kit CLI 依赖较新的运行时特性Node 16 以下会报奇怪的模块解析错误。建议直接上 Node 18 LTS 或 20 LTS。用node -v确认一下别想当然。第二个是包管理器的锁文件一致性。如果你团队里有人用 npm、有人用 pnpm装出来的依赖树可能不一致导致 CLI 行为诡异。我的做法是统一用 pnpm并在项目根目录锁定packageManager字段。# 确认 Node 版本 node -v # 期望输出 v18.x 或 v20.x # 全局安装 spec-kit CLI以 npm 为例 npm install -g spec-kit-cli # 验证安装 spec-kit --version注意如果你所在的环境对全局安装有限制可以用npx spec-kit-cli的方式临时调用但长期用还是建议本地 devDependency 安装版本可控。2.2 初始化项目时那几个交互式问题的正确答法第一次跑spec-kit init会弹出一串交互式问题很多人随手回车就过了结果目录结构不合心意后面改起来麻烦。我把关键几项说一下规范根目录默认是specs/我建议保持默认。因为 Spec-kit 的很多内置命令默认去这个路径找规范改了要额外配置。规范格式版本选最新的稳定版别选 beta。beta 版的 schema 可能和 CLI 不匹配。是否启用严格模式新手建议先关掉。严格模式会对字段命名、必填项做更严的校验初期规范还没成型时会被卡得很难受。等规范稳定了再开。# 初始化按提示回答 spec-kit init # 初始化后的典型目录结构 # specs/ # ├── schema/ # 规范的结构定义 # ├── contracts/ # 具体的接口/契约规范 # └── config.yaml # 项目级配置2.3 写第一条规范从能跑到跑对初始化完先别急着写复杂的。我建议拿一个最简单的接口练手比如一个健康检查接口。目的是把写规范 → 校验 → 生成产物这条链路先跑通。# specs/contracts/health-check.yaml name: health-check version: 1.0.0 description: 服务健康检查接口 request: method: GET path: /health response: status: 200 body: type: object properties: status: type: string enum: [ok, degraded, down] timestamp: type: integer写完跑校验spec-kit validate specs/contracts/health-check.yaml如果输出PASS说明链路通了。这一步看着简单但它验证了三件事CLI 能正常解析、schema 定义能被加载、你的规范格式符合预期。很多人跳过这步直接写复杂规范出错时根本不知道是环境问题还是规范问题。3. 规范的组织方式决定了这个工具好不好用3.1 按领域切还是按服务切一个影响长期维护的选择规范文件怎么组织是 Spec-kit 实践里最容易被低估的决策。我见过两种主流做法按领域切把规范按业务领域分组比如specs/contracts/user/、specs/contracts/order/。适合领域边界清晰的团队DDD 实践者会喜欢。按服务切按微服务或部署单元分组比如specs/contracts/user-service/、specs/contracts/order-service/。适合服务拆分明确的架构。我的经验是如果团队已经在做领域建模按领域切如果服务边界比领域边界更稳定按服务切。最怕的是两套混着来最后规范散落在各处找都找不到。组织方式适用场景优点风险按领域领域边界清晰、DDD 实践业务语义集中服务拆分变动时需重组按服务微服务架构、部署单元稳定和代码仓库对应跨服务契约归属模糊混合大型复杂系统灵活容易失控需强约定3.2 规范之间的引用和复用怎么处理真实项目里规范之间是有依赖的。比如订单服务的规范里引用了用户服务的用户 ID 类型定义。Spec-kit 支持通过$ref做引用但这里有个坑跨文件引用的路径解析规则。# specs/contracts/order/create-order.yaml request: body: properties: userId: $ref: ../user/types.yaml#/definitions/UserId这个$ref的路径是相对于当前文件的。我第一次写的时候用了绝对路径校验直接报错。记住相对路径且要算清楚层级。另外复用的粒度要控制。我建议只复用类型定义和枚举不要复用整个接口规范。接口规范一旦被复用改一处影响一片反而失去了规范化的意义。3.3 版本管理规范也要有语义化版本规范是会变的。Spec-kit 支持给规范打版本号我强烈建议用语义化版本SemVer主版本不兼容的变更比如删字段、改类型。次版本向后兼容的新增比如加可选字段。修订号文档修正、注释补充。# 给规范打版本标签 spec-kit version specs/contracts/health-check.yaml --bump minor这个版本号不只是个标记它会被下游的代码生成、契约测试消费。版本管理做得好上下游对接时我用的是哪个版本的规范这个问题就再也不会扯皮了。4. 把 Spec-kit 接进现有工作流的关键动作4.1 和 CI 的集成让规范校验成为门禁规范如果只在本地校验那和写文档没区别。真正的价值在于把它变成 CI 的门禁——规范不过代码合不进去。# .github/workflows/spec-check.yml 示例 name: Spec Validation on: pull_request: paths: - specs/** jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install -g spec-kit-cli - run: spec-kit validate specs/ --recursive这里有个细节--recursive参数会递归校验整个 specs 目录。如果你的规范文件多校验时间会变长可以考虑只校验变更的文件。但初期我建议全量校验确保没有历史遗留问题。提示CI 里校验失败时Spec-kit 会输出具体的错误位置和原因。把这个输出直接贴到 PR 评论里能省很多沟通成本。4.2 从规范生成代码骨架省的是重复劳动Spec-kit 支持从规范生成代码骨架。这个功能争议挺大——有人觉得生成的代码质量不行有人觉得省事。我的看法是生成骨架可以但别指望生成业务逻辑。# 从规范生成 TypeScript 类型定义 spec-kit generate specs/contracts/health-check.yaml --target typescript --output ./src/types生成的类型定义可以直接用省去手写 interface 的功夫。但接口的实现、业务逻辑还是得人来写。把生成产物当成起点而不是终点心态就对了。4.3 契约测试让规范和实现真正对齐这是 Spec-kit 最有价值的一环。规范写好了代码也写了怎么保证代码真的按规范实现了答案是契约测试。Spec-kit 可以基于规范生成契约测试的用例框架你只需要填充具体的断言逻辑。这样规范和实现之间就有了自动化的对齐检查。# 生成契约测试骨架 spec-kit test:generate specs/contracts/health-check.yaml --framework jest --output ./tests/contracts生成的测试会检查接口路径对不对、请求方法对不对、响应结构符不符合规范。这些检查看着基础但恰恰是最容易在迭代中被破坏的地方。5. 实操中踩过的坑和对应的解法5.1 schema 校验报错但看不出哪里错这是最常见的坑。Spec-kit 的 schema 校验报错信息有时候比较笼统只说不符合 schema不告诉你具体哪个字段。我的排查套路是先用--verbose参数跑一遍看详细输出。如果还看不出来把规范文件拆小逐个字段注释掉二分定位。对照specs/schema/下的 schema 定义逐字段核对类型和必填性。spec-kit validate specs/contracts/xxx.yaml --verbose实测下来80% 的报错是类型不匹配比如该写 integer 写成了 string和必填字段缺失。养成写完规范先本地校验的习惯能省很多 CI 上的来回。5.2 跨文件引用路径在 CI 上失效本地校验通过CI 上却报引用找不到。这个问题我遇到过两次根因都是大小写敏感。本地 macOS 文件系统默认大小写不敏感CI 上的 Linux 环境大小写敏感。../User/types.yaml和../user/types.yaml在本地都能找到CI 上就挂了。解法很简单统一用小写路径且和实际文件名严格一致。团队里最好约定一个命名规范比如所有目录和文件名都用 kebab-case。5.3 规范变更后下游产物没同步规范改了但生成的类型定义、契约测试没更新导致代码和规范脱节。这个问题的本质是缺少自动化触发。我的做法是在 CI 里加一步规范变更时自动重新生成产物并检查是否有 diff。有 diff 就说明有人改了规范但没更新产物直接 fail。# 重新生成并检查 diff spec-kit generate specs/ --recursive --output ./src/types git diff --exit-code ./src/types || (echo 产物未同步请重新生成 exit 1)这个检查加上之后规范脱节的问题基本绝迹了。5.4 团队协作时的规范冲突多人同时改规范合并时冲突。YAML 的冲突比代码冲突更难解因为格式敏感。我的建议是规范文件按领域/服务拆分得足够细减少同一文件的并发修改。规范变更走 PR 评审和代码一样对待。用统一的格式化工具比如 prettier 的 YAML 插件保证格式一致减少无意义的 diff。6. 关于 Spec-kit 和 SDD 的一些个人判断用了这段时间我对 Spec-kit 的定位有了更清晰的认识。它不是银弹不会自动让你的项目变规范。它的价值在于把规范这件事从靠自觉变成靠工具链。规范写得好不好还是取决于团队对业务的理解深度。我个人的体会是Spec-kit 最适合那些已经意识到规范重要、但苦于规范落不了地的团队。如果你连规范都还没开始写先别上工具先把规范写起来。工具是放大器它放大的是你已有的实践而不是替你建立实践。另外SDD 这套方法论本身还在演进Spec-kit 作为工程化工具也在快速迭代。我的建议是小范围试点别一上来就全团队推。选一个接口多、变更频繁的模块先跑跑通了、团队认可了再逐步铺开。踩坑的成本在小范围里可控收益也能快速验证。最后分享一个我踩过的坑别把 Spec-kit 的规范当成额外的工作。如果团队觉得写规范是负担那这套东西一定推不动。正确的姿势是把它当成减少返工的工具——前期多花半小时把规范写清楚后期少花两天扯皮接口对不上。这个账算明白了推行就顺了。