Spec Kit 使用指南

基于 GitHub Spec Kit v0.0.79 - 面向 AI 的规范驱动开发工具包

📚 目录

• 什么是 Spec Kit
• 核心理念
• 四阶段工作流
• 命令详解
• 实战示例
• 最佳实践
• 常见问题

什么是 Spec Kit

Spec Kit 是 GitHub 于 2025 年 9 月发布的开源工具包，专门为 AI 辅助编程设计的**规范驱动开发（Spec-Driven Development, SDD）**框架。

解决的核心问题

❌ 传统 AI 编程问题（“Vibe Coding”）：

• 直接让 AI 写代码 → 不知道 AI 会生成什么
• 需求模糊 → AI 基于模式补全而非真正理解意图
• 缺少检查点 → 发现问题时已经写了大量代码
• 文档滞后 → 代码写完才补文档

✅ Spec Kit 的解决方案：

• 先定义规范再写代码 → AI 知道要构建什么
• 分阶段验证 → 每个阶段都有明确的检查点
• 规范即文档 → 规范就是活文档，与代码同步演进
• 架构前置 → 技术决策在编码前确定

核心理念

规范驱动开发三原则

1. 规范是唯一真相来源（Single Source of Truth）

   • 规范定义”是什么”和”为什么”
   • 计划定义”怎么做”
   • 任务定义”具体做什么”

2. 明确检查点（Explicit Checkpoints）

   • 每个阶段完成后必须人工审核
   • 发现问题在当前阶段修正，而非继续前进
   • 避免”垃圾输入，垃圾输出”

3. AI 作为字面化搭档（Literal-Minded Pair Programmer）

   • 不要把 AI 当搜索引擎
   • 给 AI 清晰的指令和上下文
   • AI 擅长模式匹配，但不擅长读心术

四阶段工作流

      Constitution → Specify → Plan → Tasks → Implement
    ↓            ↓        ↓       ↓        ↓
  项目原则    需求规范   技术方案  任务分解   代码实现
    

阶段 0: Constitution（项目宪法）

目的：建立项目的不可协商原则

命令：/speckit.constitution

输出：.specify/memory/constitution.md

包含内容：

• 核心开发原则（如：测试优先、模块化架构）
• 技术栈约束（必须使用的框架/工具）
• 质量门禁（部署前必须通过的检查）
• 治理规则（如何修改宪法、代码审查标准）

何时使用：

• ✅ 项目初始化时（只需要做一次）
• ✅ 项目架构重大变更时
• ❌ 每次开发新功能时（不需要重复）

阶段 1: Specify（需求规范）

目的：定义功能的”是什么”和”为什么”，不涉及”怎么做”

命令：/speckit.specify

输出：.specify/memory/spec.md

关注点：

• 用户故事（谁、要做什么、为什么）
• 验收标准（如何验证功能完成）
• 用户旅程（用户如何与功能交互）
• 成功指标（如何衡量功能成功）

示例输入：

      我想添加一个用户积分系统：
- 用户发布内容可以获得积分
- 积分可以兑换特殊权益（如头像框、徽章）
- 管理员可以手动调整用户积分
- 需要有积分历史记录
    

NOT 规范中的内容（这些留给 Plan 阶段）：

• ❌ 使用 PostgreSQL 还是 MySQL
• ❌ API 端点设计
• ❌ 数据库表结构

最佳实践：

• ✅ 第一次输入尽可能详细（减少后续迭代）
• ✅ 描述边界情况（如：积分不能为负）
• ✅ 说明不做什么（明确范围）

阶段 2: Plan（技术方案）

目的：定义”怎么做”——技术架构和实现策略

命令：/speckit.plan

输出：.specify/memory/plan.md

关注点：

• 技术栈选择（框架、库、数据库）
• 架构决策（模块划分、API 设计）
• 数据流（数据如何在系统中流动）
• 外部依赖（第三方服务、API）
• 安全考量（认证、授权、数据保护）

示例输入：

      技术约束：
- 必须使用 Cloudflare D1 数据库（项目标准）
- 遵循项目的 Module-First 架构
- 使用 Drizzle ORM + Zod 验证
- API 遵循 REST 和 RPC 双模式
    

输出示例：

      ## 模块设计
- 创建 `credits` 模块
  - `credits.table.ts` - 积分表和积分历史表
  - `credits.handlers.ts` - 积分逻辑（增加/扣减/兑换）
  - `credits.routes.ts` - REST API
  - `credits.rpc.ts` - RPC API

## 数据库设计
- `credits` 表：用户 ID、当前积分、更新时间
- `credit_transactions` 表：交易历史、类型、金额、原因

## API 端点
- GET /credits/:userId - 获取用户积分
- POST /credits/earn - 赚取积分
- POST /credits/redeem - 兑换积分
- GET /credits/history - 积分历史
    

最佳实践：

• ✅ 引用项目 Constitution 中的原则
• ✅ 说明为什么选择某技术（而非仅列举）
• ✅ 识别潜在风险和缓解措施

阶段 3: Tasks（任务分解）

