# 自動化と CI/CD

Claude Code はヘッドレス（headless）モードに対応しており、スクリプト・CI/CD パイプライン・自動化ワークフローの中で、人の操作なしに実行できます。本記事ではパラメータの完全な一覧と、実際のシナリオをいくつか取り上げます。

---

## 一、基本的な使い方

### 単発実行（-p モード）

```bash
# 基本の実行
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
```

### 使えるツールを制限する

```bash
# 読み取りのみの分析（書き込みと実行を許可しない）
claude -p "コード品質を分析して" --allowedTools Read,Glob,Grep

# 読み書きを許可（コマンド実行は不可）
claude -p "このファイルをリファクタリングして" --allowedTools Read,Write,Edit,Glob,Grep

# 全ツール（管理された環境で）
claude -p "lint エラーを修正して" --allowedTools Read,Write,Edit,Bash,Glob,Grep
```

### 権限確認をスキップする

```bash
# 安全に隔離された環境でのみ使用してください！
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 コードレビュー

```yaml
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：テストの自動生成

```yaml
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：コード品質ゲート

```yaml
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 の自動生成

```bash
#!/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：ドキュメントの自動更新

```bash
#!/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 コンテナ内での実行を強く推奨します：

```dockerfile
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"]
```

実行：

```bash
docker build -t claude-ci .
docker run --rm -e ANTHROPIC_AUTH_TOKEN=cr_your_key claude-ci
```

---

## 五、セッション復元とマルチステップのパイプライン

### 複数ステップのタスク

```bash
# ステップ 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：ターン数を制限する

```bash
# 単純なタスクは 3 ターンで十分
claude -p "ざっと分析して" --max-turns 3

# 複雑なタスクでも最大 10 ターン
claude -p "全面的にリファクタリングして" --max-turns 10
```

### 戦略 2：適切なモデルを選ぶ

| 場面 | おすすめモデル | 理由 |
|------|---------|------|
| コードレビュー | Sonnet | 十分な性能で安い |
| セキュリティスキャン | Opus | 深い分析が要る |
| 一括フォーマット | Haiku | 最も安い |
| テスト生成 | Sonnet | コストパフォーマンス最良 |

```bash
claude -p "コードを整形して" --model claude-haiku-4-5 --max-turns 3
```

### 戦略 3：ツールを絞ってトークン消費を減らす

```bash
# 読み取りのみの分析 → 書き込みやテストの往復が発生しない
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 つのツールを切り替えるコストはゼロです。

---

## 八、ベストプラクティス一覧

1. **必ずターン数を制限する**：CI では `--max-turns` で暴走を防ぐ
2. **ツールを制限する**：`--allowedTools` で必要なものだけ開放する
3. **Docker で隔離する**：`--dangerously-skip-permissions` を使うならコンテナ内で
4. **JSON 出力**：自動化では `--output-format json` が解析しやすい
5. **コスト管理**：分析は Sonnet、単純なタスクは Haiku
6. **冪等性**：繰り返し実行しても副作用が出ないようにする
7. **タイムアウト**：パイプラインに job timeout を設定する（例：10 分）
8. **鍵の管理**：API キーは CI の secrets に置き、ハードコードしない

---

## 次のステップ

- [Hooks システム](/docs/advanced/hooks) — 操作を自動でトリガーする
- [CLI の便利な使い方](/docs/usage/cli-tips) — コマンドラインの活用法
- [コスト最適化](/docs/usage/cost-optimization) — 費用を抑えるコツ
- [Claude Code 完全ガイド](/docs/getting-started/claude-code-tutorial) — ゼロから使いこなすまで