# Claude Codeのheadless実行でCI/CDを自動化する

> Claude Codeは`-p`フラグで非対話実行しexit codeでCI分岐できる。`--bare`モードと権限設定でパイプラインに安全に組み込む手順を解説する。

- Canonical: https://kuucorp.com/blog/claude-code-headless-mode-cicd-pipeline-smb/
- Date: 2026-09-29
- Last modified: 2026-09-29
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
タイポチェックやPRレビューのたびに専任のレビュアーを確保できない——エンジニアが数名しかいない中小企業では、こうした定型レビュー業務が後回しになりがちだ。Claude Codeの非対話実行（headless実行）を使えば、対話UIを介さずビルドスクリプトやCIパイプラインからClaude Codeを直接呼び出せる。

Claude Codeの`-p`フラグはAgent SDKをCLI経由で呼び出す入口であり、スクリプトやCI/CDに組み込むための標準的な実行方式として公式に案内されている。本記事では、中小企業がGitHub Actionsやビルドスクリプトへ安全に組み込む手順を、公式ドキュメントに基づいて解説する。

## headless実行とは何か

> headless実行は`-p`（`--print`）フラグを付けてClaude Codeを非対話で動かし、標準出力とexit codeで結果を返す方式だ。

`claude -p "プロンプト"`のように`-p`（または`--print`）フラグを付けると、対話セッションを開かずに1回の指示を実行して結果を出力する。実行は成功時にexit code 0、失敗時に非ゼロコードで終了するため、シェルスクリプトやCIジョブはこの終了コードで後続処理を分岐できる。無効なフラグを渡すと実行前にstderrへエラーが出力され、認証エラーなど実行中に起きた失敗は標準出力に結果として表示される。

```bash
cat build-error.txt | claude -p 'このビルドエラーの根本原因を簡潔に説明して' > output.txt
```

標準入力をパイプで渡せるため、ビルドログやgit diffをそのままClaude Codeに読み込ませ、結果をファイルへリダイレクトするような使い方ができる。ただしパイプ入力は10MBが上限で、超えるとエラーで終了するため、大きな入力はファイルパスで渡す。

## `--bare`モードはなぜCIで必須か

> `--bare`はhooks・スキル・MCPサーバー・CLAUDE.mdの自動読み込みを止め、どの実行環境でも同じ結果を再現する。

`-p`だけでは対話セッションと同じコンテキスト（hooks・スキル・カスタムコマンド・サブエージェント・インストール済みプラグイン・MCPサーバー・CLAUDE.md）を読み込んでしまう。CI環境ではこれが問題になる。実行者のホームディレクトリにあるhooksや、プロジェクトの`.mcp.json`に登録されたMCPサーバーが、信頼していないリポジトリでも承認ダイアログなしにそのまま動いてしまうためだ。`--bare`を付けるとこれらの自動探索を一切行わず、起動も高速化される。公式ドキュメントもCIやスクリプト用途では`--bare`を推奨モードとしている。

`--bare`モードではOAuth認証情報やシステムキーチェーンを読まないため、Claude Consoleで発行した`ANTHROPIC_API_KEY`を環境変数として渡す必要がある（AWS Bedrock・Google Cloud・Microsoft Foundry経由の場合は各プロバイダーの認証情報をそのまま使う）。GitHub Actionsで使う場合はリポジトリのSecretsにAPIキーを登録し、ワークフロー内で環境変数として展開する。

## 権限設定と出力形式はどう組むか

> 承認者不在の実行では`--permission-prompts none`で保留中の確認を拒否に倒し、`--output-format json`でコストと結果を構造化して受け取る。

`-p`の既定の権限モードはどのプランでもManual（都度確認）のため、無人実行では明示的にモードを指定する必要がある。ロックダウンしたCIでは、許可されていない呼び出しをすべて拒否する`dontAsk`か、分類器が判断する`auto`を選び、人が確認できない実行には`--permission-prompts none`を併用する。これを付けると、本来なら承認を待つ操作は保留せずその場で拒否され、Claudeには「承認できる人がいないので再試行しないように」と伝わる。

```bash
claude --bare -p "テストスイートを実行し失敗を修正して" \
  --allowedTools "Bash,Read,Edit" \
  --permission-mode dontAsk \
  --permission-prompts none \
  --output-format json
```

`--output-format json`を使うと、応答本文だけでなく`total_cost_usd`やモデル別のコスト内訳もレスポンスに含まれるため、使用量ダッシュボードを開かなくてもスクリプト側で費用を追跡できる。値はクライアント側の推定であり実際の請求額と差が出ることがある点には注意したい。権限モードごとの承認範囲の詳細は[Claude Codeの権限設計](/blog/claude-code-permission-mode-settings-design-smb/)も参照してほしい。

## GitHub Actionsへの統合はどう始めるか

> 公式のClaude Code GitHub Actionsは`@claude`メンションかイベントトリガーでPRレビューやコード修正を自動実行できる。

Anthropicは公式のGitHub Actions統合を提供しており、Claude Codeのターミナルから`/install-github-app`を実行するとGitHubアプリと必要なSecretsのセットアップがガイドされる。導入後はPRやIssueのコメントで`@claude`とメンションするとClaudeがコードを解析し、変更の実装やコミットのpushまで行う。プロンプトを固定してpushやPRオープンなどのGitHubイベントで自動実行する構成も組める。中小企業であれば、まずは「PR差分のtypoチェック」や「失敗したテストの原因調査コメント」のような小さな用途から`--bare`実行を組み込み、動作と費用感を確認してから対象範囲を広げるのが現実的だ。

[Kuuのエージェントガバナンス支援（AI Ops）](https://kuucorp.com/services/ai-ops/)では、こうしたCI/CDへのエージェント組み込みを、権限設計・コスト監視まで含めて支援している。

## 参考

- [Run Claude Code programmatically - Claude Code Docs](https://code.claude.com/docs/en/headless)
- [Claude Code GitHub Actions - Claude Code Docs](https://code.claude.com/docs/en/github-actions)

## まとめ

Claude Codeのheadless実行は、`-p`フラグとexit codeによるCI分岐を基本に、`--bare`で環境依存の自動読み込みを止め、`--permission-prompts none`のような無人向けの権限設定と`--output-format json`によるコスト可視化を組み合わせることで、中小企業でも安全にビルドスクリプトやGitHub Actionsへ組み込める。まずは小さなタスクから始め、権限範囲とコストを確認しながら適用範囲を広げていくのが現実的な進め方だ。自社パイプラインへの組み込み設計については、[Kuu株式会社](https://kuucorp.com/services/ai-ops/)にお問い合わせください。