Claude Code /batchコマンド実践ガイド——大規模コードマイグレーションを並列で一気に片付ける

APIレスポンス型の一括変更、テストフレームワークの移行、deprecated APIの置き換え——大規模コードベースのマイグレーションは、変更箇所が数十ファイルに散らばった瞬間に心が折れる作業だ。2026年2月末にClaude Code v2.1.63で追加された/batchコマンドは、この苦行を「調査→自動分解→並列実行→PR作成」のワンストップで解決する。本記事では/batchの内部メカニズムを解剖した上で、実際のマイグレーション事例を通じて「どう使えば最大効果を得られるか」を解説する。

/batchが解決する課題——なぜ手動マイグレーションは破綻するのか

ファイル数×変更パターンの組み合わせ爆発

100ファイル超のマイグレーションでは、変更漏れ、型不整合、テスト破壊の連鎖が日常的に起こる。1箇所の型定義を変えただけで、importしている全ファイルにコンパイルエラーが波及し、修正中に別の修正がコンフリクトする——この悪循環は規模に比例して加速する。

従来のアプローチの限界

sedやjscodeshiftなどの既存ツールは、パターンマッチベースの置換には強いが、文脈に依存する変更には対応できない。「この関数の戻り値型は変えるが、同名の別モジュールは変えない」といった判断は、コードの意味を理解しなければ不可能だ。

Claude Codeの単一セッションで全ファイルを処理する方法もあるが、変更が大規模になるほどコンテキストウィンドウが溢れ、後半のファイルほど精度が落ちる。/batchはこの構造的な問題に対する回答として設計されている。

/batchの3フェーズ・オーケストレーション

/batchの核心は、単なるバッチ実行ではなく「変更の分解と並列オーケストレーション」にある。3つのフェーズを順に見ていこう。

Phase 1: Exploreエージェントによる変更範囲の調査と自動分解

/batchを実行すると、まずExploreエージェントがコードベース全体をスキャンし、変更対象を5〜30の独立したユニットに自動分解する。分解結果はユーザー承認待ちの状態で提示される。

> /batch 全ファイルのApiResponse<T>をResult<T, ApiError>に移行してください。

⏳ Exploring codebase to identify migration scope...

Found 87 files with ApiResponse<T> usage.
Proposed 12 units:

  Unit  1: src/types/result.ts (new) + src/types/api-response.ts
  Unit  2: src/api/auth/*.ts (6 files)
  Unit  3: src/api/users/*.ts (8 files)
  Unit  4: src/api/products/*.ts (11 files)
  ...
  Unit 12: tests/integration/**/*.test.ts (14 files)

? Approve unit breakdown? (y/n/edit)

この承認ステップが重要だ。依存関係のあるファイルが別ユニットに分かれていないか、共有型定義の変更が適切なユニットに含まれているかを確認できる。

Phase 2: Git Worktree隔離×並列エージェント実行

承認後、各ユニットに1つのエージェントが割り当てられ、.claude/worktrees/<name>配下のgit worktreeで真に隔離された並列実行が始まる。ブランチ名はworktree-<name>の規則で自動生成される。

各ワーカーは変更完了後に自動で/simplifyを実行し、コード品質を担保する。同一リポジトリのworktrees間でプロジェクト設定とauto memoryが共有されるため、CLAUDE.mdに記載したコーディング規約は全ワーカーが参照できる。

Running 12 units in parallel...

  Unit  │ Status      │ Files │ Duration
  ──────┼─────────────┼───────┼─────────
  1     │ ✅ Complete  │   2   │  45s
  2     │ ✅ Complete  │   6   │  1m 12s
  3     │ 🔄 Running  │   8   │  1m 30s
  4     │ 🔄 Running  │  11   │  1m 28s
  ...
  12    │ ⏳ Queued    │  14   │  --

正直、このステータステーブルがリアルタイムで更新されていくのを初めて見たときは、ちょっと感動した。

Phase 3: ユニット単位のPR作成と完了サマリー

全ユニットの処理が完了すると、各worktreeからPRが自動作成され、サマリーが出力される。

