规范驱动的 Vibe Coding：Spec-Kit 实践指南

用 GitHub 的官方工具，把 AI 代码生成从"氛围抽卡"变成可重复的规范驱动流程。

为什么 Vibe Coding 需要规范？

Vibe Coding 的问题是prompt 决定质量：模糊的 prompt 产生模糊的输出，明确的规范产生精准的结果。

Spec-Kit 的核心观点：不是 AI 不够好，是给你的上下文不够结构化。Spec-Kit 在需求和代码之间插入两个刻意步骤——规范（Spec）和规划（Plan），让 AI 拿着精确的上下文去实现，而不是对着自由格式的 prompt 猜测。

Spec-Kit 是什么？

Spec-Kit 是 GitHub 官方开源的 Spec-Driven Development（SDD） 工具包，通过结构化的 CLI 和 slash commands，让任何 AI 编码助手都能遵循规范驱动的开发流程。

核心理念

"规格成为可执行的艺术品，不是用完即弃的脚手架"

SDD 翻转了传统软件开发：代码不再是事实来源，规范才是。修改规范，重新生成代码——就像编译语言中源代码是事实来源一样。

核心特性

  • 规范优先：Spec → Plan → Tasks → Implement，每个阶段产出文档驱动下一个阶段
  • 30+ AI 工具支持：Claude Code、Copilot、Cursor、Gemini CLI、Windsurf 等，开源社区最广
  • 可扩展：91 个社区扩展、18 个预设，可以完全替换核心流程
  • 离线可用：可在防火墙后运行，支持 Windows/macOS/Linux

Spec-Kit vs OpenSpec vs BMad

维度 Spec-Kit OpenSpec BMad
出品方 GitHub Fission AI 社区
stars 100k+ 48k+ 43k+
工作流 6 阶段（Constitution → Specify → Clarify → Plan → Tasks → Implement） 轻量（propose → apply） 多 Agent 团队协作
AI Agent 支持 30+ 20+ 12+
扩展性 预设 + 扩展 自定义 Schema 自定义 Agent + Workflow
适用场景 中等复杂度，单人/小团队 Brownfield 项目 复杂产品，多角色
学习曲线 中等 低 较高

核心概念

1. Constitution（宪法）

项目层面的不变原则——编码标准、架构约束、团队规范。在任何代码生成之前建立，确保所有决策符合团队的规则。

# Constitution

## 不可变原则
- 所有 API 必须有版本控制（v1, v2）
- 数据库操作必须使用事务
- 禁止直接操作 DOM，使用框架抽象

## 代码风格
- TypeScript 严格模式
- 函数不超过 50 行
- 测试覆盖率不低于 80%

2. Specify（规范）

描述要构建什么——聚焦"做什么"和"为什么"，不包括技术细节。

# Spec: 用户认证

## 用户故事

### Story: 用户注册
- **角色**：新用户
- **想要**：通过邮箱注册账户
- **原因**：成为系统用户并使用功能

### 验收标准
- **GIVEN** 邮箱未被占用
- **WHEN** 提交有效注册信息
- **THEN** 创建账户并返回 JWT

## 边界情况
- 邮箱格式验证
- 密码强度要求（8+ 字符，包含数字和特殊字符）
- 用户名唯一性检查

3. Clarify（澄清）

AI 主动识别规范中的模糊之处并提问。这是在实现前发现需求漏洞——成本最低的时候。

典型 AI 提问：

  • "注册后是否需要邮箱验证？"
  • "密码重置流程是什么？"
  • "会话有效期是多久？"

4. Plan（规划）

技术方案阶段——在这里指定技术栈、架构、数据模型。AI 基于 Constitution 和 Spec 生成完整的技术计划。

# Plan: 用户认证

## 技术选型
- 后端：Node.js + Express
- 数据库：PostgreSQL
- 认证：JWT（jsonwebtoken）
- 验证：Zod

## 目录结构
```
src/
├── routes/auth.ts      # 认证路由
├── middleware/auth.ts  # JWT 验证中间件
├── models/user.ts      # 用户模型
└── db/index.ts         # 数据库初始化
```

## API 设计

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /auth/register | 用户注册 |
| POST | /auth/login | 用户登录 |
| POST | /auth/refresh | 刷新 Token |

## 数据模型
```typescript
interface User {
  id: string;
  email: string;
  username: string;
  passwordHash: string;
  createdAt: Date;
}
```

5. Tasks（任务分解）

把 Plan 拆成小的、可独立实现的、有序的任务。每个任务足够小，可以在一个 AI session 内完成。

# Tasks: 用户认证

## 任务列表

### Task 1: 项目初始化
- [ ] 初始化 npm 项目
- [ ] 安装依赖（express, pg, jsonwebtoken, zod）
- [ ] 配置 TypeScript

### Task 2: 数据库层
- [ ] 创建 `src/db/index.ts`
- [ ] 实现 users 表迁移
- [ ] 创建 User 模型

### Task 3: 认证路由
- [ ] 实现 POST /auth/register
- [ ] 实现 POST /auth/login
- [ ] 实现 POST /auth/refresh

