Claude Code バッチ処理完全ガイド：/batchコマンドとヘッドレスモードの実践活用¶

Claude Code の /batch コマンドは、同じ変換を数百ファイルに一括適用する場面で効果を発揮する。個別にプロンプトを送るより最大 10 倍高速で、CI/CD パイプラインへの統合も可能だ。

この記事のポイント

/batchコマンドはコードベース全体のマイグレーションを並列エージェント＋Git Worktreeで安全に実行する
ヘッドレスモード（claude -p）はCI/CDパイプラインやシェルスクリプトへの非対話統合に使う
両者はユースケースが明確に異なり、組み合わせることで開発ワークフロー全体を自動化できる

対象:

Claude Codeを日常的に使用しており、大規模変更やCI/CD統合に進みたい中〜上級者

/batchコマンドとヘッドレスモードの違い¶

/batchとclaude -pは混同されがちだが、用途がまったく異なる。前者はコードベース全体のマイグレーションを並列エージェントで自動化するもの。後者はCI/CDパイプラインにAI処理を組み込むための非対話実行モードだ。

項目	/batchコマンド	ヘッドレスモード（claude -p）
実行方法	対話セッション内でスラッシュコマンドとして実行	ターミナルからワンショットで実行
主な用途	コードベース全体のマイグレーション・リファクタリング	CI/CD統合、スクリプト自動化、パイプ処理
並列性	自動的に複数エージェントを並列起動	シェルスクリプト側で並列制御
Git連携	Git Worktreeで各エージェントを隔離、PR自動作成	標準のGit操作（スクリプト次第）
導入バージョン	v2.1.63〜¹	初期から利用可能

プロジェクト全体に一括変更を適用したいなら/batch、既存のCI/CDパイプラインにAI処理を組み込みたいならヘッドレスモードが適切な選択となる。

/batchコマンド：大規模コード変更の並列実行¶

基本的な使い方¶

/batchは対話セッション内で実行するスラッシュコマンドだ¹。自然言語で変更内容を指示するだけで、コードベースの調査から実装、PR作成まで自動で進む。

/batch migrate from React to Vue
/batch replace all uses of lodash with native equivalents
/batch add type annotations to all untyped function parameters
/batch rename all database columns from camelCase to snake_case

コマンドを実行すると、内部的にオーケストレーターエージェントが起動し、3つのフェーズで処理を進める。

内部処理の3フェーズ¶

フェーズ1：調査と計画（Research and Plan）

オーケストレーターがプランモードに入り、Exploreエージェントでコードベースを調査する。変更対象のファイル、パターン、呼び出し箇所を特定し、作業を5〜30の独立したユニットに分解する。各ユニットは他のユニットに依存せず、独立してマージ可能であることが条件だ。

検証方法（CLIテスト、既存テストスイートなど）も計画段階で決定される。検証パスが特定できない場合は、実行前にユーザーに確認が入る。

フェーズ2：ワーカー起動（Spawn Workers）

計画承認後、ユニットごとに1つのバックグラウンドエージェントが起動する。全エージェントが同時に並列実行される。各エージェントには以下が設定される。

isolation: "worktree" によるGit Worktreeでの隔離
全体目標と個別タスクを含む自己完結型プロンプト
調査フェーズで発見されたコードベースの規約情報
テスト実行手順

各ワーカーは実装完了後にテストスイートを走らせ、/simplifyによるコードレビューを経て²、コミット・プッシュ・PRの作成まで行う。

フェーズ3：進捗追跡（Track Progress）

オーケストレーターがステータステーブルを表示し、エージェントの完了に応じて更新する。最終的に「22/24 units landed as PRs」のようなサマリーが出力される。

Git Worktreeによる隔離の仕組み¶

/batchの信頼性を支えているのがGit Worktreeによる隔離機構だ。各エージェントが独自のブランチとワーキングコピーを持つことで、他のエージェントの変更と干渉しない。

project/
├── .git/                    # 共有のGitデータベース
├── .claude/
│   └── worktrees/
│       ├── batch-unit-1/    # ユニット1のワーキングコピー
│       ├── batch-unit-2/    # ユニット2のワーキングコピー
│       └── batch-unit-3/    # ユニット3のワーキングコピー
└── src/                     # メインのワーキングツリー

マージコンフリクトのリスクなしに真の並列実行が成立する。各ユニットの成果はPRとして独立しているため、一部のユニットが失敗しても他のユニットに影響しない。

/batchに適したユースケース¶

適している作業：

