Claude Codeを非対話で自動実行する前の確認事項｜安全なバッチ処理の組み方

Claude Codeは、-pまたは--printを付けると、対話画面を開かずに1回の処理を実行して終了できます。これが非対話モード(=人が横に付かない実行方法)です。便利ですが、無人実行では質問や権限確認が1回出るだけでも処理が止まります。だから安全な自動化のコツは、確認をすべて消すことではありません。留守番を頼むときに「やってよいこと」「触ってはいけない場所」「終わったら何を残すか」を紙に書いて渡すのと同じで、入力・権限・終了条件・失敗時の扱いを実行前に固定することです。この記事では、その固定のしかたを公式ドキュメントの記述に沿って順番に説明します。

非対話実行に向く作業と向かない作業

最初に選ぶ作業は、次の4つを満たすものにします。

1. 読み取りが中心で、結果を捨てて何度でもやり直せる
2. 対象のファイルが狭く、実行前に列挙できる
3. 合否を機械で判定できる(テストが通る、JSONが返る、など)
4. 失敗しても本番のサービスやお金に影響しない

指定ファイルの要約、ビルドログの分類、読み取り専用のコードレビューなどが候補です。逆に、本番配信、データ削除、権限変更、支払い、秘密情報の再発行は無人実行の対象から外します。

公式ドキュメント(Run Claude Code programmatically)では、次のように-pを付けると非対話で実行できると案内されています。

claude -p "src配下を読み、型エラーの候補だけを列挙する"

もう1つ、入力の中身にも線を引きます。公式のSecurityページは、信頼できない内容(外部から届いたログや文書など)をそのままClaudeへパイプで流し込まないこと、重要ファイルの変更は確認すること、外部サービスを扱うスクリプトでは仮想マシン(=使い捨てにできる隔離されたパソコン)を使うことを推奨しています。外から来たデータには、AIへの偽の指示が紛れ込むことがあるためです。自動化する作業の選び方そのものは毎日の作業を自動化する考え方も参考になります。

実行前に入力・環境・権限を固定する

「いい感じに直して」のような依頼は、無人処理では終了判定が揺れます。入力には、対象、許可する作業、禁止事項、出力形式、合格条件の5つを含めます。対象ファイルは先に列挙し、実行中に範囲を広げません。

スクリプトやCI(=コードを自動でテスト・配布する仕組み)では、--bareを付ける方法が公式に案内されています(Run Claude Code programmatically)。--bareは、Hooks、Skills、Plugins、MCP、CLAUDE.mdなどの自動検出を省き、実行する機械ごとの差を減らします。2026-07-26時点の公式案内では「将来-pの既定になる予定」とされていますが、現在はまだ自分で指定が必要です。

claude --bare -p "report.txtを3項目で要約する" --allowedTools "Read"

--bareはOAuthやOSのキーチェーン(=パソコンの鍵の保管庫)も読みません。Anthropic APIを使う場合は、実行環境の秘密管理からANTHROPIC_API_KEYを渡すか、--settingsで指定したJSON内のapiKeyHelperを使います。キーをコマンド本文やログへ直接書かないでください。この線引きはAI開発で秘密を漏らさない確認リストでも扱っています。

注意したいのは、--bareを付けても安全になるわけではない点です。Bash、ファイル読み取り、ファイル編集の道具自体は使えるままです。安全側の制御は権限で行います。必要な道具だけを--allowedToolsで事前許可し、--permission-mode dontAskと組み合わせます。公式のChoose a permission modeによると、dontAskは事前許可された操作などに一致しないものを、質問待ちにせず自動で拒否します。無人実行では「止まって聞く」より「拒否して失敗として記録する」ほうが安全に運用できます。

claude --bare -p "対象を読み、問題だけ報告する" \
  --permission-mode dontAsk \
  --allowedTools "Read" \
  --output-format json

bypassPermissionsは権限確認と安全チェックを外すモードです。公式も、ホストへ被害を与えられない隔離済みのコンテナや仮想マシンだけで使うよう案内しています。通常のPCや、秘密へ届く一般的なCIでは使わないでください。

もう1つ、層の違いを知っておきます。公式のConfigure permissionsによると、権限設定は「どの道具を使ってよいか」の制御で、サンドボックスは「Bashと子プロセスがOSレベルでどこまでファイルやネットワークに届くか」の制限です。別々の防御層なので、--allowedToolsだけで到達範囲まで完全に隔離できるとは考えず、危険度に応じて併用します。細かいルールの書き方はClaude Codeの権限設定を安全に整えるにまとめています。

