GitHub 开源了一个 11 万 Star 工具，让 AI 写代码不再是猜谜游戏

上个月我在用 Claude Code 开发一个新功能，需求说得很清楚：「给用户列表页加一个按注册时间排序的功能」。

AI 给出的代码看起来很完整——接口、Service 层、前端组件都有。但跑起来发现：排序逻辑用的是前端分页后的本地排序，不是数据库层面的排序。数据一多就废了。

改完这个，又发现它用的是创建时间字段，而不是注册时间。

我花了半小时 Prompt，AI 花了半小时「改」，最后代码改了七八版，还是有问题。

这就是 vibe coding 的典型死法——AI 写得很快，但方向从一开始就偏了，速度越快越难收。

GitHub 在今年 5 月开源了一个叫 Spec Kit 的工具，专门解决这个问题。发布不到一个月，它已经拿到了 11 万 Star、9,700 个 Fork（截至 2026 年 6 月 8 日），是今年 GitHub 上增长最快的 AI 工具类项目之一。

这篇文章的核心结论先放在这里：规范文件（spec.md）是 AI 编码里最被低估的基础设施。 写好它，你跟 AI 的对话质量会有质的提升，不是因为 Prompt 技巧变好了，而是因为 AI 终于知道它要做的是什么。

为什么 Vibe Coding 的天花板这么低

先说清楚问题，再说解决方案。

vibe coding 这个词是 Andrej Karpathy 提出的，原意是「顺着感觉写代码，让 AI 处理细节」。在原型验证阶段，这个方式非常有效——你描述个大概，AI 给你一个能跑起来的架子，5 分钟内看到效果。

但进入真正的功能开发之后，这个模式会遇到一个内在矛盾：

AI Agent 不是搜索引擎，它是「字面意思执行者」。

你说「加一个排序功能」，它就加排序功能。它不知道你的数据量有多大，不知道你的分页逻辑在哪一层，不知道「注册时间」和「创建时间」在你的 schema 里是不是同一个字段。它把所有这些模糊的空间，用它认为「合理」的猜测填满了。

这就是 GitHub 官方文章里说的那句话："it looks right, but doesn't quite work"——看起来对，但跑起来不对。

更深的问题是需求漂移（context drift）。你在一个长对话里反复修改需求，AI 的「记忆」会逐渐偏离最初的意图。第 10 轮修改的代码，和第 1 轮的需求之间，可能已经没有直接的对应关系了。

这不是 AI 的智力问题，是信息结构的问题。

vibe coding 本质上是把「需求」藏在了对话历史里，分散在十几条消息的来回里。AI 每次生成代码，都需要从这些碎片里重建上下文，每次重建都可能丢失细节。

Spec Kit 的解法是：把需求从对话里拿出来，放到一个结构化的文件里。

这个文件就是 spec.md，它是整个开发流程的单一真相源。AI 每次做任何决策，都从这里取信息，而不是从对话历史里猜。

vibe coding 与规范驱动开发的对比：需求漂移 vs 单一真相源

图：左边是 vibe coding 的信息结构——需求散落在对话里，AI 每次都在猜；右边是 SDD 的信息结构——spec.md 是唯一真相源，AI 从这里取信息

Spec Kit 的核心设计：七步工作流

Spec Kit 的安装很简单，核心是一套七步工作流，每一步生成一个文件，这些文件共同构成一个功能的「完整规范体系」。

在看具体命令之前，先理解这个设计哲学：

规范先于实现，文件先于代码。

传统开发是先写代码，遇到问题再补文档。Spec Kit 是先写规范，让规范驱动代码生成。这个顺序的改变，意义远大于工具本身的功能。

七步工作流全景

这七步里，最容易被跳过的是第 4 步（clarify）和第 6 步（analyze）。跳过这两步的代价，往往在第 7 步才暴露出来——任务跑到一半，发现两个模块的接口不兼容，或者某个边界情况根本没考虑进去。

有实践者在完整走完一个 Azure 微服务项目后报告：在 analyze 阶段自动发现了 9 个潜在问题，包括「缺失 FluentValidation 验证器」和「DI 注册顺序错误」——这两个如果等到 implement 阶段才发现，代价是完全不同的。

最终生成的目录结构是这样的：

specs/[FEATURE]/
├── spec.md         # 用户故事和功能需求
├── plan.md         # 技术架构和决策
├── tasks.md        # 带依赖关系的工作分解
├── data-model.md   # 数据库 schema
├── contracts/      # REST API 契约
└── research.md     # 技术栈验证

.specify/
├── memory/
│   └── constitution.md    # 项目治理原则
├── templates/
└── presets/

注意 specs/ 和 .specify/ 是两个不同的目录，前者是功能级别的规范，后者是项目级别的配置。

5 分钟上手：从安装到第一个 spec

理论说完了，直接上手。

环境准备

Spec Kit 依赖 Python 3.11+ 和 uv 包管理器。先确认 uv 已安装：

