Claude Codeをシェルループで回して複数ファイルを一括変更する

Claude Codeをシェルループで回すとはどういうことか

対象ファイルを1本ずつ挙げ、claude -p(非対話モード)をforループで呼び出し、同じ指示を機械的に適用していく手法です。Claude Code本体には「複数ファイルへ同時に変更をかける」専用コマンドはなく、この形はシェル側のループとClaude Codeの非対話実行を組み合わせて自分で組み立てます。

対象は数百〜数千ファイル規模の一括変換です。フレームワークの移行、命名規則の統一、非推奨APIの置き換えのように「やることは同じだが対象が大量にある」作業に向きます。1ファイルごとに文脈が独立しているため、前のファイルで書いた変更が次のファイルの判断に影響しません。これは弱点にも強みにもなります。

いつシェルループを使い、いつ他の手段を使うか

Claude Codeで複数ファイルを扱う方法は1つではありません。同じ「複数」でも、独立性の高さと構築コストで向き不向きが分かれます。

シェルループの強みは単純さです。ループ本体はただのbashで、Claude Code側に特別な設定は要りません。裏返すと、ファイル間の依存を考慮した判断はできません。「このファイルの変更に合わせて別のファイルも直す」ような相互参照が必要な移行には向かず、その場合はサブエージェントで1セッションに文脈をまとめるか、Claude Codeオーケストレーター設計にあるような指揮型の並列実装が適します。人が各セッションの進行を見ながら並行させたいならClaude Code Worktree実践ガイドの隔離手法のほうが向きます。ファイル単位の独立性が高い一括変換だけがシェルループの得意分野です。

3ステップで組み立てる

ステップ1: 対象ファイルの一覧を作る

最初にClaude Code自身へ対象を洗い出させ、ファイルに保存します。

Vueへの移行が必要な2,000件のファイルを列挙し、
files.txtに保存してください。

一覧を先に固定しておくことで、次のループスクリプトはただそれを読むだけで済みます。対象選定の判断とループ実行を分離する狙いです。

ステップ2: ループスクリプトを書く

files.txtを1行ずつ読み、ファイルごとにclaude -pを呼び出します。

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

--allowedToolsは確認プロンプトなしで使わせるツールを絞り込むフラグです。ここではEditとプレフィックス一致のBash(git commit *)のみを許可し、それ以外のBashコマンドやファイル削除は都度確認が必要な状態に残しています。無人実行では、この絞り込みが暴走を防ぐ実質的な安全弁になります。許可リストを広げすぎないことが、事故を減らす最短経路です。プロンプトの最後に「Return OK or FAIL」と結果形式を指定しているのも重要です。ループ側で成否を機械的に判定できるようにするための一文です。

ステップ3: 数件でテストしてから全体を回す

いきなり2,000件を流さず、最初の2〜3件で結果を確認してから本番を回します。プロンプトの指示が曖昧だと、最初の数件でずれた変更が入り、残り全部に同じずれが波及します。数件でうまくいく指示に絞り込んでから全体に適用する順番を崩さないことが、大量変換での事故を防ぐ最も安価な方法です。

たとえば「Reactから移行」とだけ書いた最初の指示が、状態管理のライブラリまで一緒に置き換えてしまったとします。ここで全件に流す前に気づければ、直す範囲はテスト対象の2〜3件だけで済みます。プロンプトに「状態管理ライブラリはそのまま残す」と明記し、同じ2〜3件で再確認してから本番のファイル数へ広げます。この往復を惜しむと、2,000件流し終えた後に同じ手戻りをファイル単位でやり直すことになり、修正コストが桁違いに増えます。

個別ツール指定と権限モード、どちらでスコープを絞るか

権限の絞り込み方には--allowedToolsのほかにもう1つ選択肢があります。セッション全体の基準を--permission-modeで決める方法です。

-pは指定がなければManualモードで始まり、都度確認が必要な状態のままループが止まります。ループ用途で現実的なのは次の2つです。

• acceptEdits: ファイル書き込みとmkdir・mv・cpのような基本的なファイル操作コマンドは確認なしで進みます。それ以外のシェルコマンドやネットワークアクセスは、引き続き--allowedToolsかpermissions.allowルールが必要です
• dontAsk: permissions.allowルールか読み取り専用コマンド以外は一律で拒否します。ロックダウンしたCI実行に向く設定で、AskUserQuestionやMCPツールのうちrequiresUserInteraction指定のものは、許可ルールに一致していても拒否されます

