用 Claude Code plan 命令构建 Agent 驱动的功能规划工作流hydra-ai 仓库的 Clarify-Research-Synthesize 实战解析【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai在大型前端/全栈仓库如本仓库 hydra-ai中一个功能从一句话需求到可执行实施计划往往要经历需求澄清、代码库调研、技术选型验证等多轮往返。本仓库在.claude/commands/plan.md中固化了一套完整的 Claude Code 规划命令slash command它以澄清 → 确认 → 任务清单 → 初始代码库研究 → 并行深度研究 → 计划综合六步工作流为核心借助researcher与planner两类 Agent 的分工协作把零散的研究结果收敛成.plans/目录下结构化的实施计划文档。读完本文你将掌握这套工作流的每一步操作模板、Agent 提示词的组织方式以及如何用它产出像 plans/2026-01-26-feat-react-ui-base-plan.md 那样可落地、可跟踪的高质量功能计划。一、定位plan.md 在仓库中的角色与触发方式plan.md位于仓库的 .claude/commands/plan.md属于 Claude Code 的自定义命令slash command定义文件。它遵循 Claude Code 命令的规范文件开头是一个 YAML frontmatter声明命令的描述信息--- description: Plan a feature with clarification, research, and synthesis ---description字段会在用户输入/plan时作为命令用途说明展示。命令正文则是发给 Claude 的指令提示词其中$ARGUMENTS是用户调用命令时传入的参数占位符——即待规划的功能需求描述Feature Request: $ARGUMENTS。从整个命令集来看该工作流并非孤立存在而是与本仓库.claude/commands/目录下的其他命令构成一条完整的开发流水线.claude/commands/plan.md规划一个功能本文主体.claude/commands/execute.md将计划并行拆解为多个子 Agent 执行.claude/commands/commit.md以用户名义创建规范化的 git 提交。也就是说/plan是整条规划 → 执行 → 提交链路的起点先通过多阶段研究得到一份计划再由execute命令按计划并行实施。二、工作流全景六步走的规划管线plan.md把功能规划拆成 6 个明确的阶段每个阶段都有对应的操作与产出物。整体管线如下Step 1 Clarify Requirements澄清需求 ↓ Step 2 Confirm Understanding确认理解 ↓ Step 3 Create Planning Todo List用 TodoWrite 建立规划任务清单 ↓ Step 4 Initial Codebase Research初始代码库研究1 个 researcher ↓ Step 5 Parallel Deep Research并行深度研究2-8 个 researcher ↓ Step 6 Synthesize Plan综合计划planner 输出到 .plans/[feature-name].mdStep 1Clarify Requirements澄清需求这是整个工作流的第一步也是质量的关键。命令要求 Claude 在动手规划前先像开发者与产品经理对话一样围绕需求本身提出澄清问题聚焦点包括功能范围scope与约束constraints具体需求细节requirements与用户诉求user needs边界情况edge cases任何技术偏好或顾虑technical preferences or concerns。原则是只问需求中不明确、有歧义的部分而不是机械式地罗列问题。Step 2Confirm Understanding确认理解在用户答复澄清问题后Claude 需要把确认后的功能需求总结并复述给用户征得用户确认。这一步建立了需求基线避免后续研究建立在错误的理解之上——这一点与执行阶段的 execute 命令中识别与计划的偏差并纠正或上报的原则前后呼应见 .claude/commands/execute.md。Step 3Create Planning Todo List建立规划任务清单需求确认后命令要求使用 Claude Code 的TodoWrite工具创建规划阶段的待办清单清单预置了 4 个任务Clarify requirements标记为已完成mark as completedInitial codebase researchParallel deep research后续会根据需要拆分为子任务Synthesize plan document。这个清单同时充当规划过程的进度仪表盘后续每个阶段开始/结束时都要同步更新对应任务的状态让用户在长流程中始终能看到当前进展。Step 4Initial Codebase Research初始代码库研究将 Initial codebase research 标记为in_progress后启动一个researcherAgent提示词模板如下/task researcher Analyze the codebase to understand: 1. What existing technologies/packages are in use (check package.json, imports, etc.) 2. Current architecture patterns 3. High-level list of files that will likely need modification 4. Key integration points Feature context: [confirmed requirements]初始研究的 4 个维度非常实用现有技术与依赖通过检查package.json、import 语句等摸清技术栈确保新功能不引入冲突的依赖当前架构模式识别仓库既有的架构约定例如本仓库中 packages/ 下的分包方式、apps/api/src 的 NestJS 分层等让计划贴合现状可能需要修改的文件清单在高层面上列出受影响文件为后续拆分研究任务和估算改动面做准备关键集成点找出新功能需要挂接的入口与调用链。Agent 完成后将该任务标记为完成并根据研究结果把并行深度研究细化为具体的研究方向更新 Todo 列表。Step 5Parallel Deep Research并行深度研究这是工作流的重火力阶段。命令要求基于初始研究结论生成2-8 个具体的研究任务数量取决于功能复杂度并在同一条消息中发起多个/task调用让多个researcherAgent 并行工作。两种典型的研究任务模板/task researcher Research how to implement [specific aspect] using [technology X]. Find: key APIs, best practices, implementation patterns, gotchas. Include documentation links./task researcher Deep dive into [specific part of codebase]. Analyze: current implementation, what needs to change, dependencies to consider.两种任务形成了很好的互补前者是外部技术调研关键 API、最佳实践、实现模式、易错点后者是仓库内部深度挖掘现状实现、改动点、依赖关系。之所以能在单条消息中并行发起多个 Task是因为这些研究任务彼此独立、互不依赖输出——这与执行阶段 execute 命令中真正独立的任务才并行的原则是一致的。Step 6Synthesize Plan综合计划所有研究结论汇总后启动plannerAgent把研究发现综合成一份最终计划/task planner Create implementation plan for: [feature name] Requirements: [confirmed requirements] Research findings: - Initial codebase analysis: [summary] - Technology research: [summary] - Codebase deep dives: [summary] Output to .plans/[feature-name].md (create the .plans/ directory if it doesnt exist)注意几个关键细节传给 planner 的是摘要summary而非原始研究全文要求 researcher 在研究阶段就做好信息压缩计划文件输出到仓库根目录的.plans/[feature-name].md若目录不存在则先创建planner 只负责写计划这一件事不承担实现职责——规划与执行在 Agent 层面彻底分离。三、配套 Agent 定义researcher 与 planner 的分工plan.md引用的/task researcher与/task planner并非凭空存在而是由仓库中两个 Agent 定义文件声明researcher通用研究专家.claude/agents/researcher.md 声明了一个名为researcher的通用研究 Agent其可用工具为Read, Glob, Grep, WebSearch, WebFetch, Bash即既能读仓库代码也能联网检索公开资料。它被要求始终提供简洁、聚焦的摘要相关的具体文件路径、包名或文档链接清晰分类的研究发现高层洞察不陷入实现细节。这套输出规范直接支撑了plan.mdStep 5 中研究要彻底但汇总的要求——多个并行 researcher 的产出必须能被 planner 直接消化。planner技术规划专家.claude/agents/planner.md 声明了plannerAgent工具集为Read, Write, Glob职责是把研究发现综合成清晰、可执行的实施计划。它接收两样输入功能需求 研究结论然后按固定结构产出计划并使用Write工具保存到.plans/[feature-name].md。四、planner 输出模板一份高质量计划的 8 个构件根据 .claude/agents/planner.md 的定义最终计划文档应包含以下结构这也是评估计划完整度的检查清单章节内容要求# Feature: [Feature Name]标题即功能名## Overview2-3 句话说明做什么、为什么## Key Design Decisions关键设计决策 简短理由每条决策一行## Architecture基于文本的架构图或数据流描述## Component Schema/Interface关键 prop schema 或接口定义用 TypeScript 示例落地设计## File Structure目录树标注(NEW)/(MODIFIED)## Implementation Phases实施阶段通常 3-5 个每阶段含文件清单、关键实现任务、复杂逻辑的伪代码## Out of Scope (v1)明确排除在 v1 之外的功能 排除理由模板还给出了明确的 DO / DONT 纪律应做DO计划保持简洁、可扫读用示例数据/schema 来落地设计仅对复杂、非显而易见的逻辑写伪代码聚焦要做什么而不是逐行代码拆成符合逻辑的阶段通常 3-5 个标记可并行完成的文件用单个 Out of Scope (v1) 小节收纳所有被排除的功能并附理由。不应做DONT不写时间估算或工作量评估不写带 import 的完整代码实现不重复范围边界把避免事项与未来事项合并进同一个 Out of Scope 小节不写大段测试章节仅提示关键测试考量不重复显而易见的任务如import React。伪代码使用原则只对复杂算法/变换、非显而易见的数据流、关键状态管理模式、需要澄清的边界处理写伪代码简单 CRUD、标准 React 模式、显而易见的工具函数一律跳过。五、仓库中的真实产物这套工作流的落地验证.plans/目录并非空壳其中两份计划文档可以印证上述模板在实际开发中的使用效果。实例一plans/2026-01-26-feat-react-ui-base-plan.mdplans/2026-01-26-feat-react-ui-base-plan.md 规划了tambo-ai/react-ui-base包把 UI 组件中的业务逻辑抽取为可复用的 hooks、工具函数与无样式基础组件。该计划严格遵循 planner 模板Overview一句话点明抽取业务逻辑到新包让用户可自建 UI 的同时复用核心功能Key Design Decisions列出独立分包、peer dependency、useTambo*命名约定、增量抽取、内部优先迁移、组合优于替换等 6 条决策及理由Architecture用 ASCII 图画出 用户代码 → react-ui-base → react → typescript-sdk 的调用链Component Schema/Interface给出UseTamboAutoScrollOptions、UseMessageInputStateOptions、UseToolResponseOptions等完整 TypeScript 接口File Structure按 feature 目录message-input/、message/、thread/、resources/、scroll/组织每个功能目录内含index.ts、源码与*.test.tsImplementation Phases拆成 Step 1-10从就地重构拆分到建包骨架、抽取纯工具函数、无状态 hooks、有状态资源 hooks、自动滚动 hook、输入状态 hook、线程管理 hook、迁移到新包、测试验证关键逻辑如草稿持久化、资源合并去重、自动滚动判定均附伪代码Out of Scope (v1)明确列出图片拖拽、TipTap 编辑器逻辑、elicitation 处理、Markdown 渲染组件等 8 项排除项及理由文档还附带Backwards Compatibility Requirements与逐步骤Acceptance Criteriacheckbox 勾选跟踪计划本身还记录了执行进度——这与 execute 命令执行后回填计划的协作模式吻合。实例二plans/api-v1-proposal.mdplans/api-v1-proposal.md 规划了 Tambo API v1 的重设计展示了模板的另一种应用方式它在 Key Design Decisions 中列出 8 条流式优先的设计决策如全 SSE 流式、AG-UI 事件协议、组件作为一等内容块、双向状态等并用 Mermaid 时序图与流程图替代 ASCII 图来描绘架构。这说明 planner 模板对架构描述一节留出了灵活性——文本图、Mermaid、流程图皆可只要把数据流讲清楚。实例三与 execute 命令的闭环规划完成后由 .claude/commands/execute.md 接手实施。execute 命令的核心纪律是协调而非实现绝不亲自编辑文件而是把独立任务在单条消息中并行分发给general-purpose子 Agent依赖任务串行推进最后统一跑类型检查与 lint、并行修复。它甚至允许创建.plans/execution-status.md状态文件跟踪进度——与plan的产物同处.plans/目录形成计划 执行状态的完整档案。六、使用要点与最佳实践总结综合plan.md及其配套 Agent 定义这套工作流可以提炼出几条可复用的工程经验先澄清后研究需求未确认前不启动任何代码库研究避免研究方向跑偏研究分两档1 个 researcher 先做全局摸底再按摸底结果并行派出 2-8 个定向 researcher规模随复杂度自适应并行以独立为前提只有在任务互不依赖输出时才在单条消息中并行发起多个/task相关或相互影响的任务应串行研究要压缩传给 planner 的是摘要而非全文要求 researcher 输出带文件路径、分类清晰的高层结论计划结构化Overview → 设计决策 → 架构 → 接口 schema → 文件结构 → 实施阶段 → Out of Scope每一节都服务于让实现者无歧义地开工显式声明 Out of Scope把 v1 不做的内容连同理由写清楚能有效防止实施阶段的范围蔓延计划即文档计划落地到.plans/[feature-name].md随代码一起入库既是实施蓝图也是后续评审与回溯的依据。这套定义位于仓库的 .claude/commands/plan.md配套 Agent 定义在 .claude/agents/researcher.md 与 .claude/agents/planner.md真实计划产物可参考 plans/2026-01-26-feat-react-ui-base-plan.md 与 plans/api-v1-proposal.md。在实际使用中只需在仓库内输入/plan并附上功能需求即可按这条流水线从一句话需求推进到一份结构完整、可执行、可跟踪的实施计划。【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
