Claude Codeの/batchコマンドで大規模改修を並列実行する

Claude Codeの/batchコマンドとは

/batch <指示>は、コードベース全体に及ぶ大規模な変更を1文の指示から自動で分解し、複数のPull Requestとして仕上げるClaude Code組み込みのスキルです。実行するとまずコードベースを調査し、変更を5〜30個の独立したユニットに分解した計画を提示します。承認すると、ユニットごとに専用のgit worktreeへ隔離されたバックグラウンドサブエージェントが1本ずつ立ち上がり、実装・テスト実行・PR作成までを個別に完走させます。gitリポジトリでの実行が前提で、リポジトリでない場所では動きません。

/batch migrate src/ from Solid to React

名前が同じ「バッチ」でも、AnthropicのBatch API(非同期リクエストをまとめて送信し、料金が半額になるAPI機能)とは別物です。/batchはターミナルの中でコードベースそのものを改修するコマンド、Batch APIはAPIリクエストをまとめて安く処理する仕組みという違いがあります。API課金の話であれば、Batch APIの記事を参照してください。

ステップ1: 指示を渡すと調査とユニット分解の計画が返る

指示を渡すと、Claudeはまずコードベースを調査し、変更を独立して実装できる単位に分解します。ユニット数は5から30の範囲に収まるよう設計されており、細かすぎて並列化の恩恵が薄い分解も、逆に1ユニットが肥大化して結局は逐次実行に近くなる分解も避ける設計です。提示される計画には、ユニットごとの担当範囲とファイル群が含まれます。

想定と違う切り方が出てきたら、承認せずに指示をより具体的に言い換えて再実行できます。「src/配下をSolidからReactへ移行」のような広い指示より、「コンポーネント単位で移行し、テストファイルは対応するコンポーネントと同じユニットに含める」のように分割基準まで指定した方が、狙いどおりのユニットに分解されやすくなります。

ステップ2: 承認すると、worktree隔離されたサブエージェントが並列で動く

計画を承認すると、Claude Codeはユニット数と同じ本数のバックグラウンドサブエージェントを立ち上げます。各サブエージェントは専用のgit worktreeにチェックアウトされ、他のユニットのファイル変更と混ざりません。この隔離の仕組み自体はWorktree実践ガイドで扱った内容と同じで、/batchはその隔離を1コマンドの中で自動的に組み立てて使っています。

並走するサブエージェントの状態はclaude agentsで開くagent viewから一覧できます。どのユニットが完了し、どのユニットが承認待ちで止まっているかを1画面で確認できるので、実行中に別の作業へ移ることもできます。状態アイコンやキーバインドの詳細はagent viewガイドにまとめました。

ステップ3: 各サブエージェントがテストとPR作成まで完走する

各サブエージェントは自分のユニットを実装し、テストを実行し、main・masterではない自分専用のブランチへpushして、draft状態のPull Requestを開きます。ここまでが1本のサブエージェントの完走条件で、人間の確認を待たずに自動で進みます。

レビューする側から見ると、/batchは「1個の巨大なPR」ではなく「粒度が揃った5〜30個のPR」を短時間で生み出します。レビューの負荷はPRの本数にほぼ比例するので、大規模な改修ほどレビュー体制を先に整えておく価値があります。ユニット数が多い計画を承認する前に、誰がどのPRを見るかをざっくり割り振っておくと、承認後の混乱が減ります。実行そのものは並列で速く終わっても、レビューが追いつかなければ改修全体が止まったままになる点は覚えておいて損はありません。

具体例 — ライブラリ移行での使い方

たとえば、社内の管理画面で使っているUIコンポーネントライブラリを別のものに置き換えるとします。対象コンポーネントが40個あり、置き換え方はほぼ機械的だが、コンポーネントごとにpropsの受け渡し方が微妙に違う、というのはよくある状況です。

このケースでは/batchに「components/配下の各コンポーネントを新ライブラリのAPIへ移行し、既存のpropsインターフェースは変えない」のように指示します。提示される計画では、多くの場合コンポーネント単位かディレクトリ単位でユニットが切られ、1コンポーネントの移行漏れが他のコンポーネントに波及しない粒度になります。承認すれば、40個の対象が5〜30本のユニットにまとめられたうえで並列に動き出し、数十本の個別PRとして仕上がってきます。1本の巨大なPRで40コンポーネント分の差分をレビューするより、コンポーネントごとに独立したPRを順に見ていく方が、レビュー担当者を分担しやすいという利点もあります。

