Hooke / mlaj

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
f11a76c4 1 parent 5ac993f9

docs: 添加SpecKit学习指南文档 

添加SpecKit规范驱动开发工具包的详细学习指南文档，包含核心概念、四阶段工作流、命令参考、最佳实践和常见问题解答等内容。文档基于SpecKit v0.0.79版本整理，为开发者提供AI辅助编程的规范驱动开发指导。
Inline Side-by-side
Showing 1 changed file with 439 additions and 0 deletions
# 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（已完成）
```markdown
✅ 已创建 itypol2 Constitution v1.0.0
- Module-First 架构
- Database-First 工作流
- 端到端类型安全
```
### 📋 Step 1: Specify
```markdown
/speckit.specify
我想为 itypol2 添加用户积分系统：
【功能描述】
- 用户通过以下行为获得积分：
- 发布内容：+10 积分
- 内容被点赞：+2 积分/次
- 每日登录：+5 积分
- 积分可以兑换权益：
- 100 积分 → 专属头像框
- 500 积分 → 作者徽章
- 1000 积分 → VIP 标识
- 管理员功能：
- 手动调整任意用户积分（需审计日志）
- 查看积分统计报表
【边界条件】
- 积分不能为负数
- 兑换后积分扣除，但不可退款
- 积分历史永久保留（用于审计）
【不包含的功能】
- 积分过期机制（v1 不做）
- 积分转赠功能（v1 不做）
- 积分商城（单独项目）
```
#### 🎯 AI 会生成详细的 `spec.md`，包含：
- 用户故事（5-10 个）
- 验收标准（明确的可测试条件）
- 用户旅程（从获得积分到兑换的流程）
- 成功指标（如：90% 用户完成首次兑换）
#### 🔍 审核要点：
- ✅ 是否覆盖所有场景
- ✅ 是否有遗漏的边界情况
- ✅ 验收标准是否可测试
### 🛠️ Step 2: Plan
```markdown
/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
```markdown
/speckit.tasks
```
#### 🎯 AI 会生成 `tasks.md`，包含：
```markdown
## 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
```markdown
/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. 👥 团队协作 - 统一标准和流程
## 🚀 快速开始
```markdown
# 1. 已完成：初始化 Spec Kit
✅ itypol2 已配置好 Spec Kit
# 2. 开始第一个功能
/speckit.specify [详细描述你的功能需求]
# 3. 后续按流程
/speckit.plan → /speckit.tasks → /speckit.implement
```
🎉 祝你使用 Spec Kit 愉快！
💫 这份学习指南基于 Spec Kit 官方文档整理，结合了最佳实践和实战经验。建议收藏并在实际项目中反复参考。
---
## 补充信息
- 项目地址：[GitHub 仓库](https://github.com/github/speckit)（假设地址，原文未提供具体链接）
- 许可证：MIT（完全开源，欢迎贡献）
- 核心定位：Spec Kit 代表了 GitHub 对 AI 原生开发（AI-Native Development）的理解——AI 不应替代开发者，而应放大开发者的意图。
> 本文基于 Spec Kit v0.0.79 版本整理，若后续版本有功能更新，请参考官方文档。