Spec Kit 学习指南

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

📖 目录

1. 快速概览
2. 核心理念
3. 四阶段工作流详解
4. 命令参考手册
5. 实战案例演练
6. 最佳实践指南
7. 常见问题解答

🚀 快速概览

什么是 Spec Kit？

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

解决的核心问题

❌ 传统 AI 编程问题	✅ Spec Kit 解决方案
直接让 AI 写代码 → 不知道 AI 会生成什么	📋 先定义规范再写代码 → AI 知道要构建什么
需求模糊 → AI 基于模式补全而非真正理解意图	🎯 分阶段验证 → 每个阶段都有明确的检查点
缺少检查点 → 发现问题时已经写了大量代码	⚙️ 规范即文档 → 规范就是活文档，与代码同步演进
文档滞后 → 代码写完才补文档	🏗️ 架构前置 → 技术决策在编码前确定

🎯 核心理念

三大核心原则

1. 🔑 规范是唯一真相来源
   • 规范定义"是什么"和"为什么"
   • 计划定义"怎么做"
   • 任务定义"具体做什么"
2. ✅ 明确检查点
   • 每个阶段完成后必须人工审核
   • 发现问题在当前阶段修正，而非继续前进
   • 避免"垃圾输入，垃圾输出"
3. 🤖 AI 作为字面化搭档
   • 不要把 AI 当搜索引擎
   • 给 AI 清晰的指令和上下文
   • AI 擅长模式匹配，但不擅长读心术

🔄 四阶段工作流详解

Constitution（项目宪法）→ Specify（需求规范）→ Plan（技术方案）→ Tasks（任务分解）→ Implement（代码实现）

🏛️ 阶段 0: Constitution（项目宪法）

• 📍 目的：建立项目的不可协商原则
• ⚡ 命令：/speckit.constitution
• 📁 输出：.specify/memory/constitution.md
• 📝 包含内容：
  • 核心开发原则（如：测试优先、模块化架构）
  • 技术栈约束（必须使用的框架/工具）
  • 质量门禁（部署前必须通过的检查）
  • 治理规则（如何修改宪法、代码审查标准）
• ⏰ 使用时机：
  • ✅ 项目初始化时（只需要做一次）
  • ✅ 项目架构重大变更时
  • ❌ 每次开发新功能时（不需要重复）

📋 阶段 1: Specify（需求规范）

• 📍 目的：定义功能的"是什么"和"为什么"，不涉及"怎么做"
• ⚡ 命令：/speckit.specify
• 📁 输出：.specify/memory/spec.md
• 🎯 关注点：
  • 用户故事（谁、要做什么、为什么）
  • 验收标准（如何验证功能完成）
  • 用户旅程（用户如何与功能交互）
  • 成功指标（如何衡量功能成功）
• 💡 示例输入： 我想添加一个用户积分系统： - 用户发布内容可以获得积分 - 积分可以兑换特殊权益（如头像框、徽章） - 管理员可以手动调整用户积分 - 需要有积分历史记录
• 🚫 规范中不包含（这些留给 Plan 阶段）：
  • ❌ 使用 PostgreSQL 还是 MySQL
  • ❌ API 端点设计
  • ❌ 数据库表结构
• ✅ 最佳实践：
  • 第一次输入尽可能详细（减少后续迭代）
  • 描述边界情况（如：积分不能为负）
  • 说明不做什么（明确范围）

🛠️ 阶段 2: Plan（技术方案）

• 📍 目的：定义"怎么做"——技术架构和实现策略
• ⚡ 命令：/speckit.plan
• 📁 输出：.specify/memory/plan.md
• 🎯 关注点：
  • 技术栈选择（框架、库、数据库）
  • 架构决策（模块划分、API 设计）
  • 数据流（数据如何在系统中流动）
  • 外部依赖（第三方服务、API）
  • 安全考量（认证、授权、数据保护）
• 💡 示例输入： 技术约束： - 必须使用 Cloudflare D1 数据库（项目标准） - 遵循项目的 Module-First 架构 - 使用 Drizzle ORM + Zod 验证 - API 遵循 REST 和 RPC 双模式
• 📝 输出示例： ``markdown ## 模块设计 - 创建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 行代码）
  • 依赖关系（任务执行顺序）
  • 并行机会（哪些任务可以同时做）
  • 测试要求（每个任务的测试覆盖）
• 📝 输出示例： ```markdown ## 任务列表

数据库层 (可并行)

• 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
• 🔄 工作方式：
  • AI 按照 Tasks 列表逐个实现
  • 每个任务实现完成后，开发者审核
  • 审核通过后，继续下一个任务
  • 如有问题，修改后再继续
• 🤖 AI 的优势：
  • ✅ AI 知道要构建什么（Spec 告诉它）
  • ✅ AI 知道怎么构建（Plan 告诉它）
  • ✅ AI 知道当前做什么（Task 告诉它）
• 🔍 审核要点：
  • 代码是否符合 Constitution 原则
  • 是否通过所有测试
  • 是否有未处理的边界情况
  • 代码可读性和可维护性

📚 命令参考手册

核心命令

命令	作用	输出文件	使用时机
\speckit.constitution	建立项目原则	constitution.md	项目初始化（一次）
\speckit.specify	定义需求规范	spec.md	每个新功能开始
\speckit.plan	创建技术方案	plan.md	规范审核通过后
\speckit.tasks	分解任务列表	tasks.md	方案审核通过后
\speckit.implement	执行代码实现	实际代码文件	任务列表审核通过后

增强命令（可选）

命令	作用	使用时机
\speckit.clarify	澄清模糊需求	Plan 前，需求不清晰时
\speckit.analyze	检查一致性	Tasks 和 Implement 之间
\speckit.checklist	生成质量检查清单	Plan 后，提高质量保证

🎮 实战案例演练

场景：为 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 会按顺序执行：

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

⚠️ 每步审核后才继续下一步

✨ 最佳实践指南

✅ 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 生成的内容不符合预期怎么办？

🛠️ 解决方案：

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

Q4: Tasks 太多怎么办？

📊 策略：

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

Q5: 如何处理需求变更？

🔄 流程：

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

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

传统流程	Spec Kit 流程
需求 → 代码 → 文档	需求 → 规范 → 方案 → 任务 → 代码
文档滞后	规范即文档
架构临时决策	架构前置决策
大块代码审核	小任务逐步审核
AI 不知道上下文	AI 有清晰上下文

🎯 核心价值总结

💡 五大核心价值

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

🚀 快速开始

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

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

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

🎉 祝你使用 Spec Kit 愉快！ 💫 这份学习指南基于 Spec Kit 官方文档整理，结合了最佳实践和实战经验。建议收藏并在实际项目中反复参考。

---

补充信息

• 项目地址：GitHub 仓库（假设地址，原文未提供具体链接）
• 许可证：MIT（完全开源，欢迎贡献）
• 核心定位：Spec Kit 代表了 GitHub 对 AI 原生开发（AI-Native Development）的理解——AI 不应替代开发者，而应放大开发者的意图。

本文基于 Spec Kit v0.0.79 版本整理，若后续版本有功能更新，请参考官方文档。