Claude Codeをヘッドレス実行する — claude -p でCI・GitHub Actions・スクリプト自動化

結論

-p（--print）は Anthropic 公式の Best practices for Claude Code でも非対話実行の手段として挙げられている実在のフラグです。本記事は公式に記載のあるオプションを軸に、CIやスクリプトへ組み込むときの判断基準を補足します。フラグ名や対応フォーマットの最新仕様は公式ドキュメントで都度確認してください。

claude -p の基本的な使い方は？

claude -p "<プロンプト>" を実行すると、Claude Code は対話セッションを開かずに一度だけ応答を生成し、標準出力へ書き出して終了します。結果をそのまま別コマンドへパイプできるので、自動化の起点になります。

# ワンショットで質問し、結果を標準出力に得る
claude -p "src/utils/date.ts の公開関数の一覧を箇条書きで出して"

# パイプで前段の出力を渡す
git diff --staged | claude -p "この差分のリスクを3点以内で指摘して"

出力の扱い方は --output-format で切り替えます。人が読むログには既定の text、プログラムで結果を受け取るなら json、長時間ジョブの進捗を逐次監視するなら stream-json が向きます。

# JSONで受け取り、jq で必要なフィールドだけ抽出
claude -p "package.json の dependencies を JSON 配列で列挙して" \
  --output-format json | jq '.result'

# 逐次イベントを流し、ログに追記しながら監視
claude -p "テストを実行して失敗の要因を要約して" \
  --output-format stream-json | tee build/claude-stream.log

CIに載せる前に、同じコマンドをローカルのシェルで実行して期待どおりの出力が出るか確認しておくと手戻りが減ります。プロンプト・許可ツール・出力フォーマットの3点が安定してから、初めてワークフローへ移植するのが安全です。

複数ファイルへループでファンアウトするには？

対象ファイルをシェルのループで回し、1ファイルにつき1回 claude -p を呼ぶのが基本形です。ファイル単位に分けると1回あたりのコンテキストが小さくなり、失敗箇所の切り分けも容易になります。

# 変更されたMarkdownだけにフロントマター検査をかける
git diff --name-only --diff-filter=ACM main... \
  | grep '\.mdx\?$' \
  | while read -r f; do
      echo "== $f =="
      claude -p "次のファイルのフロントマターに必須フィールドが揃っているか確認し、不足があれば列挙して。ファイル: $f" \
        --allowedTools "Read" \
        --output-format text
    done

ここで重要なのが --allowedTools です。この例では Read だけを許可し、書き込み・実行系のツールを与えていません。検査だけさせたいジョブでファイル編集やコマンド実行を許可しないことで、想定外の副作用を構造的に防げます。許可するツール名は環境で利用可能なものに合わせ、必要最小限に絞ります。

auto モードと -p はどう組み合わせる？

非対話実行では人が承認できないため、承認方針を先に決めておく必要があります。公式ベストプラクティスは権限プロンプトを減らす手段として、別の分類器モデルが危険な操作だけをブロックする auto の考え方、特定コマンドの allowlist、OSレベルの隔離を挙げています。-p と組み合わせる際の指針は次のとおりです。

• 許可ツールを明示する: --allowedTools で実行できる操作を列挙し、それ以外は実行させない。
• 承認方針を指定する: --permission-mode で方針を選ぶ。非対話では「承認できない操作はブロックされる」前提で設計する。
• ブロックされたら止める: 分類器が繰り返し危険と判断する操作はそもそもCIに向きません。許可外操作で詰まったら、ジョブを失敗として終了させ、人手の確認に回します。

# 承認方針と許可ツールを明示してヘッドレス実行
claude -p "lint エラーを修正して" \
  --permission-mode auto \
  --allowedTools "Read,Edit,Bash(npm run lint)" \
  --output-format json

CI・GitHub Actions に載せる勘所は？

CIに載せるときは「認証・権限・コスト・冪等性・失敗時の扱い」の5点を先に設計します。これらは個別のフラグの話ではなく、ジョブ全体の作り方の問題です。