目的：将 Plan 拆解为可执行的原子任务

命令：/speckit.tasks

输出：.specify/memory/tasks.md

关注点：

• 任务粒度（每个任务 < 200 行代码）
• 依赖关系（任务执行顺序）
• 并行机会（哪些任务可以同时做）
• 测试要求（每个任务的测试覆盖）

输出示例：

      ## 任务列表

### 数据库层 (可并行)
- [ ] Task 1: 创建 credits 表结构
  - 文件: `src/server/modules/credits/credits.table.ts`
  - 测试: 表结构验证

- [ ] Task 2: 创建 credit_transactions 表结构
  - 文件: `src/server/modules/credits/credits.table.ts`
  - 测试: 表结构验证

### 业务逻辑层 (依赖数据库层)
- [ ] Task 3: 实现积分增加逻辑
  - 文件: `src/server/modules/credits/credits.handlers.ts`
  - 依赖: Task 1, 2
  - 测试: 单元测试 + 集成测试

- [ ] Task 4: 实现积分兑换逻辑
  - 文件: `src/server/modules/credits/credits.handlers.ts`
  - 依赖: Task 3
  - 测试: 边界情况测试（余额不足）

### API 层 (依赖业务逻辑层)
- [ ] Task 5: 创建 REST API 路由
  - 文件: `src/server/modules/credits/credits.routes.ts`
  - 依赖: Task 3, 4
  - 测试: API 集成测试
    

最佳实践：

• ✅ 每个任务独立可测试
• ✅ 明确文件路径（AI 知道写到哪里）
• ✅ 标注依赖关系（避免顺序错误）
• ✅ 遵循 TDD（先写测试，再实现）

阶段 4: Implement（代码实现）

目的：按任务逐个实现代码

命令：/speckit.implement

工作方式：

1. AI 按照 Tasks 列表逐个实现
2. 每个任务实现完成后，开发者审核
3. 审核通过后，继续下一个任务
4. 如有问题，修改后再继续

AI 的优势：

• ✅ AI 知道要构建什么（Spec 告诉它）
• ✅ AI 知道怎么构建（Plan 告诉它）
• ✅ AI 知道当前做什么（Task 告诉它）

审核要点：

• 代码是否符合 Constitution 原则
• 是否通过所有测试
• 是否有未处理的边界情况
• 代码可读性和可维护性

命令详解

核心命令

增强命令（可选）

实战示例

场景：为 itypol2 添加用户积分系统

Step 0: Constitution（已完成）

      ✅ 已创建 itypol2 Constitution v1.0.0
- Module-First 架构
- Database-First 工作流
- 端到端类型安全
    

Step 1: Specify

      /speckit.specify

我想为 itypol2 添加用户积分系统：

【功能描述】
- 用户通过以下行为获得积分：
  - 发布内容：+10 积分
  - 内容被点赞：+2 积分/次
  - 每日登录：+5 积分
- 积分可以兑换权益：
  - 100 积分 → 专属头像框
  - 500 积分 → 作者徽章
  - 1000 积分 → VIP 标识
- 管理员功能：
  - 手动调整任意用户积分（需审计日志）
  - 查看积分统计报表

【边界条件】
- 积分不能为负数
- 兑换后积分扣除，但不可退款
- 积分历史永久保留（用于审计）

【不包含的功能】
- 积分过期机制（v1 不做）
- 积分转赠功能（v1 不做）
- 积分商城（单独项目）
    

AI 会生成详细的 spec.md，包含：

• 用户故事（5-10 个）
• 验收标准（明确的可测试条件）
• 用户旅程（从获得积分到兑换的流程）
• 成功指标（如：90% 用户完成首次兑换）

审核要点：

• ✅ 是否覆盖所有场景
• ✅ 是否有遗漏的边界情况
• ✅ 验收标准是否可测试

Step 2: Plan

      /speckit.plan

技术约束：
- 遵循 itypol2 Constitution 原则
- 使用 Cloudflare D1 + Drizzle ORM
- 使用 bun run scaffold:module credits 生成模块
- API 遵循 REST + RPC 双模式
- 所有操作需要 Google OAuth 认证
    

AI 会生成 plan.md，包含：

• 模块结构（符合 Module-First）
• 数据库设计（credits 表 + credit_transactions 表）
• API 设计（6 个端点）
• 认证策略（Better Auth 中间件）
• 迁移计划（如何从现有系统集成）

审核要点：

• ✅ 是否符合 Constitution 原则
• ✅ 数据库设计是否规范
• ✅ API 设计是否 RESTful

Step 3: Tasks

      /speckit.tasks
    

AI 会生成 tasks.md，包含：

      ## Phase 1: 数据库层（可并行）
- [ ] Task 1.1: 定义 credits 表
- [ ] Task 1.2: 定义 credit_transactions 表
- [ ] Task 1.3: 生成并应用迁移

