需求分析技能

提供系统化的 9 阶段需求分析与实施工作流，确保从深度分析到质量交付的完整过程。

快速开始

工作流 (阶段 1-9)：

需求理解 → 代码探索 → 外部资源研究 → 澄清问题 → 深度分析 → 展示计划 → 实施开发 → 代码审查 → 总结

核心特性：

• 深度分析：使用 深度思考 进行复杂需求分析
• 外部资源：集成 context7、网页搜索工具研究最佳实践
• 结构化产出：详细的实施计划 + 完整代码实现
• Task List 管理：进度可视化、断点恢复

与 feat-dev 的区别：

• 本技能：9 阶段，包含外部资源研究，适合复杂需求和新技术栈
• feat-dev：7 阶段，快速实施流程，适合需求相对明确的场景

执行环境兼容性

本 skill 同时兼容 Claude Code 和 Codex。遇到环境专有工具时，按以下规则映射：

• 用户澄清/确认
  • Claude Code：使用 AskUserQuestion
  • Codex Plan 模式：优先使用 request_user_input
  • Codex Default 模式：直接用简洁的纯文本消息提问，并等待用户回复
• 进度跟踪
  • Claude Code：使用 TaskList / TaskUpdate
  • Codex：使用 update_plan，并在对话中输出阶段进度块
• 并行子任务
  • Claude Code：使用 Task / TaskOutput
  • Codex：使用 spawn_agent / send_input / wait_agent；纯工具并行可用 multi_tool_use.parallel
• 项目规范文件
  • Codex：优先查找 AGENTS.md，找不到再查 CLAUDE.md
  • Claude Code：优先查找 CLAUDE.md，找不到再查 AGENTS.md
• 网页搜索
  • Claude Code：exa → WebSearch
  • Codex：web.search_query / open

Task List 管理

本技能自动管理任务列表，提供进度可视化和断点恢复能力。

基础模式：

Claude Code:

- 开始阶段时使用 TaskList/TaskUpdate 标记 `in_progress`
- 完成阶段时使用 TaskUpdate 标记 `completed`

Codex:

- 开始阶段时调用 `update_plan`，将当前阶段标记为 `in_progress`
- 完成阶段时调用 `update_plan`，将当前阶段标记为 `completed`

条件执行阶段： 对于条件执行的阶段（如外部资源研究）：

Claude Code:

- TaskUpdate(task.id, status="completed", metadata={note: "不满足执行条件，已跳过"})

Codex:

- update_plan 中将该步骤标记为 `completed`
- 在 explanation 或进度消息中注明“已跳过”

断点恢复：

• Claude Code：检查 TaskList() 找到 in_progress 或 pending 状态的任务并继续
• Codex：检查最近一次 update_plan 和阶段进度消息，从最后一个 in_progress 或未完成阶段继续

高级用法：Task List 管理

深度思考 使用指南

工具：mcp__sequential-thinking__sequentialthinking

何时使用：

• ✅ 阶段1：需求涉及多个模块、复杂业务逻辑、描述模糊
• ✅ 阶段5：必须使用（深度分析）
• ❌ 简单 CRUD 或单一模块需求可跳过

使用方法：

思考内容：

- 阶段1：分解需求组件、识别依赖关系、分析潜在风险
- 阶段5：设计数据结构、API端点、服务层、识别边缘情况、规划实施步骤

工作流程

阶段 1: 需求理解

目标：全面理解用户需求

执行要点：

• 识别核心功能、业务实体、API 端点、业务规则
• 根据复杂度决定是否使用 深度思考
• 记录需求理解摘要

任务管理：

Claude Code:

- TaskUpdate(..., status="in_progress")
- 完成时 TaskUpdate(..., status="completed")

Codex:

- update_plan 将“阶段 1: 需求理解”标记为 `in_progress`
- 完成时标记为 `completed`

阶段 2: 代码库探索

目标：全面探索代码库，理解项目架构

首要任务：查找并阅读项目规范文件，优先级如下：

• Codex：AGENTS.md → CLAUDE.md
• Claude Code：CLAUDE.md → AGENTS.md

探索模式：

基础模式（简单需求）：

