自動化と CI/CD
Claude Code のヘッドレスモードを完全習得 — パラメータ一覧、5 つの CI/CD 実例、Docker 隔離、セッション復元、Codex との比較
最終更新 2026-09-03
目次
Claude Code はヘッドレス(headless)モードに対応しており、スクリプト・CI/CD パイプライン・自動化ワークフローの中で、人の操作なしに実行できます。本記事ではパラメータの完全な一覧と、実際のシナリオをいくつか取り上げます。
一、基本的な使い方¶
単発実行(-p モード)¶
# 基本の実行
claude -p "このプロジェクトのアーキテクチャを分析して"
# JSON 形式で出力
claude -p "すべての TODO コメントを列挙して" --output-format json
# 実行ターン数を制限
claude -p "UserService の単体テストを書いて" --max-turns 5
# モデルを指定(日常は claude-sonnet-5 が使えます。4.x も販売中)
claude -p "コードのセキュリティをレビューして" --model claude-opus-5
使えるツールを制限する¶
# 読み取りのみの分析(書き込みと実行を許可しない)
claude -p "コード品質を分析して" --allowedTools Read,Glob,Grep
# 読み書きを許可(コマンド実行は不可)
claude -p "このファイルをリファクタリングして" --allowedTools Read,Write,Edit,Glob,Grep
# 全ツール(管理された環境で)
claude -p "lint エラーを修正して" --allowedTools Read,Write,Edit,Bash,Glob,Grep
権限確認をスキップする¶
# 安全に隔離された環境でのみ使用してください!
claude -p "すべての lint エラーを直してコミットして" --dangerously-skip-permissions
セキュリティ警告:
--dangerously-skip-permissionsはすべての権限確認をスキップします。Docker コンテナまたは隔離された CI 環境でのみ使用してください。
二、パラメータ完全リファレンス¶
実行の制御¶
| パラメータ | 説明 | 例 |
|---|---|---|
-p "prompt" |
ヘッドレスモード。単発タスクを実行 | claude -p "アーキテクチャを分析" |
--bare |
最小モード。hooks/LSP/plugins をスキップ | claude --bare -p "..." |
--max-turns N |
対話ターン数の上限 | --max-turns 5 |
--model MODEL |
モデルを指定 | --model claude-opus-5 |
--dangerously-skip-permissions |
権限確認をすべてスキップ | 隔離環境のみ |
出力形式¶
| パラメータ | 説明 | 用途 |
|---|---|---|
--output-format text |
プレーンテキスト(既定) | 人が読む |
--output-format json |
構造化 JSON | スクリプトで解析する |
--output-format stream-json |
ストリーミング JSON | リアルタイム処理 |
ツールの制限¶
| パラメータ | 説明 |
|---|---|
--allowedTools Tool1,Tool2 |
指定したツールのみ許可 |
使えるツール名:Read、Write、Edit、Bash、Glob、Grep、WebFetch、WebSearch、Agent、NotebookEdit
セッション管理¶
| パラメータ | 説明 |
|---|---|
--session-id ID |
セッション ID を指定 |
--resume |
以前のセッションを再開 |
環境変数¶
| 変数 | 説明 |
|---|---|
ANTHROPIC_BASE_URL |
API エンドポイント(QCode.cc: https://api.qcode.cc/api) |
ANTHROPIC_AUTH_TOKEN |
API キー(cr_ で始まる) |
CLAUDE_CODE_MAX_TURNS |
既定の最大ターン数 |
CLAUDE_CODE_OUTPUT_FORMAT |
既定の出力形式 |
CLAUDE_MODEL |
既定のモデル |
三、CI/CD 実践例¶
実践 1:GitHub Actions — AI コードレビュー¶
name: AI Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # diff のために全履歴を取得
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: AI Code Review
env:
ANTHROPIC_BASE_URL: "https://api.qcode.cc/api"
ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
run: |
# PR で変更されたファイルを取得
FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
claude -p "以下のファイルのコード変更をレビューしてください。重点は:
1. セキュリティ脆弱性(SQL インジェクション、XSS、機密情報の漏洩)
2. 性能上の問題(N+1 クエリ、メモリリーク)
3. ロジックの誤り
4. コードスタイルの問題
変更ファイル:
$FILES" \
--output-format json \
--max-turns 3 \
--model claude-sonnet-5 \
--allowedTools Read,Glob,Grep \
> review.json
echo "Review completed"
cat review.json | jq -r '.result' || cat review.json
実践 2:テストの自動生成¶
name: Auto Generate Tests
on:
push:
paths: ['src/**/*.ts', '!src/**/*.test.ts']
jobs:
generate-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install dependencies
run: |
npm ci
npm install -g @anthropic-ai/claude-code
- name: Generate missing tests
env:
ANTHROPIC_BASE_URL: "https://api.qcode.cc/api"
ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
run: |
claude -p "src/ 配下の .ts ファイルを確認し、テストがないファイルに単体テストを作成してください。
Vitest + Testing Library を使ってください。
テストファイルは xxx.test.ts という名前で、同じディレクトリに置いてください。
カバレッジ目標は 80% 以上です。" \
--max-turns 10 \
--allowedTools Read,Write,Glob,Grep,Bash \
--dangerously-skip-permissions
- name: Run tests
run: npx vitest --run
- name: Create PR with tests
if: success()
run: |
git config user.name "claude-bot"
git config user.email "bot@qcode.cc"
git checkout -b auto-tests-$(date +%s)
git add '*.test.ts'
git commit -m "test: auto-generated unit tests" || exit 0
git push origin HEAD
実践 3:コード品質ゲート¶
name: Code Quality Gate
on: [pull_request]
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- run: npm install -g @anthropic-ai/claude-code
- name: Quality Analysis
env:
ANTHROPIC_BASE_URL: "https://api.qcode.cc/api"
ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
run: |
claude -p "コード品質を分析し、JSON 形式で出力してください:
{
\"score\": 0-100,
\"issues\": [{\"severity\": \"high|medium|low\", \"file\": \"...\", \"description\": \"...\"}],
\"summary\": \"一文のまとめ\"
}
採点基準:
- 型安全性(20 点)
- エラーハンドリング(20 点)
- テストカバレッジ(20 点)
- 可読性(20 点)
- セキュリティ(20 点)" \
--output-format json \
--max-turns 3 \
--model claude-sonnet-5 \
--allowedTools Read,Glob,Grep \
> quality.json
- name: Check score
run: |
SCORE=$(cat quality.json | jq -r '.result' | jq -r '.score // 0')
echo "Quality score: $SCORE"
if [ "$SCORE" -lt 60 ]; then
echo "Quality gate failed: score $SCORE < 60"
exit 1
fi
実践 4:Changelog の自動生成¶
#!/bin/bash
# generate-changelog.sh — Git コミットから Changelog を自動生成する
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"
# 前回の tag 以降のコミットを取得
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LAST_TAG" ]; then
COMMITS=$(git log --oneline -20)
else
COMMITS=$(git log --oneline ${LAST_TAG}..HEAD)
fi
claude -p "以下の Git コミット履歴から、構造化された Changelog を作成してください:
$COMMITS
形式:
## [バージョン] - $(date +%Y-%m-%d)
### 新機能
### 修正
### 改善
### 破壊的変更(あれば)
日本語で、簡潔かつプロフェッショナルな文体で書いてください。" \
--output-format text \
--max-turns 2 \
--model claude-sonnet-5 \
--allowedTools Read,Glob,Grep
実践 5:ドキュメントの自動更新¶
#!/bin/bash
# update-docs.sh — コード変更後に API ドキュメントを自動更新する
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_api_key"
claude -p "src/api/ 配下のルーティングファイルを確認し、docs/api.md の記述と突き合わせてください。
ドキュメントに不足している、または古くなっている API の説明を見つけ、docs/api.md を自動更新してください。
既存のドキュメントの形式と文体は保ってください。" \
--max-turns 8 \
--allowedTools Read,Write,Edit,Glob,Grep
四、Docker による隔離環境¶
CI/CD で --dangerously-skip-permissions を使う場合、Docker コンテナ内での実行を強く推奨します:
FROM node:22-slim
# Claude Code をインストール
RUN npm install -g @anthropic-ai/claude-code
# プロジェクトの依存関係をインストール
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
# QCode.cc の環境変数を設定
ENV ANTHROPIC_BASE_URL=https://api.qcode.cc/api
# ANTHROPIC_AUTH_TOKEN は実行時に注入する
# 非 root ユーザーで実行
RUN useradd -m claude
USER claude
CMD ["claude", "-p", "コードレビューを実行", "--dangerously-skip-permissions", "--max-turns", "5"]
実行:
docker build -t claude-ci .
docker run --rm -e ANTHROPIC_AUTH_TOKEN=cr_your_key claude-ci
五、セッション復元とマルチステップのパイプライン¶
複数ステップのタスク¶
# ステップ 1:分析
claude -p "プロジェクトのアーキテクチャを分析して" \
--session-id "pipeline-42" \
--output-format json \
--max-turns 3 \
--allowedTools Read,Glob,Grep
# ステップ 2:分析結果をもとに方針を立てる
claude -p "前回の分析をもとに、リファクタリング方針を立てて" \
--resume --session-id "pipeline-42" \
--max-turns 3
# ステップ 3:方針を実行する
claude -p "リファクタリング方針の第 1 ステップを実行して" \
--resume --session-id "pipeline-42" \
--max-turns 10 \
--allowedTools Read,Write,Edit,Bash,Glob,Grep
六、コスト管理¶
戦略 1:ターン数を制限する¶
# 単純なタスクは 3 ターンで十分
claude -p "ざっと分析して" --max-turns 3
# 複雑なタスクでも最大 10 ターン
claude -p "全面的にリファクタリングして" --max-turns 10
戦略 2:適切なモデルを選ぶ¶
| 場面 | おすすめモデル | 理由 |
|---|---|---|
| コードレビュー | Sonnet | 十分な性能で安い |
| セキュリティスキャン | Opus | 深い分析が要る |
| 一括フォーマット | Haiku | 最も安い |
| テスト生成 | Sonnet | コストパフォーマンス最良 |
claude -p "コードを整形して" --model claude-haiku-4-5 --max-turns 3
戦略 3:ツールを絞ってトークン消費を減らす¶
# 読み取りのみの分析 → 書き込みやテストの往復が発生しない
claude -p "コードを分析して" --allowedTools Read,Glob,Grep --max-turns 3
七、Codex のヘッドレスモードとの比較¶
| 項目 | Claude Code -p | Codex headless |
|---|---|---|
| パラメータ | -p "prompt" |
codex -q "prompt" |
| サンドボックス | Docker による隔離が必要 | カーネルレベルのサンドボックス内蔵 |
| 出力形式 | text/json/stream-json | text/json |
| セッション復元 | --resume --session-id |
非対応 |
| ツール制限 | --allowedTools |
--approval-mode |
| 並列実行 | 非対応 | codex cloud exec |
併用のコツ:Claude Code で分析と計画(読み取りのみ)、Codex で実行(全自動)。
QCode.cc のプランは枠を共有するため、CI 内で 2 つのツールを切り替えるコストはゼロです。
八、ベストプラクティス一覧¶
- 必ずターン数を制限する:CI では
--max-turnsで暴走を防ぐ - ツールを制限する:
--allowedToolsで必要なものだけ開放する - Docker で隔離する:
--dangerously-skip-permissionsを使うならコンテナ内で - JSON 出力:自動化では
--output-format jsonが解析しやすい - コスト管理:分析は Sonnet、単純なタスクは Haiku
- 冪等性:繰り返し実行しても副作用が出ないようにする
- タイムアウト:パイプラインに job timeout を設定する(例:10 分)
- 鍵の管理:API キーは CI の secrets に置き、ハードコードしない
次のステップ¶
- Hooks システム — 操作を自動でトリガーする
- CLI の便利な使い方 — コマンドラインの活用法
- コスト最適化 — 費用を抑えるコツ
- Claude Code 完全ガイド — ゼロから使いこなすまで