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の組み込み機能（ファイル読み取り・コマンド実行など）を維持しつつ、追加指示だけを上乗せできます。

出力フォーマットの使い分け

テキスト出力（デフォルト）

人が直接読む場合やシンプルなパイプライン向きです。

claude -p "READMEの誤字を列挙して"

JSON出力

スクリプトで応答を解析する場合に使います。resultフィールドにテキスト結果、session_idにセッションIDが含まれます。

# テキスト結果だけ抽出
claude -p "プロジェクトを要約して" --output-format json | jq -r '.result'

# セッションIDを変数にキャプチャ
session_id=$(claude -p "レビュー開始" --output-format json | jq -r '.session_id')

構造化出力（JSON Schema）

--json-schemaを指定すると、応答のstructured_outputフィールドに指定したスキーマに準拠したJSONが返ります。データ抽出やパイプライン連携で出力形式を固定したいときに有効です。

# 関数名の一覧を配列で取得
claude -p "auth.pyから関数名を抽出して" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

ストリーミングJSON

長い処理の進捗をリアルタイムで受け取りたい場合に使います。各行が1つのJSONイベントです。

# テキストデルタだけを連続表示
claude -p "再帰について説明して" \
  --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

ツール承認とパーミッション制御

ヘッドレスモードでは対話的な承認ダイアログが出ないため、使用を許可するツールを--allowedToolsで事前に列挙します。

# ファイルの読み書きとBashコマンドを許可
claude -p "テストスイートを実行して失敗を修正して" \
  --allowedTools "Bash,Read,Edit"

パーミッションルール構文

--allowedToolsはパターンマッチングに対応しています。Bash(git diff *)のように書くと、git diffで始まるコマンドだけを許可できます。末尾のスペース＋*がプレフィックスマッチを有効にするため、Bash(git diff*)（スペースなし）とは挙動が異なる点に注意が必要です。

# gitのdiff, log, status, commitだけ許可する例
claude -p "ステージ済みの変更を確認してコミットして" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

全権限スキップ（–dangerously-skip-permissions）

--dangerously-skip-permissionsを使うと、すべてのパーミッションチェックが無効になります。lint修正や定型コード生成のような低リスクな作業には便利ですが、任意コマンドを無制限に実行できるため、本番環境ではネットワーク隔離されたコンテナ内でのみ使用するのが鉄則です。

# Docker内でのみ使用する例
docker run --rm -it --network=none \
  -v $(pwd):/workspace -w /workspace \
  claude-dev:latest \
  claude -p "全ファイルのlintエラーを修正して" \
  --dangerously-skip-permissions

会話の継続とセッション管理

1回のプロンプトで完結しないタスクには、会話の継続機能が有効です。

# ステップ1: 初回分析
claude -p "このコードベースのパフォーマンス問題をレビューして"

# ステップ2: 直近の会話を継続して深掘り
claude -p "データベースクエリに絞って最適化案を出して" --continue

# ステップ3: さらに継続
claude -p "見つかった全問題のサマリーを生成して" --continue

複数のパイプラインを同時に走らせている場合は、session_idを明示して特定会話を再開します。

# セッションIDをキャプチャ
sid=$(claude -p "レビュー開始" --output-format json | jq -r '.session_id')

# 特定セッションを再開
claude -p "レビューの続き" --resume "$sid"

CI/CDパイプラインとの統合

GitHub Actionsでの活用

Claude Code GitHub Actionsを使うと、PRやIssueで@claudeとメンションするだけでコード分析やPR作成を自動化できます。

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "このPRの変更をレビューしてセキュリティ上の問題を指摘して"
          claude_args: "--max-turns 5"

claude_argsパラメータに任意のCLIフラグを渡せるため、--model、--max-turns、--allowedToolsなどをワークフローごとに調整できます。

セットアップ手順

Claude GitHub Appをリポジトリにインストール
ANTHROPIC_API_KEYをリポジトリのSecretsに登録
.github/workflows/にワークフローYAMLを配置