• 使用单个探索子代理
• 快速定位相关代码

并行模式（复杂需求）：

• 同时启动 3 个探索子代理；只有问题天然分层且相互独立时才按需扩到 3 个以上 5 个以内
• 按架构层次或功能模块分解
• ⚠️ 必须在单个响应中发起所有并行子任务
• Claude Code：使用 Task + run_in_background: true + TaskOutput
• Codex：使用 spawn_agent(fork_context=true, ...)，需要结果时使用 wait_agent

查找内容：

• AGENTS.md / CLAUDE.md / 其他项目规范
• 相关实体和服务
• 现有模式和约定

稳定性要求：

• 每个子代理负责一个清晰主题或角度，允许在该范围内展开分析
• 父进程必须给出相关文件、目标层次和期望输出格式
• 子代理失败后先缩小任务重试 1 次，再由主进程接管

并行模式示例：并行模式指南

阶段 3: 外部资源研究 (条件执行)

目标：研究外部资源，获取最新信息和最佳实践

执行条件（满足任一即执行）：

• 涉及新的第三方库或框架
• 需要了解行业最新实践
• 内部代码库示例不充分

工具优先级：

1. 网页搜索：exa（如可用）→ 网页搜索工具
2. 库文档：context7 → 网页搜索 + rg + 文件阅读

跳过场景：

• 完全基于已有代码
• 团队对技术已经熟悉
• 时间紧急且需求简单

跳过处理：

Claude Code:

- TaskUpdate(task.id, status="completed", metadata={note: "不满足执行条件，已跳过"})

Codex:

- update_plan 将当前阶段标记为 `completed`
- 在阶段说明中写明“已跳过”

阶段 4: 澄清问题

目标：解决所有不清楚、模糊或有歧义的需求点

重要：必须向用户发起澄清或确认

工具映射：

• Claude Code：AskUserQuestion
• Codex ：request_user_input

澄清内容：

• 模糊或规格不足的需求
• 多个有效实施方法之间的选择
• 业务规则细节
• 技术选型或架构决策

最佳实践：

• 一次提问多个相关问题（使用 multiSelect）
• 提供具体选项和说明影响
• 推荐首选选项并说明理由

任务管理：

Claude Code:

- TaskUpdate(..., status="in_progress")
- 用户回应后 TaskUpdate(..., status="completed")

Codex:

- update_plan 将“阶段 4: 澄清问题”标记为 `in_progress`
- 用户回应并处理后标记为 `completed`

阶段 5: 深度分析

目标：使用 深度思考 进行深度分析，设计完整的技术方案

必须使用 深度思考：mcp__sequential-thinking__sequentialthinking

分析内容：

1. 分析需求组件（回顾阶段1结果）

   • 分解为可实施的功能模块
   • 识别模块间的依赖关系
   • 分析潜在的技术和业务风险

2. 设计数据结构（符合项目规范）

   • 实体/表结构定义
   • 字段类型和约束
   • 关联关系和索引

3. 设计 API 端点（符合项目规范）

   • HTTP 方法、路径设计
   • 请求/响应结构
   • 认证和权限要求

4. 设计服务层（符合项目规范）

   • 服务接口定义
   • 依赖关系设计
   • 业务逻辑流程

5. 识别风险和边缘情况

   • 考虑阶段4中用户澄清的特殊情况
   • 分析潜在的错误场景
   • 规划异常处理策略

6. 规划详细实施步骤

   • 整合所有上述分析
   • 制定可执行的分步实施计划

注意事项： 虽然 深度思考 能够访问完整对话历史，但建议明确引用和总结之前阶段的关键发现，确保分析的连贯性和准确性。

阶段 6: 展示实施计划

目标：向用户展示完整的实施计划，等待确认

展示内容：

1. 需求总结 - 理解的核心要点
2. 代码库发现 - 相关代码和模式
3. 外部资源（如适用）- 搜索结果和库文档
4. 技术设计 - 数据库、API、服务层
5. 实施步骤 - 编号的详细步骤
6. 风险和注意事项

重要：在用户确认前，不要标记任务为 completed

询问："这个实施计划看起来如何？我可以开始实施了吗？"

用户确认后：

