Spec-Kit、SDD 和 OpenSpec 到底有什么区别？其实核心思想都一样：先写清楚，再让 AI 干活

最近 AI 编程工具越来越卷，Cursor、Claude Code、Cline、Trae、Copilot 各种 Agent 都开始能“自己读代码、自己改代码、自己跑测试”。

但用久了你会发现一个很现实的问题：

AI 写代码不是最难的，难的是让 AI 持续写对代码。

尤其是项目一复杂，需求一模糊，AI 很容易出现几类经典问题：

  • 一上来就开写，完全不做设计；
  • 改了 A 文件，忘了 B 文件的约束；
  • 当前回答看起来很聪明，下一步就开始“智商降级”；
  • 不理解项目长期规则，只围着当前 prompt 打转；
  • 代码能跑，但架构、边界、测试、验收全是糊的。

所以现在很多团队开始讨论 Spec-Kit、SDD、OpenSpec 这一类东西。

尤其是 Spec-Kit，最近在 GitHub 上的关注度明显越来越高，star 数持续增长，说明越来越多开发者开始意识到：AI 编程不能只靠一句 prompt 硬冲，复杂项目必须重新回到“规约先行”的工程化路径上。

它们名字不同，工具形态不同，但底层想解决的是同一个问题：

不要直接让 AI 写代码，而是先把需求、约束、设计、任务和验收标准写成结构化规约，再让 AI 按规约执行。

本文主要讲 Spec-Kit，同时顺手解释一下它和 SDD、OpenSpec 的区别。

先说结论：三者关系可以这样理解

如果只用一句话概括：

SDD 是思想，Spec-Kit 是工程化工具链，OpenSpec 更像开放规约表达方式或轻量规约工作流。

可以简单类比：

名称更像什么核心作用
SDD / Specification-Driven Development方法论强调先写规约，再写代码
Spec-Kit工程工具链把规约驱动开发落成可执行流程
OpenSpec开放规约/契约表达用更开放、标准化的方式描述能力、接口、行为或约束

所以你会感觉它们“差不多”，这个感觉是对的。

因为它们都站在同一个方向上：

把 AI 从“凭感觉写代码”拉回“按规格施工”。

区别只是在于：

  • SDD 更偏理念；
  • Spec-Kit 更偏落地；
  • OpenSpec 更偏开放描述和规范表达。

一、什么是 SDD？它是“先设计后编码”的思想

很多人会把它写成 SSD，但在 AI 编程语境里，更常见的说法是 SDD：Specification-Driven Development，也就是规约驱动开发。

它的核心很简单：

代码不是从 prompt 直接生成的，而是从 specification 生成的。

传统 AI 编程方式通常是这样：

用户：帮我做一个忘记密码功能。
AI：好的，我开始写代码……

听起来很高效，但问题是：

  • 忘记密码用手机号还是邮箱？
  • 验证码有效期多久？
  • 是否限制发送频率？
  • 新密码规则是什么？
  • 是否要让旧登录态失效？
  • 前端要不要倒计时？
  • 后端要不要防止用户枚举？
  • 接口错误信息怎么统一？
  • 测试用例覆盖哪些场景？

这些问题如果不提前说清楚，AI 就只能猜。

而 AI 一猜，项目就危险。

SDD 的做法是先把需求整理成类似这样的结构：

1. 用户故事
2. 业务规则
3. 边界条件
4. 非功能需求
5. 接口约定
6. 数据模型
7. 异常场景
8. 验收标准
9. 测试清单
10. 实施任务

也就是说，SDD 不是一个具体工具，而是一种工作方式。

它强调：

先把“要做什么、不能做什么、做到什么程度算完成”定义清楚，再进入编码阶段。

这和传统软件工程里的需求文档、概要设计、详细设计有点像，只不过它面向的是 AI 协作场景。

二、什么是 Spec-Kit？它是把 SDD 落地的“施工流程”