なお、パイプで渡す標準入力には上限があります。2026-07-26時点の公式案内では、Claude Code v2.1.128以降は10MBまでで、超えると失敗として終了します。大きいログはファイルへ保存し、プロンプトからパスを指定してください。

出力と終了コードを機械で検査する

後続処理が結果を読むなら、構造化出力(=決まった形のデータ)を使います。公式のCLI referenceによると、--output-formatにはtext、json、stream-jsonを指定できます。--json-schemaを併用すると、指定した型に合う出力がstructured_outputという項目に入ります。

claude --bare -p "テスト失敗の原因候補を3件以内で報告する" \
  --allowedTools "Read" \
  --max-turns 4 \
  --output-format json

「完了しました」という文章が出たことを成功条件にしてはいけません。作文は上手でも、仕事が終わっているとは限らないからです。呼び出し側で、次の順に機械検査します。

1. 終了コード(=プログラムが最後に残す成否の番号)が0かを見る
2. 出力がJSONとして壊れていないかを検査する
3. 必須キー(結果、対象、件数など)が全部あるかを確認する
4. 期待した成果物(ファイルやレポート)が実在するかを照合する
5. 変更を伴う処理なら、テストの合否まで確認する

stream-json(=途中経過を1行ずつ流す形式)を使う場合の注意も公式にあります。最後の行が、最終応答・費用・セッション情報を含むresultメッセージです。途中の行だけを見て成功と判定しないでください。検査項目の作り方はAI生成コードの検品チェックリストが使えます。

上限・ログ・人へ戻す境界を決める

無人処理には上限を3種類、別々に置きます。ここを1つで済ませようとするのが、いちばん多いつまずきです。

1つ目はターン数です。--max-turnsは非対話モードでエージェントのやり取りの回数を制限し、到達するとエラー終了します。公式仕様では既定の上限がないため、明示します。ただしこれは回数の上限であって、時計の経過時間ではありません。

2つ目は経過時間です。これは呼び出す側で設定します。GitHub Actionsなら、公式のワークフロー構文にあるとおり、stepとjobにtimeout-minutesを置けます(stepの上限は360分、jobは未指定だと360分で自動キャンセル)。Node.jsから呼ぶなら、child_processの公式仕様のとおりtimeoutの既定は0(無効)なので、値を指定して超過時にSIGTERM(=終了してほしいという合図)を送らせます。Windowsでは注意が1つあり、Wait-Processの公式仕様によると-Timeoutは「待つのをやめる」機能で、プロセスを終了させる機能ではありません。時間切れの後に、対象と子孫のプロセスが残っていないかを別に確認します。Claude Code側の挙動としては、claude -pをSIGTERMで止めると、進行中のターンと実行中Bashのプロセスツリーを止め、SessionEnd Hooksを実行して終了コード143で終わると公式に説明されています。設定例はGitHub Actionsにタイムアウトを追加するとWindowsで終了コードを確認するにあります。

3つ目は費用です。非対話モードでは--max-budget-usdでAPI呼び出し額の上限を指定でき、サブエージェント(=子として動くAI)の支出も上限に数えられます。JSON出力のtotal_cost_usdは実行ごとの目安には便利ですが、請求書の確定額そのものとして扱わないでください。金額や仕様は変わりやすいので、2026-07-26時点の公式案内を確認してから設定してください。記録のつけ方はAIコーディングの費用を記録するが参考になります。

制御したいこと	主な指定	公式仕様上の要点	呼び出し側で行う確認
対話なしで1回実行	-p / --print	応答を出力して終了する	終了コードと成果物を確認
環境差を減らす	--bare	自動検出とOAuth・キーチェーン読み取りを省く	必要な設定と認証を明示
出力を機械判定	--output-format json、--json-schema	指定スキーマに合う出力はstructured_outputに入る	必須キーと値を検証
道具を限定	--permission-mode dontAsk、--allowedTools	事前許可以外は質問せず拒否する	拒否を失敗として記録
回数を限定	--max-turns N	既定上限はなく、到達時はエラー終了する	経過時間の上限を別に設定
費用を限定	--max-budget-usd 金額	サブエージェントの支出も上限へ数える	請求元の利用記録も確認
大きい入力を渡す	ファイル保存+パス指定	標準入力はv2.1.128以降10MBまで	超える入力はファイル化

ログには、実行ID、開始・終了時刻、対象、設定、終了コード、結果の保存先、失敗の分類を残します。一方で、APIキー、個人情報、未公開コードは通知やログへ入れません。公式のMonitoringによると、OpenTelemetry(=利用状況を送る監視の仕組み)でも、ユーザープロンプト本文、応答本文、ツール引数などの記録は既定で無効です。これらを有効にすると秘密や会話履歴が含まれ得るため、有効化の前に保存先と閲覧権限を決めてください。

