1. 从“能跑就行”到“可交付”Spec-Kit 要解决的真问题我最早接触 Spec-Kit 是在一个多人协作的中型项目里。当时团队里每个人都在用 AI 编程助手写代码效率确实高但问题也很快暴露出来同一个需求A 用 Claude Code 生成了一版实现B 用另一款工具又生成了一版两版代码风格、目录结构、错误处理方式完全不同。代码评审的时候大家吵的不是业务逻辑对不对而是“为什么你要这么写”。更麻烦的是AI 生成的代码往往缺少可追溯的上下文——它为什么这么设计、边界条件考虑了哪些、后续要改哪里全凭生成者脑子里的记忆。Spec-Kit 就是在这个背景下进入我视野的。它本质上是一套面向 AI 智能体协作开发的规范框架核心思路是把“规格说明Spec”作为整个开发流程的中心让 AI 智能体、开发者和工具链都围绕同一份可执行、可验证的规格来工作。你可以把它理解成给 AI 编程智能体立的一套“交通规则”不是限制它写代码的能力而是让它在写代码之前先明确“要做什么、做到什么程度、怎么验证做对了”。这套框架特别适合三类人一是正在用 Claude Code、OpenSpec 这类 AI 编程工具做实际项目的开发者二是需要多个 AI 智能体协同完成一个模块的团队三是想把 AI 生成代码纳入正规研发流程、而不是停留在“玩具项目”阶段的技术负责人。如果你只是偶尔让 AI 写个脚本可能感受不到它的价值但只要你开始让 AI 参与真实业务代码Spec-Kit 这套思路就会变得非常关键。我在这篇文章里不会照搬官方文档的条目而是结合我自己在项目里落地 Spec-Kit 的完整过程把它的核心机制、实操步骤、踩过的坑和验证方法讲清楚。无论你用的是 Claude Code、OpenSpec 还是其他 AI 编程智能体工具这套规范思路都是通用的。2. Spec-Kit 的核心机制规格如何驱动 AI 智能体2.1 规格不是文档而是可执行的契约很多人第一次听到“规格驱动开发”会下意识觉得就是写一份详细的需求文档。Spec-Kit 里的 Spec 和传统需求文档最大的区别在于它是机器可读、可校验、可追踪的。传统文档写完就放在那里代码和文档脱节是常态而 Spec-Kit 的规格会直接参与 AI 智能体的生成过程成为约束条件。具体来说一份 Spec-Kit 规格通常包含几个层次最上层是意图描述用自然语言说清楚这个功能要解决什么问题中间层是接口契约定义输入输出、数据结构、错误码底层是验收条件用可执行的断言或测试用例表达“什么叫做完了”。AI 智能体在生成代码时会同时读取这三层信息而不是只根据一句“帮我写个登录功能”就自由发挥。我实测下来的感受是规格的粒度控制很关键。太粗AI 还是会乱写太细写规格的时间比写代码还长。我的经验是接口契约和验收条件必须精确到可执行意图描述可以保持简洁。比如一个用户注册功能意图描述一句话就够但密码强度校验规则、重复邮箱的处理方式、验证码有效期这些必须写死。2.2 多智能体协作下的规格同步Spec-Kit 另一个让我觉得设计巧妙的地方是它天然支持多智能体协作。在一个稍大的模块里我可能会让一个智能体负责数据层另一个负责业务逻辑第三个负责接口层。如果没有统一规格这三个智能体生成的东西拼不到一起。Spec-Kit 的做法是让规格成为共享的单一事实来源。每个智能体在开始工作前都先读取同一份规格文件生成过程中产生的中间决策也会回写到规格的扩展字段里。这样当智能体 B 需要调用智能体 A 生成的接口时它不需要去读 A 的代码只需要读规格里定义的契约。这里有个实操细节值得注意规格文件的版本管理要和代码版本管理绑定。我试过把规格文件和代码放在同一个仓库里用同一个分支管理每次规格变更都走一次代码评审。这样做的好处是当 AI 生成的代码和规格不一致时CI 流程能直接发现。如果规格和代码分仓管理很容易出现规格更新了但代码没跟上、或者代码改了规格没同步的情况。2.3 与 Claude Code、OpenSpec 等工具的衔接方式Spec-Kit 本身不是一个具体的编码工具它更像是一层规范协议。你可以把它和 Claude Code 结合使用在 Claude Code 的工作目录里放一份 Spec-Kit 规格文件然后在提示词里明确要求“严格按照 spec 目录下的规格生成代码”。Claude Code 会读取这些文件作为上下文生成结果会明显更贴近预期。和 OpenSpec 的配合也类似。OpenSpec 本身强调规格先行Spec-Kit 可以作为它的规格格式补充。我在项目里实际的做法是用 Spec-Kit 定义核心契约和验收条件用 OpenSpec 管理规格的生命周期和变更记录。两者并不冲突反而互补。需要提醒的是不同工具对规格文件的解析能力不一样。Claude Code 对 Markdown 格式的规格支持很好OpenSpec 可能更偏好结构化数据。我的建议是规格主体用 Markdown 写关键契约用 YAML 或 JSON 片段嵌入这样大多数工具都能解析。3. 在真实项目里落地 Spec-Kit 的完整操作链路3.1 环境准备与目录结构设计落地 Spec-Kit 的第一步不是写规格而是把目录结构定下来。我踩过的第一个坑就是规格文件到处放最后自己都找不到哪份是最新的。后来我固定了一套结构在项目根目录下建一个specs/目录里面按模块分子目录每个模块目录下固定几个文件specs/ user-auth/ intent.md # 意图描述 contract.yaml # 接口契约 acceptance.md # 验收条件 changelog.md # 规格变更记录 order-flow/ ...intent.md用自然语言写清楚这个模块要做什么给人和 AI 看都行。contract.yaml是机器可读的核心定义数据结构、接口签名、错误码。acceptance.md里放可执行的验收条件我通常直接写成测试用例的伪代码或者 Gherkin 格式。changelog.md记录每次规格变更的原因和影响范围这个在多人协作时特别重要。环境方面如果你用 Claude Code确保它的工作目录能访问到specs/目录。我一般会在项目根目录放一个.claude配置文件把 specs 目录加入上下文白名单。OpenSpec 的话在它的配置文件里指定 specs 路径即可。3.2 从零写一份可被 AI 正确执行的规格写规格这件事我总结了一个“三层递进”的方法。第一层先写意图不要超过 200 字重点说清楚这个功能为谁解决什么问题。比如“为注册用户提供邮箱验证功能防止恶意注册验证链接 24 小时内有效”。这句话里已经隐含了关键约束验证链接有时效。第二层写契约。这一步要具体到字段级别。以邮箱验证为例契约里要定义请求参数邮箱、验证码、响应结构成功/失败、错误码、状态流转待验证、已验证、已过期。我习惯用 YAML 写因为结构清晰AI 解析准确率高。第三层写验收条件。这是最容易被忽略但最重要的一层。验收条件要写成“给定什么条件执行什么操作期望什么结果”的形式。比如“给定一个已过期的验证码当用户提交验证时返回错误码 TOKEN_EXPIRED”。这些条件后续可以直接转成自动化测试。我实测下来一份中等复杂度的模块规格写清楚大概需要 30 到 60 分钟。听起来不少但相比后面反复修改 AI 生成代码的时间这个投入非常划算。而且规格写一次可以复用后续需求变更只需要改对应部分。3.3 让 AI 智能体按规格生成代码的提示词技巧规格写好了怎么让 AI 智能体真正按规格执行提示词很关键。我试过很多种写法最后固定了一套模板效果最稳请阅读 specs/user-auth/ 目录下的 intent.md、contract.yaml 和 acceptance.md。严格按照 contract.yaml 中定义的接口签名和数据结构生成代码。生成完成后逐条对照 acceptance.md 中的验收条件进行自检并输出自检结果。这段话里有三个关键点明确指定文件路径、强调契约的约束力、要求自检并输出结果。特别是最后一点让 AI 自己对照验收条件检查能过滤掉大部分低级错误。还有一个技巧是分步生成。不要一次性让 AI 生成整个模块而是按契约里的接口逐个生成。每生成一个接口就让它对照验收条件自检一次。这样即使某个接口有问题也不会影响其他部分。我在 Claude Code 里就是这么操作的生成质量明显比一次性生成高。另外如果项目里已经有一些既有代码风格可以在提示词里加一句“参考 src/ 目录下现有代码的风格”。AI 会去读现有代码生成结果的一致性会好很多。3.4 规格与代码不一致时的处理流程不管规格写得多细AI 生成代码和规格不一致的情况一定会发生。关键是要有一套处理流程而不是每次靠人肉发现。我的做法是在 CI 里加一个规格校验步骤用脚本解析 contract.yaml然后检查生成的代码里是否有对应的接口实现、参数名是否匹配、错误码是否一致。这个校验脚本不需要很复杂我一开始就是用 Python 写了个简单的解析器把 contract.yaml 里的接口名和参数列表提取出来然后在代码里做字符串匹配。虽然粗糙但能抓住大部分明显的不一致。后来逐步完善加入了类型检查和返回值校验。当校验失败时我的处理原则是先判断是规格错了还是代码错了。如果是规格描述有歧义导致 AI 理解偏差就改规格如果是 AI 没按规格执行就重新生成或者手动修正代码。每次修正后都要在 changelog.md 里记一笔说明原因和修正方式。这样积累下来规格会越来越精确AI 生成的一次通过率也会越来越高。4. 踩过的坑Spec-Kit 落地过程中的典型问题与排查4.1 规格粒度过粗导致 AI 自由发挥这是我最早踩的坑。当时觉得规格写个大概就行结果 AI 生成的代码里错误处理方式五花八门有的抛异常有的返回 null有的返回错误码。排查的时候发现规格里只写了“处理失败情况”没定义具体怎么处理。排查这个问题的链路很清晰先看 AI 生成的代码哪里不符合预期然后回溯到规格里对应的描述发现描述本身就有歧义。解决办法是把“处理失败情况”改成具体的错误码定义和返回结构。改完之后重新生成问题就消失了。这个坑给我的教训是凡是 AI 可能做出不同选择的地方规格里都要明确。不要假设 AI 会按照“常识”来它的常识和你的常识可能不一样。4.2 多智能体之间的规格版本冲突第二个坑出现在多智能体协作场景。我让两个智能体分别处理用户模块和订单模块它们各自读取了规格文件。但问题是订单模块需要调用用户模块的接口而两个智能体读取规格的时间点不同用户模块的规格在中间更新过一次导致订单智能体拿到的是旧版契约。这个问题的排查花了些时间因为表面上看两个模块单独都能跑只有集成的时候才报错。后来我在规格文件里加了版本号字段并且要求所有智能体在开始工作前先检查规格版本如果版本不一致就暂停并提示。更彻底的解决办法是引入一个规格协调者角色。这个角色可以由人担任也可以由一个专门的智能体担任负责在多个智能体开始工作前统一分发最新规格并在规格变更时通知所有相关智能体。我在后来的项目里就是这么做的冲突明显减少。4.3 验收条件写得不可执行等于没写第三个坑比较隐蔽。我一开始写验收条件的时候写的是“系统应该正确处理用户登录”。这种描述看起来没问题但实际上不可执行——什么叫“正确处理”AI 没法判断自己有没有做到。后来我把验收条件全部改成可执行的形式比如“给定正确的用户名和密码调用登录接口返回状态码 200 且响应体包含 token 字段”。这样 AI 在自检的时候可以逐条对照明确知道自己有没有达标。这个改进带来的效果非常明显。之前 AI 生成完代码后我还要花大量时间手动测试改成可执行验收条件后AI 自检就能过滤掉大部分问题我只需要做最终确认。4.4 规格变更后的连锁反应处理最后一个坑是规格变更引发的连锁反应。有一次我修改了用户模块的一个接口参数以为只影响用户模块结果订单模块、支付模块都调用了这个接口全部需要同步更新。如果没有规格追踪机制这种变更很容易漏掉。我的解决办法是在 changelog.md 里记录每次变更的影响范围并且用脚本分析规格文件之间的依赖关系。当某个规格变更时脚本会自动列出所有依赖它的模块提醒我逐一检查。这个脚本我后来开源在了团队内部工具库里成了 Spec-Kit 落地流程的标准配置。5. 验证 Spec-Kit 是否真正生效的几个硬指标5.1 AI 生成代码的一次通过率判断 Spec-Kit 有没有起作用最直接的指标是 AI 生成代码的一次通过率。我记录过一组数据在没有使用 Spec-Kit 之前AI 生成的代码能直接通过评审的比例大概在 40% 左右使用 Spec-Kit 并配合可执行验收条件后这个比例提升到了 75% 以上。这个提升主要来自两个方面一是规格约束减少了 AI 的自由发挥空间二是验收条件让 AI 能够自检。我建议你在落地 Spec-Kit 的初期就建立这个指标的基线然后持续跟踪。如果一段时间后没有提升说明规格写得还不够精确或者提示词还需要调整。5.2 规格与代码的偏差率第二个指标是规格与代码的偏差率也就是 CI 校验中发现的规格与实现不一致的比例。这个指标反映的是规格的执行力度。偏差率过高说明 AI 没有认真读规格或者规格本身有歧义偏差率过低反而要警惕可能是校验脚本太宽松漏掉了问题。我的经验是偏差率控制在 5% 到 10% 之间比较健康。完全为零不太现实因为总有一些边界情况规格没覆盖到超过 15% 就说明规格质量或者执行流程有问题需要排查。5.3 新成员上手时间的变化第三个指标比较间接但很有说服力新成员上手项目的时间。Spec-Kit 的规格文件本身就是很好的项目文档新成员通过读规格就能理解模块的职责和接口。我观察到的现象是使用 Spec-Kit 的项目新成员从入职到能独立提交代码的时间比没有规格的项目缩短了大约三分之一。这个指标对于团队负责人来说特别有价值。因为 AI 编程工具虽然提高了个人效率但如果项目知识只存在于个别人的脑子里团队整体效率反而会下降。Spec-Kit 把知识固化在规格里降低了人员流动带来的风险。6. 把 Spec-Kit 用出效果的几个个人心得我在多个项目里落地 Spec-Kit 之后有几个心得是官方文档里不会写的。第一个是规格要当代码一样对待。什么意思就是规格也要走代码评审、也要有版本管理、也要写变更记录。我见过太多团队把规格当成一次性文档写完就扔结果 AI 生成代码时读到的规格和实际需求早就脱节了。第二个心得是不要追求一步到位。Spec-Kit 的规格体系可以逐步完善一开始只需要写清楚核心契约和关键验收条件其他部分可以随着项目推进慢慢补充。我第一个项目落地 Spec-Kit 的时候规格只覆盖了 60% 的接口但已经能明显感受到 AI 生成质量的提升。后来逐步补全效果越来越好。第三个心得是让 AI 参与规格的维护。这听起来有点反直觉但实际效果不错。我会让 AI 智能体在生成代码后检查规格里是否有遗漏或过时的描述并给出修改建议。AI 在理解代码和规格的一致性方面有天然优势它能发现人容易忽略的细节偏差。最后一个心得是关于工具选择的。Spec-Kit 本身不绑定任何特定工具Claude Code、OpenSpec 或者其他 AI 编程智能体都可以配合使用。我的建议是先用你手头最顺手的工具跑通流程再考虑工具切换。流程和规范的价值远大于工具本身不要因为纠结工具选择而迟迟不开始。如果你现在正在用 AI 编程工具做实际项目我强烈建议你从下一个模块开始试着写一份 Spec-Kit 规格。不用追求完美先把意图、契约、验收条件这三层写出来然后让 AI 按规格生成一次代码对比一下和之前的差异。我敢说只要你认真试过一次就很难再回到“随口让 AI 写代码”的方式了。