uv --version

如果没有 uv，一行命令安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

第一步：安装 specify-cli

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.9.5

安装完成后验证：

specify --version

预期输出类似：

specify-cli 0.9.5

“踩坑记录：如果你用的是较老版本的 uv，可能遇到 No module named 'specify' 错误。先执行 uv self update 升级 uv，再重新安装。

第二步：初始化项目

在你的项目根目录执行：

specify init my-project --integration claude

--integration 参数指定你用的 AI 工具。支持的值包括 claude、copilot、gemini、cursor、codex 等，完整列表用 specify integration list 查看。

对于 Claude Code 用户，这一步会以 Skill 模式安装，而不是 slash commands——这意味着规范命令会以 Claude Code 的 Skill 形式加载进来，而不是普通的斜杠命令。这个区别在实际使用时几乎感知不到，但底层机制不同。

第三步：建立项目规范（constitution）

在 Claude Code 里执行：

/speckit.constitution

这一步会生成 .specify/memory/constitution.md，内容是你的项目治理原则：技术栈约定、代码风格要求、不允许引入的依赖、安全要求等。

一个实际的 constitution.md 片段是这样的：

# 项目治理原则

## 技术栈约定
- 后端：Java 17 + Spring Boot 3.x
- 数据库：MySQL 8.0，禁止使用 JSON 字段做核心业务查询
- ORM：MyBatis-Plus，禁止写原生 SQL 到 Service 层

## 性能要求
- 列表接口 P99 ≤ 200ms（数据量 < 100 万时）
- 分页必须在数据库层面完成，禁止前端分页

## 禁止行为
- 禁止在 Controller 层写业务逻辑
- 禁止 @Transactional 注解用在 private 方法上

这个文件写得越详细，后续每个 spec 的质量就越高——因为 AI 在生成 plan 和 tasks 时，会把这些约束自动带进去。

第四步：写第一个 spec

假设你要实现「用户列表按注册时间排序」这个功能，在 Claude Code 里执行：

/speckit.specify

AI 会引导你描述需求，最终生成 specs/001-user-list-sort/spec.md。

一个规范的 spec.md 长这样：

# 用户列表排序功能

## 背景
运营团队需要能够按注册时间对用户列表进行排序，以便优先联系最新注册的用户。

## 用户故事
作为运营人员，我希望能够在用户列表页按注册时间（升序/降序）排序，
以便我能快速定位需要跟进的新用户。

## 功能需求
- 支持按 `registered_at` 字段排序（非 `created_at`）
- 默认按注册时间降序
- 排序必须在数据库层面完成，支持分页场景下的正确性
- 前端控件：列表头部的可点击排序箭头

## 不在范围内
- 多字段组合排序
- 排序偏好的持久化（不记忆用户上次的排序选择）

## 验收标准
- [ ] 10 万条数据量下，排序接口响应 < 200ms
- [ ] 排序与分页同时使用时，结果正确

注意 spec.md 里只写「什么」和「为什么」，不写技术实现细节——字段用哪个索引、接口参数怎么设计，这些留给下一步的 plan.md 处理。

第五步：生成计划和任务

/speckit.plan    # 生成技术架构方案
/speckit.clarify # （可选但强烈建议）让 AI 提出它的困惑点，你来回答
/speckit.tasks   # 生成带依赖关系的任务清单
/speckit.analyze # 验证各文件之间的一致性

analyze 完成后，执行：

/speckit.implement

AI 会系统性地执行 tasks.md 里的每一个任务，而不是「猜着写」。

完整流程总结：

Spec Kit 七步工作流：从 constitution 到 implement 的完整路径

图：Spec Kit 七步工作流，每一步都有明确的输入和输出，AI 在整个过程中是执行者而非决策者

一张对比图：vibe coding vs SDD 的真实差异

光说原理不够直观，我来画一张更具体的对比。

假设你要开发「用户注册邮件验证」功能。

vibe coding 路径：

第 1 轮 Prompt：「帮我实现用户注册的邮件验证功能」 → AI 给了一个完整的实现，用了某个邮件库，有验证码逻辑

第 2 轮：「验证码的有效期改成 10 分钟」 → AI 改了，但顺便把验证码长度也改了（你没说保持不变）

第 3 轮：「验证链接要包含用户 ID 吗？」 → AI 说「可以」，然后改了实现，但新的 URL 格式和你的路由配置冲突了

第 4 轮：「路由报 404」 → ...

SDD 路径（Spec Kit）：

spec.md 里明确写了：

• 验证方式：链接，不是验证码
• 有效期：10 分钟
• URL 格式：/verify?token={jwt_token}，token 包含 user_id，不暴露在 URL 里
• 依赖库：已有的 spring-boot-starter-mail，不引入新依赖

plan.md 里明确写了：

• 用 Redis 存储 token，key 格式 email:verify:{token}，TTL 10 分钟
• 验证接口 GET /verify 的参数和响应格式

