Spec Workflow MCP

# 工作流程指南 本指南解释了完整的规格驱动开发工作流程以及使用 Spec Workflow MCP 的最佳实践。 ## 概述 规格驱动工作流程遵循结构化方法： ``` 指导 → 规格 → 实现 → 验证 ``` 每个阶段都建立在前一个阶段的基础上，确保系统化和良好记录的开发。 ## 阶段 1：使用指导文档进行项目设置 ### 为什么需要指导文档？ 指导文档提供高级指导，使您的项目保持一致和协调。它们充当所有开发决策的北极星。 ### 创建指导文档 ``` "为我的项目创建指导文档" ``` 这将生成三个关键文档： #### 1. 产品指导（`steering/product.md`） - 产品愿景和使命 - 目标用户和角色 - 核心功能和优先级 - 成功指标和 KPI - 非目标和约束 #### 2. 技术指导（`steering/tech.md`） - 架构决策 - 技术栈选择 - 性能要求 - 安全考虑 - 可扩展性方法 #### 3. 结构指导（`steering/structure.md`） - 项目组织 - 文件和文件夹约定 - 命名标准 - 模块边界 - 文档结构 ### 指导的最佳实践 1. **尽早创建** - 在任何规格之前设置指导 2. **保持更新** - 随着项目发展进行修订 3. **经常参考** - 用于决策 4. **广泛共享** - 确保团队一致 ## 阶段 2：规格创建 ### 三文档系统 每个规格由三个顺序文档组成： ``` 需求 → 设计 → 任务 ``` ### 需求文档 **目的**：定义需要构建什么 **内容**： - 功能概述 - 用户故事 - 功能要求 - 非功能要求 - 验收标准 - 约束和假设 **创建示例**： ``` "为支持以下功能的用户通知系统创建需求： - 电子邮件通知 - 应用内通知 - 推送通知 - 用户偏好 - 通知历史" ``` ### 设计文档 **目的**：定义如何构建 **内容**： - 技术架构 - 组件设计 - 数据模型 - API 规范 - 集成点 - 实现方法 **自动生成**：在需求批准后创建 ### 任务文档 **目的**：定义构建的步骤 **内容**： - 分层任务分解 - 依赖关系 - 工作量估算 - 实现顺序 - 测试要求 **结构示例**： ``` 1.0 数据库设置 1.1 创建通知表 1.2 设置索引 1.3 创建迁移脚本 2.0 后端实现 2.1 创建通知服务 2.1.1 电子邮件处理器 2.1.2 推送处理器 2.2 创建 API 端点 2.3 添加身份验证 3.0 前端实现 3.1 创建通知组件 3.2 与 API 集成 3.3 添加偏好 UI ``` ## 阶段 3：审查和批准 ### 审批工作流程 1. **文档创建** - AI 生成文档 2. **审查请求** - 自动请求审批 3. **用户审查** - 在仪表板/扩展中审查 4. **决策** - 批准、请求更改或拒绝 5. **修订**（如果需要）- AI 根据反馈更新 6. **最终批准** - 文档锁定以供实现 ### 做出审批决策 #### 何时批准 - 需求完整且清晰 - 设计解决了所述问题 - 任务逻辑且全面 - 没有重大关注或差距 #### 何时请求更改 - 缺少重要细节 - 规格不清楚 - 有更好的方法可用 - 需要与标准保持一致 #### 何时拒绝 - 根本性误解 - 方法完全错误 - 需要完全重新思考 ### 提供有效反馈 好的反馈： ``` "身份验证流程应该使用 JWT 令牌而不是会话。 向 API 端点添加速率限制。 包含网络故障的错误处理。" ``` 糟糕的反馈： ``` "这看起来不对。修复它。" ``` ## 阶段 4：实现 ### 任务执行策略 #### 顺序实现 最适合依赖任务： ``` "从 user-auth 规格实现任务 1.1" "现在实现任务 1.2" "继续任务 1.3" ``` #### 并行实现 用于独立任务： ``` "在我处理后端时，从仪表板规格实现所有 UI 任务" ``` #### 基于章节的实现 用于逻辑分组： ``` "从支付规格实现所有数据库任务" ``` ### 进度跟踪 通过以下方式监控实现： - 仪表板任务视图 - 进度条 - 状态指示器 - 完成百分比 ### 处理阻塞 当被阻塞时： 1. 记录阻塞 2. 为解决创建子任务 3. 如果可能，移至并行任务 4. 将任务状态更新为"已阻塞" ## 阶段 5：验证 ### 测试策略 实现后： 1. **单元测试** ``` "为通知服务创建单元测试" ``` 2. **集成测试** ``` "为 API 端点创建集成测试" ``` 3. **端到端测试** ``` "为完整的通知流程创建 E2E 测试" ``` ### 文档更新 保持文档最新： ``` "更新新端点的 API 文档" "向 README 添加使用示例" ``` ## 文件结构和组织 ### 标准项目结构 ``` your-project/ ├── .spec-workflow/ │ ├── steering/ │ │ ├── product.md │ │ ├── tech.md │ │ └── structure.md │ ├── specs/ │ │ ├── user-auth/ │ │ │ ├── requirements.md │ │ │ ├── design.md │ │ │ └── tasks.md │ │ └── payment-gateway/ │ │ ├── requirements.md │ │ ├── design.md │ │ └── tasks.md │ └── approval/ │ └── [审批跟踪文件] ├── src/ │ └── [您的实现] └── tests/ └── [您的测试] ``` ### 命名约定 **规格名称**： - 使用 kebab-case：`user-authentication` - 具有描述性：`payment-processing` 而不是 `payments` - 避免版本：`user-profile` 而不是 `user-profile-v2` **文档名称**： - 始终：`requirements.md`、`design.md`、`tasks.md` - 所有规格中保持一致 ## 高级工作流程 ### 功能迭代 对于不断发展的功能： 1. 创建初始规格 2. 实现 MVP 3. 创建增强规格 4. 引用原始规格 5. 在现有工作的基础上构建 示例： ``` "为 user-auth 创建增强规格，添加： - 社交登录（Google、Facebook） - 生物识别身份验证 - 会话管理改进" ``` ### 重构工作流程 1. **记录当前状态** ``` "创建记录当前身份验证系统的规格" ``` 2. **设计改进** ``` "设计重构以提高身份验证性能" ``` 3. **计划迁移** ``` "为重构创建迁移任务" ``` 4. **逐步实现** ``` "实现具有向后兼容性的重构任务" ``` ### Bug 解决工作流程 1. **Bug 报告** ``` "为登录超时问题创建 bug 报告" ``` 2. **调查** ``` "调查 bug #45 的根本原因" ``` 3. **解决方案设计** ``` "为超时问题设计修复" ``` 4. **实现** ``` "实现 bug 修复" ``` 5. **验证** ``` "为 bug #45 创建回归测试" ``` ## 最佳实践 ### 1. 保持规格粒度 **好**：每个功能一个规格 - `user-authentication` - `payment-processing` - `notification-system` **差**：过于宽泛的规格 - `backend-system` - `all-features` ### 2. 顺序文档创建 始终遵循顺序： 1. 需求（是什么） 2. 设计（如何做） 3. 任务（步骤） 永远不要跳过。 ### 3. 实现前完成审批 - ✅ 批准需求 → 创建设计 - ✅ 批准设计 → 创建任务 - ✅ 审查任务 → 开始实现 - ❌ 跳过审批 → 实现问题 ### 4. 保持规格更新 当需求改变时： ``` "更新 user-auth 的需求以包含 SSO 支持" ``` ### 5. 使用一致的术语 在以下方面保持一致性： - 规格名称 - 组件名称 - API 术语 - 数据库命名 ### 6. 归档已完成的规格 保持工作区整洁： ``` "归档已完成的 user-auth 规格" ``` ## 常见模式 ### MVP 到完整功能 1. 从 MVP 规格开始 2. 实现核心功能 3. 创建增强规格 4. 增量构建 5. 保持向后兼容性 ### 微服务开发 1. 创建服务指导文档 2. 定义服务边界 3. 为每个服务创建规格 4. 定义集成点 5. 独立实现服务 ### API 优先开发 1. 首先创建 API 规格 2. 设计合约 3. 生成文档 4. 实现端点 5. 创建客户端 SDK ## 工作流程问题故障排除 ### 规格变得太大 **解决方案**：拆分为更小的规格 ``` "将电子商务规格拆分为： - product-catalog - shopping-cart - checkout-process - order-management" ``` ### 需求不清楚 **解决方案**：请求澄清 ``` "需求需要更多详细信息： - 用户角色和权限 - 错误处理场景 - 性能要求" ``` ### 设计与需求不匹配 **解决方案**：请求修订 ``` "设计没有解决多租户要求。 请修订以包含租户隔离。" ``` ## 与开发过程集成 ### Git 工作流程 1. 为每个规格创建功能分支 2. 每个任务完成后提交 3. 在提交消息中引用规格 4. 规格完成时 PR ### CI/CD 集成 - 为已完成的任务运行测试 - 根据需求验证 - 部署已完成的功能 - 根据成功指标监控 ### 团队协作 - 共享仪表板 URL - 将规格分配给团队成员 - 审查彼此的规格 - 通过审批协调 ## 相关文档 - [用户指南](USER-GUIDE.zh.md) - 一般使用说明 - [提示指南](PROMPTING-GUIDE.zh.md) - 示例提示和模式 - [工具参考](TOOLS-REFERENCE.zh.md) - 完整的工具文档 - [界面指南](INTERFACES.zh.md) - 仪表板和扩展详情