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

Claude Codeの/batchコマンドとは

/batch <指示>は、コードベース全体に及ぶ大規模な変更を1文の指示から分解し、並列に実装させるClaude Code組み込みのスキルです。コマンド一覧ではSkillとして載っており、機能としてはサブエージェントとworktreeを組み合わせて使う仕組みです。公式のagentsページも、/batchを別の協調方式ではなく、サブエージェントとworktreeをまとめて使う形と位置づけています。

スキルは、決まった処理を直接実行する組み込みコマンドとは性格が違います。公式の説明では、同梱スキルはClaudeに詳しい手順を渡し、Claudeがツールを使って段取りを組む、プロンプトベースのものです。分解の切り方が毎回まったく同じになる保証はなく、計画の承認が重要になる理由もここにあります。/batchはv2.1.63で同梱スキルとして加わり、同梱スキル自体を無効にしたいときはdisableBundledSkills設定を使います。

実行すると、調査と計画の提示までが自動で進み、承認を境に並列実装へ移ります。指示は次のように1行で渡します。

/batch migrate src/ from Solid to React

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

指示から並列実装までの流れ

流れは「調査 → 計画の提示 → 承認 → 並列実装」の4段階です。人間が介入するのは計画の承認の1回で、その前後は自動で進みます。

承認前なら、計画に納得できないときは指示を言い換えて再実行できます。「src/配下をSolidからReactへ移行」のような広い指示より、分割基準まで書いた方が意図に近い切り方になりやすいはずです。たとえば「コンポーネント単位で移行し、テストは対応するコンポーネントと同じユニットに含める」のように書きます。

worktreeによる隔離の仕組みはWorktree実践ガイドの内容と同じです。/batchは、その隔離を1コマンドの中で組み立てて使っています。

PRはどこまで自動で作られるか

コマンド一覧の説明は、各サブエージェントが「実装し、テストを走らせ、変更を公開する」とだけ書いています。PRをdraftで作るのか、どのブランチへpushするのかは、この記述からは分かりません。

PRとして現れたときの見え方は、agent viewの仕様から分かります。セッションがPRを開くと、一覧の行の右端に#1234のようなラベルが付き、PRへのリンクになります。GitLabのマージリクエストなら!1234です。追加の指示を送ったあとも、行が実行中の進捗表示に戻るあいだラベルは残ります。リンクにならない端末では、FORCE_HYPERLINK=0を設定するとラベルが素のテキストで描画されます。

実機で確認したclaude agentsのオプション

並走するセッションの状況はclaude agentsで開くagent viewで見ます。手元のClaude Code v2.1.287でclaude agents --helpを実行すると、次のオプションが並びました(抜粋)。

Usage: claude agents [options]
 
Manage background agents
 
Options:
  --cwd <path>         Show only background sessions started under <path>
  --json               Print active sessions (interactive and background) as a
                       JSON array and exit (for scripting; does not require a TTY)
  --all                With --json: also include completed background sessions
  --permission-mode <mode>  Default permission mode for sessions dispatched
                       from agent view
  --model <model>      Default model for sessions dispatched from agent view
  --effort <level>     Default effort level for sessions dispatched from agent view

大規模改修で役に立つのは--cwdと--jsonです。agent viewは既定で、自分が起動した全プロジェクトのセッションを並べます。複数のリポジトリで作業していると、/batchの20本前後のセッションが他の作業と混ざります。--cwdでリポジトリのパスを渡せば、そのディレクトリ配下のセッションだけに絞れます。

--jsonはTTYを必要とせず、完了済みも含めたいときは--allを足します。進捗を端末の別窓やスクリプトで確かめたいときに使えます。ここで確認したのはヘルプの文言までで、/batchの実行中にJSONがどんな形で出るかまでは試していません。

状態アイコンやキーバインドの詳細はagent viewガイドにあります。

後片付けで気をつけたいのが削除です。Ctrl+Xを2秒以内に2回押すとセッションを削除でき、worktreeの扱いは削除のしかたと中身で変わります。agent viewから削除すると、未コミットの変更ごとworktreeが消えます。残したい変更は先にコミットしてください。claude rmなら、未コミットの変更があるworktreeはセッションの行ごと残ります。未pushのコミットがあるときは削除が拒否され、pushするか、もう一度削除して破棄するかを選びます。コマンドで破棄するならclaude rm <id> --discard-unpushed <commit>@<worktree-id>の形で、v2.1.260以降が必要です。

