背景
数十〜数百ファイルにまたがる大規模リファクタリングを、Claude Codeの/batchコマンドで並列実行するハンズオンをやりました。5〜30の並列エージェントが同時に修正しても互いに干渉しない理由と、実行前に安全確認する仕組みを整理します。
1. 各エージェントは独立したgit worktree上で動く
/batch <変更指示>
├── Agent 1（worktree）→ ファイルグループA を修正 → PR作成
├── Agent 2（worktree）→ ファイルグループB を修正 → PR作成
└── Agent N（worktree）→ ファイルグループN を修正 → PR作成
複数のエージェントが同じ作業ディレクトリを共有すると、ファイル競合や中途半端な変更の混在が起こります。/batchは各エージェントに独立したgit worktreeを割り当てることで、この問題を構造的に回避しています。
2. 内部では調査→計画→並列実行→PR作成の4フェーズが自動実行される
Phase 1: 調査 — コードベース全体をスキャンし対象ファイルを網羅的に洗い出す
Phase 2: 計画 — 独立した作業単位に分割、5〜30のエージェント数を決定
Phase 3: 並列実行 — 各ユニットに独立worktreeエージェントを起動
Phase 4: PR作成 — 変更単位ごとに個別のGitHub PRを作成
ファイル間に依存関係がある場合は同じユニットにまとめ、独立しているものだけを別ユニットとして並列化します。この依存解析があるため、順序が重要な変更でも安全に扱えます。
3. --planでドライラン、対象規模を実行前に確認できる
/batch --plan TypeScriptのany型をすべて適切な型定義に置き換えて
実際に変更を加える前に、何ファイルが対象になるか・どう分割されるかを確認できます。エージェント数が多いと数ドル〜数十ドルのコストがかかるため、大規模な変更ほど--planでの事前確認が重要になります。
4. /tasksで実行中の依存待ちも含めて可視化される
[実行中] Agent 1: src/api/ 配下のエンドポイント命名変更 (3/8 ファイル完了)
[完了] Agent 3: src/utils/ 配下のエンドポイント命名変更 → PR #47 作成済み
[待機中] Agent 4: src/tests/ 配下 (Agent 1, 2 の完了待ち)
依存関係のあるエージェントは自動的に待機状態になり、前段のエージェントが完了してから実行が始まります。/tasksでこの待機状態も含めて進捗を確認できるため、「なぜこのエージェントだけ動いていないのか」が分かりやすくなっています。
5. /batchが向く変更・向かない変更は「全ファイルで同じパターンか」で判断する
向いている: console.log → logger.info、any型の排除、命名規則の統一
向いていない: アーキテクチャの再設計、ビジネスロジックの変更
「全ファイルで同じパターンを機械的に適用する」変更は/batchが得意ですが、「ファイルごとに判断が必要な変更」は各エージェントが文脈依存の判断を誤るリスクがあり、通常のClaude Codeでの手動サポートの方が適切です。
まとめ
git worktreeによるエージェント間の隔離と、--planによる事前のドライランが、/batchを安全に使いこなす上でのポイントでした。大きな差分を1つのPRにまとめるのではなく作業単位ごとに小さなPRへ分割してくれる設計も、レビューのしやすさに直結しています。