需求分析技能 Skill

需求分析技能

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

快速开始

工作流 (阶段 1-9)：

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

核心特性：

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

执行档位

9 阶段对所有需求一刀切是过度流程——给小需求配全套并行探索与多路审查，流程开销会超过任务本身。阶段 1 结束时按下表判定档位，向用户声明并允许覆盖：

light    — 单文件/单模块、无新依赖、无方案分歧（如加字段、改文案）
           跳过: 阶段 3、并行探索、阶段 5 的深度思考（直接给方案）、并行审查
           保留: 阶段 6 路径确认（一句话级）、阶段 8 单 agent 审查

standard — 默认档。跨 2-3 模块或有方案取舍
           按 9 阶段执行，探索/审查用并行模式

deep     — 跨层架构变更、新技术栈、用户使用"彻底/全面/审计"等措辞
           standard 基础上启用完整编排模式（judge panel、multi-modal sweep、
           对抗复核全量开启；见阶段 2 / 阶段 5 / 阶段 8 与 parallel-patterns.md）

判定依据客观化：涉及文件数与模块数（阶段 1 初判，阶段 2 修正）、是否引入新依赖、是否存在多解取舍、用户措辞强度。

档位声明格式：「本需求判定为 {档位}（理由），如需更彻底/更轻量请告知」。

light 档交互预算：全流程 ≤ 2 次用户交互（阶段 6 一句话级路径确认 + 阶段 8 审查处理确认）；阶段 4 仅在确有疑点时增加提问。

执行环境兼容性

本 skill 同时兼容 Claude Code 和 Codex。核心工具映射：

| 用途 | Claude Code | Codex | |------|-------------|-------| | 用户澄清/确认 | AskUserQuestion | 对话消息提问并等待回复 | | 进度跟踪 | TaskList / TaskUpdate | update_plan + 阶段进度块 | | 并行子任务 | Agent（后台加 run_in_background: true，完成通知自动送达） | spawn_agent(fork_context=true) + wait_agent | | 项目规范文件 | CLAUDE.md → AGENTS.md | AGENTS.md → CLAUDE.md | | 网页搜索 | exa → WebSearch | web.search_query / open |

Codex 环境的完整规则（环境判定、提问规范、任务管理细则）见 codex-compat.md。

任务列表与进度

每个阶段开始时标记 in_progress，完成时标记 completed；条件执行的阶段被跳过时，标记 completed 并注明"已跳过"及原因。中断后恢复：找到最后一个 in_progress 或未完成阶段继续，已完成阶段不重做。

进度显示格式、降级模式（任务工具不可用时退化为纯文本进度）见 task-list-management.md。

深度思考使用指南

工具：mcp__sequential-thinking__sequentialthinking

✅ 阶段 1（需求涉及多模块、复杂逻辑、描述模糊时）：分解需求组件、识别依赖、分析风险
✅ 阶段 5（见该阶段的使用要求与降级路径）：设计数据结构、API、服务层、边缘情况、实施步骤
❌ 简单 CRUD 或单一模块需求可跳过（light 档默认跳过）

工作流程

阶段 1: 需求理解

目标：全面理解用户需求

执行要点：

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

阶段 2: 代码库探索

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

首要任务：查找并阅读项目规范文件（优先级按环境，见上文映射表）。

探索模式：

基础模式（light 档）：单个探索子代理，快速定位相关代码
并行模式（standard 档）：同时启动 3 个探索子代理，按架构层次或功能模块分解；只有问题天然分层且相互独立时才扩到 3 个以上 5 个以内。并行子任务在单个响应中一次性发起——分批发起会退化为串行等待，丧失并行收益。
multi-modal sweep（deep 档）：3-4 个 code-explorer 各持一个模态（入口追踪/数据流/配置约定/测试反推）彼此盲扫，输出 exploration-report 契约 JSON 经校验后合并去重——完整编排见 parallel-patterns.md

查找内容：项目规范文件、相关实体和服务、现有模式和约定。

稳定性要求：

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

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

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

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

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

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

工具优先级：

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

跳过场景：完全基于已有代码；团队对技术已经熟悉；时间紧急且需求简单。跳过时按"任务列表与进度"一节的跳过规则处理。

阶段 4: 澄清问题

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

重要：存在待澄清项时必须提问——带着错误假设进入实施的返工成本远高于一次提问。若阶段 1-3 未暴露任何歧义、约束冲突或多解取舍，明确记录"需求已清晰，无需澄清"后直接进入阶段 5，不要为了走流程而编造问题。

澄清内容（以下仅在确实存在对应疑点时提出）：