失敗したときの再実行にも境界を引きます。すべての失敗を同じように再試行してはいけません。

• 入力不備・認証失敗・権限拒否・出力不正は、自動で再試行しない。人が原因を直すまで止める
• API側の一時的な失敗だけ、再試行の回数と待ち時間を運用側で先に決めて自動再試行する(公式が推奨する固定回数はないため、自分の環境で決めて記録します)
• 対象外のファイルが変わった、未許可の外部通信を要求した、同じ失敗を繰り返す——このどれかを検出したら、無人処理を止めて人へ戻す

「ここから先は人へ戻す」という停止条件を先に書いておくことが、確認を減らしながら安全を保つ唯一の方法です。検出の自動化はClaude Code Hooksで検品を自動化する方法につながります。

よくある質問

Claude Codeの非対話モードとは何ですか？

claude -p "依頼"のように、対話画面を開かずに1回の処理結果を出力して終了する実行方法です。スクリプトやCIから呼べますが、合否判定と停止条件は呼び出し側にも必要です。

--bareを付けると何が変わりますか？

Hooks、Skills、Plugins、MCP、CLAUDE.mdなどの自動検出を省き、機械ごとの差を減らします。OAuthとキーチェーンも読まないため、必要な認証と設定は自分で明示して渡します。ただし道具自体は使えるままなので、--bareだけで安全になるわけではありません。

dontAskとbypassPermissionsの違いは何ですか？

dontAskは、事前許可されていない操作を質問せずに拒否するモードで、制限されたCI向けです。bypassPermissionsは権限確認と安全チェックを外すため、公式が示す隔離済みのコンテナや仮想マシンだけに用途を限定し、通常のPCや一般的なCIでは使いません。

--max-turnsだけでタイムアウトできますか？

できません。--max-turnsはエージェントのターン数の上限で、経過時間の上限ではありません。GitHub Actionsのtimeout-minutesや、Node.js・PowerShellなど呼び出し側のプロセス監視を併用します。

失敗したら何回まで自動でやり直してよいですか？

失敗の種類で分けます。入力不備・認証・権限拒否・出力不正は、人が直すまで自動再試行しません。一時的なAPI失敗だけ、回数と待ち時間を先に決めて再試行します。公式仕様として決まった回数はないため、自分の運用ルールとして記録に残してください。

まとめ

安全な最小構成は「固定した入力を渡す」「必要最小限の道具だけ許可する」「回数・時間・費用に別々の上限を置く」「構造化出力と終了コードを検査する」「危険な条件では人へ戻す」の5点です。次にやることは3つです。

• 読み取り専用の小さな1処理を選び、--bare + --allowedTools "Read" + dontAsk + --output-format jsonで1回動かしてみる
• わざと失敗させて(存在しないファイルを指定するなど)、終了コード・拒否・時間切れがログでどう見えるかを確認する
• その記録をもとに、許可する道具と対象を1つずつ広げ、人へ戻す停止条件を文章で書き残す

公式一次情報

確認日: 2026-07-26

• Run Claude Code programmatically - Claude Code Docs: -p/--printの非対話実行、--bareの挙動、標準入力10MB上限、SIGTERM時の終了コード143の説明
• CLI reference - Claude Code Docs: --allowedTools、--output-format、--json-schema、--max-turns、--max-budget-usdなど各フラグの用途と制約の一覧
• Choose a permission mode - Claude Code Docs: dontAskが未許可操作を質問せず拒否すること、bypassPermissionsを隔離環境に限定する案内
• Configure permissions - Claude Code Docs: 権限ルールとOSレベルのサンドボックスが別の防御層であることの説明
• Security - Claude Code Docs: 信頼できない内容を直接パイプしない、重要ファイルの変更を確認する、外部サービスを扱うスクリプトでは仮想マシンを使うという推奨
• Monitoring - Claude Code Docs: OpenTelemetry設定と、プロンプト本文・ツール引数などの記録が既定で無効であることの説明
• Workflow syntax for GitHub Actions - GitHub Docs: stepとjobのtimeout-minutesの上限と既定値の説明
• Child process | Node.js v26.5.0 Documentation: execのtimeout既定値0とSIGTERM送出、終了コード・シグナルの取得、孫プロセスが残り得る注意
• Wait-Process (Microsoft.PowerShell.Management) - PowerShell | Microsoft Learn: -Timeoutが待機を打ち切るだけで、プロセスを終了する機能ではないことの説明