Claude Code:

- TaskUpdate(task.id, status="completed")

Codex:

- update_plan 将“阶段 6: 展示实施计划”标记为 `completed`

# 下一阶段自动解除阻塞，可以开始

输出格式：输出模板

阶段 7: 实施开发

目标：基于阶段6的架构设计，实施功能代码

前提：必须获得用户明确确认（阶段6完成）

执行原则：

1. 严格遵循 AGENTS.md / CLAUDE.md / 项目规范
2. 按照架构设计实施功能
3. 保持代码简洁，避免过度工程
4. 及时验证和测试
5. 遇到关键歧义时及时向用户确认

阶段职责：

• 编写功能代码
• 实现设计的 API、数据结构、服务层
• 编写单元测试（如需要）
• 不包含代码审查（审查在阶段8）

完成标志：

• 所有功能代码实现完成
• 代码通过基本测试
• 符合项目规范

阶段 8: 代码审查

目标：独立的质量把关阶段，全面审查代码质量

阶段职责：

• 独立的质量把关阶段
• 检查代码质量、规范遵循
• 识别 bug 和潜在问题
• 提供改进建议

审查模式选择：

单一审查模式（简单需求）：

• 使用 1 个审查子代理
• 全面审查所有维度

并行深度审查模式（复杂需求）：

• 同时启动 2-3 个审查任务
• 每个聚焦于特定维度（功能正确性、代码风格、规范遵循）
• ⚠️ 必须在单个响应中发起所有并行子任务
• Claude Code：使用 Task + run_in_background: true + TaskOutput
• Codex：使用 spawn_agent(fork_context=true, ...)，再用 wait_agent 收集结果

执行步骤：

1. 选择审查模式（基于需求复杂度）
2. 启动审查 agents
3. 收集审查结果（Claude Code 用 TaskOutput；Codex 用 wait_agent）
4. 整合问题列表
5. 向用户询问处理方式

审查后必须：

• 向用户确认如何处理问题
• 不得自动修复，必须征求确认
• 子代理超时、跑偏或结果不完整时，缩小范围重试 1 次；仍失败则主进程手动审查

产出：审查报告（问题列表、严重性标注）、改进建议

阶段 9: 总结

目标：总结整个需求分析流程，提供后续建议

总结内容：

1. 需求总结

   • 核心功能回顾
   • 实现的关键特性

2. 成果清单

   • 完成的功能模块
   • 创建的文件
   • 编写的代码

3. 质量指标

   • 审查发现的问题数量
   • 修复情况
   • 代码质量评分

4. 后续建议

   • 进一步优化建议
   • 潜在改进点
   • 文档更新建议

5. 经验教训

   • 遇到的挑战
   • 解决方案
   • 最佳实践

最终进度显示：

### [完成] 所有阶段完成！

需求分析项目 - 100% 完成

📝 阶段完成情况：
[完成] 阶段 1: 需求理解
[完成] 阶段 2: 代码库探索
[跳过] 阶段 3: 外部资源研究 (跳过)
[完成] 阶段 4: 澄清问题
[完成] 阶段 5: 深度分析
[完成] 阶段 6: 展示实施计划
[完成] 阶段 7: 实施开发
[完成] 阶段 8: 代码审查
[完成] 阶段 9: 总结

项目成功完成！

重要原则

1. 自适应语言交互：根据用户输入语言和项目文档语言沟通
2. 严格遵循项目规范：必须阅读并遵守 AGENTS.md / CLAUDE.md / 其他规范文件
3. 主动提问：不清楚的地方必须澄清
4. 合理使用 深度思考：阶段1可选，阶段5必须
5. 善用外部资源：需要时使用 context7、网页搜索工具（带降级方案）
6. 合理使用并行化：复杂需求使用并行探索和审查，必须在单个响应中发起
7. 必须代码审查：实施完成后必须执行阶段 8
8. 审查前征求确认：必须先征求确认，不得自动修复
9. 切勿急躁：计划确认前不要编码
10. 保持彻底：考虑边缘情况、错误和性能

参考文档

详细指南

• Task List 管理高级用法
• 并行模式详细示例
• 使用示例
• 输出格式模板