## Phase 2: 业务逻辑层（依赖 Phase 1）
- [ ] Task 2.1: 实现积分增加 handler
- [ ] Task 2.2: 实现积分兑换 handler
- [ ] Task 2.3: 实现积分历史查询 handler
- [ ] Task 2.4: 实现管理员调整 handler

## Phase 3: API 层（依赖 Phase 2）
- [ ] Task 3.1: 创建 REST routes
- [ ] Task 3.2: 创建 RPC routes
- [ ] Task 3.3: 添加 OpenAPI 文档

## Phase 4: 测试（与 Phase 2-3 并行）
- [ ] Task 4.1: 单元测试 - handlers
- [ ] Task 4.2: 集成测试 - API
- [ ] Task 4.3: 边界测试 - 余额不足等
    

审核要点：

• ✅ 任务粒度是否合理
• ✅ 依赖关系是否正确
• ✅ 是否包含测试任务

Step 4: Implement

      /speckit.implement
    

AI 会按顺序执行：

1. 创建数据库表 → 等待审核
2. 实现业务逻辑 → 等待审核
3. 创建 API 路由 → 等待审核
4. 编写测试 → 等待审核

每步审核后才继续下一步。

最佳实践

✅ DO（推荐做法）

1. 详细的初始输入

   • 第一次 /speckit.specify 时，尽可能详细描述需求
   • 包含边界条件、不做什么、优先级
   • 减少后续来回修改

2. 遵循检查点

   • 每个阶段完成后必须审核
   • 发现问题立即修正，不要带到下一阶段
   • 审核通过才运行下一个命令

3. 引用 Constitution

   • 在 Plan 中明确引用项目原则
   • 让 AI 理解项目的约束和标准
   • 保持代码风格一致

4. 小任务优于大任务

   • 每个任务 < 200 行代码
   • 任务独立可测试
   • 便于审核和调试

5. 活文档思维

   • 规范随代码演进
   • 修改代码时同步更新规范
   • 规范即文档

❌ DON’T（避免做法）

1. 跳过阶段

   • ❌ 不要直接从 Specify 跳到 Implement
   • ❌ 不要省略 Plan（会导致架构混乱）

2. 模糊输入

   • ❌ “帮我做一个用户系统”（太宽泛）
   • ✅ “用户系统包含注册、登录、个人资料编辑，使用 Google OAuth”

3. 忽略 Constitution

   • ❌ 不要在 Plan 中使用未批准的技术栈
   • ❌ 不要违反项目原则（如跳过测试）

4. 过大的任务

   • ❌ “实现整个积分系统”（太大）
   • ✅ “实现积分增加逻辑”（合理）

5. 文档滞后

   • ❌ 代码改了但规范不更新
   • ❌ 规范与实际代码不一致

常见问题

Q1: 什么时候适合用 Spec Kit？

适合场景：

• ✅ 绿地项目（全新项目）
• ✅ 大型功能开发（需要多个模块配合）
• ✅ 遗留系统现代化（需要清晰的架构决策）
• ✅ 团队协作项目（需要统一标准）

不适合场景：

• ❌ 简单 bug 修复（几行代码）
• ❌ 紧急热修复（时间紧迫）
• ❌ 实验性原型（需求不明确）

Q2: 每次都要从 Constitution 开始吗？

不需要！

• Constitution 只在项目初始化时创建一次
• 后续每个功能从 Specify 开始即可
• 只有在项目架构重大变更时才更新 Constitution

Q3: 如果 AI 生成的内容不符合预期怎么办？

解决方案：

1. 当前阶段修正 - 直接修改生成的文件（如 spec.md）
2. 重新运行命令 - 提供更详细的输入重新生成
3. 使用 /speckit.clarify - 让 AI 提问澄清需求
4. 不要继续前进 - 当前阶段不满意就不要进入下一阶段

Q4: Tasks 太多怎么办？

策略：

• 分批实现 - 不需要一次完成所有任务
• MVP 优先 - 先实现核心功能，再扩展
• 并行开发 - 标记可并行的任务，提高效率

Q5: 如何处理需求变更？

流程：

1. 更新 Spec - 修改 spec.md 反映新需求
2. 重新 Plan - 运行 /speckit.plan（如果架构变化）
3. 调整 Tasks - 更新或新增任务
4. 版本控制 - 提交规范变更到 Git

Q6: Spec Kit 和传统开发流程的区别？

总结

核心价值

1. 降低认知负荷 - 每次只关注一个阶段
2. 提高代码质量 - 架构前置，避免返工
3. 改善 AI 输出 - 清晰上下文 → 准确代码
4. 活文档系统 - 规范与代码同步演进
5. 团队协作 - 统一标准和流程

快速开始

      # 1. 已完成：初始化 Spec Kit
✅ itypol2 已配置好 Spec Kit

# 2. 开始第一个功能
/speckit.specify
[详细描述你的功能需求]

# 3. 后续按流程
/speckit.plan → /speckit.tasks → /speckit.implement
    

进一步学习

• 官方仓库: https://github.com/github/spec-kit
• 博客文章: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• 社区讨论: GitHub Issues & Discussions

祝你使用 Spec Kit 愉快！🚀