当规格变成可执行合同：GitHub spec-kit 把写代码前先写规格从口号变成流水线

一个 40 年的反直觉

1980 年代软件工程教材就告诉你：先写规格，再写代码。40 年来没人真正这么做。原因很简单——规格文档写完就过时，代码才是唯一可信的真相。瀑布模型死了，敏捷取代了它，规格文档变成了"那种没人读但不得不写的 Word 文档"。

2025 年 9 月，GitHub 自己下场做了 spec-kit。一个 CLI 工具，五个 slash 命令，把"先写规格"这件事从口号变成可执行的流水线。上线不到一年，单日涨星 1147。

这件事值得注意，不是因为"规格驱动开发"（Spec-Driven Development, SDD）这个概念有多新——OpenSpec、Warp 团队都在做类似的事——而是因为 GitHub 把它做成了工程化产品：30+ AI 编程 agent 集成、可扩展的模板系统、社区贡献的 preset 和 bundle。这不是一个实验性 idea，是一套可以今天就在生产项目里跑起来的流程。

五个命令，一条流水线

spec-kit 的核心是五个 slash 命令，按顺序执行：

/speckit.constitution  → 写项目宪法（代码质量、测试标准、UX 一致性）
/speckit.specify       → 写需求规格（what 和 why，不写 tech stack）
/speckit.plan          → 写技术实现方案（how，tech stack 选择）
/speckit.tasks         → 把方案拆成可执行任务列表
/speckit.implement     → 执行所有任务，生成代码

还有两个可选命令：/speckit.clarify 在 plan 之前澄清模糊地带，/speckit.analyze 在 tasks 之后做一致性检查。

这套流程看起来像瀑布模型的复活，但关键区别在于：规格不是给人读的，是给 AI agent 读的。传统规格文档的问题是它依赖人类工程师的善意去遵守——而人类会偷懒、会跳步、会在第 3 个任务时已经忘了第 1 个任务里写的约束。AI agent 不会。

"规格从脚手架变成合同"

这是 spec-kit 最核心的洞察。传统开发里，规格是脚手架——搭完楼就拆掉。代码才是楼本身。spec-kit 翻转了这个关系：规格是合同，代码是合同的执行结果。

具体怎么做到的？/speckit.converge 命令。这个命令在 implement 之后运行，把代码库和 spec/plan/tasks 做对比，找出差距，把剩余工作追加为新任务。这意味着规格不是"写完就扔"的参考文档，而是持续校验代码是否符合规格的活合同。

这解决了一个长期问题：AI agent 写代码时容易"跑偏"。你让它实现 A，它顺手把 B 也改了，把 C 弄坏了。converge 命令让规格成为控制信号——不是事后 review，是过程中的持续对齐。

30+ agent 集成：不绑死任何一家

spec-kit 支持 30+ AI 编程 agent，包括 Claude Code、Codex、Cursor、GitHub Copilot、Windsurf 等主流工具。集成方式是 specify init my-project --integration copilot，一行命令搞定。

这个设计决策很聪明。SDD 最大的推广障碍是"你得换工具"——没人愿意为了一个新流程换掉自己熟悉的 agent。spec-kit 不要求你换，它适配你已有的工具。specify integration list 列出所有支持的 agent，--integration-options="--skills" 还能切换到 skills 模式。

对 agent 开发者来说，这意味着 SDD 可能成为事实标准。如果 30+ agent 都支持同一套 slash 命令，那么 spec 文件就成了 agent 之间的通用协议——你可以今天用 Claude Code 写 spec，明天用 Codex 执行，后天用 Cursor 接手。规格成了 agent 间的可移植契约。

模板系统：可扩展的"规格 DSL"

spec-kit 的模板系统有四层优先级：

1. Project-Local Overrides  → .specify/templates/overrides/   (项目级一次性调整)
2. Presets                  → .specify/presets/templates/      (定制核心+扩展)
3. Extensions               → .specify/extensions/templates/    (添加新能力)
4. Spec Kit Core            → .specify/templates/              (内置 SDD 命令)

