Claude Codeの/batchコマンド｜大規模コード変更を並列エージェントで一括実行する

プロジェクト全体のテストファイル生成、型定義の一括変更、importパスの統一修正——こうした大規模なコード変更を1ファイルずつ順番に処理するのは、Claude Codeを使っていても時間がかかります。/batchコマンドは、Git worktreeと並列エージェントを組み合わせて、複数のファイル変更を同時並行で実行する機能です。1つのセッションで数十ファイルの変更を安全かつ高速に完了できます。

この記事でわかること

数十ファイルにまたがる大規模なコード変更を、並列エージェントで安全かつ高速に一括実行する/batchコマンドの使い方を解説します。

• /batchコマンドの仕組み（Git worktreeベースの並列実行アーキテクチャ） — /batchは、ClaudeCodeが複数の独立したタスクを並列エージェントで同時実行するコマンドです。
• テスト生成、型変更、import修正など大規模変更の具体的なユースケース — 並列実行の特性上、/batchには向き・不向きがあります。判断基準は「各ファイルの変更が他のファイルの変更に依存しないか」です。
• 並列実行時のコンフリクト回避と安全な運用ルール — /batchが使うGitworktreeは、1つのGitリポジトリから複数の作業ディレクトリを作成する機能です。

対象読者: 大規模リファクタリングやコード変更を効率的に進めたいエンジニア

/batchコマンドとは

/batchは、Claude Codeが複数の独立したタスクを並列エージェントで同時実行するコマンドです。

内部的には、Git worktree（Gitの作業ツリー分離機能）を活用して、各エージェントが独立した作業ディレクトリで同時にコードを変更します。変更が完了すると、各worktreeの変更を元のブランチにマージします。これにより、互いに干渉しない独立したファイル変更を高速に並列処理できます。

基本的な使い方

シンプルな実行

/batch src/components/配下の全コンポーネントにユニットテストを追加してください

Claude Codeが対象ファイルを分析し、独立して処理可能な単位に自動分割した上で、複数のエージェントが並列にテストファイルを生成します。

対象を明示した実行

/batch 以下のファイルのimportパスを@/lib/から@/utils/に変更してください: src/components/Header.tsx, src/components/Footer.tsx, src/components/Sidebar.tsx, src/pages/index.tsx, src/pages/about.tsx

対象ファイルを明示的に指定することで、より精密な並列実行が可能です。

処理の流れ

/batchの内部処理は以下の順序で進みます。

実務での活用パターン

パターン1: プロジェクト全体のテストファイル一括生成

既存コードにテストが不足しているプロジェクトで、一括でテストファイルを追加する場面です。

Before（順次実行）:

20個のコンポーネントに対してテストを1つずつ生成。1ファイルあたり2-3分かかり、全体で約50分。途中でコンテキストが溢れ、後半のテストの品質が低下する。

After（/batchで並列実行）:

/batch src/components/配下の全.tsxファイルにReact Testing Libraryを使ったユニットテストを追加してください。各テストファイルは対応するコンポーネントと同じディレクトリに配置し、ファイル名は{コンポーネント名}.test.tsxとしてください

5つの並列エージェントが各4ファイルを担当し、全20ファイルのテストを約10分で生成。各エージェントが独立したコンテキストで作業するため、後半でも品質が維持されます。

パターン2: 型定義の一括変更（TypeScript）

APIレスポンスの型定義が変更された場合、その型を使用している全ファイルの修正が必要です。

Before（順次実行）:

User型にcreatedAtフィールドが追加された場合、User型を参照している30ファイルを1つずつ修正。修正漏れが発生しやすく、ビルドエラーの解消に追加の時間がかかる。

After（/batchで並列実行）:

/batch src/types/user.tsのUser型にcreatedAt: stringフィールドが追加されました。このUser型を使用している全ファイルについて、createdAtフィールドへの対応（表示、フォーム、バリデーション）を追加してください

各エージェントが担当ファイルの文脈を理解した上で、コンポーネントの表示処理、フォームのバリデーション、APIクライアントのシリアライズ処理など、ファイルの役割に応じた適切な修正を並列で実行します。

パターン3: importパスの一括修正

プロジェクトのディレクトリ構造を変更した後、全ファイルのimportパスを一括修正する場面です。

Before（順次実行）:

src/lib/をsrc/utils/にリネーム後、importパスの修正を1ファイルずつ実行。ファイル数が多いため、途中で修正パターンがずれて一貫性が失われる。

After（/batchで並列実行）:

/batch 全ての.ts/.tsxファイルについて、import文の@/lib/を@/utils/に変更してください。re-exportファイルがある場合はそのパスも更新してください

全ファイルのimportパスが並列で一括修正されます。各エージェントは同じルール（@/lib/ → @/utils/）に従って機械的に処理するため、修正の一貫性が保たれます。なお、Claude Codeを活用した経営データの可視化やコンテンツマーケティングの支援についても、具体的な取り組みをご紹介しています。

/batchが適するタスクと適さないタスク

並列実行の特性上、/batchには向き・不向きがあります。

適するタスク

適さないタスク

判断基準は「各ファイルの変更が他のファイルの変更に依存しないか」です。依存がなければ/batchに適しています。依存がある場合は、通常モードで順次実行するか、/planコマンドで事前に実行順序を計画してください。