模糊或规格不足的需求
多个有效实施方法之间的选择
业务规则细节
技术选型或架构决策
阶段 1-3 中发现的不足、未覆盖点和隐含假设
代码库探索或外部研究暴露出的约束冲突、缺口和边缘场景

最佳实践：

提问前先汇总阶段 1-3 的关键发现，列出"已明确 / 待确认 / 可能遗漏"的问题清单
将未考虑到的业务规则、兼容性、权限、数据迁移、异常处理、性能和测试风险转化为用户可回答的问题
Claude Code：一次提问多个相关问题（multiSelect），提供具体选项和影响说明，推荐首选项并说明理由
Codex：提问规范见 codex-compat.md

阶段 5: 深度分析

目标：进行结构化深度分析，设计完整的技术方案

分档执行：

light：主线程直接给方案（分点列出组件分解 → 数据结构 → API → 风险 → 步骤），不派 agent、不用深度思考
standard：先派 1 个 code-architect agent 产出架构蓝图，主线程再用深度思考基于蓝图做整合与风险分析——agent 出蓝图、主线程做决策，职责分离
deep：judge panel——2-3 个 code-architect 各持一个优先级视角（风险最小化/长期可维护/交付速度）盲评出蓝图，主进程按 4 维评分合成（完整编排与评分规则见 parallel-patterns.md）

code-architect 输入契约（standard/deep 档派发时必须提供以下 4 项）：

任务描述（阶段 1 的需求理解摘要）
关键文件列表（阶段 2 探索发现的相关文件）
项目规范要点（阶段 2 读取的规范文件核心约定）
已确认的澄清结论（阶段 4 的用户答案与取舍）

agent 的输出格式遵循其自身定义（架构蓝图含关键文件清单、架构决策、组件设计、实施路线图），无需在此重复。

深度思考要求：standard/deep 档使用 sequential-thinking 做结构化深度分析——多模块方案的取舍如果跳过结构化思考，遗漏率显著升高。若该 MCP 不可用，降级为在回复中显式分点推演（组件分解 → 数据结构 → API → 风险 → 步骤），不要因工具缺失跳过分析本身。

上下文要求：分析开始前，先整理阶段 1-4 的上下文包，并在思考中显式使用：

阶段 1：需求理解摘要、业务目标、功能边界和初始风险
阶段 2：代码库结构、现有实现模式、项目规范和可复用代码
阶段 3：外部资源结论；如已跳过，记录跳过原因和因此保留的假设
阶段 4：用户澄清答案、确认的取舍、仍需在实现中防守的约束

分析内容：

分析需求组件：分解为可实施的功能模块，识别依赖关系，分析技术和业务风险
设计数据结构（符合项目规范）：实体/表结构、字段类型和约束、关联关系和索引
设计 API 端点（符合项目规范）：HTTP 方法、路径、请求/响应结构、认证和权限
设计服务层（符合项目规范）：服务接口、依赖关系、业务逻辑流程
识别风险和边缘情况：覆盖阶段 4 澄清的特殊情况，回看阶段 1-3 暴露但未被澄清完全覆盖的遗漏，规划异常处理策略
规划详细实施步骤：整合上下文包和所有分析，制定可执行的分步计划

注意：虽然深度思考能访问完整对话历史，但必须显式引用和总结之前阶段的关键发现（standard 档还包括 code-architect 蓝图的关键结论），确保分析、取舍和实施步骤都能追溯到阶段 1-4 的输入。

阶段 6: 展示实施计划

目标：向用户展示完整的实施计划，确认后续路径

展示内容：

需求总结 - 理解的核心要点
代码库发现 - 相关代码和模式
外部资源（如适用）- 搜索结果和库文档
澄清结论 - 用户确认的取舍、约束和待防守假设
技术设计 - 数据库、API、服务层
实施步骤 - 编号的详细步骤
风险和注意事项

计划要求：展示前先用阶段 1-4 上下文包自检（是否遗漏需求、代码约束、研究结论或澄清答案）；技术设计和实施步骤必须能对应到阶段 1-4 的发现或用户确认，避免孤立方案；发现阶段 4 仍未覆盖的关键缺口时，先回到阶段 4 继续澄清，不要带着关键未知项进入确认。

确认门槛：在用户选定后续路径前不要标记本阶段为 completed——计划是阶段 7 的执行依据，未经确认的计划意味着后续工作建立在假设之上；路径 2 的共识计划、路径 3 的拆分结果同样需经用户确认后本阶段才算完成。

路径确认菜单（计划反馈与路径选择合并为一次交互；用户对计划本身给出修改意见时回到计划修订，修改后重新展示并重出菜单——不强迫三选一）：