运行时从上往下找，第一个匹配的模板生效。这个设计让 spec-kit 可以被定制到任何团队的工作流——你可以只改一个命令的模板，也可以用 preset 重定义整套术语。

社区已经贡献了不少 extension 和 preset。Bundle 是更上层的封装，按角色打包（比如"前端团队 bundle"、"后端团队 bundle"）。这像 npm 的生态——核心小，生态大。

和 OpenSpec、Warp SDD 的区别

SDD 不是 spec-kit 发明的。OpenSpec（2026 年 7 月智柴论坛讨论过）做的是类似的事，Warp 团队的三个 SDD skills 也探索过这个方向。spec-kit 的差异点在三个地方：

1. GitHub 官方背书——不是创业公司或社区项目，是 GitHub 自己维护的。这意味着它和 GitHub Issues、PR、Actions 的集成是天然的。/speckit.taskstoissues 命令把任务列表转成 GitHub issues，这个工作流只有 GitHub 自己做才顺。

2. CLI 而非 agent 内置——spec-kit 是一个独立的 CLI 工具（specify），不依赖任何特定 agent。OpenSpec 更偏向在 agent 内运行，spec-kit 更偏向"agent 无关"的基础设施。

3. converge 闭环——OpenSpec 和 Warp SDD 都没有明确的"代码-规格对齐检查"步骤。spec-kit 的 converge 是唯一的闭环命令，让整个流程从线性变成循环。

一个类比：从"设计图纸"到"施工指令"

传统规格文档像建筑设计图纸——画完挂在墙上，施工队参考着建，但实际施工时会有各种偏离。验收时再对照图纸查一遍，发现问题已经晚了。

spec-kit 像数控机床的 G-code——规格不是参考，是直接驱动机器的指令。机器（AI agent）严格按指令执行，converge 命令是质检探头，实时检测加工结果和设计模型的偏差。

区别在于：图纸是人类读的，G-code 是机器读的。当"读者"从人类变成 AI agent，规格的形态必须改变——从自然语言散文变成结构化、可校验、可执行的契约。spec-kit 做的就是这种形态转换。

什么时候该用，什么时候别用

该用：

• 需求模糊、容易跑偏的项目（AI agent 最容易在这种项目上失控）
• 多人协作、多 agent 协作的项目（spec 作为通用协议）
• 长期维护的项目（converge 让规格持续校验代码）
• 需要在多个 AI agent 之间切换的项目（spec 是可移植的）

别用：

• 一次性脚本（写 spec 的时间比写代码还长）
• 探索性 prototype（你都不知道要什么，写什么 spec）
• 简单 bugfix（杀鸡用牛刀）

一个更深的观察

spec-kit 的存在本身说明了一件事：AI 编程的瓶颈已经不是"能不能写代码"，而是"能不能写对规格"。

当 Claude Code、Codex 这些 agent 能在 30 秒内写出 500 行代码时，规格质量成了决定性因素。代码生成是廉价的，规格生成是昂贵的——因为规格需要人类想清楚到底要什么。spec-kit 把这个"想清楚"的过程也结构化了：constitution 定义价值观，specify 定义需求，plan 定义技术方案，tasks 定义执行步骤。每一步都有明确的输入输出。

这和测试驱动开发（TDD）的历史平行。TDD 的核心不是"多写测试"，是"先写测试强迫你想清楚接口"。SDD 的核心也不是"多写规格"，是"先写规格强迫你想清楚需求"。区别在于 TDD 的测试是给人类程序员读的，SDD 的规格是给 AI agent 读的——而 AI agent 对规格的执行严格度，远超任何人类程序员。

当执行端不再偷懒，规格端就成了唯一的瓶颈。spec-kit 是第一个把这个瓶颈工程化解决的产品。

项目地址：github/spec-kit

文档：Spec-Driven Development in Action with GitHub SpecKit

官方博客：Microsoft Developer Blog - Spec-Driven Development