如果说 SDD 是思想，那 Spec-Kit 就是把这个思想真正工程化的一套工具和流程。

我更愿意把 Spec-Kit 理解成：

给 AI 戴上的“工程紧箍咒”。

以前我们用 AI 编程，很像 Vibe Coding：

我有个感觉 → 写个 prompt → AI 开始生成 → 看结果再改

这种方式适合小脚本、小页面、小 Demo。

但一旦进入真实项目，比如：

  • 登录注册；
  • 忘记密码；
  • 支付订单；
  • 权限系统；
  • 多服务协作；
  • 老项目重构；
  • 涉及数据库迁移；
  • 涉及前后端联调；

直接让 AI 写代码就很容易翻车。

Spec-Kit 的价值在于，它不是让 AI 立刻开工，而是先让 AI 进入一套固定流程。

典型流程大概是：

/specify  →  生成需求规约
/clarify  →  澄清模糊点
/plan     →  生成技术方案
/tasks    →  拆解实施任务
/implement → 按任务执行
/analyze  →  检查规约、计划、任务是否一致

这就像现实工程里的流程：

需求确认 → 技术方案 → 任务拆解 → 编码实现 → 验收检查

AI 不再是一个“想到哪写到哪”的实习生，而更像一个被流程约束的工程执行者。

三、Spec-Kit 解决的核心问题：AI 的上下文失控

AI 编程最大的问题不是不会写代码，而是容易忘记上下文。

尤其在复杂项目里，AI 可能当前文件看得很明白，但全局关系完全断掉。

比如你让它做一个“忘记密码”功能，它可能会：

  • 前端新增了页面，但没接入路由；
  • 后端写了接口，但没加 DTO 校验；
  • 密码重置成功了，但没有让旧 token 失效；
  • 返回了“手机号不存在”，造成账号枚举风险；
  • 改了 auth-service，却忘记 web 侧 API 类型；
  • 写了代码，但没有补测试和验收标准。

这些问题本质上都是：

AI 缺少一个稳定、长期、结构化的任务上下文。

Spec-Kit 的作用就是把这个上下文沉淀下来。

它会把一个功能拆成多份文档，例如：

spec.md      需求规格
plan.md      技术方案
tasks.md     实施任务
research.md  调研结论
contracts/   接口契约
quickstart.md 验收说明

这些文件不是写给人看的形式主义文档，而是写给 AI 的“施工图纸”。

只要图纸清楚，AI 每次执行任务时就能回到同一套约束里，而不是每次重新猜。

四、OpenSpec 又是什么？它更偏“开放规约表达”

OpenSpec 这个词在不同团队里可能会有不同用法。

有些人说 OpenSpec，指的是一种开放的 specification 描述方式；有些人会把它理解成类似 OpenAPI 那样的契约文档；也有人把它当成一套面向 AI Agent 的开放规约格式。

但无论具体实现是哪一种，它通常强调的是：

用开放、结构化、可复用的格式来描述系统能力、接口行为、约束条件和验收规则。

所以 OpenSpec 更关注“规约怎么表达”。

比如它可能更在意：

  • 接口契约是否清楚；
  • 输入输出是否标准化；
  • schema 是否可被工具解析；
  • 能不能跨工具、跨团队复用；
  • 能不能作为 AI、测试、文档、代码生成的共同输入。

从这个角度看，OpenSpec 和 Spec-Kit 是互补关系。

OpenSpec 偏“格式和表达”，Spec-Kit 偏“流程和执行”。

五、Spec-Kit 和 OpenSpec 的区别

它们最大的区别不在理念，而在关注点。

1. Spec-Kit 更关注流程闭环

Spec-Kit 关心的是：

一个需求如何从想法变成可执行任务？
AI 在每一步应该产出什么？
什么时候可以编码？
什么时候需要澄清？
什么时候需要分析一致性？