ターミナルからclaudeを開いて/install-github-appを実行すると、上記を対話的にセットアップできます。

GitLab CI/CDでの活用

GitLab CI/CDでも同様にヘッドレスモードを組み込めます。.gitlab-ci.ymlにステージを追加するだけです。

code-review:
  stage: review
  image: node:20
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - |
      claude -p "このマージリクエストのdiffをレビューして問題を報告して" \
        --output-format json \
        --max-turns 5 \
        --allowedTools "Read,Bash(git diff *),Bash(git log *)"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

cronジョブでの定期実行

夜間バッチや定期レポートの生成にも応用できます。

#!/bin/bash
# nightly-review.sh
set -euo pipefail

REPORT_DIR="./reports/$(date +%Y-%m-%d)"
mkdir -p "$REPORT_DIR"

claude -p "テストスイートを実行して、失敗したテストの原因分析レポートを作成して" \
  --output-format json \
  --max-turns 10 \
  --max-budget-usd 2.00 \
  --allowedTools "Bash(npm test *),Bash(npx jest *),Read" \
  | jq -r '.result' > "$REPORT_DIR/test-report.md"

echo "レポート出力先: $REPORT_DIR/test-report.md"

crontabに登録すれば毎晩自動でQAレポートが生成されます。

0 3 * * * cd /path/to/project && ./nightly-review.sh >> /var/log/nightly-review.log 2>&1

Claude Agent SDKとの関係

Claude Codeの公式ドキュメントでは、ヘッドレスモード（-pフラグ）を「Claude Agent SDK」の一部として位置づけています。もともと「Claude Code SDK」と呼ばれていましたが、Claude Agent SDKに名称変更されています。Agent SDKはCLI（claude -p）に加え、Pythonパッケージ（claude-agent-sdk）とTypeScriptパッケージ（@anthropic-ai/claude-agent-sdk）も提供しており、プログラムからフック・サブエージェント・MCP連携など高度な制御が可能です。

アクセス方法	パッケージ名	適した場面
CLI (`claude -p`)	—	シェルスクリプト・CI/CD・バッチ処理
Python SDK	`claude-agent-sdk`	Pythonアプリへの組み込み
TypeScript SDK	`@anthropic-ai/claude-agent-sdk`	Node.jsアプリへの組み込み

3つの方式は同じエージェントループとツール群（Read, Edit, Bash, Grep等）を共有しています。シェルスクリプトから始めて、フックやサブエージェントが必要になった段階でSDKへ移行するのが実用的な進め方です。

セキュリティとコスト管理

実行環境の隔離

ヘッドレスモードは無人で動作するため、意図しないファイル変更やコマンド実行のリスクがあります。

推奨する安全策:

--allowedToolsで許可ツールを最小限に絞る
--max-turnsと--max-budget-usdで暴走を防止
本番環境では読み取り専用マウント or コンテナ内で実行
--dangerously-skip-permissionsはネットワーク隔離されたコンテナ限定

APIコストの見積もり

ヘッドレスモードの各実行はAPIトークンを消費します。コスト管理のポイントは以下のとおりです。

--max-budget-usdで1回の実行あたりの上限金額を設定
--max-turnsでエージェントの反復回数を制限
--model sonnetを指定するとOpusより低コストで実行可能
GitHub Actionsの場合、ランナーの実行時間（分数）にも注意

監査ログの取得

--output-format jsonで出力すれば、各実行のプロンプト・応答・使用トークン数が記録されます。これを保存しておくことで、後から何が実行されたかを追跡できます。

# 実行ログを日付付きで保存
claude -p "コードレビュー実施" \
  --output-format json \
  --allowedTools "Read" \
  | tee "./logs/review-$(date +%Y%m%d-%H%M%S).json" \
  | jq -r '.result'

ユースケース別の実装パターン

PRレビューの自動化

PRのdiffをパイプで渡し、レビューコメントをJSON形式で取得するパターンです。

gh pr diff "$PR_NUMBER" | claude -p \
  --append-system-prompt "セキュリティエンジニアとしてレビューして。脆弱性を重点的に確認して。" \
  --output-format json

