docs: 添加SpecKit学习指南文档

添加SpecKit规范驱动开发工具包的详细学习指南文档，包含核心概念、四阶段工作流、命令参考、最佳实践和常见问题解答等内容。文档基于SpecKit v0.0.79版本整理，为开发者提供AI辅助编程的规范驱动开发指导。

+# 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 版本整理，若后续版本有功能更新，请参考官方文档。