企业官网建设流程全解析

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 command（Claude Code 自定义命令），它们共同构成一条可复用的开发流水线：

配合 .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开篇即给出四条不可逾越的核心规则，它们是整个命令设计哲学的基础：

1. 绝不亲自编辑文件——所有文件操作一律委派给子代理执行。协调者的价值在于"高层视角"而非"实现细节"，亲自改文件会破坏并行度和职责边界；
2. 智能并行化——真正相互独立的任务并发启动，但要克制地判断哪些任务适合放在一起跑，避免盲目堆并发；
3. 用 TodoWrite 跟踪进度——通过待办清单维护执行状态，让长流程可审计、可恢复；
4. 汇总结果——收集并综合各子代理的输出，以文件为单位向用户报告变更。

其中第 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 的输入时，必须显式串行化：

1. 等待前一个子代理完成；
2. 用它的结果作为下一个任务的输入信息；
3. 再启动下一波并行任务。

这与 Step 2 形成对照：依赖是并行化的"闸门"，只有在依赖边界处才需要等待。协调者需要区分"同波次并行"与"跨波次串行"两种节奏。

Step 4：收集与综合（Collect and Synthesize）

子代理全部完成后，协调者依次执行：

1. 更新待办清单，将已完成任务标记为完成；
2. 按文件逐一总结变更内容；
3. 记录遇到的任何问题或阻塞项；
4. 确定下一步行动。

这一步有一个容易被忽略的关键动作：识别与计划的偏差（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-types（TS 全工作区类型检查）、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 步——分解：

第 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" 清单是对全文的收束，也是使用这个命令时的行为准则：

• 你的职责是协调，不是实现——每当你发现自己要动手改业务代码时，停下来把它委派给子代理；
• 聪明地并行——先一起跑检查拿到全貌，再跨文件并行修复；文档明确警告"不要过度并行"（Don't 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 验证"两个环节，是判断任务能否并入同波次的天然依据。

七、如何在仓库中使用这条命令

查看与使用这条命令不需要修改仓库任何内容：

1. 阅读命令定义：直接打开 .claude/commands/execute.md，其 frontmatter 的description会在 Claude Code 的命令列表中展示；
2. 调用方式：在 Claude Code 中输入/execute并附上任务描述，命令正文中的$ARGUMENTS会被你的任务文本替换，从而激活执行协调者角色；
3. 配套使用：配合/plan（产出计划文档）、/commit（原子化提交）、/create-pr（生成 PR 描述）可形成完整闭环；子代理的提示词模板参考 .claude/agents/planner.md 与 .claude/agents/researcher.md；
4. 本地开发环境：仓库的 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