为什么 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）
• 默认按注册时间降序
• 排序必须在数据库层面完成，支持分页场景下的正确性
• 前端控件：列表头部的可点击排序箭头

不在范围内

• 多字段组合排序
• 排序偏好的持久化（不记忆用户上次的排序选择）