✅ Batch complete: 11/12 units landed as PRs

  Failed: Unit 7 (src/lib/legacy/*.ts) - build error
  PRs: #142, #143, #144, #145, #146, #147, #148, #149, #150, #151, #152

実践：APIレスポンス型の一括変更を/batchで実行する

プロンプト設計のコツ

/batchに渡すプロンプトは「何を」「なぜ」「制約条件」の3要素を明示すると、分解精度が格段に上がる。

/batch 全ファイルのApiResponse<T>をResult<T, ApiError>に移行してください。
型定義はsrc/types/result.tsに新規作成し、各ファイルのimportパスを更新してください。
テストも修正対象に含めてください。
移行理由: エラーハンドリングの型安全性向上。
制約: src/legacy/配下は対象外。

「制約」を明示することで、Exploreエージェントが不要なファイルをスキャン対象から除外し、ユニット数が適切な範囲に収まりやすくなる。

マージ戦略

生成された複数PRは、依存関係のないものから順にマージする。共通型定義（上の例ではsrc/types/result.tsを含むUnit 1）は他のユニットが参照するため、最初にマージするのが鉄則だ。CIが通ったPRから順次マージしていくワークフローが実務では安定する。

実践：テストフレームワーク移行（Jest → Vitest）を/batchで実行する

Jest→Vitest移行は/batchの威力が最も発揮されるユースケースの1つだ。ポイントは、設定変更とテストコード変更を分けてバッチ処理する戦略にある。

/batch JestからVitestへテストフレームワークを移行してください。
- jest.fn() → vi.fn(), jest.mock() → vi.mock() 等のAPI置換
- import文をvitest由来に変更
- jest.config.tsは変更対象外（別途対応）

設定ファイル（jest.config.ts → vitest.config.ts）の変更は/batchとは別に手動で先に済ませておく方が安全だ。設定変更を複数ユニットが同時に触ろうとしてコンフリクトするリスクを回避できる。

テストフレームワーク移行でworktree隔離が真価を発揮するのは、各ユニットが独立してvitest runを実行できる点だ。ユニットAのテストが壊れていても、ユニットBの作業には影響しない。

ハマりポイントと対処法

ユニット間の暗黙的依存でコンフリクトが発生する

共有の型定義や設定ファイルを複数ユニットが同時に変更しようとすると、マージ時にコンフリクトが発生する。Phase 1の承認画面で、共有ファイルを変更するユニットが複数ないか確認し、あればeditで1つのユニットに統合するのが最善策だ。

分解粒度の調整

ユニット数が5未満になる場合はプロンプトのスコープが広すぎる。逆に30を超える場合はディレクトリ単位でのグルーピングをプロンプトで指示する。例えば「src/api/配下はサブディレクトリ単位でユニットを分けてください」と追記するだけで粒度が安定する。

/simplifyの意図しないリファクタ混入

各ワーカーが自動実行する/simplifyは、マイグレーションと無関係なリファクタリングを混ぜ込むことがある。これはCLAUDE.mdに以下のような指示を追加することで抑制できる。

# /batch実行時の制約
/simplifyではマイグレーション対象の変更のみをレビューし、
無関係なリファクタリングは行わないでください。

なお、不要になったworktreeブランチはgit worktree listで確認し、git worktree removeで削除しておこう。放置するとブランチが溜まる。

まとめ——/batchで変わるマイグレーション戦略

/batchの本質は「変更の分解と並列オーケストレーション」だ。Exploreエージェントの調査能力とGit Worktreeの隔離性を組み合わせることで、手動で1日かかっていたマイグレーションをプロンプト1行と承認クリックで完了できる。

効果が高いのは、型定義の一括変更、テストフレームワーク移行、deprecated APIの置換など「変更パターンは明確だが対象ファイルが多い」ケースだ。逆に、密結合な設計変更やビジネスロジックの大幅な書き換えなど、ユニット間の独立性が担保できないケースには不向きである。

v2.1.63時点では分解ロジックの手動調整が必要な場面もあるが、大規模マイグレーションの戦略そのものを変えるポテンシャルを持つ機能であることは間違いない。まずは小規模な型変更から試して、チームのマイグレーション戦略に組み込んでみてほしい。