tasks.md 里明确写了：

• Task 1：Redis 存储逻辑（无前置依赖）
• Task 2：邮件发送服务（依赖 Task 1）
• Task 3：验证接口（依赖 Task 1）
• Task 4：前端「已发送验证邮件」提示页（无后端依赖）

AI 执行 /speckit.implement 的时候，它知道每一个 task 要做什么、不能做什么、依赖什么。33 个 task，逐一 ✅。

这不是说 SDD 没有返工，而是返工发生在「写文档」阶段，而不是「跑测试」阶段——在 spec 里改一行字的代价，远低于在代码里 debug 一个小时。

vibe coding vs 规范驱动开发的返工成本对比

图：两种模式下的返工时机对比——SDD 把问题暴露在「写规范」阶段，vibe coding 把问题留到「跑代码」阶段

这套方法的边界在哪里

Spec Kit 不是银弹，有几个场景它不适合：

1. 5 分钟的快速原型

如果你只是想看看「这个 API 能不能用」「这个 UI 大概长什么样」，vibe coding 更快。Spec Kit 的七步工作流是有成本的，这个成本在原型验证阶段不划算。

2. 需求高度不确定的探索期

如果你连「要做什么」都还没想清楚，写 spec 会很痛苦——你不知道要往里填什么，或者每天都在改。这个阶段 vibe coding 反而是合理的，因为你在用代码来探索需求。

3. 独立开发者的个人小项目

五步规范流程对一个人做的小工具来说太重了。不过即使不用完整流程，constitution.md 这个单一文件就值得写——它相当于你给 AI 的全局配置，比每次 Prompt 里重复说约束高效得多。

Spec Kit 真正发挥价值的场景是：

• 多人协作项目，AI 需要和不同成员的约定保持一致
• 功能复杂度高，涉及多个模块和接口契约
• 有遗留系统，需要在已有代码约定下做新开发
• 对交付质量有明确验收标准的功能

用 GitHub 自己的分类：绿地新项目（greenfield）、已有系统加功能（N+1）、遗留系统改造——Spec Kit 对这三类都有具体的预设支持。

目前它已经有 105 个社区扩展、22 个预设，包括专门针对 Spring Boot 项目、Go 微服务、前端组件库的特化版本。装完基础工具后，用 specify extension list 可以看到完整目录。

常见问题

Q：写 spec.md 很花时间，我这种快节奏团队用得起吗？

这个问题的隐含假设是「写文档 = 额外成本」。换个角度：你现在花在解释需求、修 AI 的错、合并冲突上的时间，有多少？spec.md 把这些成本前置了。按 Peter Saktor 的实测经验，完整走完 Spec Kit 流程的项目，33 个任务全部正确完成，0 编译错误——而不走规范流程时，同等复杂度的功能通常需要多轮返工。

Q：Spec Kit 支持中文写 spec 吗？

完全支持。constitution.md 和 spec.md 都可以用中文写，AI 理解没有问题。甚至更推荐中文写——因为你的团队用中文思考需求，写规范的时候用中文更不容易出现翻译层的信息损耗。

Q：我现在用 Cursor，需要换工具吗？

不需要。Spec Kit 支持 Cursor 的 .cursorrules 模式，specify init my-project --integration cursor 就行。它的设计本来就是工具无关的，规范文件（spec.md/plan.md/tasks.md）是纯 Markdown，任何 AI 工具都能读。

Q：Spec Kit 本身会过时吗？

这是个好问题。AGENTS.md 和 CLAUDE.md 这类「AI 配置文件」的生态已经在快速标准化，Linux Foundation 旗下已有 60+ 工具支持 AGENTS.md 这个格式。Spec Kit 的 constitution.md 是这一趋势的进化版——如果说 AGENTS.md 是给 AI 的使用说明书，constitution.md 是给 AI 的工程契约。方向是对的，标准化程度只会越来越高。

Q：规范文件太详细会不会限制 AI 发挥？

这里有个认知误区：我们不是想让 AI「发挥创意」，我们想让 AI「准确执行意图」。规范文件限制的不是 AI 的能力，是 AI 的猜测空间——让它少猜，多做。生产代码里 AI 的「创意发挥」，大多数情况下是麻烦的来源，而不是价值的来源。

总结

说到底，Spec Kit 解决的不是「怎么跟 AI 说话」的问题，是「把什么东西告诉 AI」的问题。Prompt 再好，也只是在优化「信息传递的效率」；spec.md 改变的是「你给 AI 的信息结构」——这两件事的量级不在同一个层面。

我在几个项目里推广下来的感受是：前三次用 Spec Kit 会觉得「这也太繁琐了」，第四次开始就不想回去了，因为你会清楚地感受到少返工有多爽。下一篇打算拆解 constitution.md 的完整写法，给出针对不同技术栈的中文模板，感兴趣的关注一下。如果你身边有团队正在规模化推广 AI 编码，这篇可以直接甩给他们，比重新解释一遍省事。