它强调的是完整生命周期。

从需求到实现，中间每一步都要留下规约痕迹。

2. OpenSpec 更关注规约本身的开放性

OpenSpec 关心的是：

规约如何被不同工具理解？
接口、行为、约束如何标准化描述？
这些描述能不能被测试工具、文档工具、AI 工具共同消费？

它更像一个开放契约层。

3. Spec-Kit 更适合 AI 编码流程控制

如果你的核心问题是：

  • AI 老是乱改；
  • 需求总是说不清；
  • 复杂功能容易做到一半偏航；
  • 多文件、多服务修改不好控制；
  • 希望 AI 先规划、再编码；

那 Spec-Kit 更直接。

4. OpenSpec 更适合统一接口和能力描述

如果你的核心问题是：

  • 多系统之间契约不一致；
  • 接口文档和实现脱节；
  • 希望规约可以被多个工具消费；
  • 希望规范更开放、更标准化；

那 OpenSpec 的价值更明显。

六、为什么我主要推荐讲 Spec-Kit？

因为对大多数正在使用 AI 编程的开发者来说，真正的痛点不是“不知道怎么写规约”，而是：

我知道要先设计，但实际一打开 AI 工具，还是忍不住直接让它写代码。

Spec-Kit 的好处是，它把“先设计后编码”变成了强制流程。

你不是靠自觉，而是靠工具约束。

这点很重要。

因为 AI 编程最大的诱惑就是“快”。

你输入一句话，它马上给你 300 行代码，这种反馈太爽了。

但爽完以后，常见结局是：

  • 第一版看着能用；
  • 第二轮需求开始打补丁；
  • 第三轮改动破坏原逻辑；
  • 第四轮 AI 已经忘了之前为什么这么设计；
  • 最后代码变成一坨更难维护的新屎山。

Spec-Kit 的价值就是在这个地方。

它会强制你慢下来：

别急，先写 spec。
别急，这里还有模糊点。
别急，先出 plan。
别急，先拆 tasks。
别急，先检查一致性。

短期看，它比直接写代码慢。

长期看，它是在帮你省返工成本。

七、用一个例子理解：忘记密码功能

可以拿我当前项目里的“忘记密码”功能举例。

一开始的原始需求其实很简单：

我想实现忘记密码功能。
前端页面已经有了，位置在 apps/web/src/pages/ForgotPassword。
认证微服务在 services/auth-service。
业务微服务在 services/backend。

如果直接把这段话丢给 AI，它大概率会马上开始改前端页面、写接口、补几个表单校验。

但真正进入项目以后，会发现这里面其实有很多隐含规则：

  • 前端不能直接调用 auth-service，只能调用 backend；
  • backend 只是中间层，真正的密码重置能力仍然归 auth-service；
  • 当前阶段验证码能力还没接入，所以重置密码暂时不校验验证码；
  • 但获取验证码按钮仍然要有模拟成功或友好提示，不能阻断主流程；
  • 手机号必须是 11 位数字；
  • 新密码和确认密码必须一致；
  • 新密码不能和旧密码相同；
  • 密码重置后，旧密码必须登录失败，新密码必须登录成功；
  • 重置成功后，需要清理用户已有的 Refresh Token，让旧登录态失效；
  • 错误提示不能直接暴露“手机号是否已注册”，避免账号枚举；
  • 日志里不能记录明文密码、完整验证码、Token 等敏感信息。

这些内容如果不提前写清楚，AI 就会自己猜。

而 Spec-Kit 的价值，就是把这些“隐藏在脑子里的规则”拆成不同的规约产物。

比如在 spec.md 里，它会把需求拆成用户故事：

US1：用户可以通过手机号重置密码。
US2：验证码未接入阶段，也能先完成可用恢复流程。
US3：忘记密码流程不能暴露账号存在性和敏感信息。

在 contracts/forgot-password-api.md 里，它会继续把接口契约写清楚：

