batch-orchestration

バッチオーケストレーション

大規模な並列変更を行うための /batch コマンドパターンです。

仕組み

/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

構文

/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

指示では個々のファイルではなく、変更パターンを説明してください。バッチシステムが対象ファイルを見つけます。

フェーズ 1：調査

オーケストレーターはリポジトリをスキャンし、指示に一致するすべての箇所を見つけます。

grep -r "class.*extends.*Component" --include="*.tsx" -l

対象の完全な一覧を作成し、独立性に基づいてグループ化します。

フェーズ 2：分解

各ユニットは次の条件を満たす必要があります。

• 独立している — 他のユニットと状態を共有しない
• 自己完結している — 単独で実装およびテストできる
• 検証可能である — 明確な合否基準がある

適切なユニット：

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)

不適切なユニット：

Unit 1: Convert all components in src/components/ (too broad)
Unit 2: Fix issues from Unit 1 (dependent)

ユニット数は 5～30 を目標にしてください。5 未満ではオーバーヘッドに見合いません。30 を超えると調整コストが増加します。

フェーズ 3：計画の承認

オーケストレーターは次の内容を提示します。

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)

承認を待ってください。 明示的な確認なしにエージェントを起動してはいけません。

フェーズ 4：実行

承認後、各ユニットについて次の作業を行います。

1. 分離された git worktree を作成する
2. その worktree 内でバックグラウンドエージェントを起動する
3. エージェントが変更を実装する
4. エージェントが関連するテストを実行する
5. エージェントが PR を作成する

エージェントは並列で動作します。それぞれが独自のコンテキストウィンドウと worktree を持つため、競合は発生しません。

[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

最適な用途

ユースケース	バッチが適している理由
API の移行	多数のエンドポイントに同じパターンを適用できる
依存関係のアップグレード	コードベース全体で検索と置換を行い、修正できる
Codemod スタイルのリファクタリング	ファイル単位の機械的な変換
計測機能の追加	あらゆる場所に同じトレース／ロギングパターンを適用できる
テストカバレッジの不足	未テストのモジュールに個別にテストを追加できる
Lint ルールの導入	すべてのファイルに新しいルールの修正を適用できる

アンチパターン

バッチ処理を避けるケース	理由
相互依存する変更	互いに依存しているユニットは並列実行できない
共有状態の変更	複数のエージェントが同じ設定ファイルや状態ファイルに書き込む
アーキテクチャの変更	ファイル単位ではなく、全体を考慮した判断が必要
スキーマの移行	データベースの変更は順番に行う必要がある
ファイルごとに人間の判断が必要な変更	自動化の目的に反する

他のパターンとの関係

パターン	規模	分離方法
直接編集	1～3 ファイル	不要
サブエージェント	1 つの特定タスク	コンテキストのフォーク
Worktree	1 つの機能ブランチ	リポジトリ全体のコピー
エージェントチーム	3～5 件の並列タスク	共有タスクリスト
バッチ	同一パターンを 5～30 件	ユニットごとに専用の worktree

バッチは最も大掛かりなツールです。変更が機械的かつ反復的で、各ユニットが本当に独立している場合に使用してください。

ガードレール

• 承認する前に必ず分解内容を確認する
• 各エージェントは PR を作成する前にテストを実行する
• 失敗したユニットにはフラグを立て、黙ってスキップしない
• すべてのエージェントが完了した後、worktree をクリーンアップする
• PR はまとめてレビューし、確認せずにマージしない