本文へスキップ
hdknr blog

claude -p によるヘッドレス実行

Claude Code の非対話モード claude -p を、構造化出力を返す関数としてスクリプトやジョブから呼ぶための手順と注意点。--bare による入力トークン削減、Celery からの呼び出し

概要

claude -p は Claude Code の非対話(ヘッドレス)モードで、--output-format json と --json-schema を組み合わせると「スキーマどおりの JSON を返す 1 回の関数呼び出し」として使える。ただし中身は Claude Code そのものなので、プロンプトを短くしても既定では Claude Code のシステムプロンプトや設定由来の情報が毎回送られる。小さな判断を大量に呼ぶ自動化では、この 固定分 を --bare で削り、キャッシュに乗せる設計が要る。

詳細

構造化出力を返す関数として使う

オプション役割
--output-format json結果を 1 つの JSON で返す(session_id・total_cost_usd・usage を含む)
--json-schema '<schema>'出力を JSON Schema で検証。検証済みの値は structured_output に入る
--tools ""組み込みツールをすべて無効化(判断だけさせる)
--max-budget-usd1 回の費用上限(推定値で判定するので僅かに超えうる)
--no-session-persistenceセッションをディスクに保存しない

入力トークンの実測(固定分)

数百トークンの計画プロンプトを Sonnet で呼んだときの入力(cache_creation_input_tokens + cache_read_input_tokens):

呼び出し方入力トークン
既定(リポジトリ内)約 13,400
既定(空のディレクトリ)約 8,600
--system-prompt で差し替え約 14,400(減らない)
--setting-sources ""約 6,500
上記+--strict-mcp-config+--system-prompt約 4,100
--bare約 700

読み取れること:

数値は環境依存なので、jq '.usage.cache_creation_input_tokens + .usage.cache_read_input_tokens' out.json で自分の環境を測ってから決める。

--bare の認証と課金

使い分け

Celery から計画役として呼ぶ

Celery のタスクから claude -p --tools "" --json-schema ... を呼び、LLM には次の子タスクを JSON で提案させるだけにする構成。許可リスト・重複・分岐数の検査と投入はコード、並列実行と待ち合わせは Celery の chord、再帰もコールバックで起こす。歯止めとして深さ・root_id ごとの呼び出し回数(Redis の INCR)・1 回の費用上限・リトライ上限を重ねる。子タスクの結果は <task-results> で囲んでデータとして渡すが、最終防御は許可リスト検査の側に置く。

計画役は入力・出力・失敗(ValueError / SubprocessError)の約束さえ守れば Codex CLI(codex exec --output-schema --sandbox read-only)などに差し替えられる。費用上限オプションがない計画役では、呼び出し回数の上限がほぼ唯一の費用の歯止めになる。設計の背景は オーケストレーター/コーダー分業と承認ゲート を参照。

他のエージェントとのやり取り

関連ページ

ソース記事