はじめに
「50ファイルにまたがるAPIのエラーハンドリングを統一しなければならないのに、手作業では終わらない…」
「any 型を全ファイルから削除するリファクタリング、一人でやると修正漏れが必ず出る」
「大規模な変更を一気にやると差分が膨大になってレビューできない」
こんな悩みを抱えたことがある方は多いのではないでしょうか。
Claude Code には、これらを解決する大規模リファクタリング専用のコマンド /batch が用意されています。5〜30の並列エージェントがコードベース全体を同時に修正し、それぞれがPRを作成してくれる仕組みです。
| 従来の手作業 | /batch を使った場合 |
|---|---|
| 1人が全ファイルを順番に修正 | 複数エージェントが並列で同時修正 |
| 修正漏れが発生しやすい | 調査フェーズで対象を網羅的に洗い出す |
| 差分が膨大でレビューしにくい | ファイルグループごとに個別PRが作成される |
| 数日〜数週間かかる | 数時間〜1日程度に短縮できる |
この記事では /batch コマンドの仕組みと実践的な使い方を解説します。
この記事で分かること
/batchコマンドの仕組みと内部の実行フロー- Dynamic Workflows との関係と 2026 年 6 月の進化
/batchが得意な変更・苦手な変更の見分け方- TypeScript の
any型削除・API 命名統一など実践的なユースケース /tasksを使った実行中の進捗確認方法
こんな人におすすめ
- 数十〜数百ファイルにまたがるリファクタリングを抱えている方
- 手作業の修正漏れに悩んでいる開発者
- 大きな差分を細かいPRに分割してレビューしやすくしたい方
- Claude Code の自動化機能を本格的に活用したい方
/batch コマンドの全体像
/batch の仕組みをひと言で表すと、「大規模な変更を調査→計画→並列実行→PR作成まで自動でこなす」コマンドです。
/batch <変更指示>
│
├── Phase 1: 調査（コードベース全体を分析）
├── Phase 2: 計画（独立した作業単位に分割）
│
├── Agent 1（worktree）→ ファイルグループA を修正 → PR作成
├── Agent 2（worktree）→ ファイルグループB を修正 → PR作成
├── Agent 3（worktree）→ ファイルグループC を修正 → PR作成
├── ...（最大 30 エージェント）
└── Agent N（worktree）→ ファイルグループN を修正 → PR作成各エージェントは独立した git worktree 上で動作するため、互いに干渉せず安全に並列実行できます。
/batch 詳細解説
基本的な使い方
/batch TypeScript の any 型を strict 型に置き換えて
/batch APIエンドポイントの命名をケバブケースに統一して
/batch console.log をロガー呼び出しに置き換えて
/batch 非推奨の componentWillMount を componentDidMount に移行して/batch の後に自然言語で変更内容を指示するだけです。具体的な対象ファイルや修正方法は Claude が調査フェーズで判断します。
実行フローを順番に理解する
/batch を実行すると、内部で以下の4フェーズが自動的に進みます。
Phase 1: 調査
Claude がコードベース全体をスキャン
↓
変更が必要なファイルを網羅的に洗い出す
↓
ファイル間の依存関係・修正の複雑さを分析手作業では見落としがちなファイルも、この調査フェーズで漏れなく発見します。
Phase 2: 計画
洗い出したファイルを独立した作業単位（ユニット）に分割
↓
並列実行できるグループと順序依存があるグループを整理
↓
5〜30 のエージェント数を決定互いに依存しているファイルは同じユニットにまとめ、独立しているものは別ユニットとして並列化します。
Phase 3: 並列実行
各ユニットに対して独立した worktree エージェントを起動
↓
全エージェントが同時に修正作業を実行
↓
テスト・ビルドの検証もエージェントが担当Phase 4: PR 作成
各エージェントが担当した変更をコミット
↓
それぞれ独立した PR を GitHub に作成
↓
PR には変更内容・影響範囲・テスト結果がまとめられる大きな差分を一つの PR にまとめるのではなく、作業単位ごとに小さな PR が複数作られるため、レビューが格段にしやすくなります。
オプション
/batch --plan <変更指示> # 実行せずに計画だけ確認する（ドライラン）
/batch --max-agents 10 <指示> # エージェント数の上限を指定--plan オプションで事前に何ファイルが対象になるか・どう分割されるかを確認できます。大規模な変更を実行する前に必ず確認しましょう。
Dynamic Workflows とは
2026 年 6 月に正式リリース
2026 年 5 月 28 日、Claude Code v2.1.154 でDynamic Workflows が正式リリースされました。これは Claude が自律的に最大 1,000 の並列サブエージェントをオーケストレーションできる仕組みです。
Dynamic Workflows の構造
Orchestrator（Claude）
│
├── Sub-agent 1 ← 独立したタスクを担当
├── Sub-agent 2
├── Sub-agent 3
├── ...
└── Sub-agent N ← 最大 1,000 並列/batch との関係
/batch は Dynamic Workflows の応用実装として位置付けられます。
/batch | Dynamic Workflows（一般） | |
|---|---|---|
| 用途 | 大規模コード変更の並列化 | 汎用的なタスク並列化 |
| エージェント数 | 5〜30（コード変更に最適化） | 最大 1,000 |
| 各エージェントの成果物 | GitHub PR | タスク依存（ファイル・レポートなど） |
| 操作方法 | /batch <指示> で直接呼び出し | Claude が自律的に判断して起動 |
/batch は「コードのリファクタリング」という用途に特化した Dynamic Workflows の専用インターフェースです。/batch を使えば Dynamic Workflows の恩恵を、特別な設定なしにすぐ受けられます。
Ultracode との組み合わせ
/effort ultracode（最高推論レベル）と /batch を組み合わせると、調査・計画フェーズでより深い分析が行われます。複雑な依存関係を持つコードベースの大規模変更には有効です。
/batch が得意なこと・苦手なこと
得意なシーン
| シーン | 具体例 |
|---|---|
| パターンが一定の置き換え | console.log → logger.info、var → const |
| 全ファイルへの一律適用 | ライセンスヘッダーの追加、コーディング規約の統一 |
| 非推奨 API の移行 | React クラスコンポーネント → 関数コンポーネント |
| 型定義の強化 | any 型の排除、strict モードへの移行 |
| 命名規則の統一 | APIエンドポイント・変数名・ファイル名のリネーム |
| インポートの整理 | 未使用インポートの削除、import 順序の統一 |
苦手なシーン
| シーン | 理由と代替手段 |
|---|---|
| アーキテクチャの再設計 | 全体の構造を変える変更は /batch より設計議論が先 |
| ビジネスロジックの変更 | 動作の変更を伴う修正は手動レビューが不可欠 |
| ファイル間に強い依存がある変更 | 一部は並列化できず、順次実行になる場合がある |
| テストなしのコードベース | 変更の正しさを検証する手段がないと品質保証が難しい |
判断の目安: 「全ファイルで同じパターンを適用する」なら
/batchが向いています。「ファイルごとに判断が必要な変更」は手作業か通常の Claude のサポートが適切です。
実践ワークフロー：シーン別の使い方
ケース1：TypeScript の any 型を全廃する
大規模な TypeScript プロジェクトで any 型を一掃するケースです。
# まず計画を確認（ドライラン）
/batch --plan TypeScriptのany型をすべて適切な型定義に置き換えて
# 内容を確認してから実行
/batch TypeScriptのany型をすべて適切な型定義に置き換えて--plan で対象ファイル数と分割方法を確認してから実行するのが安全です。any 型の置き換えはコンテキストによって適切な型が異なるため、各エージェントが担当ファイルの文脈を読みながら修正します。
ケース2：API エンドポイントの命名規則を統一する
REST API のエンドポイントがキャメルケース・スネークケース・ケバブケースで混在しているケースです。
/batch すべてのAPIエンドポイントの命名をケバブケース（例: /user-profile）に統一して。
ルーター定義・テスト・ドキュメントも合わせて変更することルーター・テスト・ドキュメントを含めた横断的な変更も、一度の指示でまとめて対応できます。
ケース3：ロガーライブラリを移行する
console.log から構造化ロガー（例: pino）への移行ケースです。
/batch console.log・console.error・console.warn をすべて pino ロガーの
対応メソッド（logger.info・logger.error・logger.warn）に置き換えて。
import文の追加も忘れずにインポート文の追加も含めた指示を出すことで、各エージェントが漏れなく対応します。
ケース4：React クラスコンポーネントを関数コンポーネントに移行する
# まず計画を確認
/batch --plan Reactクラスコンポーネントを関数コンポーネント（Hooks使用）に移行して
# 対象が多い場合は段階的に実行
/batch src/components/forms/ 配下のクラスコンポーネントを関数コンポーネントに移行して影響範囲が広い場合は、ディレクトリを絞って段階的に実行するのが安全です。
/tasks で進捗を確認する
/batch を実行すると複数のエージェントがバックグラウンドで動き始めます。進捗は /tasks コマンドで確認できます。
/tasks実行中のエージェント一覧・各エージェントの状態・完了したPRのリストが表示されます。
/bg でターミナルを解放する
/batch の実行中にターミナルを解放して別の作業をしたい場合は /bg を使います。
/bg # セッションをバックグラウンドに送るバックグラウンドに送った後も /tasks で状況を確認でき、全エージェントが完了したら通知が届きます。
実行中の状態の見方
/tasks で表示される情報の例
[実行中] Agent 1: src/api/ 配下のエンドポイント命名変更 (3/8 ファイル完了)
[実行中] Agent 2: src/services/ 配下のエンドポイント命名変更 (5/12 ファイル完了)
[完了] Agent 3: src/utils/ 配下のエンドポイント命名変更 → PR #47 作成済み
[待機中] Agent 4: src/tests/ 配下 (Agent 1, 2 の完了待ち)依存関係のあるエージェントは自動的に待機し、前のエージェントが完了してから実行が始まります。
よくある質問（FAQ）
Q. /loop との違いは？
役割が根本的に異なります。
/batch | /loop | |
|---|---|---|
| 目的 | 大規模コード変更の並列実行 | プロンプトの定期繰り返し実行 |
| 使いどころ | リファクタリング・一括置換 | 定期監視・定期チェック |
| 成果物 | 複数の GitHub PR | なし（繰り返し実行するだけ） |
Q. 作成された PR はどう確認・マージすればいい？
各 PR は GitHub 上に通常の PR として作成されます。gh pr list でリストを確認し、内容をレビューしてからマージします。/code-review 123 --comment を使って各 PR に自動でインラインレビューコメントを付けることもできます。
# /batch が作成したPRの一覧を確認
gh pr list --label batch
# 各PRにレビューコメントを自動付与
/code-review 47 --comment
/code-review 48 --commentQ. エージェントが失敗した場合はどうなる？
失敗したエージェントの分は PR が作成されません。/tasks で失敗したエージェントを確認し、対象ファイルを絞って再実行するか、手動で修正します。
/tasks # 失敗したエージェントを確認
/batch src/foo.ts のみ APIエンドポイントを修正して # 対象を絞って再実行Q. 実行中に中断することはできる？
/tasks でタスクを確認してから、特定のエージェントを停止できます。完了済みのエージェントが作成した PR は残ります。
Q. コストはどれくらいかかる？
エージェント数・対象ファイル数・変更の複雑さによって異なります。30 エージェントで数百ファイルを処理する場合、数ドル〜数十ドル程度のコストになることがあります。--plan で事前に規模を確認してからコスト感を掴んでおくと安心です。
Q. テストのないコードベースでも使える？
使えますが、修正の正しさを検証する手段がなくなるため、各 PR のレビューを丁寧に行う必要があります。できればテストがある状態で実行するのが理想です。
まとめ
/batch コマンドの要点を振り返りましょう。
| 項目 | 内容 |
|---|---|
| 何をするコマンド | 大規模変更を調査→計画→並列実行→PR作成まで自動化 |
| エージェント数 | 5〜30（作業量に応じて自動調整） |
| 成果物 | 作業単位ごとに個別の GitHub PR |
| 進捗確認 | /tasks で随時確認 |
| 事前確認 | --plan でドライランして規模を把握 |
まず試すならこの手順:
# ステップ1: 計画を確認
/batch --plan <やりたい変更>
# ステップ2: 対象・分割方法を確認してから実行
/batch <やりたい変更>
# ステップ3: 進捗確認
/tasks数十〜数百ファイルにまたがるリファクタリングは、手作業でやると時間がかかるうえ修正漏れのリスクもあります。/batch を活用することで、人間はPRのレビューという本当に重要な判断に集中できるようになります。
ぜひ次の大規模変更のときに試してみてください。
関連記事：
- 【2026年6月最新版】Claude Code全90コマンド以上徹底解説
- 【2026年版】Claude Code サブエージェント活用術｜並列実行でブログ執筆・調査を最大4倍速にする方法
- 【2026年最新】Claude Codeのコードレビューを自動化する方法
- 【まとめ記事】Claude Code完全攻略ロードマップ
コメント