Spec Workflow MCP

# 提示指南 一个全面的指南，包含通过 AI 助手与 Spec Workflow MCP 交互的示例和最佳实践。 ## 快速参考 ### 基本命令 ``` "为 [功能] 创建规格" "列出我的所有规格" "显示 [规格名称] 的状态" "从 [规格] 实现任务 [编号]" "创建指导文档" ``` ## 创建规格 ### 基本规格创建 #### 简单请求 ``` "创建一个用户认证的规格" ``` AI 将创建： - 需求文档 - 设计文档（批准后） - 任务分解（设计批准后） #### 详细请求 ``` "创建一个名为 payment-processing 的规格，包含： - 通过 Stripe 的信用卡支付 - PayPal 集成 - 退款处理 - 支付事件的 webhook 处理 - PCI 合规性考虑" ``` #### 从现有文档创建 ``` "从 @product-requirements.md 中的 PRD 创建规格" ``` ``` "基于 @figma-export.md 的设计文档构建规格" ``` ### 高级规格创建 #### 带技术约束 ``` "创建一个实时通知规格，要求： - 使用 WebSockets 进行实时更新 - 对旧浏览器回退到轮询 - 处理多达 10,000 个并发连接 - 维护消息顺序 - 包含离线队列支持" ``` #### 带验收标准 ``` "创建一个搜索功能规格，具有以下验收标准： - 结果在 200 毫秒内出现 - 支持模糊匹配 - 包含日期、类别和作者的过滤器 - 显示相关性评分 - 处理拼写错误和同义词" ``` #### 微服务规格 ``` "创建一个库存微服务规格，要求： - 公开 REST API - 使用 PostgreSQL 存储 - 向 Kafka 发布事件 - 实现 CQRS 模式 - 包含健康检查端点" ``` ## 管理规格 ### 列出和状态 #### 获取概览 ``` "列出我的所有规格" "显示所有规格及其进度" "哪些规格正在等待审批？" "目前正在进行哪些规格？" ``` #### 特定状态 ``` "显示 user-auth 规格的状态" "payment-processing 的进度如何？" "显示通知规格中还剩下什么要做" "user-profile 中哪些任务已完成？" ``` #### 过滤 ``` "显示完成度超过 50% 的规格" "列出等待我审批的规格" "哪些规格还没有完成任何任务？" "显示被阻塞或卡住的规格" ``` ### 文档管理 #### 查看文档 ``` "显示 user-auth 的需求" "显示支付的设计文档" "通知系统的任务是什么？" "显示搜索规格的所有文档" ``` #### 更新文档 ``` "更新 user-auth 需求以包含 2FA" "修改支付设计以使用 Stripe Connect" "向 user-profile 添加安全测试任务" "根据反馈更新需求：[反馈]" ``` ## 实现提示 ### 单个任务 #### 基本实现 ``` "从 user-auth 实现任务 1.2" "完成支付规格中的任务 2.1.3" "处理通知中的下一个待处理任务" ``` #### 带上下文 ``` "使用 TypeScript 和 Express 从 user-auth 实现任务 1.2" "使用 Prisma 完成数据库迁移任务" "遵循 REST 约定实现 API 端点任务" ``` ### 批量实现 #### 按章节 ``` "从 user-auth 实现所有数据库任务" "完成仪表板规格中的所有前端任务" "处理支付的所有 API 任务" ``` #### 按优先级 ``` "首先实现所有关键任务" "完成 user-profile 的 MVP 任务" "专注于演示所需的任务" ``` #### 顺序 ``` "从 user-auth 实现任务 1.1 到 1.5" "完成第 2 节下的所有子任务" "按顺序完成设置任务" ``` ### 实现策略 #### 测试驱动 ``` "对于任务 1.2，先编写测试然后实现" "实现任务 2.1 并提供完整的测试覆盖率" "在实现服务任务时创建单元测试" ``` #### 带文档 ``` "实现任务 1.3 并记录 API" "完成带有内联注释的身份验证任务" "实现并为任务 2.2 创建使用示例" ``` ## 指导文档 ### 创建指导 #### 完整集 ``` "为我的电子商务项目创建指导文档" "为 SaaS 应用程序设置指导" "为移动应用创建项目指导" ``` #### 单个文档 ``` "创建专注于用户体验的产品指导文档" "为微服务架构创建技术指导" "为 monorepo 设置创建结构指导" ``` #### 从上下文创建 ``` "基于 @project-brief.md 创建指导文档" "从 @architecture.md 中的技术决策生成指导" ``` ### 更新指导 ``` "更新产品指导以包含 B2B 功能" "修改技术指导以使用 GraphQL 而不是 REST" "更新新模块系统的结构指导" ``` ## 审批工作流程 ### 请求反馈 #### 带特定关注点 ``` "请求批准 user-auth 需求 - 特别检查安全部分" "要求审查支付设计 - 重点关注错误处理" "请求对任务分解的反馈 - 是否太细化？" ``` #### 修订请求 ``` "需求需要更多详细信息： - 错误处理场景 - 性能要求 - 安全考虑 请修订并重新提交" ``` ### 审批决策 #### 批准 ``` "批准 user-auth 需求" "设计看起来不错，批准它" "按原样接受任务分解" ``` #### 请求更改 ``` "请求对需求的更改： - 添加多租户支持 - 包含速率限制 - 指定数据保留策略" ``` #### 拒绝 ``` "拒绝当前设计 - 我们需要改用事件驱动架构" "重新开始需求 - 范围太广" ``` ## Bug 工作流程 ### 报告 Bug #### 详细报告 ``` "创建 bug 报告： 标题：使用特殊字符登录失败 步骤：1）输入带有 '+' 的电子邮件 2）提交表单 3）看到错误 预期：登录成功 实际：500 错误 优先级：高 环境：生产" ``` #### 从错误日志创建 ``` "从此错误创建 bug 报告：[粘贴堆栈跟踪]" "从 Sentry 警报记录此 bug：[链接]" ``` ### Bug 解决 #### 调查 ``` "调查 bug #45 的根本原因" "分析支付 webhook 为何失败" "调试搜索端点中的性能问题" ``` #### 修复实现 ``` "在用户认证中为 bug #45 创建修复" "为支付超时问题实现解决方案" "修复通知服务中的内存泄漏" ``` ## 实现中期更改 ### 当规格在开发期间发生变化时 在实现过程中，需求和设计经常会演变。发生这种情况时，您需要使 tasks.md 与当前规格保持一致，同时保留已完成的工作。 ### 使用任务刷新功能 AI 可以通过 refresh-tasks 提示访问全面的任务刷新说明。只需告知 AI 您的更改： #### 基本任务刷新 ``` "需求已更新。请刷新 tasks.md 以与当前的 requirements.md 和 design.md 保持一致。" ``` #### 带上下文的详细任务刷新 ``` "我已使用以下更改更新了规格： - 删除了报告模块 - 将数据库从 MongoDB 更改为 PostgreSQL - 添加了社交登录功能 请按照任务刷新过程刷新 tasks.md： 1. 保留所有已完成和进行中的任务 2. 为数据库更改添加迁移任务 3. 删除报告模块的待处理任务 4. 为社交登录添加新任务" ``` #### 需要迁移的架构更改 ``` "我们正在从 REST API 切换到 GraphQL。几个 REST 端点已经实现。请更新 tasks.md： 1. 保留所有已完成的 REST 工作 2. 添加迁移任务以在 GraphQL 解析器中包装 REST 逻辑 3. 新的 GraphQL 实现任务 4. 在 GraphQL 验证后删除 REST 的清理任务" ``` ### 预期的 AI 行为 当您请求任务刷新时，AI 将： 1. **分析当前状态** - 阅读 requirements.md 和 design.md 以获取当前规格 - 识别已完成、进行中和待处理的任务 - 确定添加、删除或更改了哪些功能 2. **保留已完成的工作** - 保持所有 [x] 已完成的任务不变 - 保持所有 [-] 进行中的任务不变 - 为已删除功能的已完成工作添加备注 3. **处理架构更改** - 在需要更新的已完成工作后添加迁移任务 - 为渐进式迁移创建过渡任务 - 在删除旧实现之前包含验证任务 4. **更新待处理任务** - 删除已删除功能的待处理任务 - 更新已更改需求的待处理任务 - 为新功能添加新任务 5. **维护任务结构** - 保持顺序编号 - 保留任务格式 - 包含需求引用 - 维护依赖顺序 ### 示例场景 #### 功能删除 ``` "我们决定从规格中删除报告模块。相应地更新 tasks.md。" ``` 预期的 AI 行为： - 保留所有已完成的报告任务及其 [x] 状态 - 保留所有进行中的报告任务及其 [-] 状态 - 仅删除待处理的 [ ] 报告任务 - 添加备注："_注意：报告功能已从规格中删除，但保留了已完成的工作_" #### 带已完成工作的架构更改 ``` "我们正在从 MongoDB 切换到 PostgreSQL。更新待处理的数据库任务。请注意，我们已经实现了 MongoDB 架构和连接逻辑。" ``` 预期的 AI 行为： - 完全按原样保留所有已完成的 MongoDB 任务 - 完全按原样保留所有进行中的 MongoDB 任务 - 在已完成的 MongoDB 工作后立即添加新的迁移任务： - 将 MongoDB 架构迁移到 PostgreSQL 表 - 用 PostgreSQL 客户端替换 MongoDB 连接逻辑 - 将数据库查询从 MongoDB 更新为 PostgreSQL 语法 - 将现有 MongoDB 数据迁移到 PostgreSQL - 更新 PostgreSQL 的环境配置 - 在迁移验证后删除 MongoDB 依赖项 - 将剩余的待处理数据库任务更新为使用 PostgreSQL - 维护任务编号顺序 #### 功能添加 ``` "向身份验证规格添加社交登录。需求和设计已更新。" ``` 预期的 AI 行为： - 分析当前任务结构以找到逻辑插入点 - 添加具有适当编号的新社交登录任务 - 引用社交登录的特定需求 - 确保新任务维护依赖顺序 - 如果基本身份验证已实现，则添加集成任务 ### 处理架构迁移 当架构更改影响已实现的代码时： #### REST 到 GraphQL 迁移 ``` "我们正在从 REST 更改为 GraphQL。几个 REST 端点已经实现。" ``` 预期的任务添加： - 保留已完成的 REST 端点任务 - 添加 GraphQL 架构定义任务 - 添加解析器实现任务 - 添加迁移任务以在 GraphQL 解析器中包装现有的 REST 逻辑 - 添加任务以更新客户端代码以使用 GraphQL - 在 GraphQL 验证后添加删除 REST 端点的清理任务 #### 单体到微服务拆分 ``` "我们正在将单体用户服务拆分为单独的身份验证和配置文件服务。" ``` 预期的任务添加： - 保留已完成的单体服务任务 - 添加服务分离任务 - 添加服务间通信任务 - 如果数据库正在拆分，则添加数据迁移任务 - 为新服务添加部署配置任务 - 在服务验证后添加删除单体代码的清理任务 ### 迁移的任务格式 迁移任务应清楚地表明其目的： ``` "刷新任务后，我看到您添加了： - [ ] 2.4 将 MongoDB 架构迁移到 PostgreSQL 表 - 文件：src/database/migrations/mongo-to-postgres.ts - 将文档架构转换为关系表 - 将嵌入式文档映射到外键关系 - 保留所有现有数据关系 - 目的：将数据库层过渡到新架构 - _利用：任务 2.1-2.3 中已完成的 MongoDB 架构_ - _需求：设计第 3.2 节_" ``` ### 向 AI 传达更改 在告知 AI 规格更改时： #### 具体说明更改和影响 ``` "支付处理需求已更改。现在需要 Stripe 而不是 PayPal。我们已经实现了 PayPal webhook 处理程序。请更新 tasks.md 以反映此更改，包括迁移任务。" ``` #### 提供保留和迁移的上下文 ``` "虽然我们正在从 MongoDB 迁移到 PostgreSQL，但保留所有已完成的 MongoDB 任务，因为该工作已经完成。添加迁移任务以将已实现的 MongoDB 代码过渡到 PostgreSQL。" ``` #### 请求验证 ``` "更新 tasks.md 后，确认 requirements.md 中的所有需求都有相应的任务，架构更改存在迁移路径，并且不存在已删除功能的待处理任务。" ``` ### 渐进式迁移策略 对于重大架构更改，AI 应创建支持渐进式迁移的任务： 1. 在现有架构的基础上实现新架构 2. 添加兼容性层任务 3. 增量迁移功能 4. 验证每个迁移步骤 5. 仅在完全验证后删除旧实现 这确保应用程序在整个过渡期间保持功能。 ### 使用刷新任务提示 您还可以明确调用刷新任务提示： ``` "为 user-auth 规格使用 refresh-tasks 提示。更改是：从 JWT 切换到 OAuth2 进行身份验证。" ``` 然后，AI 将遵循全面的刷新说明来更新您的任务，同时保留所有已完成的工作。 ## 高级模式 ### 多规格工作流程 #### 相关规格 ``` "创建一个 admin-dashboard 规格，它与以下内容集成： - user-management 规格 - analytics 规格 - reporting 规格" ``` #### 规格依赖关系 ``` "创建一个通知规格，依赖于： - user-auth 完成 - message-queue 实现 - email-service 可用" ``` ### 增量开发 #### MVP 优先 ``` "为 user-profiles 创建 MVP 规格，仅包含： - 基本配置文件创建 - 显示名称和头像 - 公共配置文件视图 （我们稍后会添加社交功能）" ``` #### 增强规格 ``` "为 user-auth 创建增强规格，添加： - 社交登录（Google、GitHub） - 生物识别身份验证 - 增强的会话管理 - 帐户链接" ``` ### 复杂场景 #### 迁移规格 ``` "创建从 MongoDB 迁移到 PostgreSQL 的规格： - 记录当前架构 - 设计新的关系结构 - 计划零停机迁移 - 包含回滚程序" ``` #### 重构规格 ``` "创建重构规格以： - 将单体拆分为服务 - 提取共享组件 - 将测试覆盖率提高到 80% - 保持向后兼容性" ``` #### 性能规格 ``` "创建性能优化规格： - 分析当前瓶颈 - 设计缓存策略 - 计划数据库索引 - 实现监控" ``` ## 工作流程组合 ### 完整功能流程 ``` 1. "为项目创建指导文档" 2. "创建用户认证规格" 3. "审查并批准需求" 4. "审查并批准设计" 5. "实现任务 1.1 - 数据库架构" 6. "实现任务 1.2 - 身份验证服务" 7. "为身份验证流程创建测试" 8. "将所有任务标记为完成" ``` ### 并行开发 ``` "在我审查需求的同时，开始起草 API 设计" "并行创建前端和后端的规格" "在后端团队执行 API 任务时处理 UI 任务" ``` ### 迭代优化 ``` 1. "为搜索创建初始规格" 2. "实现基本搜索（任务 1-3）" 3. "为高级搜索创建增强规格" 4. "添加过滤和排序功能" 5. "为搜索性能创建优化规格" ``` ## 上下文感知提示 ### 使用项目上下文 ``` "创建遵循我们现有模式的规格" "实现此任务与我们的代码库保持一致" "设计此功能以与我们当前的架构集成" ``` ### 引用其他规格 ``` "创建与 user-auth 类似但用于管理员身份验证的规格" "使用与支付规格相同的设计模式" "遵循我们通知规格中的任务结构" ``` ### 在先前工作的基础上构建 ``` "扩展 user-auth 规格以包含团队管理" "向现有的 REST API 规格添加 GraphQL 支持" "使用机器学习功能增强搜索规格" ``` ## 有效提示的技巧 ### 具体明确 ❌ **模糊**："创建登录规格" ✅ **具体**："创建一个电子邮件/密码登录规格，包含 2FA、记住我和密码重置" ### 提供上下文 ❌ **无上下文**："实现任务" ✅ **有上下文**："使用我们现有的 Express 中间件和 PostgreSQL 数据库实现任务 1.2" ### 设定明确的期望 ❌ **不清楚**："让它更好" ✅ **清楚**："改进设计以处理当前流量的 10 倍，响应时间低于 200 毫秒" ### 使用增量请求 ❌ **太多**："创建 5 个规格并实现所有内容" ✅ **增量**："首先创建 user-auth 规格，然后我们在继续下一个之前进行审查" ### 引用现有工作 ❌ **重新开始**："创建新的支付系统" ✅ **在基础上构建**："增强我们的支付规格以添加订阅计费" ## 常见模式库 ### CRUD 操作 ``` "创建产品 CRUD 操作规格，包括： - 带验证的创建 - 带分页和过滤的读取 - 带乐观锁的更新 - 带恢复选项的软删除" ``` ### 身份验证和授权 ``` "创建身份验证规格，包含： - 基于 JWT 的身份验证 - 基于角色的访问控制 - API 密钥管理 - 会话处理 - 刷新令牌轮换" ``` ### 实时功能 ``` "创建实时聊天规格： - WebSocket 连接 - 消息持久化 - 输入指示器 - 已读回执 - 离线消息队列" ``` ### 文件管理 ``` "创建文件上传规格： - 大文件的分块上传 - 进度跟踪 - 恢复功能 - 病毒扫描 - CDN 集成" ``` ### 分析和报告 ``` "创建分析规格： - 事件跟踪 - 自定义维度 - 实时仪表板 - 计划报告 - 数据导出选项" ``` ## 故障排除提示 ### 当出现问题时 ``` "为什么这个规格没有显示？" "调试为什么任务没有完成" "什么阻止了审批？" "帮我理解这个错误" ``` ### 摆脱困境 ``` "接下来我应该做什么？" "显示阻止进度的内容" "在等待时我可以处理哪些任务？" "如何解决这个依赖关系？" ``` ## 相关文档 - [用户指南](USER-GUIDE.zh.md) - 一般使用说明 - [工作流程](WORKFLOW.zh.md) - 理解工作流程 - [工具参考](TOOLS-REFERENCE.zh.md) - 完整的工具文档 - [故障排除](TROUBLESHOOTING.zh.md) - 解决常见问题