Claude Code ヘッドレスモード完全ガイド｜-pフラグの使い方からCI/CD連携・自動化まで
Claude Codeをスクリプトやパイプラインから自動実行したいとき、対話モードでは人間の入力待ちが発生して困ります。ヘッドレスモードは、この問題を解決するCLI実行方式です。-p（--print）フラグひとつで対話なしの非対話実行に切り替わり、CI/CDパイプラインやcronジョブから直接呼び出せるようになります。 ヘッドレスモードの基本と仕組み Claude Codeのヘッドレスモードとは、ターミナルのREPL（対話型インターフェース）を起動せずにプロンプトを送り、応答を標準出力に返す実行方式です。公式ドキュメントでは「Claude Agent SDK」の一部として位置づけられており、CLI経由での利用は-pフラグで実現します。 # 最もシンプルなヘッドレス実行 claude -p "auth.pyのバグを見つけて修正して" 通常のclaudeコマンドがインタラクティブREPLを起動するのに対し、-pを付けると応答をテキストで返して即座に終了します。パイプ入力にも対応しているため、他のコマンドの出力を直接受け渡せます。 # パイプで入力を渡す cat error.log | claude -p "このエラーログの原因を特定して" # 別のコマンドの出力を分析 git diff HEAD~3 | claude -p "このdiffをレビューして脆弱性がないか確認して" 通常モードとの違い 観点 通常モード (claude) ヘッドレスモード (claude -p) ユーザー入力 対話形式で逐次入力 起動時にプロンプトを一括指定 ツール承認 都度ユーザーに確認 --allowedToolsで事前許可 出力形式 ターミナルUI text / json / stream-json 主な用途 日常の開発作業 スクリプト・CI/CD・バッチ処理 スラッシュコマンド /commit等が利用可 利用不可（タスクを説明して指示） 主要なCLIフラグ一覧 ヘッドレスモードで頻繁に使うフラグを用途別に整理します。すべてのフラグは公式CLIリファレンスで確認できます。 出力制御 フラグ 説明 使用例 --output-format text プレーンテキスト出力（デフォルト） claude -p "要約して" --output-format json セッションID・メタデータ付きJSON claude -p "要約して" --output-format json --output-format stream-json 改行区切りのストリーミングJSON claude -p "説明して" --output-format stream-json --json-schema JSON Schemaに準拠した構造化出力 後述の構造化出力を参照 --verbose 詳細ログ（ターンごとの出力を表示） デバッグ時に使用 --include-partial-messages 部分的なストリーミングイベントを含める stream-jsonとの併用が必要 実行制御 フラグ 説明 使用例 --max-turns N エージェントのターン数上限 claude -p "テスト実行" --max-turns 5 --max-budget-usd N API呼び出しの費用上限（USD） claude -p "分析して" --max-budget-usd 3.00 --model 使用モデルの指定 claude -p "query" --model sonnet --allowedTools 許可するツールの指定 claude -p "修正して" --allowedTools "Read,Edit,Bash" --disallowedTools 禁止するツールの指定 claude -p "分析して" --disallowedTools "Edit" --dangerously-skip-permissions 全パーミッションチェックをスキップ コンテナ内での使用を推奨 会話管理 フラグ 説明 使用例 --continue / -c 直近の会話を継続 claude -p "続きを実装して" -c --resume SESSION_ID 特定セッションを再開 claude -p "追加修正" --resume "$sid" システムプロンプトのカスタマイズ フラグ 動作 --system-prompt デフォルトプロンプトを完全に置換 --system-prompt-file ファイルから読み込んで完全置換 --append-system-prompt デフォルトに追記（推奨） --append-system-prompt-file ファイルからデフォルトに追記 大半のケースでは--append-system-promptが安全です。Claude Codeの組み込み機能（ファイル読み取り・コマンド実行など）を維持しつつ、追加指示だけを上乗せできます。 ...