gitリポジトリがないときは動くか

gitリポジトリでなくても、条件を満たせば動きます。公式のコマンド一覧が示す実行条件は次のとおりです。

changelogには、/batchをWorktreeCreateフックがworktreeを提供する環境でも動くよう改善した、という項目があります。想定されているのは、SVNやPerforce、Mercurialのような別のバージョン管理を使う環境です。フックの書き方はworktreesのドキュメントに、SVNのチェックアウトを例にした設定があります。

gitの外で止まるのは、フックの無い環境でgit initしていないディレクトリから実行したときです。解消するには、リポジトリにするか、フックを用意します。古い環境で止まるときは、まずclaude --versionでバージョンを確かめます。フックでworktreeを作る場合は.worktreeincludeが処理されないので、ローカルの設定ファイルのコピーはフックのスクリプトに書きます。

20本の壁と、先に決めておく承認の流れ

ユニットは最大30本に分解されますが、1セッションで同時に動くサブエージェントの数は、v2.1.217以降、既定で20本までです。上限に達した状態でAgentツールが新しい起動を試みると、Concurrent subagent limit reachedというエラーで失敗します。Claude側には再試行しないよう伝えられます。実行中の本数が上限を下回れば、また起動できます。制限されるのは同時に動く本数だけで、1セッションの間に起動できる総数に上限はありません。ユニット数が20を超える計画で、21本目以降をどう処理するかは公式に記述がなく、起動失敗のエラーが出ることがあります。

上限はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSに正の整数を入れると変えられます。数字以外の値は無視されるので、上限を外すことはできず、調整だけができます。ultracodeを有効にしたセッションでは、この上限自体が適用されません。

数え方には癖があります。/subtaskで作ったセッション内のフォークは実行中に1枠を使いますが、上限で止められることはありません。完了済みのサブエージェントを再開すると、上限を確認せずに新しい枠を使うので、再開が重なると実行中の本数が上限を超えることがあります。

承認プロンプトの扱いは、公式の記述から確かめられた範囲が狭い部分です。ユニット数が多いと確認が立て続けに来そうですが、/batch専用の承認の挙動はコマンド一覧には書かれていません。事前に許可ルールを整える、信頼できるリポジトリならauto modeを検討する、といった一般的な選択肢を取ると、途中停止は減らせます。claude agents --permission-modeで、agent viewから起動するセッションの既定モードを決める手もあります。

計画の承認前にレビュー体制を決めておく

レビューする側から見ると、/batchは1個の巨大なPRでなく、粒度の揃った5〜30個の変更を短時間で生み出します。レビューの負荷は本数にほぼ比例するので、実装が速く終わってもレビューが追いつかなければ改修全体が止まります。

計画を承認する前に、誰がどのユニットを見るかをざっくり割り振っておくと、承認後の混乱が減ります。ユニットごとに独立しているので、レビュー担当者を分担しやすいのも利点です。

たとえば、社内の管理画面でUIコンポーネントライブラリを置き換えるとします。対象が40個あり、置き換え方はほぼ機械的でも、コンポーネントごとにpropsの受け渡しが少しずつ違う状況です。「components/配下の各コンポーネントを新ライブラリのAPIへ移行し、既存のpropsインターフェースは変えない」と指示すれば、40個が5〜30本のユニットにまとめられて並列に進みます。1コンポーネントの移行漏れが別のユニットに波及しにくい切り方になるかどうかは、計画の段階で確かめられます。

向くケースと向かないケース

最後の行について、公式の説明は「5〜30の独立したユニット」としか書いておらず、依存がある場合の挙動は記述がありません。

選ぶ軸としては、agentsページが比較している他の手段も目安になります。小さな並列タスクはサブエージェントへの委譲が向きます。数百ファイル規模の移行や結果の相互検証が要る作業は、同ページがdynamic workflowsの用途として挙げています。ワークフローやエージェントチームのエージェントには、この20本の上限は掛からず、別の上限に従います。ワークフローの1回の実行では、既定で最大16本が同時に動き、CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTSで1〜256に変えられます(v2.1.269以降)。/batchは、その中間で「1つの指示から計画を作って任せたい」ときの選択肢です。

まとめ

/batchで時間がかかるのは実装でなく、計画の承認とレビューの分担です。同時実行は既定で20本まで、gitの外ではv2.1.281以降とフックが要る、という2つの条件を先に押さえておけば、大規模な移行で途中停止する場面は減らせます。