• 認証: APIキーやトークンはCIのシークレットに保存し、環境変数で渡します。ログやエコーに出さないよう注意します。
• 権限: --allowedTools で最小権限にします。書き込みやコミットはClaudeに任せず、CIの後続ステップ（git commit など）に分離すると監査しやすくなります。
• コスト: ループや頻繁なトリガーはトークン消費が積み上がります。対象を絞り、同時実行数とタイムアウトの上限を設定します。
• 冪等性: 同じ入力で何度走らせても安全な作りにします。生成物は決め打ちのパスに出し、差分があるときだけ後続処理を動かします。
• 失敗時の扱い: 終了コードを見て後続を制御します。--output-format json の結果を検査し、想定外なら非ゼロで落とします。

GitHub Actions では、概念としては次の流れになります。具体的なアクション名・入力・SDKの呼び出し方は変わりやすいため、ここでは構造だけ示します。実際の YAML は公式アクションや SDK の最新仕様を必ず確認してください。

# 概念例（実際のアクション名・入力は公式の最新仕様で確認すること）
jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Code headless
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff --staged > diff.txt
          claude -p "diff.txt の変更をレビューし、重大な問題のみ JSON で返して" \
            --allowedTools "Read" \
            --output-format json > review.json
      - name: Fail on critical findings
        run: |
          test "$(jq '.findings | length' review.json)" -eq 0

公式の Extend Claude Code では、CLAUDE.md・hooks・スキル・MCP などで実行環境を作り込む方向が示されています。CIでも、リポジトリの CLAUDE.md に検証コマンドや規約を書いておくと、ヘッドレス実行時の判断がブレにくくなります。

暴走させないための安全策は？

安全策の柱は「最小権限・ドライラン・全ログ・終了コード設計」の4つです。これらを満たすと、自動化が想定外の動きをしても被害が局所化します。

• 最小権限: 検査だけなら Read のみ、修正させるなら編集と限定的なコマンドだけ。Bash(npm run lint) のようにコマンドまで絞れると安全です。
• ドライラン: 書き込みを伴うジョブは、まず「何を変更するか」を出力させて確認してから、実際の変更ステップを走らせます。
• 全ログ保存: --output-format json や stream-json の出力をアーティファクトとして保存し、後から監査できるようにします。
• 終了コード設計: Claudeの出力を機械的に検査し、基準を満たさないときはCIを明示的に失敗させます。

書き込みやpushはClaudeの責務から外し、CIの別ステップに置くのが安全側の設計です。Claudeには「生成」と「検証」を任せ、「適用」は人またはCIが制御すると、レビューと自動化の両立がしやすくなります。

よくある質問

claude -p とは何ですか？

-p（--print）は Claude Code をヘッドレスで一度だけ実行するフラグです。プロンプトを渡すと対話セッションを開かずに応答を標準出力へ返して終了するため、シェルスクリプトやCIのステップにそのまま組み込めます。

出力をプログラムで扱うにはどうしますか？

--output-format json または stream-json を指定します。json は実行結果を1つのJSONオブジェクトで返すのでパースしやすく、stream-json は途中経過を逐次イベントで流すので長時間ジョブの進捗監視に向きます。既定の text は人が読むログ向けです。

CIで承認プロンプトを止めるにはどうしますか？

--allowedTools で許可するツールを明示的に列挙し、必要なら --permission-mode で承認方針を指定します。非対話環境では誰も承認できないので、許可する操作を最小限に絞ったうえで、許可外の操作は実行させない設計にします。

自動化で暴走を防ぐ安全策は？

最小権限（許可ツールの絞り込み）、ドライランでの差分確認、出力の全ログ保存、失敗時の明示的な終了コード扱いの4点です。書き込みやpushはCIの別ステップに分離し、Claudeには生成と検証だけ任せると事故が減ります。

コストはどう管理しますか？

ヘッドレス実行はループで何度も走るとトークン消費が積み上がります。対象ファイルを絞る、出力をjsonにして無駄な再実行を避ける、CIではタイムアウトと同時実行数の上限を設定する、といった基本で抑えます。実際の課金単位は公式の料金ページで確認してください。

関連記事

• Claude Code公式ベストプラクティス全訳＋実例補完
• GitHub Copilot クラウドエージェントのPRワークフロー
• Codexで記事公開を自動化したケーススタディ
• Claude Code のサブエージェント活用