ヘッドレスモードと Agent SDK
Claude をスクリプトや CI/CD パイプラインで自動実行する
⏱ 想定 ~6 分
01 · 読む
ここまで Claude Code で行ってきたことはすべてインタラクティブでした — あなたが打ち、Claude が応え、あなたが承認する。しかし、Claude を自動で走らせたいときは？プルリクエストごとにレビューする CI/CD パイプラインで？毎晩 lint エラーを直すスクリプトで？
ヘッドレスモード (claude -p) は、インタラクティブターミナルなしで Claude を走らせます。プロンプトを与えると、作業を実行し、結果を返します。タイピングも承認ダイアログもなし — 入力と出力だけです。
これが、チームが Claude を自動ワークフローに統合する方法です : code review bot、test fixer、ドキュメント生成、その他多数。
💡 想像してみてくださいインタラクティブな Claude は、隣に座った同僚と会話するようなものです。ヘッドレスな Claude は、彼らにタスクをメールで送るようなもの — リクエストを送り、彼らが作業し、あなたは結果を受け取る。やり取りは不要です。
ポイントまとめ
- claude -p は Claude を非インタラクティブに走らせる (ヘッドレスモード)
- スクリプト、CI/CD パイプライン、自動化に最適
- 承認ダイアログなし — 許可ツールを事前に指定する
- 出力はテキスト、JSON、ストリーミング JSON が選べる
02 · コード例
以下は一般的なヘッドレスモードのパターンです。-p フラグで非インタラクティブになります。
ヘッドレスモードの基本的な使い方
# Simple query
claude -p "Find all TODO comments in this project"
# With allowed tools (auto-approved, no prompts)
claude -p "Run tests and fix failures" \
--allowedTools "Bash(npm test*),Read,Edit"
# Structured JSON output
claude -p "List all API endpoints" \
--output-format json
-p フラグ ('print' の短縮形) は Claude を非インタラクティブに走らせます。--allowedTools は特定のツールを事前承認するので、Claude はパーミッションプロンプトなしで作業できます。--output-format json は、プレーンテキストではなく構造化データを返します — 他のプログラムが結果をパースする必要があるときに便利です。
03 · コード例
以下は、チームが CI/CD パイプラインでヘッドレスモードを使う方法です — プルリクエストごとに走る自動 code reviewer です。
GitHub Actions — 自動 code review
# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Review PR
run: |
claude -p "Review the changes in this PR. \
Focus on bugs, security, and performance." \
--allowedTools "Read,Grep,Glob" \
--output-format text
この GitHub Action は、プルリクエストごとにヘッドレスモードで Claude を走らせます。read-only ツール (Read、Grep、Glob) だけを許可するので、Claude はコードを分析できますが何も変更できません。レビュー出力は CI ログに表示され、チームが読めます。
04 · 読む
より高度な自動化のために、Anthropic は Agent SDK — Claude ツールサポート付きで本番エージェントを構築するための Python と TypeScript ライブラリ — を提供しています。
Agent SDK はすべてをプログラム的にコントロールできます : どのツールが利用可能か、結果をどう処理するか、セッション管理 (会話を再開する)、さらには MCP サーバー接続まで。これが最も洗練された Claude Code 統合を支える仕組みです。
CLI (claude -p) は単純な自動化に最適。Agent SDK は完全なプログラム制御が必要なときに使います — カスタムエラー処理、結果のストリーミング、複数の Claude 呼び出しの連結、Claude の能力の上に製品を作るとき。
ポイントまとめ
- Agent SDK : 本番エージェント構築のための Python と TypeScript ライブラリ
- ツール、セッション、結果を完全にプログラム制御
- CLI (claude -p) : 単純な自動化とスクリプト
- Agent SDK : 高度なアプリケーションと本番システム
- セッション管理 : プログラムで会話をキャプチャして再開
05 · コード例
以下はシンプルな TypeScript の Agent SDK 例で、プログラム的にバグを見つけて直します。
Agent SDK — bug fixer
import { query } from '@anthropic-ai/claude-agent-sdk';
for await (const msg of query({
prompt: "Find and fix the failing test in auth.test.ts",
options: {
allowedTools: ["Read", "Edit", "Bash"],
}
})) {
if (msg.result) {
console.log('Fix applied:', msg.result);
}
}
Agent SDK はストリーミングインターフェイスを提供します — Claude が作業する間、メッセージをイテレートします。allowedTools 配列が Claude にできることをコントロールします。Claude が終了すると、result メッセージに何が行われたかの要約が含まれます。これが、ファイル読み込み、編集、コマンド実行のできる自動エージェントの作り方です。
06 · クイズ
どのフラグが Claude Code をインタラクティブターミナルなしで非インタラクティブに走らせますか？
- claude --headless
- claude --auto
- claude -p
- claude --batch
07 · 空欄補充
ユーザー操作なしで CI/CD パイプラインで Claude を走らせるには、claude _____ "あなたのプロンプト" を使います。
08 · 対応づけ
それぞれの自動化手法を最適な用途と結びつけてください。
（このセクションはインタラクティブです — JavaScript を有効にしてください。）
⚠ 全機能のインタラクティブ体験には JavaScript が必要です。JavaScript を有効にして再読み込みしてください。
※ このサイトは独立した教育プロジェクトで、Anthropic の公式製品ではありません。Claude™ は Anthropic, PBC の商標です。