### Task 4: 中间件
- [ ] 实现 JWT 验证中间件
- [ ] 实现错误处理

### Task 5: 测试
- [ ] 单元测试：User 模型
- [ ] 集成测试：认证 API

6. Implement（实现）

执行所有任务——按照 Tasks 的顺序，一个一个实现。

工作流命令

初始化项目后，AI Agent 获得以下 slash commands：

命令 用途
/speckit.constitution 建立项目宪法（首先运行一次）
/speckit.specify 定义要构建什么
/speckit.clarify 识别并解决模糊点
/speckit.plan 生成技术实现计划
/speckit.analyze 跨工件一致性分析
/speckit.tasks 产出有序任务列表
/speckit.implement 执行所有任务

安装与初始化

# 安装（推荐方式）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 或 pipx
pipx install git+https://github.com/github/spec-kit.git

初始化项目

# 指定 AI 代理
specify init my-project --ai claude

# 支持的 AI 代理
--ai claude          # Claude Code
--ai copilot          # GitHub Copilot
--ai cursor           # Cursor
--ai gemini           # Gemini CLI
--ai windsurf         # Windsurf
--ai generic          # 任何其他 AI 工具

# 当前目录初始化
specify init . --ai claude

# 跳过 git 初始化
specify init my-project --ai claude --no-git

初始化后项目结构：

my-project/
├── .specify/              # SDD 模板和脚本
│   ├── spec-template.md
│   ├── plan-template.md
│   ├── tasks-template.md
│   └── constitution.md
├── .github/               # AI Agent 特定的 prompt 定义
│   ├── specify.prompt.md
│   ├── plan.prompt.md
│   └── tasks.prompt.md
└── src/                   # 你的代码

完整示例：构建一个任务管理 API

Step 1: 初始化

specify init task-api --ai claude
cd task-api

Step 2: 创建 Constitution

在 Claude Code 中运行：

/speckit.constitution

输入项目宪法：

## 项目宪法

## 不可变原则
- RESTful API 设计
- 所有端点需要认证（/auth 除外）
- 错误响应使用标准 HTTP 状态码

## 技术约束
- Node.js + Express
- TypeScript 严格模式
- 使用 Zod 做请求验证
- 单元测试覆盖率 ≥ 80%

## 代码风格
- 单一职责原则
- 函数不超过 40 行
- 所有文件名小写 + 连字符

Step 3: 创建 Spec

/speckit.specify

描述要构建的内容：

构建一个任务管理 API，支持：
- 用户注册和登录（JWT）
- CRUD 任务（创建、读取、更新、删除）
- 任务支持标记完成
- 任务列表支持分页和筛选

AI 生成完整规范，包含用户故事、验收标准、边界情况。

Step 4: 澄清

/speckit.clarify

AI 会问：

  • "任务是否需要支持子任务？"
  • "删除任务是否需要软删除？"
  • "列表是否需要排序选项？"

回答后，Spec 更新为更完整的版本。

Step 5: 生成 Plan

/speckit.plan

AI 基于 Constitution 和 Spec 生成：

  • 目录结构
  • API 端点设计
  • 数据模型
  • 技术决策及理由

Step 6: 生成 Tasks

/speckit.tasks

Plan 被拆成有序任务列表：

  • Task 1: 项目初始化 + 安装依赖
  • Task 2: 数据库设置
  • Task 3: 用户认证（注册/登录）
  • Task 4: 任务 CRUD
  • Task 5: 任务列表（分页/筛选）
  • Task 6: 测试

Step 7: 实现

/speckit.implement

AI 按照 Tasks 顺序，一个一个实现，并在每个任务后标记 [x]。

扩展与预设

社区扩展（91 个）

扩展 用途
CI Guard 规范合规检查，进入 CI
Architecture Guard 架构约束验证

预设（18 个）

可以替换默认的 SDD 流程：

预设 说明
AIDE 7 步 AI 驱动工程生命周期
Canon 基线驱动工作流（规范优先/代码优先/规范漂移）
Product Forge 产品管理导向的 SDD
MAQA 多 Agent 编排 + 质量保证门禁

为什么 Spec-Kit 能解决 Vibe Coding 的问题？

Vibe Coding 的问题 Spec-Kit 的解法
prompt 模糊导致输出不确定 规范 + 澄清阶段，确保需求清晰
上下文在聊天中丢失 每个阶段产出文档，持久化在代码库
缺乏验收标准 Clarify 阶段明确验收标准（Given/When/Then）
技术决策临时性 Plan 阶段记录技术选型及理由
任务分解主观 Tasks 阶段自动生成有序任务列表
无法跨 Agent 保持一致 Constitution 确保所有决策符合团队规则

何时用 Spec-Kit？

场景 推荐度
独立开发者，中小功能 ⭐⭐⭐⭐
小团队，3-5 人项目 ⭐⭐⭐⭐
已有代码库的功能迭代 ⭐⭐⭐
复杂产品，多 Agent 协作 ⭐⭐（用 BMad）
快速原型验证 ⭐⭐（用 OpenSpec）

参考资源