直接开始实施 — 进入阶段 7
与 codex 计划讨论 — 调用 codex CLI 多轮评审（≤3 轮），共识计划经用户确认后写入 docs/YYYYMMDD-计划名/plan.md，再重出精简菜单（仅路径 1/3）继续
计划拆分落盘 — 在 docs/YYYYMMDD-计划名/ 生成 plan.md + tasks.md + progress.md 三件套（分步可执行、进度精确到每任务、中断可恢复），立即实施时将任务注册进运行时任务管理（Claude Code 用 TaskCreate/TaskUpdate，Codex 用 update_plan）

路径 2/3 的执行细则（codex 命令序列、三件套生成与双轨同步规则边界）见 plan-handoff.md；Codex 环境下菜单仅提供路径 1/3（理由与形态见 codex-compat.md）。

输出格式：输出模板

阶段 7: 实施开发

目标：基于阶段 6 确认的设计实施功能代码

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

执行原则：严格遵循项目规范文件；按照架构设计实施功能；保持代码简洁，避免过度工程；及时验证和测试；遇到关键歧义时及时向用户确认。

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

完成标志：所有功能代码实现完成、通过基本测试（"通过"必须附测试命令与输出摘要——无证据的自报告不算通过；无法运行测试时注明原因并将该项标记为未验证）、符合项目规范。

阶段 8: 代码审查

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

编排（按伪代码执行；每个编排动作前用一句话告知用户进度）：

DIMENSIONS = 按档位选维度（light: [A]；standard: [A,B,C]；deep: 5 路拆分，见 parallel-patterns.md）
seen = []        # 已见发现集合（含被否决的），按 file:line+category 去重

repeat (最多 2 轮):
  # fan-out：单条消息内并行派出全部维度（每维度一个 code-reviewer 子代理）
  #          分批发起会退化为串行，丧失并行收益
  reports = parallel for d in DIMENSIONS:
      Agent(code-reviewer, 范围=本次变更, 维度=d,
            输出=review-findings 契约 JSON，落盘到临时目录)
  # 契约校验：每份报告落盘后运行
  #   node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-output.mjs review-findings <file>
  #   失败 → 把 errors 清单发回该子代理补全一次；再失败 → 主进程接管该维度
  # pipeline 优先：单维度报告校验通过即可进入复核，无需等齐所有维度——
  #   仅当去重需要跨维度信息时才等待（barrier 的判定标准）
  fresh = dedupe(所有 findings, against=seen)
  if fresh 为空: break          # loop-until-dry：枯竭即停
  seen += fresh                  # 注意：复核否决的也留在 seen，防止下轮重现
  # 对抗复核：仅 severity ∈ {高, 中}，每条派 1 个独立子代理，指令为
  #   "试图反驳此发现：给出 file:line 证据证明它不成立或属误报；
  #    无法证实存在即判误报"
  confirmed += [f for f in fresh if 复核(f) == 成立]

# completeness critic（1 个子代理）：
#   "对照本次变更文件清单与维度表，哪些文件/风险面没有被任何发现覆盖？
#    哪些维度的 coverage_note 声明了截断？" → 输出并入报告"覆盖声明"节

失败隔离：某维度子代理失败 → 缩小该维度范围重试 1 次 → 仍失败则主进程接管该维度，其余维度流水线不受影响。

收尾：按 output-template 输出报告（confirmed 按严重性分组 + 覆盖声明），向用户征求处理方式——哪些值得修、按什么顺序修是用户的优先级决策，不要自动修复。

Codex 形态：见 parallel-patterns.md 的 Codex 降级说明。

阶段 9: 总结

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

总结内容：需求总结（核心功能与关键特性）、成果清单（功能模块/文件/代码）、质量指标（审查问题数与修复情况）、后续建议（优化点与文档更新）、经验教训（挑战与解决方案）。

最后输出全阶段完成情况清单（格式见 task-list-management.md 的最终进度显示）。

重要原则

自适应语言交互：根据用户输入语言和项目文档语言沟通
严格遵循项目规范：必须阅读并遵守项目规范文件——它们承载团队约定，违背规范的实现无法合入
主动提问：不清楚的地方必须澄清（理由见阶段 4）；计划确认前不编码（理由见阶段 6）；审查后先确认再修（理由见阶段 8）
按档位执行：先判档再走流程，向用户声明并允许覆盖（见"执行档位"）
善用外部资源：需要时使用 context7、网页搜索工具（带降级方案）
合理使用并行化：standard/deep 档使用并行探索和审查，单个响应中一次性发起
必须代码审查：实施完成后必须执行阶段 8——未经独立审查的代码缺少质量把关
保持彻底：考虑边缘情况、错误和性能

Agent Skills: 需求分析技能

Install this agent skill to your local

Skill Files