コンフリクト回避と安全な運用ルール

Git worktreeの仕組みを理解する

/batchが使うGit worktreeは、1つのGitリポジトリから複数の作業ディレクトリを作成する機能です。各worktreeは独立したブランチまたはコミットをチェックアウトした状態で存在し、互いのファイル変更が干渉しません。

メインの作業ディレクトリ（元のブランチ）
├── worktree-1/（エージェント1が担当するファイル群）
├── worktree-2/（エージェント2が担当するファイル群）
├── worktree-3/（エージェント3が担当するファイル群）
└── worktree-4/（エージェント4が担当するファイル群）

コンフリクトが発生するケース

同じファイルを複数のエージェントが編集した場合、マージ時にコンフリクトが発生します。/batchはタスクを分割する際にファイルの重複を避けるよう設計されていますが、共通のファイル（型定義ファイル、設定ファイルなど）が影響を受ける場合は注意が必要です。

安全な運用のためのチェックリスト

/batch実行前の推奨フロー

1. git status で未コミット変更がないことを確認
2. 作業ブランチを作成（git checkout -b feature/batch-update）
3. /plan で変更計画を作成し、タスクの独立性を確認
4. /batch で並列実行
5. 実行後にgit diff で変更内容を確認
6. テスト実行で品質を検証

関連コマンドとの組み合わせ

/plan + /batch の計画→実行フロー

大規模変更は「/planで計画→レビュー→/batchで実行」のフローが最も安全です。/planの段階でタスクの独立性を確認し、並列実行可能な単位に分割できるかを見極めます。

/batch + /diff の変更確認

/batchの実行後、/diffで全ファイルの変更差分を確認します。並列処理で意図しない変更が含まれていないか、全エージェントの変更が一貫しているかを検証する重要なステップです。

/batch + /compact の大規模セッション管理

/batchの実行結果はコンテキストを大きく消費します。実行後に/compactで結果をまとめ、次のタスクに備えてコンテキストを回復させます。

あわせて読みたい

• Claude Code × Figma連携｜デザインからコード実装までAIで一気通貫する方法
• Claude Codeでプロジェクト管理を効率化する方法｜CLAUDE.md・タスク分割・進捗管理の実践
• Claude Codeのセッション管理｜/resume・/fork・/renameで作業を効率的に引き継ぐ方法

導入時の注意点

ただし、すべての企業に同じアプローチが当てはまるわけではありません。自社の規模や業界特性、既存システムとの制約を踏まえた上で、段階的に導入することが重要です。

まとめ

StartLinkでは、こうした取り組みを企業規模に合わせてご支援しています。

まずは自社の現状を棚卸しし、最も効果が見込める領域から第一歩を踏み出してみてください。

属人化を防ぎ、チーム全体で再現可能な仕組みとして標準化することが成功の鍵です。

自社の業務フローや要件に応じて、段階的にカスタマイズしていくことをおすすめします。

• /batchコマンドは、独立したファイル変更を並列エージェントで同時実行し、大規模なコード変更を高速かつ安全に完了するための機能です
• テスト生成、importパス修正、型定義の反映といった「各ファイルが独立して変更可能」なタスクで効果を発揮します
• Git worktreeによるファイル分離があるため並列処理でもコンフリクトのリスクが低く、/planで事前に計画を立てた上で実行すれば、数十ファイル規模の変更も安全に処理できます

• *Claude Codeの全コマンド一覧はClaude Codeチートシートをご覧ください
• AI活用の全体像はAI活用完全ガイドで解説しています

よくある質問（FAQ）

Q1. /batchの並列エージェント数は指定できますか？

並列エージェントの数はClaude Codeが対象タスクの規模に応じて自動的に決定します。手動で並列数を指定する場合は、タスクの分割を明示的に行い、各エージェントの担当範囲を指示に含めます。例えば「src/components/A-Fを1グループ、G-Lを1グループとして並列処理してください」のように指定します。

Q2. /batchの実行中にエラーが発生したらどうなりますか？

1つのエージェントでエラーが発生しても、他のエージェントの処理は継続します。エラーが発生したタスクはスキップされ、実行完了後にエラーの内容と対象ファイルが報告されます。エラーが発生したファイルだけを通常モードで個別に修正できます。

Q3. /batchはGitリポジトリでないプロジェクトでも使えますか？

Git worktreeを使用するため、Gitリポジトリであることが前提です。Gitで管理されていないプロジェクトでは/batchは使用できません。Gitの初期化（git init）を行い、少なくとも1回のコミットがある状態にしてから使用してください。

Q4. /batchと手動で複数のClaude Codeセッションを開く方法はどう違いますか？

/batchはClaude Code内部でGit worktreeを自動管理し、タスクの分割・並列実行・結果のマージを一貫して処理します。手動で複数セッションを開く場合は、タスクの分割・コンフリクト回避・マージを自分で管理する必要があります。独立したファイル変更の一括処理には/batchが適しており、異なる種類のタスクを同時進行する場合は手動の複数セッションが適しています。チーム開発での並列作業については「Claude Codeマルチエージェント開発」で詳しく解説しています。