使い分け早見表 — /batchが向くケース、向かないケース

よくあるつまずき

同時実行数のデフォルト上限にひっかかる。ユニットが最大30本に分解されても、1セッションで同時に動かせるサブエージェントの本数はデフォルトで20本までに制限されています(v2.1.217以降)。上限に達した状態で新しいサブエージェントの起動を試みると失敗する仕様で、Claude側にも再試行しないよう指示が渡ります。ユニット数が20に近づく規模の改修では、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS環境変数を事前に引き上げておくと安全です。

承認プロンプトが並列で押し寄せる。バックグラウンドサブエージェントは通常より絞られたツールセットで動きますが、承認が必要なツール呼び出しはメインセッションに転送されます。ユニット数が多いと、承認プロンプトが短時間に立て続けに届くことがあります。事前にauto modeや許可ルールを整えておくと、実行が途中で止まらずに進みます。

依存関係のあるユニットは想定通りに動かない。/batchはユニット同士が独立に実装できることを前提に計画を立てます。「ユニットBの実装はユニットAの完了が前提」のような依存があると、並列実行の性質上うまく噛み合いません。依存があるとわかっている変更は、事前に指示で依存の少ない切り方を明示するか、依存する部分だけ通常のセッションで先に済ませておく方が安全です。

「gitリポジトリではありません」で止まる。/batchはgitリポジトリの存在を前提にしています。git initしていないディレクトリや、リポジトリの外側で実行すると動作しません。

よくある質問

/batchとAnthropicのBatch APIは同じ機能ですか

別物です。/batchはClaude Codeのターミナル上で動く組み込みスキルで、コードベースの変更をユニットに分解してPRを作ります。Batch APIはAnthropicのAPI機能で、非同期リクエストをまとめて送信すると通常料金の半額になる仕組みです。「バッチ」という名前だけでは区別が付きにくいので、料金や実装手順を知りたい場合は、冒頭で触れたBatch APIの記事を参照してください。

作られるPRはどのブランチを元にしていますか

main・masterではない、各サブエージェント専用のブランチです。worktree隔離されたバックグラウンドセッションは、完了時に自分の作業を隔離ブランチへpushしてdraft PRを開く仕様になっています。

使い終わったworktreeの後始末はどうすればいいですか

agent viewからセッションを削除すると、そのセッションが使っていたworktreeも一緒に削除されます。マージ前に削除すると未pushの変更を失うので、対応するPRがマージされたことを確認してから削除する運用が安全です。

権限モードはどう設定すればいいですか

各サブエージェントの承認プロンプトはメインセッションに集約されます。ユニット数が多い実行を止めずに流したい場合は、事前に許可ルールを設定しておくか、信頼できるリポジトリではauto modeを使う選択肢もあります。

分解された計画が気に入らなければやり直せますか

承認する前であれば、指示を言い換えて再実行できます。ユニットの切り方が粗すぎる、あるいは細かすぎると感じたら、分割の基準(ディレクトリ単位・機能単位・ファイル単位など)を指示に明示的に書き加えると、狙いに近い計画が返ってきやすくなります。計画の段階で違和感があれば、承認する前に調整しておくのが一番手戻りが少ない進め方です。

まとめ

/batchは、1文の指示から調査・ユニット分解・承認・並列実装・PR作成までを1コマンドで完走させる仕組みです。人手を介さず走り切る分、計画の承認とレビュー体制の準備が実質的な律速段階になります。gitリポジトリが前提で、同時実行数のデフォルト上限(20本)を超える規模の改修では環境変数の調整が必要になります。数十ファイルにまたがる機械的な移行や一括置換のような、ユニット同士が独立して進められる大規模な改修に向いています。設計方針を相談しながら詰めたい変更や、依存関係が強い変更には向かないので、通常のセッションやsubagentsによる委譲と使い分けるとよいでしょう。