フレームワークマイグレーション（React → Vue、Jest → Vitestなど）
APIコントラクト変更に伴う全呼び出し元の更新
命名規約の統一（camelCase → snake_caseなど）
ライブラリ置換（axios → fetch wrapperなど）

適さない作業：

ファイル間で強い依存関係がある変更（エージェントAが作成したユーティリティをエージェントBがインポートするケース）
ゴールが不明確な探索的リファクタリング
単一ファイルの変更

ユニット間の調整が必要な作業にはAgent Teamsや通常のClaude Codeセッションが適している。

/simplifyとの連携¶

/simplifyは/batchと同時にv2.1.63で導入されたコードレビュー用スラッシュコマンドだ¹。3つの並列レビューエージェント（コード再利用、コード品質、効率性）が変更箇所を自動チェックし、問題があれば修正まで行う。

# /simplifyは単独でも使用可能
/simplify
/simplify focus on error handling

/batchのワーカーはPR作成前に/simplifyを実行するため²、PRは自動レビュー済みの状態で作成される。手動でのチェイン実行は不要だ。

ヘッドレスモード（claude -p）：CI/CDとスクリプト統合¶

基本構文¶

-p（--print）フラグを付けることで、Claude Codeを非対話モードで実行できる³。プロンプトを処理し、結果をstdoutに出力して終了する。

# 基本実行
claude -p "プロジェクトのアーキテクチャを説明して"

# パイプ経由のデータ処理
cat error.log | claude -p "このログの主要なエラーを要約して"

# ファイル入力と出力のリダイレクト
claude -p "セキュリティ脆弱性をレビューして" < app.py > security_report.txt

出力形式の選択¶

3つの出力形式が選択可能で、用途に応じて使い分ける。

# テキスト形式（デフォルト）— 人間が読む用途
claude -p "このファイルを要約して" --output-format text

# JSON形式 — 自動処理・CI/CDでの利用に推奨
claude -p "TODOコメントを一覧にして" --output-format json

# ストリーミングJSON形式 — リアルタイム処理向け
claude -p "大規模データセットを処理して" --output-format stream-json

JSON形式の出力はjqで加工できる。応答テキストの抽出やトークン使用量の確認に便利だ。

# 応答テキストのみ抽出
claude -p "このコードを分析して" --output-format json | jq -r '.result'

# トークン使用量の確認
claude -p "このファイルを要約して" --output-format json | jq '.usage'

ツール権限の制御¶

ヘッドレスモードでは対話的な権限確認ができない。--allowedToolsフラグで明示的に許可するツールを指定する。

# 読み取り専用（安全）
claude -p "コードを分析して" --allowedTools "Read,Grep,Glob"

# 限定的な書き込み許可
claude -p "バグを修正して" --allowedTools "Read,Write,Edit"

# Git操作の許可（プレフィックスマッチ）
claude -p "ステージされた変更からコミットを作成して" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git commit *)"

--allowedToolsではプレフィックスマッチが使える。Bash(git diff *)はgit diffで始まる全コマンドを許可する。スペースの位置に注意が必要で、Bash(git diff*)とするとgit diff-index等も許可対象に含まれる。

権限設定の注意点

--dangerously-skip-permissionsフラグは全権限を無条件に許可する。CI/CDのコンテナ環境など、完全に隔離された環境でのみ使用すること。本番環境やローカル開発環境での使用は推奨されない。

マルチターンセッション¶

セッションIDを利用して、複数のclaude -p呼び出し間でコンテキストを維持できる。

# 最初の呼び出し
claude -p "パフォーマンス問題をレビューして"

# 直前のセッションを継続
claude -p "データベースクエリに焦点を当てて" --continue

# セッションIDを指定して継続
session_id=$(claude -p "レビューを開始" --output-format json \
  | jq -r '.session_id')
claude -p "レビューを続行" --resume "$session_id"

セッションは約200,000トークンのコンテキストを保持する。ただしターンが増えるごとにトークン消費も増加する点に注意が必要だ。--max-turnsで実行ターン数を制限することでコスト管理が可能。

システムプロンプトのカスタマイズ¶

4つのフラグで実行時のプロンプトを制御できる。

# デフォルト動作を維持しつつ追加指示（推奨）
gh pr diff "$1" | claude -p \
  --append-system-prompt "セキュリティエンジニアとして脆弱性をレビューして" \
  --output-format json

# ファイルからの追加指示（チーム共有向け）
claude -p "コードをレビューして" \
  --append-system-prompt-file ./review-rules.md

