Level 6: Systems Builder — ヘッドレス自動化とパイプライン

Claude Code はターミナルで対話的に使うだけでなく、--print フラグを使って出力を受け取るだけで終了する「ヘッドレスモード」で動作させることができます。これにより、シェルスクリプトや GitHub Actions などの CI/CD パイプラインに組み込んだ自動化が実現できます。

対象読者: マルチステップの作業を Claude Code で実践しており、自動化パイプラインへの組み込みに挑戦したい方。

学習時間の目安: 読了 25分 + 実践 40分

---

ヘッドレスモードとは

通常の Claude Code は対話的（インタラクティブ）に動作します。--print フラグを使うと、プロンプトを渡して出力を受け取るだけで終了するヘッドレスモードになります。

# 通常モード（対話的）
claude

# ヘッドレスモード（プロンプトを渡して結果を受け取り、終了する）
claude --print "src/api/main.py のコードレビューをしてください"

ヘッドレスモードはスクリプトや CI からの呼び出し、他のコマンドとのパイプ接続に適しています。

標準入力からコードを渡す

cat とパイプを使って、ファイルの内容を Claude に渡すことができます。

# ファイルの差分を標準入力で渡す
git diff main...HEAD | claude --print "この差分をコードレビューしてください"

# 複数ファイルの内容を渡す
cat src/api/routes.py | claude --print "このコードの問題点を列挙してください"

この方法を使うと、動的に生成されたデータをそのまま Claude に渡すパイプラインを構築できます。

—output-format json と jq の組み合わせ

--output-format json を使うと、Claude の出力を JSON 形式で受け取れます。jq コマンドと組み合わせることで、後続の処理で構造化データとして扱えます。

# JSON 形式で出力を受け取る
RESULT=$(claude --print --output-format json "
以下のエラーログを分析して、原因と対処法を JSON 形式で返してください。
{\"error\": \"原因\", \"solution\": \"対処法\"}

$(cat logs/app.log | tail -50)
")

# jq で特定フィールドを取り出す
echo "$RESULT" | jq -r '.solution'

シェルスクリプトへの組み込み例

汎用的な PR レビュースクリプトを作成します。任意のプロジェクトで使えるように、対象ファイルの拡張子を引数で受け取る設計にします。

#!/bin/bash
# scripts/review_pr.sh
# PR の差分を Claude にレビューさせる汎用スクリプト
# 使用方法: ./scripts/review_pr.sh "*.py *.ts"

set -e

# 対象拡張子（デフォルトは Python・TypeScript）
FILE_PATTERNS=${1:-"*.py *.ts *.tsx"}

# main との差分を取得
DIFF=$(git diff main...HEAD -- $FILE_PATTERNS)

if [ -z "$DIFF" ]; then
  echo "レビュー対象の変更なし"
  exit 0
fi

echo "=== AI コードレビュー ==="

REVIEW=$(echo "$DIFF" | claude --print "
以下はコードの差分です。以下の観点でレビューしてください：

1. バグ・ロジックエラーの可能性
2. セキュリティ上の問題（未サニタイズな値・シークレットのハードコード）
3. パフォーマンス上の問題
4. 可読性・保守性の問題

問題があれば「[重要度: 高/中/低] ファイル名:行: 説明」の形式で列挙してください。
問題がなければ「LGTM」とだけ返してください。
")

echo "$REVIEW"

# 高優先度の問題が検出された場合は終了コード 1 を返す
if echo "$REVIEW" | grep -q "\[重要度: 高\]"; then
  echo ""
  echo "高優先度の問題が検出されました。修正後に再レビューしてください。"
  exit 1
fi

スクリプトに実行権限を与えてテストします。

chmod +x scripts/review_pr.sh
./scripts/review_pr.sh "*.py"

GitHub Actions への組み込み例

.github/workflows/ai-review.yml を作成すると、PR が作成・更新されるたびに自動でレビューが実行されます。

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)

          if [ -z "$DIFF" ]; then
            echo "レビュー対象なし"
            exit 0
          fi

          echo "$DIFF" | claude --print \
            --dangerously-skip-permissions \
            "この差分をコードレビューしてください。
            バグ・セキュリティ・パフォーマンスの観点で確認してください。
            問題があれば重要度付きで列挙し、なければ LGTM と返してください。" \
            > review_result.txt

          cat review_result.txt

      - name: Post Review Comment
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs')
            const review = fs.readFileSync('review_result.txt', 'utf8')
            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## AI コードレビュー\n\n${review}\n\n---\n*Claude Code による自動レビュー*`
            })

—dangerously-skip-permissions フラグ

CI 環境など、ユーザーの確認が取れない自動実行環境では、--dangerously-skip-permissions フラグで確認ダイアログをスキップできます。

claude --print --dangerously-skip-permissions "..."

このフラグはファイルの変更・削除など、すべての操作権限を Claude に与えます。**信頼できる CI 環境など、操作内容が限定・管理された場所でのみ使用してください。**ローカル開発環境での常用は避けることを推奨します。

---

FAQ

Q. ヘッドレスモードと通常モードの使い分けは？

自動化スクリプト・CI/CD・他のコマンドとのパイプ処理にはヘッドレスモードを使います。複雑な対話が必要なタスクや対話的なデバッグには通常モードが適しています。

Q. —output-format json を使うと何が変わる？

Claude の応答がメタデータを含む JSON 形式で返ります。jq で特定フィールドを取り出せるため、後続のスクリプトで処理しやすくなります。

---

実践チュートリアル

このレベルの実践チュートリアル →

次のレベルへ

ヘッドレスモードで PR レビューを自動化する仕組みを理解しました。次は MCP を使ってブラウザを操作する方法を学びます。

Level 7: Browser Automator — ブラウザ操作・スクレイピング・PDF へ進みましょう。