ファイル1本ごとに許可するツールが変わらないなら--allowedToolsで個別に列挙するほうが見通しがよく、逆に「書き込みは許すがそれ以外は全部止める」という一律の基準で運用したいなら--permission-modeで先にベースラインを決めてから、必要な差分だけ--allowedToolsで足す組み合わせが機能します。

落とし穴 — 無人実行だからこそ起きる失敗

シェルループは対話的な確認が入らない分、途中の異常に人が気づきにくくなります。実行前に押さえておきたい点を挙げます。

• 429/529でループが早期に止まる: API側が混雑すると429(利用上限)や529(過負荷)のエラーが返ります。既定のリトライ回数は10回で上限15回までしか増やせません。CI・夜間バッチのように長時間の無人実行では、環境変数CLAUDE_CODE_RETRY_WATCHDOG=1を設定すると429/529を無制限にリトライするようになり、サーバーエラーやタイムアウトのリトライ上限も300回相当まで引き上がります
• --allowedToolsを広く許可しすぎる: Bashを無条件で許可すると、意図しないコマンドまで確認なしで実行されます。Bash(git commit *)のようにプレフィックス一致で絞り込み、必要なコマンドだけを通します
• 各呼び出しがセッションを1つ作る: claude -pはデフォルトで再開可能なセッションを保存します。数千回のループを流すとセッションが積み上がるため、後から参照する必要がなければ--no-session-persistenceを付けて保存自体を止めます
• OK/FAILの判定だけでは不十分な変更を見逃す: プロンプトが返す成否は「エラーなく終わったか」であって「意図通りに直っているか」ではありません。ビルドやテストが通る変更かどうかは、ループとは別に検証を挟む必要があります

出力を次のコマンドに渡す

--output-format jsonを付けると、応答が構造化されたJSONオブジェクトで返ります。resultフィールドに本文、total_cost_usdにそのセッションの推定コストが入るため、jqで抜き出してパイプラインに組み込めます。

claude -p "<your prompt>" --output-format json | your_command

ループの中でこの形式を使えば、ファイルごとの成否とコストを1行ずつログに残せます。失敗した行だけを抽出して再実行対象にする、といった後処理もこの形式が前提になります。デバッグ中は--verboseを足して詳細ログを見て、本番では外す運用にすると、ログの量を必要な場面だけに絞れます。

まとめ

シェルループによる一括適用は、Claude Code本体の機能ではなくシェル側の組み合わせ技です。対象一覧の固定、--allowedToolsでの権限絞り込み、少数件での検証という3ステップを踏めば、数百〜数千ファイルの機械的な一括変換を安全に流せます。ファイル間の依存を判断させたい場合や、実装を人が指揮しながら並行させたい場合は、この記事の手段ではなくサブエージェントやオーケストレーター運用のほうが向きます。無人で長時間走らせるなら、リトライ設定と権限スコープの2点だけは実行前に必ず見直してください。

よくある質問

ループを並列実行に変えることはできますか

公式の例は1件ずつ順番に処理する逐次ループです。シェル側で&によるバックグラウンド実行やxargs -Pを使えば同時実行数を増やせますが、その分APIのレート制限に早く当たりやすくなり、同じファイルへの同時コミットで衝突する可能性も出ます。依存のないファイルの読み取り専用処理から試すのが安全です。

途中で失敗したファイルだけ再実行するにはどうしますか

プロンプトに「OK or FAIL」のような機械可読な結果を返させ、ループ側でFAILだけをファイルに書き出しておきます。再実行時はそのファイルをfiles.txtの代わりに読み込めば、成功済みのファイルを二重に処理せずに済みます。

コストはどう見積もればよいですか

--output-format jsonで返るtotal_cost_usdはクライアント側の推定額で、実際の請求額とは差が出ることがあります。数件のテスト実行で1件あたりのコストを確認し、対象件数を掛けて概算する進め方が現実的です。

CLAUDE.mdの規約はループの各呼び出しでも読まれますか

読まれます。CLAUDE.mdはセッション開始時に毎回読み込まれる仕組みなので、claude -pをループで2,000回呼べば2,000回読み込まれます。プロジェクトの命名規則やコーディング規約をCLAUDE.mdに書いておけば、都度プロンプトに書き足さなくても各ファイルの変換に反映されます。逆に、ループ専用の指示(「このファイルだけは対象外」等)はCLAUDE.mdに書かず、都度のプロンプトかファイル一覧側で制御するほうが、他のセッションへの影響を避けられます。

CI(GitHub Actions等)に組み込めますか

組み込めます。非対話実行そのものはCI・pre-commitフック・自動化パイプラインへの統合を想定した機能で、GitHub Actions上での具体的な設定はClaude CodeをGitHub Actionsに組み込むで扱っています。