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 写代码”的方式了。
与贝叶斯正则化实现TFP高精度预测)
