Claude Code 并行子代理执行编排深入解析 hydra-ai 仓库的 execute 命令设计【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai本文以 .claude/commands/execute.md 为核心主体结合本仓库hydra-ai即 Tambo AI 的 Generative UI SDK 与云平台 Turborepo 单体仓库中的配套命令、Agent 定义、开发规范与构建脚本系统讲解如何设计一个只协调、不落地的多子代理并行执行编排命令。读完你能够掌握任务分解与并行判定方法、/task子代理调用模式、顺序依赖处理、验证与并行修复策略以及如何在 Claude Code 中落地一套 plan → execute → commit → create-pr 的完整工程化工作流。一、命令在仓库中的定位一条完整的 Agent 工程化流水线在 hydra-ai 仓库的 .claude/commands 目录下共有四个 slash commandClaude Code 自定义命令它们共同构成一条可复用的开发流水线命令文件职责.claude/commands/plan.md澄清需求 → 启动 researcher 子代理做代码库研究 → 并行深挖 → 由 planner 子代理综合输出实现计划.claude/commands/execute.md把已确认的计划拆解为并行/串行任务通过多个子代理并行实施最后统一验证与汇总.claude/commands/commit.md用git status/git diff分析改动规划原子化提交提交信息不包含任何 AI 署名.claude/commands/create-pr.md基于当前分支与基础分支的差异生成 PR 描述Summary / Why / Test Plan配合 .claude/agents/planner.md把研究结论综合为结构化实现计划与 .claude/agents/researcher.md通用研究型子代理这套体系的典型用法是先用plan命令产出.plans/[feature-name].md计划文档再用execute命令按计划并行实施。仓库根目录的 plans 目录下沉淀的真实计划文档如 plans/agent-friendly-cli.md、plans/implement-api-v1.md即是这一工作流的产物证据。execute.md在文件头通过 frontmatter 声明description: Orchestrate parallel implementation through subagents正文定义了执行协调者Execution Orchestrator的完整行为契约本文接下来的所有内容均围绕这份契约展开。二、核心规则协调者的四条行为红线execute.md开篇即给出四条不可逾越的核心规则它们是整个命令设计哲学的基础绝不亲自编辑文件——所有文件操作一律委派给子代理执行。协调者的价值在于高层视角而非实现细节亲自改文件会破坏并行度和职责边界智能并行化——真正相互独立的任务并发启动但要克制地判断哪些任务适合放在一起跑避免盲目堆并发用 TodoWrite 跟踪进度——通过待办清单维护执行状态让长流程可审计、可恢复汇总结果——收集并综合各子代理的输出以文件为单位向用户报告变更。其中第 1 条在命令末尾的 Status Tracking 一节有一个明确例外协调者可以也仅此一处直接创建/编辑一个状态文件例如.plans/execution-status.md用于记录已完成任务、活跃子代理、阻塞项与变更摘要。也就是说不直接改文件指的是业务代码状态跟踪文件是协调者被允许保留的唯一自留地。三、五步执行流程从拆解到验证的完整闭环Step 1任务分解Break Down Work收到任务后协调者首先要做的是分析并识别四类信息独立工作流可并行执行不同文件、互不依赖输出的任务依赖工作流必须串行执行后一个任务的输入依赖前一个任务的输出需要修改的文件明确改动范围为后续分配子代理做准备测试/验证步骤预留验证环节而不是全部精力放在实现上。分解完成后用 TodoWrite 建立带明确阶段phase的待办清单。这一步的质量直接决定后续并行度上限——分解越细、依赖越清晰可安全并行的任务就越多。Step 2并行启动Launch Parallel Execution对于同一阶段内的所有独立任务在一个消息内一次性发出多个/task调用这是该命令最核心的调用模式# Single message with multiple parallel agents: /task general-purpose Edit src/components/foo.tsx: [specific changes] Report back: summary of changes made /task general-purpose Edit src/lib/bar.ts: [specific changes] Report back: summary of changes made /task general-purpose Edit src/utils/baz.ts: [specific changes] Report back: summary of changes made关键原则在文档中反复强调如果任务之间不依赖彼此的产出就在同一条消息里用多个 Task 调用一起启动。同时每个任务都必须给出具体改动 回报方式的指令——注意示例中每个提示都要求子代理回报改了什么这正是 Step 4 汇总环节能够按文件粒度复述变更的前提。Step 3顺序依赖处理Sequential Dependencies当任务 A 的产出是任务 B 的输入时必须显式串行化等待前一个子代理完成用它的结果作为下一个任务的输入信息再启动下一波并行任务。这与 Step 2 形成对照依赖是并行化的闸门只有在依赖边界处才需要等待。协调者需要区分同波次并行与跨波次串行两种节奏。Step 4收集与综合Collect and Synthesize子代理全部完成后协调者依次执行更新待办清单将已完成任务标记为完成按文件逐一总结变更内容记录遇到的任何问题或阻塞项确定下一步行动。这一步有一个容易被忽略的关键动作识别与计划的偏差variance。文档明确要求——如果实现结果与原计划不一致要么立即纠正要么必须在最终报告中向用户说明。这保证了计划-执行两条线始终对齐避免子代理自由发挥导致计划文档失真。Step 5验证Validation验证阶段遵循先聚合、再并行修复的两段式策略# First: Run checks together to see all issues /task general-purpose Run type checking and linting: 1. npm run check-types 2. npm run lint Report all errors found with file locations如果错误分布在多个相互独立的文件中则并行修复# After seeing the error report, launch parallel fixes: /task general-purpose Fix type errors in src/components/foo.tsx: [specific errors] /task general-purpose Fix lint issues in src/lib/bar.ts: [specific issues] /task general-purpose Fix type errors in src/utils/baz.ts: [specific errors]文档给出的 Rationale 非常值得借鉴先一起跑检查能拿到完整的错误全景再按文件并行修复因为跨文件的修复彼此独立。把检查和修复拆成两波既避免了修复时只见树木不见森林又保留了并行修复的吞吐优势。这一策略与仓库 AGENTS.md 中规定的提交前质量关卡完全呼应——npm run check-typesTS 全工作区类型检查、npm run lint:fix、npm run format、npm test是每个 PR 提交前的强制验证命令。execute 命令中的验证步骤正是把这些命令以子代理任务的形式编排进流程类型检查与 Lint 对应npm run check-types与npm run lint而测试对应仓库 devdocs/TESTING.md 描述的 Jest 单测/集成测试体系。四、沟通格式与状态跟踪让长流程可读、可审计execute.md为协调者规定了面向用户的沟通模板强调用精炼更新持续同步进展Phase 1: Core Implementation Launching 3 parallel agents to modify: - src/components/foo.tsx - src/lib/bar.ts - src/utils/baz.ts [Wait for results] ✓ All agents completed successfully Summary of changes: - foo.tsx: Added new prop handling for X - bar.ts: Implemented helper function Y - baz.ts: Updated utility Z Phase 2: Integration Launching 2 agents...这个模板的价值在于它以阶段为单位组织信息每一波都说明启动了谁、改了什么文件、结果如何用户无需展开每个子代理的完整输出即可掌握全局进度。状态跟踪方面协调者被允许直接编辑的唯一文件是状态文件例如.plans/execution-status.md记录已完成任务、活跃子代理、阻塞项、变更摘要。在本仓库的工程实践中计划文档入 .plans 目录是一条被执行的约定——conductor-setup.sh 在环境初始化时会从根仓库复制.plans目录而仓库根目录的 plans 目录正是计划文档的沉淀处。从源码结构看execute 命令建议的.plans/execution-status.md与计划文档放在同一层级便于计划 执行状态对照查看。五、完整示例拆解以为应用添加暗色模式为样本execute.md提供了一个端到端的编排示例完整展示协调者如何把抽象需求变为并行执行计划用户需求Add dark mode support across the application第 1 步——分解子任务依赖关系添加 theme context/provider独立更新 UI 组件组件内部独立但依赖 context 的存在添加 toggle 控制开关依赖 context更新全局样式独立第 2 步——Phase 1 基础层并行/task general-purpose Create src/contexts/theme-context.tsx... /task general-purpose Add theme configuration to src/lib/theme-config.ts... /task general-purpose Update global styles in src/app/globals.css...第 3 步——Phase 2 组件层并行/task general-purpose Update src/components/header.tsx... /task general-purpose Update src/components/sidebar.tsx... /task general-purpose Update src/components/footer.tsx...第 4 步——Phase 3 开关控件/task general-purpose Create src/components/theme-toggle.tsx...第 5 步——验证与并行修复先跑类型检查与 lint 拿全量错误报告再按文件并行修复Fix errors in header.tsx.../Fix errors in sidebar.tsx...。这个示例清晰演示了三层编排思想基础层先行context 是后两层的依赖故单独成 Phase 1、依赖层波次推进组件层依赖基础层但组件之间彼此独立故同波并行、验证驱动收尾检查与修复分离。示例中的主题 context 组件、样式文件与开关控件的拆法也符合本仓库 AGENTS.md 中业务逻辑与 UI 分离优先 props 透传、少建 context的组件架构约定。六、编排边界与最佳实践什么时候该并行什么时候必须串行命令结尾的 Remember 清单是对全文的收束也是使用这个命令时的行为准则你的职责是协调不是实现——每当你发现自己要动手改业务代码时停下来把它委派给子代理聪明地并行——先一起跑检查拿到全貌再跨文件并行修复文档明确警告不要过度并行Dont over-parallelize如果任务彼此相关、或一个任务的产出会启发另一个任务就串行执行真正独立的工作用一条消息内的多个 Task 调用启动——这是并行化的唯一合法依据即无输出依赖始终给出清晰、精炼的进度汇总待办清单随阶段和子任务的完成实时更新。结合本仓库的实际情况这套编排模式的适用边界还可以进一步具体化hydra-ai 是一个 Turborepo 单体仓库包含 react-sdk、showcase、docs 等框架包以及 apps/web、apps/api、packages/db 等云平台应用。跨包改动时AGENTS.md 要求跨包变更应一起测试并且 react-sdk 的改动需要验证 showcase 集成、showcase 的组件需要从 cli 注册表同步——这些改动后必须联动验证的约束恰好对应 execute 命令中串行依赖与Step 5 验证两个环节是判断任务能否并入同波次的天然依据。七、如何在仓库中使用这条命令查看与使用这条命令不需要修改仓库任何内容阅读命令定义直接打开 .claude/commands/execute.md其 frontmatter 的description会在 Claude Code 的命令列表中展示调用方式在 Claude Code 中输入/execute并附上任务描述命令正文中的$ARGUMENTS会被你的任务文本替换从而激活执行协调者角色配套使用配合/plan产出计划文档、/commit原子化提交、/create-pr生成 PR 描述可形成完整闭环子代理的提示词模板参考 .claude/agents/planner.md 与 .claude/agents/researcher.md本地开发环境仓库的 conductor-setup.sh校验 Node.js ≥ 22 并安装依赖、按 .env.example 初始化各应用环境文件与 conductor-run.sh提供 showcase/docs/web/api 的 7 种组合启动选项必要时自动拉起 Supabase为执行验证提供了配套支撑执行完成后可按需选用其一启动对应应用进行人工验收。小结.claude/commands/execute.md表面上是几十行提示词实质上是一份完整的多代理并行执行编排契约它以绝不亲自实现为底线以无依赖即并行、有依赖即串行为并行化判据以先聚合检查、再并行修复为验证策略并辅以阶段化沟通模板与状态文件机制保证长流程的可读性与可审计性。结合本仓库 AGENTS.md 的质量关卡、plans 目录的真实计划产物以及 conductor 系列脚本的工程配套这套模式完全可以在任何多文件、多包协作的开发任务中复制落地——它解决的不仅是一次命令调用而是AI 团队如何像一支真实工程团队一样分工、并行、验收与汇报的问题。【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Claude Code 并行子代理执行编排：深入解析 hydra-ai 仓库的 execute 命令设计
Claude Code 并行子代理执行编排深入解析 hydra-ai 仓库的 execute 命令设计【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai本文以 .claude/commands/execute.md 为核心主体结合本仓库hydra-ai即 Tambo AI 的 Generative UI SDK 与云平台 Turborepo 单体仓库中的配套命令、Agent 定义、开发规范与构建脚本系统讲解如何设计一个只协调、不落地的多子代理并行执行编排命令。读完你能够掌握任务分解与并行判定方法、/task子代理调用模式、顺序依赖处理、验证与并行修复策略以及如何在 Claude Code 中落地一套 plan → execute → commit → create-pr 的完整工程化工作流。一、命令在仓库中的定位一条完整的 Agent 工程化流水线在 hydra-ai 仓库的 .claude/commands 目录下共有四个 slash commandClaude Code 自定义命令它们共同构成一条可复用的开发流水线命令文件职责.claude/commands/plan.md澄清需求 → 启动 researcher 子代理做代码库研究 → 并行深挖 → 由 planner 子代理综合输出实现计划.claude/commands/execute.md把已确认的计划拆解为并行/串行任务通过多个子代理并行实施最后统一验证与汇总.claude/commands/commit.md用git status/git diff分析改动规划原子化提交提交信息不包含任何 AI 署名.claude/commands/create-pr.md基于当前分支与基础分支的差异生成 PR 描述Summary / Why / Test Plan配合 .claude/agents/planner.md把研究结论综合为结构化实现计划与 .claude/agents/researcher.md通用研究型子代理这套体系的典型用法是先用plan命令产出.plans/[feature-name].md计划文档再用execute命令按计划并行实施。仓库根目录的 plans 目录下沉淀的真实计划文档如 plans/agent-friendly-cli.md、plans/implement-api-v1.md即是这一工作流的产物证据。execute.md在文件头通过 frontmatter 声明description: Orchestrate parallel implementation through subagents正文定义了执行协调者Execution Orchestrator的完整行为契约本文接下来的所有内容均围绕这份契约展开。二、核心规则协调者的四条行为红线execute.md开篇即给出四条不可逾越的核心规则它们是整个命令设计哲学的基础绝不亲自编辑文件——所有文件操作一律委派给子代理执行。协调者的价值在于高层视角而非实现细节亲自改文件会破坏并行度和职责边界智能并行化——真正相互独立的任务并发启动但要克制地判断哪些任务适合放在一起跑避免盲目堆并发用 TodoWrite 跟踪进度——通过待办清单维护执行状态让长流程可审计、可恢复汇总结果——收集并综合各子代理的输出以文件为单位向用户报告变更。其中第 1 条在命令末尾的 Status Tracking 一节有一个明确例外协调者可以也仅此一处直接创建/编辑一个状态文件例如.plans/execution-status.md用于记录已完成任务、活跃子代理、阻塞项与变更摘要。也就是说不直接改文件指的是业务代码状态跟踪文件是协调者被允许保留的唯一自留地。三、五步执行流程从拆解到验证的完整闭环Step 1任务分解Break Down Work收到任务后协调者首先要做的是分析并识别四类信息独立工作流可并行执行不同文件、互不依赖输出的任务依赖工作流必须串行执行后一个任务的输入依赖前一个任务的输出需要修改的文件明确改动范围为后续分配子代理做准备测试/验证步骤预留验证环节而不是全部精力放在实现上。分解完成后用 TodoWrite 建立带明确阶段phase的待办清单。这一步的质量直接决定后续并行度上限——分解越细、依赖越清晰可安全并行的任务就越多。Step 2并行启动Launch Parallel Execution对于同一阶段内的所有独立任务在一个消息内一次性发出多个/task调用这是该命令最核心的调用模式# Single message with multiple parallel agents: /task general-purpose Edit src/components/foo.tsx: [specific changes] Report back: summary of changes made /task general-purpose Edit src/lib/bar.ts: [specific changes] Report back: summary of changes made /task general-purpose Edit src/utils/baz.ts: [specific changes] Report back: summary of changes made关键原则在文档中反复强调如果任务之间不依赖彼此的产出就在同一条消息里用多个 Task 调用一起启动。同时每个任务都必须给出具体改动 回报方式的指令——注意示例中每个提示都要求子代理回报改了什么这正是 Step 4 汇总环节能够按文件粒度复述变更的前提。Step 3顺序依赖处理Sequential Dependencies当任务 A 的产出是任务 B 的输入时必须显式串行化等待前一个子代理完成用它的结果作为下一个任务的输入信息再启动下一波并行任务。这与 Step 2 形成对照依赖是并行化的闸门只有在依赖边界处才需要等待。协调者需要区分同波次并行与跨波次串行两种节奏。Step 4收集与综合Collect and Synthesize子代理全部完成后协调者依次执行更新待办清单将已完成任务标记为完成按文件逐一总结变更内容记录遇到的任何问题或阻塞项确定下一步行动。这一步有一个容易被忽略的关键动作识别与计划的偏差variance。文档明确要求——如果实现结果与原计划不一致要么立即纠正要么必须在最终报告中向用户说明。这保证了计划-执行两条线始终对齐避免子代理自由发挥导致计划文档失真。Step 5验证Validation验证阶段遵循先聚合、再并行修复的两段式策略# First: Run checks together to see all issues /task general-purpose Run type checking and linting: 1. npm run check-types 2. npm run lint Report all errors found with file locations如果错误分布在多个相互独立的文件中则并行修复# After seeing the error report, launch parallel fixes: /task general-purpose Fix type errors in src/components/foo.tsx: [specific errors] /task general-purpose Fix lint issues in src/lib/bar.ts: [specific issues] /task general-purpose Fix type errors in src/utils/baz.ts: [specific errors]文档给出的 Rationale 非常值得借鉴先一起跑检查能拿到完整的错误全景再按文件并行修复因为跨文件的修复彼此独立。把检查和修复拆成两波既避免了修复时只见树木不见森林又保留了并行修复的吞吐优势。这一策略与仓库 AGENTS.md 中规定的提交前质量关卡完全呼应——npm run check-typesTS 全工作区类型检查、npm run lint:fix、npm run format、npm test是每个 PR 提交前的强制验证命令。execute 命令中的验证步骤正是把这些命令以子代理任务的形式编排进流程类型检查与 Lint 对应npm run check-types与npm run lint而测试对应仓库 devdocs/TESTING.md 描述的 Jest 单测/集成测试体系。四、沟通格式与状态跟踪让长流程可读、可审计execute.md为协调者规定了面向用户的沟通模板强调用精炼更新持续同步进展Phase 1: Core Implementation Launching 3 parallel agents to modify: - src/components/foo.tsx - src/lib/bar.ts - src/utils/baz.ts [Wait for results] ✓ All agents completed successfully Summary of changes: - foo.tsx: Added new prop handling for X - bar.ts: Implemented helper function Y - baz.ts: Updated utility Z Phase 2: Integration Launching 2 agents...这个模板的价值在于它以阶段为单位组织信息每一波都说明启动了谁、改了什么文件、结果如何用户无需展开每个子代理的完整输出即可掌握全局进度。状态跟踪方面协调者被允许直接编辑的唯一文件是状态文件例如.plans/execution-status.md记录已完成任务、活跃子代理、阻塞项、变更摘要。在本仓库的工程实践中计划文档入 .plans 目录是一条被执行的约定——conductor-setup.sh 在环境初始化时会从根仓库复制.plans目录而仓库根目录的 plans 目录正是计划文档的沉淀处。从源码结构看execute 命令建议的.plans/execution-status.md与计划文档放在同一层级便于计划 执行状态对照查看。五、完整示例拆解以为应用添加暗色模式为样本execute.md提供了一个端到端的编排示例完整展示协调者如何把抽象需求变为并行执行计划用户需求Add dark mode support across the application第 1 步——分解子任务依赖关系添加 theme context/provider独立更新 UI 组件组件内部独立但依赖 context 的存在添加 toggle 控制开关依赖 context更新全局样式独立第 2 步——Phase 1 基础层并行/task general-purpose Create src/contexts/theme-context.tsx... /task general-purpose Add theme configuration to src/lib/theme-config.ts... /task general-purpose Update global styles in src/app/globals.css...第 3 步——Phase 2 组件层并行/task general-purpose Update src/components/header.tsx... /task general-purpose Update src/components/sidebar.tsx... /task general-purpose Update src/components/footer.tsx...第 4 步——Phase 3 开关控件/task general-purpose Create src/components/theme-toggle.tsx...第 5 步——验证与并行修复先跑类型检查与 lint 拿全量错误报告再按文件并行修复Fix errors in header.tsx.../Fix errors in sidebar.tsx...。这个示例清晰演示了三层编排思想基础层先行context 是后两层的依赖故单独成 Phase 1、依赖层波次推进组件层依赖基础层但组件之间彼此独立故同波并行、验证驱动收尾检查与修复分离。示例中的主题 context 组件、样式文件与开关控件的拆法也符合本仓库 AGENTS.md 中业务逻辑与 UI 分离优先 props 透传、少建 context的组件架构约定。六、编排边界与最佳实践什么时候该并行什么时候必须串行命令结尾的 Remember 清单是对全文的收束也是使用这个命令时的行为准则你的职责是协调不是实现——每当你发现自己要动手改业务代码时停下来把它委派给子代理聪明地并行——先一起跑检查拿到全貌再跨文件并行修复文档明确警告不要过度并行Dont over-parallelize如果任务彼此相关、或一个任务的产出会启发另一个任务就串行执行真正独立的工作用一条消息内的多个 Task 调用启动——这是并行化的唯一合法依据即无输出依赖始终给出清晰、精炼的进度汇总待办清单随阶段和子任务的完成实时更新。结合本仓库的实际情况这套编排模式的适用边界还可以进一步具体化hydra-ai 是一个 Turborepo 单体仓库包含 react-sdk、showcase、docs 等框架包以及 apps/web、apps/api、packages/db 等云平台应用。跨包改动时AGENTS.md 要求跨包变更应一起测试并且 react-sdk 的改动需要验证 showcase 集成、showcase 的组件需要从 cli 注册表同步——这些改动后必须联动验证的约束恰好对应 execute 命令中串行依赖与Step 5 验证两个环节是判断任务能否并入同波次的天然依据。七、如何在仓库中使用这条命令查看与使用这条命令不需要修改仓库任何内容阅读命令定义直接打开 .claude/commands/execute.md其 frontmatter 的description会在 Claude Code 的命令列表中展示调用方式在 Claude Code 中输入/execute并附上任务描述命令正文中的$ARGUMENTS会被你的任务文本替换从而激活执行协调者角色配套使用配合/plan产出计划文档、/commit原子化提交、/create-pr生成 PR 描述可形成完整闭环子代理的提示词模板参考 .claude/agents/planner.md 与 .claude/agents/researcher.md本地开发环境仓库的 conductor-setup.sh校验 Node.js ≥ 22 并安装依赖、按 .env.example 初始化各应用环境文件与 conductor-run.sh提供 showcase/docs/web/api 的 7 种组合启动选项必要时自动拉起 Supabase为执行验证提供了配套支撑执行完成后可按需选用其一启动对应应用进行人工验收。小结.claude/commands/execute.md表面上是几十行提示词实质上是一份完整的多代理并行执行编排契约它以绝不亲自实现为底线以无依赖即并行、有依赖即串行为并行化判据以先聚合检查、再并行修复为验证策略并辅以阶段化沟通模板与状态文件机制保证长流程的可读性与可审计性。结合本仓库 AGENTS.md 的质量关卡、plans 目录的真实计划产物以及 conductor 系列脚本的工程配套这套模式完全可以在任何多文件、多包协作的开发任务中复制落地——它解决的不仅是一次命令调用而是AI 团队如何像一支真实工程团队一样分工、并行、验收与汇报的问题。【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
