Back to Details

batch-orchestration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Batch Orchestration

批量编排

The 
/batch
command pattern for large-scale parallel changes.
用于大规模并行变更的 
/batch
命令模式。

How It Works

工作原理

text
/batch <instruction>
  │
  ├── 1. Research: scan repo, understand scope
  ├── 2. Decompose: split into 5-30 independent units
  ├── 3. Present plan: show units, ask for approval
  ├── 4. Execute: one background agent per unit in isolated worktree
  └── 5. Collect: each agent runs tests and opens a PR
text
/batch <instruction>
  │
  ├── 1. Research: scan repo, understand scope
  ├── 2. Decompose: split into 5-30 independent units
  ├── 3. Present plan: show units, ask for approval
  ├── 4. Execute: one background agent per unit in isolated worktree
  └── 5. Collect: each agent runs tests and opens a PR

Syntax

语法

bash
/batch Convert all React class components to function components
/batch Add error boundaries to every page component
/batch Migrate from moment.js to dayjs across the codebase
/batch Add OpenTelemetry tracing to all API handlers
The instruction should describe the change pattern, not individual files. The batch system finds the files.
bash
/batch Convert all React class components to function components
/batch Add error boundaries to every page component
/batch Migrate from moment.js to dayjs across the codebase
/batch Add OpenTelemetry tracing to all API handlers
指令应描述变更模式，而不是具体文件。Batch 系统会查找相关文件。

Phase 1: Research

阶段 1：研究

The orchestrator scans the repo to find every instance that matches the instruction:
bash
grep -r "class.*extends.*Component" --include="*.tsx" -l
It builds a complete list of targets and groups them by independence.
编排器扫描仓库，查找与指令匹配的所有实例：
bash
grep -r "class.*extends.*Component" --include="*.tsx" -l
它会构建完整的目标列表，并按独立性对这些目标进行分组。

Phase 2: Decompose

阶段 2：拆分

Each unit must be:
  • Independent — no shared state with other units
  • Self-contained — can be implemented and tested alone
  • Verifiable — has a clear pass/fail criteria
Good units:
text
Unit 1: Convert src/components/Header.tsx (class → function)
Unit 2: Convert src/components/Footer.tsx (class → function)
Unit 3: Convert src/components/Sidebar.tsx (class → function)
Bad units:
text
Unit 1: Convert all components in src/components/ (too broad)
Unit 2: Fix issues from Unit 1 (dependent)
Target 5-30 units. Fewer than 5 doesn't justify the overhead. More than 30 and coordination costs grow.
每个单元都必须满足以下条件：
  • 独立——与其他单元之间没有共享状态
  • 自包含——可以单独实现和测试
  • 可验证——具有明确的通过/失败标准
合适的单元：
text
Unit 1: Convert src/components/Header.tsx (class → function)
Unit 2: Convert src/components/Footer.tsx (class → function)
Unit 3: Convert src/components/Sidebar.tsx (class → function)
不合适的单元：
text
Unit 1: Convert all components in src/components/ (too broad)
Unit 2: Fix issues from Unit 1 (dependent)
目标为 5–30 个单元。少于 5 个不足以抵消额外开销；超过 30 个后，协作成本会不断增长。

Phase 3: Plan Approval

阶段 3：计划审批

The orchestrator presents:
text
BATCH: Convert class components to function components

Found: 18 class components across src/

Units (18):
  1. src/components/Header.tsx — class Header → function
  2. src/components/Footer.tsx — class Footer → function
  ...
  18. src/pages/Settings.tsx — class Settings → function

Per unit: convert class to function, update hooks, run component tests
Estimated: ~2 min per unit, ~5 min total (parallel)

Proceed? (y/n)
Wait for approval. Never spawn agents without explicit confirmation.
编排器会展示以下内容：
text
BATCH: Convert class components to function components

Found: 18 class components across src/

Units (18):
  1. src/components/Header.tsx — class Header → function
  2. src/components/Footer.tsx — class Footer → function
  ...
  18. src/pages/Settings.tsx — class Settings → function

Per unit: convert class to function, update hooks, run component tests
Estimated: ~2 min per unit, ~5 min total (parallel)

Proceed? (y/n)
等待审批。 未获得明确确认前，绝不启动 Agent。

Phase 4: Execute

阶段 4：执行