POST /auth/forgot-password/send-code
POST /auth/forgot-password/reset

前端只调用 backend。
backend 再调用 auth-service。
当前阶段 code 字段可以接收，但不作为重置成功的必要条件。
响应里不能返回密码、Token、完整验证码或内部错误细节。

在 tasks.md 里，它会把实现拆成可执行任务：

先确认 auth-service、backend、前端 API 的现有结构。
再创建 DTO、响应类型和错误码。
然后实现 auth-service 的 resetForgotPassword。
再实现 backend 的代理入口。
最后把前端 ForgotPassword store 从 localStorage mock 改成真实调用 backend API。

在 quickstart.md 里，它还会把验收方式写出来：

使用已注册手机号重置密码。
确认新密码登录成功，旧密码登录失败。
确认验证码未接入时不阻断主流程。
确认未注册手机号不会直接暴露账号是否存在。
分别在 auth-service、backend、apps/web 执行 lint、build、typecheck。

这就是 Spec-Kit 和普通 prompt 最大的区别。

普通 prompt 是：

帮我做忘记密码。

Spec-Kit 是：

先明确业务规则。
再明确服务边界。
再明确接口契约。
再明确任务顺序。
最后明确验收标准。

这样 AI 再去实现时，它就不是在“自由发挥”，而是在按施工图施工。

八、什么时候不需要 Spec-Kit？

Spec-Kit 不是银弹。

如果你只是写：

  • 一个临时脚本；
  • 一个简单组件；
  • 一个 Demo 页面；
  • 一个一次性数据处理工具；
  • 一个很小的 bugfix；

那没必要上这么重的流程。

直接用 AI 写就行。

否则你会感觉：

我只是想拧一颗螺丝，你却让我先写施工方案。

但如果你面对的是：

  • 复杂业务功能；
  • 多模块联动；
  • 前后端一起改；
  • 涉及认证、安全、支付、权限；
  • 老项目重构；
  • 团队协作；
  • 长期维护项目；

那 Spec-Kit 就非常值得用。

因为这类任务最怕的不是写得慢，而是写错方向。

九、我的理解：Spec-Kit 是 AI 时代的“需求防火墙”

以前我们写代码，最重要的是代码规范。

现在用 AI 写代码，最重要的可能是规约规范。

因为 AI 的输出质量，很大程度取决于输入质量。

你给它一句模糊需求，它就只能输出一个模糊实现。

你给它一套结构化规约，它才可能输出一个可维护、可测试、可验收的工程结果。

所以 Spec-Kit 的意义不是“让 AI 更聪明”。

它真正的意义是：

让 AI 不那么容易乱来。

这也是我觉得 Spec-Kit 最值得讲的地方。

它不是又一个炫酷的 AI 编码插件，而是把 AI 编程重新拉回软件工程基本面：

需求清楚
边界清楚
设计清楚
任务清楚
验收清楚

只要这五件事清楚，AI 才能真正成为生产力。

否则，它只是一个打字很快的风险放大器。

最后总结

Spec-Kit、SDD、OpenSpec 的区别可以这样记：

  • SDD：规约驱动开发的方法论，强调先写 specification，再写代码；
  • Spec-Kit：把 SDD 落地成 AI 编程流程的工具链，强调从需求到任务再到实现的闭环；
  • OpenSpec：更偏开放规约表达，强调规约可以标准化、结构化、跨工具复用。

它们本质上确实差不多，都是为了解决 AI 编程里的同一个核心问题：

AI 不能只靠 prompt 驱动，而应该靠 spec 驱动。

如果你主要想讲 Spec-Kit，可以把文章重点放在这句话上：

Spec-Kit 不是让 AI 写得更快，而是让 AI 写得更稳。

在 AI 编程越来越普及的今天，真正拉开差距的可能不再是谁更会写代码，而是谁更会给 AI 写“施工图”。