Spec-kit 规范驱动开发实战：从文档脱节到 CI 自动校验

1. 为什么我们需要重新审视“规范”这件事第一次接触 Spec-kit 是在一个多人协作的后端项目里。当时团队有五个人接口文档散落在三个不同的地方有人写在 Notion 里有人直接写在代码注释里还有人靠口头同步。结果就是联调阶段每天都在吵架——前端说后端返回的字段和文档不一致后端说前端根本没按约定传参。那段时间我最大的感受是代码可以重构但“规范”一旦失控整个团队的沟通成本会指数级上升。Spec-kit 这个工具本质上就是冲着这个问题来的。它属于SDDSpecification-Driven Development规范驱动开发这一方法论下的工程化落地工具形态是一个 CLI。你可以把它理解成“把项目规范从散落的文档里抽出来变成可执行、可校验、可版本化的工程资产”。它解决的问题很具体规范写在哪里、谁来维护、怎么保证代码和规范不脱节、怎么在 CI 里自动拦截违规。这篇文章适合三类人看一是正在被“文档和代码两张皮”折磨的团队技术负责人二是想在自己项目里引入 SDD 但不知道从哪下手的独立开发者三是已经在用各类 CLI 工具比如 codex cli、claude cli 这类做 AI 辅助开发想让 AI 产出更可控的工程师。我会把 Spec-kit 的设计思路、核心机制、实操流程、踩坑经验全部摊开讲尽量做到你看完就能在自己项目里跑起来。需要先说明一点Spec-kit 目前生态还在快速演进不同版本的行为可能有差异。我下面讲的内容基于我实际使用过的版本和常见实践如果你拿到的版本对不上以官方仓库的 README 为准但思路是通用的。2. Spec-kit 的整体设计与思路拆解2.1 它到底把“规范”放在了什么位置传统开发流程里规范是“人读的文档”代码是“机器执行的文本”两者之间靠人的自觉来维系。Spec-kit 的核心思路是把规范变成“机器也能读的结构化文件”然后围绕这个文件构建一整套工具链。这个结构化文件通常以 YAML 或类似声明式格式存在描述的是接口契约、字段约束、命名规则、目录结构约定这些东西。为什么选声明式而不是自然语言因为自然语言没法自动校验。你写“用户名字段必填”CI 没法判断代码里到底有没有做非空校验但你写required: true加上类型约束工具就能扫描代码、比对差异、直接报错。这就是 SDD 和“写文档”最本质的区别——规范要能被程序消费。Spec-kit 在这个体系里扮演的是“执行者”和“协调者”的角色。它不负责定义规范长什么样那是你团队的事它负责的是读取规范、解析规范、把规范投射到代码检查、生成报告、在流水线里卡口。这种职责划分很关键因为它意味着 Spec-kit 可以适配不同团队的规范风格而不是强迫所有人用同一套模板。2.2 为什么做成 CLI 而不是 IDE 插件或 Web 服务我一开始也疑惑为什么不做成 IDE 插件实时提示不是更爽后来想明白了CLI 是唯一能同时覆盖本地开发和 CI 流水线的形态。IDE 插件只能在编辑器里生效Web 服务需要额外部署和维护而 CLI 可以在开发者本地跑、可以在 Git hook 里跑、可以在 CI runner 里跑一套逻辑三处复用。而且 CLI 天然适合和现有工具链组合。你可以把 Spec-kit 的输出接到 codex cli 或 claude cli 这类 AI 辅助工具里让 AI 基于规范生成代码也可以把它的检查结果喂给通知系统。这种“可组合性”是 IDE 插件给不了的。我在实际项目里就是把 Spec-kit 的校验结果作为 AI 生成代码的前置输入效果比让 AI 自由发挥好太多。2.3 规范驱动开发和测试驱动开发的关系很多人会把 SDD 和 TDD 混为一谈其实两者关注点不同。TDD 关注的是“行为正确性”先写测试再写实现SDD 关注的是“契约一致性”先定规范再写代码。两者可以叠加规范定义接口长什么样测试验证接口行为对不对。Spec-kit 更偏 SDD 这一侧。它不替代单元测试但它能在测试之前就拦住一批低级错误比如字段名拼错、类型不匹配、必填项缺失。我在项目里的实践是Spec-kit 跑在 pre-commit 阶段测试跑在 CI 阶段两层过滤返工率明显下降。2.4 方案选型背后的取舍Spec-kit 选择“规范文件独立于代码”而不是“规范内嵌在代码注释里”这个取舍值得说一下。内嵌注释的好处是离代码近不容易脱节坏处是跨文件、跨模块的全局约束很难表达而且注释格式五花八门解析成本高。独立规范文件的好处是全局视角清晰、格式统一、易于版本管理坏处是有脱节风险。Spec-kit 用“自动校验”来对冲这个风险——只要 CI 里强制跑校验脱节就会立刻暴露。这个设计逻辑和“基础设施即代码”是一个路子把隐式约定显式化然后用工具保证显式约定不被违反。3. 核心机制解析与关键细节3.1 规范文件的结构长什么样Spec-kit 消费的规范文件通常包含几个层次全局配置、模块定义、接口契约、字段约束。我用一个简化例子说明实际项目会更复杂project: name: user-service version: 1.2.0 modules: - name: user path: src/user interfaces: - name: getUser method: GET path: /api/user/{id} params: - name: id type: string required: true response: - name: username type: string required: true - name: age type: integer required: false这个结构的关键在于每个字段都有类型和必填标记接口有明确的路径和方法。Spec-kit 解析这个文件后就能对照代码做检查。比如代码里getUser返回的username如果可能为 null而规范里写了required: true就会报不一致。注意规范文件的字段命名要和代码里的实际命名保持一致否则校验会大量误报。我建议在项目初期就定好命名映射规则比如规范里用 camelCase代码里如果用 snake_case就要在配置里声明转换规则。3.2 校验是怎么做到的Spec-kit 的校验分两类静态结构校验和动态行为校验。静态结构校验是扫描代码文件提取接口定义、字段声明和规范文件比对。动态行为校验是跑实际请求看返回结果是否符合规范。静态校验的实现方式通常是 AST 解析或者正则匹配。AST 解析更准确但依赖语言生态正则匹配更通用但容易误判。Spec-kit 一般会提供多种解析器你根据项目语言选。我在 Node.js 项目里用的是基于 TypeScript 编译器的解析器准确率很高在一个 Python 老项目里用的是正则方案需要手动排除一些误报。动态校验需要项目能跑起来通常放在集成测试阶段。Spec-kit 会发请求、拿响应、对照规范检查字段类型和必填项。这个环节能抓到静态检查抓不到的问题比如运行时类型转换导致的偏差。3.3 和 AI 辅助工具的配合方式现在很多人用 codex cli 或 claude cli 做代码生成Spec-kit 在这里能发挥很大作用。具体做法是把规范文件作为 AI 的输入上下文让 AI 基于规范生成代码生成后再用 Spec-kit 校验。这样 AI 的产出就有了明确的约束边界不会天马行空。我实测下来加了规范约束后AI 生成代码的返工率能降一半以上。因为 AI 最怕的就是“需求模糊”而规范文件恰好把模糊地带消除了。你可以把规范文件的内容直接拼进 prompt也可以让 Spec-kit 生成一个精简版的“约束摘要”喂给 AI后者 token 消耗更少。3.4 版本管理和变更追踪规范文件是要进版本库的这点很重要。每次规范变更都应该有对应的 commit这样出问题时可以追溯“是哪次规范变更导致了这次不一致”。Spec-kit 通常会提供 diff 功能对比当前代码和规范的差异输出变更报告。我在项目里定了个规矩规范文件的修改必须单独提 PR不能和业务代码混在一起。这样 review 的时候能清楚看到规范变了什么也方便回滚。这个习惯看起来麻烦但真出问题时能省大量排查时间。4. 实操流程与核心环节实现4.1 安装与初始化Spec-kit 的安装方式取决于它的分发渠道常见的是通过包管理器安装。以 npm 生态为例大致流程是npm install -g spec-kit spec-kit initinit命令会在项目根目录生成一个规范文件模板和配置文件。模板里有一些示例内容你需要根据项目实际情况修改。配置文件里通常包含解析器选择、检查规则开关、忽略路径等。提示初始化后先别急着写完整规范先跑一次spec-kit check看看默认配置下的输出。这样你能了解工具的报错风格再决定哪些规则要开、哪些要关。如果你用的是其他语言生态安装命令可能是pip install spec-kit或go install具体看官方文档。安装完成后建议先验证版本spec-kit --version这一步能确认工具装对了也能避免后面因为版本差异导致的困惑。4.2 编写第一版规范文件第一版规范不要追求大而全先把核心接口和关键字段写进去。我的经验是从最容易被违反的约定开始写。比如团队经常搞错的字段命名、经常漏掉的必填校验、经常不一致的返回结构。写规范文件时要注意几点一是字段类型要写清楚string、integer、boolean、array、object 这些基本类型要明确二是必填和可选要区分不要所有字段都写 required三是嵌套结构要展开不要用“详见文档”这种偷懒写法因为工具解析不了。写完第一版后跑一次校验看看报错数量。如果报错太多说明规范定得太严或者代码确实问题多这时候要分批次修不要一次性全改容易引入新问题。4.3 接入本地开发流程本地开发阶段最有效的接入方式是 Git hook。在 pre-commit 里跑 Spec-kit 校验不通过就不让提交。这样能把问题拦在本地不会污染远程仓库。配置方式是在.git/hooks/pre-commit里加一行#!/bin/sh spec-kit check --staged--staged参数表示只检查暂存区的文件速度更快。如果项目大、全量检查慢这个参数很关键。我试过全量检查要几十秒只查暂存区就一两秒体验差别很大。注意Git hook 不会自动同步到团队其他成员每个人都要手动配置。如果团队人多建议用 husky 这类工具统一管理 hook避免有人漏配。4.4 接入 CI 流水线CI 阶段是 Spec-kit 发挥最大价值的地方。在流水线里加一个校验步骤不通过就阻断合并。这样能保证主分支的代码始终和规范一致。以常见的 CI 配置为例大致是这样steps: - name: Install dependencies run: npm install - name: Spec validation run: spec-kit check --all --format json spec-report.json - name: Upload report run: upload-artifact spec-report.json--format json让输出变成结构化数据方便后续处理。你可以把报告上传成 artifact也可以解析后发通知。我在项目里是把报告解析后把违规项按模块分组发给对应的负责人这样责任清晰。4.5 和 AI 工具联动的实操如果你在用 codex cli 或 claude cli可以这样联动先用 Spec-kit 生成一份“约束摘要”再把摘要和需求一起喂给 AI。约束摘要的生成命令大致是spec-kit export --format prompt constraints.txt这个文件里包含了当前项目的核心规范约束token 量比完整规范文件小很多。把它作为 AI 的 system prompt 或上下文AI 生成代码时就会自觉遵守这些约束。我实测的流程是需求描述 约束摘要 → AI 生成代码 → Spec-kit 校验 → 不通过则把报错喂回 AI 让它修 → 再校验。这个循环跑两三轮基本就能得到符合规范的代码。比人工写快比纯 AI 生成可控。4.6 参数计算与规则调优Spec-kit 的检查规则通常有严格程度分级。太松了没效果太严了误报多。我建议的做法是先全开跑一遍统计每类规则的报错数量然后按“报错多且修复成本低”的优先级逐步收紧。比如“字段命名不一致”这类规则报错多但修复简单可以优先开“返回类型不匹配”这类规则报错少但修复复杂可以放后面。这个调优过程要结合项目实际情况没有万能配置。另外忽略规则要慎用。有些团队为了快速通过校验大量加 ignore结果规范形同虚设。我的原则是ignore 必须写清楚原因和负责人定期 review能修的就修掉。5. 常见问题与排查技巧实录5.1 校验报错太多怎么办这是新手最常见的问题。第一次跑校验报几百个错直接劝退。我的处理方式是分三步第一步先看报错分类统计每类有多少第二步挑一类影响最大、修复最简单的先修第三步修完后把这类规则设为强制其他规则暂时设为警告。这样分批推进既能快速看到效果又不会一次性压垮团队。我在一个老项目里就是这么干的第一周只修了字段命名第二周修了必填校验一个月后规范覆盖率就到了八成以上。5.2 规范文件和代码脱节怎么防脱节的根源是“规范改了但代码没改”或者“代码改了但规范没改”。防脱节的核心是让校验成为强制环节。本地 hook 加 CI 卡口两层保险。另外规范文件的修改要单独 review确保改规范的人知道自己在改什么。我还见过一种情况规范文件写得太细代码实现有合理偏差导致大量误报。这时候要反思规范是不是定得过死。规范应该约束“对外契约”而不是“内部实现细节”。把边界划清楚脱节问题会少很多。5.3 和现有工具链冲突怎么处理Spec-kit 可能和现有的 lint 工具、格式化工具产生重叠或冲突。比如 ESLint 也在检查命名规范Spec-kit 也在检查两边规则不一致就会打架。处理方式是明确分工lint 管代码风格Spec-kit 管接口契约各管各的规则不要重叠。如果确实有重叠以 Spec-kit 为准把 lint 里的对应规则关掉。这样职责清晰维护起来也简单。5.4 性能问题怎么优化项目大了之后全量校验可能很慢。优化方向有几个一是只校验变更文件用--staged或--diff参数二是开启缓存把上次校验结果缓存起来没变的文件跳过三是并行校验Spec-kit 一般支持多进程配置里开一下。我在一个上万文件的项目里通过缓存加并行把校验时间从几分钟压到了十几秒。关键是要让校验足够快快到开发者愿意在本地跑否则大家就会绕过它。5.5 常见问题速查表问题现象可能原因排查方向解决方式报错数量异常多规范定得太严或解析器不匹配检查规则配置和解析器选择分批收紧规则换解析器校验结果和实际不符缓存过期或路径配置错误清缓存检查 ignore 路径清缓存重跑修正路径CI 通过但本地失败环境差异或版本不一致对比本地和 CI 的工具版本统一版本锁定依赖AI 生成代码仍违规约束摘要不完整或 prompt 太长被截断检查摘要内容精简 prompt补全约束分段喂给 AI校验速度慢全量检查或未开缓存看是否用了 diff 模式开缓存用增量检查5.6 几个我踩过的坑第一个坑是规范文件用了中文注释结果解析器报编码错误。后来统一改成英文注释问题消失。如果你的项目有国际化需求规范文件本身建议用英文注释可以另开文档。第二个坑是 ignore 规则写得太宽把整个目录忽略了结果那个目录下的问题一直没被发现。后来改成精确到文件定期 review ignore 列表。第三个坑是没锁定 Spec-kit 版本CI 上自动装了新版本行为变了导致流水线突然失败。后来在 package.json 里锁死版本升级时手动改改完先本地验证再上 CI。6. 把规范变成团队资产的一些体会Spec-kit 这类工具的价值不在于它本身多复杂而在于它强迫团队把“隐式约定”变成“显式资产”。这个过程一开始会有点痛因为要把脑子里想的东西写下来还要接受工具的无情检查。但坚持一段时间后你会发现沟通成本明显下降新人上手也快了很多。我现在带项目第一件事就是搭 Spec-kit把核心接口和关键约束写进去。哪怕项目还很小这个习惯也值得养成。因为规范这东西越早建立越省事等到代码烂成一团再补成本会高得离谱。如果你也在用 AI 辅助开发强烈建议把 Spec-kit 和 codex cli、claude cli 这类工具串起来用。规范给 AI 划边界AI 在边界内发挥产出质量和速度都能兼顾。这个组合我用了大半年是目前我觉得最顺手的开发方式之一。最后分享一个小技巧Spec-kit 的校验报告可以定期归档每个月看一次趋势。如果违规数量在下降说明规范在落地如果一直居高不下说明要么规范不合理要么执行不到位需要调整策略。数据不会骗人比感觉靠谱。