使用 Claude Code 进行 AI 编码开发新功能时，开发者常常会遇到这样的场景：需求描述得非常清晰——「在用户列表页面中，增加一个按注册时间排序的功能」。

AI 生成的代码看起来十分完整，涵盖了接口层、Service 服务层以及前端组件。然而，真正运行起来后才发现问题所在：排序逻辑竟然是基于前端分页后的本地数据排序，并非数据库层面的排序。一旦数据量增加，这套方案便完全失效。

修复了这个问题后，又发现 AI 使用的是创建时间字段，而非预期的注册时间字段。

仅仅编写 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 就能为你搭建一个可运行的雏形，五分钟内即可看到效果。

然而，一旦进入真正的功能开发阶段，这种模式会暴露出一个内在矛盾：

AI Agent 并非搜索引擎，它是「字面意思的忠实执行者」。

当你提出「增加一个排序功能」时，它就会添加排序功能。但它无法判断你的数据量有多大，不清楚你的分页逻辑位于哪一层，也不了解「注册时间」和「创建时间」在你的数据表结构中是否为同一个字段。AI 会基于它认为「合理」的猜测，来填补所有这些模糊不清的空间。

这正是 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 的信息结构——需求散落在对话中，AI 每次都在猜测；右侧是 SDD 的信息结构——spec.md 作为唯一真相源，AI 从此处获取信息

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

Spec Kit 的安装过程非常简便，其核心是一套七步工作流，每一步都会生成一个文件，这些文件共同构成一个功能的「完整规范体系」。

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

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

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

七步工作流全景

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

有实践者在完整完成一个 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

第二步：初始化项目

在项目的根目录下执行以下命令：

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，禁止在 Service 层编写原生 SQL
## 性能要求
- 列表接口 P99 响应时间 ≤ 200ms（数据量 < 100 万时）
- 分页必须在数据库层面完成，禁止前端分页
## 禁止行为
- 禁止在 Controller 层编写业务逻辑
- 禁止在 private 方法上使用 @Transactional 注解

这个文件编写得越详细，后续每个 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 七步工作流，每一步都有明确的输入和输出，AI 在整个过程中扮演的是执行者而非决策者

一张对比图：vibe coding 与 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 中修改一行文字的代价，远低于在代码中调试一个小时。

图：两种模式下的返工时机对比——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 的「创意发挥」大多数情况下是麻烦的来源，而非价值的来源。

参考资料

• GitHub Spec Kit 官方仓库（当前版本 v0.9.5，2026 年 6 月 5 日发布）
• Spec-driven development with AI: Get started with a new open source toolkit（GitHub 官方博客）
• GitHub Spec Kit Documentation（官方文档）

总而言之，Spec Kit 解决的不是「如何与 AI 对话」的问题，而是「应该把什么信息告诉 AI」的问题。Prompt 编写得再好，也只是在优化「信息传递的效率」；而 spec.md 则改变了「你提供给 AI 的信息结构」——这两件事的重要程度不在同一个层面。

从多个项目的推广经验来看，前三次使用 Spec Kit 时会觉得「这也太繁琐了」，但从第四次开始就不想再回到过去的方式了，因为你能清晰地感受到减少返工是多么令人愉悦。下一篇计划深入拆解 constitution.md 的完整编写方法，并提供针对不同技术栈的中文模板。如果你身边有团队正在规模化推广 AI 编码，这篇文章可以直接分享给他们，比重新解释一遍要省事得多。