After approval, for each unit:
  1. Create isolated git worktree
  2. Spawn background agent in that worktree
  3. Agent implements the change
  4. Agent runs relevant tests
  5. Agent opens a PR
Agents run in parallel. Each has its own context window and worktree — no conflicts.
text
[Agent 1] ── worktree-1 ── Header.tsx ── tests pass ── PR #41
[Agent 2] ── worktree-2 ── Footer.tsx ── tests pass ── PR #42
[Agent 3] ── worktree-3 ── Sidebar.tsx ── tests fail ── flagged
获得批准后，对每个单元执行以下操作：
  1. 创建隔离的 git worktree
  2. 在该 worktree 中启动后台 Agent
  3. Agent 实施变更
  4. Agent 运行相关测试
  5. Agent 创建 PR
Agent 并行运行。每个 Agent 都有独立的上下文窗口和 worktree，因此不会产生冲突。
text
[Agent 1] ── worktree-1 ── Header.tsx ── tests pass ── PR #41
[Agent 2] ── worktree-2 ── Footer.tsx ── tests pass ── PR #42
[Agent 3] ── worktree-3 ── Sidebar.tsx ── tests fail ── flagged

Phase 5: Collect

阶段 5：收集

After all agents complete:
  • Summary of pass/fail per unit
  • Links to opened PRs
  • Any units that failed with error details
  • Failed units can be retried individually
所有 Agent 完成后：
  • 汇总每个单元的通过/失败情况
  • 提供已创建 PR 的链接
  • 列出失败单元及其错误详情
  • 可以单独重试失败的单元

Best For

适用场景

Use CaseWhy Batch Works
API migrationsSame pattern across many endpoints
Dependency upgradesFind/replace + fix across codebase
Codemod-style refactorsMechanical transformation, file by file
Adding instrumentationSame tracing/logging pattern everywhere
Test coverage gapsAdd tests to untested modules independently
Lint rule adoptionApply new rule fixes across all files
用例Batch 适用的原因
API 迁移许多端点中采用相同模式
依赖项升级跨代码库执行查找/替换和修复
Codemod 风格重构逐文件进行机械式转换
添加 instrumentation在各处应用相同的追踪/日志模式
测试覆盖缺口为未测试的模块独立添加测试
引入 Lint 规则对所有文件应用新规则的修复

Anti-Patterns

反模式

Don't BatchWhy
Interdependent changesUnits can't run in parallel if they depend on each other
Shared state modificationsMultiple agents writing to the same config or state file
Architecture changesNeed holistic reasoning, not file-by-file
Schema migrationsDatabase changes must be sequential
Changes requiring human judgment per fileDefeats the purpose of automation
不应使用 Batch 的情况原因
相互依赖的变更如果单元相互依赖，则无法并行运行
修改共享状态多个 Agent 写入同一个配置或状态文件
架构变更需要整体推理，而非逐文件处理
Schema 迁移数据库变更必须顺序执行
每个文件都需要人工判断的变更会失去自动化的意义

Relationship to Other Patterns

与其他模式的关系

PatternScaleIsolation
Direct edit1-3 filesNone needed
Subagent1 focused taskForked context
Worktree1 feature branchFull repo copy
Agent teams3-5 parallel tasksShared task list
Batch5-30 identical patternFull worktree per unit
Batch is the heaviest tool. Use it when the change is mechanical, repetitive, and the units are truly independent.
模式规模隔离方式
Direct edit1–3 个文件无需隔离
Subagent1 个聚焦任务分叉上下文
Worktree1 个功能分支完整仓库副本
Agent teams3–5 个并行任务共享任务列表
Batch5–30 个采用相同模式的单元每个单元使用完整的 worktree
Batch 是最重型的工具。仅当变更具有机械性、重复性，并且各单元真正独立时使用。

Guardrails

防护措施

  • Always review the decomposition before approving
  • Each agent must run tests before opening a PR
  • Failed units get flagged, not silently skipped
  • Clean up worktrees after all agents complete
  • Review PRs in batches — don't merge blindly
  • 审批前始终审查拆分结果
  • 每个 Agent 创建 PR 前必须运行测试
  • 标记失败的单元，不得静默跳过
  • 所有 Agent 完成后清理 worktree
  • 按批次审查 PR——不要盲目合并