上个月我在用 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 是先写规范，让规范驱动代码生成。这个顺序的改变，意义远大于工具本身的功能。

七步工作流全景
步骤 命令 生成文件 核心作用
1 /speckit.constitution .specify/memory/constitution.md 项目治理原则，所有后续决策的底线
2 /speckit.specify specs/[FEATURE]/spec.md 用户故事和功能需求（only「what」和「why」）
3 /speckit.plan specs/[FEATURE]/plan.md 技术架构和技术栈选型
4 /speckit.clarify — 解决歧义，提前暴露假设
5 /speckit.tasks specs/[FEATURE]/tasks.md 带依赖关系的任务清单
6 /speckit.analyze — 跨文件一致性验证
7 /speckit.implement 实际代码 系统性执行所有任务
这七步里，最容易被跳过的是第 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）