コミットメッセージの自動生成

ステージ済みの変更内容から適切なコミットメッセージを生成します。

MSG=$(claude -p "ステージ済みの変更を見て適切なコミットメッセージを生成して" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *)" \
  --output-format json | jq -r '.result')

git commit -m "$MSG"

ドキュメントの自動更新

コード変更に合わせてドキュメントを自動更新するCIジョブです。

claude -p "src/ディレクトリの最新コードに合わせてdocs/api.mdを更新して" \
  --allowedTools "Read,Edit" \
  --max-turns 5

ファンアウト（大量ファイルの並列処理）

数百ファイルの一括変換には、ファイルリストを作成してループで並列実行します。

# ステップ1: 対象ファイルをリスト化
claude -p "移行対象のPythonファイルを全てリストして" \
  --output-format json | jq -r '.result' > files.txt

# ステップ2: ループで並列実行
cat files.txt | xargs -P 4 -I {} bash -c '
  claude -p "{} のimport文をPython 3.12形式に更新して" \
    --allowedTools "Read,Edit" \
    --max-turns 3
'

xargs -P 4で最大4並列に制御することで、APIレート制限を考慮しつつスループットを上げられます。

トラブルシューティング

出力が不安定な場合

同じプロンプトでも結果が毎回異なる場合は、プロンプトの具体性を上げるか、--json-schemaで出力形式を固定します。温度パラメータの調整はCLIからは直接できないため、プロンプトエンジニアリングで対処するのが基本です。

認証エラー（ANTHROPIC_API_KEY）

-pフラグは環境変数ANTHROPIC_API_KEYが設定されている必要があります。CI環境ではSecretsに登録した値がジョブ実行時に注入されます。

# 環境変数が正しく設定されているか確認
echo $ANTHROPIC_API_KEY | head -c 10

パイプ入力が文字化けする場合

UTF-8以外のエンコーディングが混在していると出力が壊れることがあります。LANG=ja_JP.UTF-8やLC_ALL=C.UTF-8を設定した上で実行すると改善する場合があります。

ターン数超過で中断される場合

--max-turnsの値が低すぎると、複雑なタスクの途中で終了します。--continueで前回の会話を引き継いで続行するか、上限値を引き上げてください。

まとめ

Claude Codeのヘッドレスモードは、-pフラグを付けるだけで対話不要の自動実行が可能になる機能です。--output-format jsonや--json-schemaで出力を構造化し、--allowedToolsでツール権限を絞り、--max-turns/--max-budget-usdでコストと暴走を制御する——この組み合わせが自動化の基本パターンです。

GitHub Actionsとの連携はanthropics/claude-code-actionから、より高度なプログラム統合はClaude Agent SDKの公式ドキュメントから始められます。CLIの全フラグはCLIリファレンスで確認できます。

ヘッドレスモードの基本と仕組み#

通常モードとの違い#

主要なCLIフラグ一覧#

出力制御#

実行制御#

会話管理#

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

出力フォーマットの使い分け#

テキスト出力（デフォルト）#

JSON出力#

構造化出力（JSON Schema）#

ストリーミングJSON#

ツール承認とパーミッション制御#

パーミッションルール構文#

全権限スキップ（–dangerously-skip-permissions）#

会話の継続とセッション管理#

CI/CDパイプラインとの統合#

GitHub Actionsでの活用#

セットアップ手順#

GitLab CI/CDでの活用#

cronジョブでの定期実行#

Claude Agent SDKとの関係#

セキュリティとコスト管理#

実行環境の隔離#

APIコストの見積もり#

監査ログの取得#

ユースケース別の実装パターン#

PRレビューの自動化#

コミットメッセージの自動生成#

ドキュメントの自動更新#

ファンアウト（大量ファイルの並列処理）#

トラブルシューティング#

出力が不安定な場合#

認証エラー（ANTHROPIC_API_KEY）#

パイプ入力が文字化けする場合#

ターン数超過で中断される場合#

まとめ#