# 完全なプロンプト置換（高度な用途）
claude -p "分析して" --system-prompt "あなたはシニアアーキテクトです。"

--append-system-promptはClaude Codeのデフォルト機能を維持したまま追加指示を与える。大半のユースケースではこちらが適切だ。--system-promptはデフォルトの指示を完全に置換するため、組み込み機能が不要な場合にのみ使用する。

CI/CDパイプラインへの統合¶

/batchはセッション内コマンドなのでCI/CDには組み込めない。パイプラインに統合するのはヘッドレスモード（claude -p）だ。

GitHub Actions¶

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Claude Code
        run: |
          curl -sSL https://claude.ai/install.sh | sh
          echo "$HOME/.claude/bin" >> $GITHUB_PATH

      - name: Security Analysis
        run: |
          git diff origin/main...HEAD | claude -p \
            --append-system-prompt "セキュリティエンジニアとして脆弱性を分析してください" \
            --output-format json > security-report.json

      - name: Post Review Comment
        uses: actions/github-script@v6
        with:
          script: |
            const report = require('./security-report.json');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: report.result
            });

GitLab CI¶

stages:
  - analysis
  - report

code_analysis:
  stage: analysis
  image: ubuntu:latest
  before_script:
    - apt-get update && apt-get install -y curl jq
    - curl -sSL https://claude.ai/install.sh | sh
    - export PATH="$HOME/.claude/bin:$PATH"
  script:
    - claude -p "保守性の課題を分析して" --output-format json
        > maintainability.json
    - claude -p "パフォーマンスのボトルネックを確認して" --output-format json
        > performance.json
  artifacts:
    paths:
      - "*.json"
    expire_in: 1 week

シェルスクリプトによるバッチ処理¶

#!/bin/bash
set -euo pipefail

# 複数ファイルのバッチレビュー
review_code() {
  local file="$1"
  claude -p "品質とセキュリティの観点でレビューして" \
    --allowedTools "Read,Grep,Glob" \
    --output-format json < "$file" \
    | jq -r '.result'
}

echo "# コードレビューレポート" > review_report.md
echo "生成日時: $(date)" >> review_report.md

for file in src/*.py; do
  echo "レビュー中: $file"
  echo -e "\n## $file\n" >> review_report.md
  review_code "$file" >> review_report.md
done

echo "レビュー完了: review_report.md"

並列実行を行う場合はGNU parallelとの組み合わせが有効だ。

# 4並列でファイルを処理
find src -name "*.py" | parallel -j 4 \
  claude -p "このコードを最適化して" \
    --allowedTools "Read" < {} "> optimized/{/}"

実践的なベストプラクティス¶

/batchコマンド使用時¶

.claude/worktrees/を.gitignoreに追加する。ワーキングツリーの内容がuntrackedファイルとして表示されるのを防げる
計画フェーズを精査する。実行前に提示される計画のファイル分割が適切か確認する。不適切なら実行前に調整できる
独立性を確認する。共有ユーティリティの作成が必要な場合は、/batchではなく通常セッションで先に実施する

ヘッドレスモード使用時¶

権限は最小限。読み取り専用の分析タスクには--allowedTools "Read,Grep,Glob"のみで十分
ターン数を制限する。--max-turns 1〜3で大半の単純タスクは完了する
終了コードを確認する。0が成功、1が汎用エラー、2が認証エラー
JSON出力を活用する。自動処理には--output-format jsonを使い、jqでパースする

コスト最適化¶

マルチターンセッションは、ターンが増えるごとにトークン消費が30〜50%増加する。大量のファイルを処理する場合は、個別のワンショット呼び出しの方がコスト効率が良い。一方で、コンテキストを維持した方が分析精度が上がるタスク（アーキテクチャレビューなど）ではセッション継続が有効だ。

用途に応じて使い分けることが、品質とコストを両立する鍵となる。

まとめ¶

Claude Codeのバッチ処理は、/batchとヘッドレスモード（claude -p）の2軸で構成されている。

/batchはGit Worktreeによるエージェント隔離と自動PR作成により、フレームワークマイグレーションや命名規約の統一を安全に並列実行できる。ヘッドレスモードはCI/CDパイプラインやシェルスクリプトへの統合を担い、既存ワークフローにAIレビューや自動分析を組み込む基盤となる。

今後のClaude Codeアップデートで/batchのユニット間調整機能が強化されれば、現在は対象外としている依存関係を持つ変更にも適用範囲が広がる可能性がある。公式のリリースノート¹を定期的に確認しておきたい。