Claude Codeヘッドレスモード: ターミナルからのデプロイ検証

Claude Codeのヘッドレスモードでは、ターミナルからclaude -pを使用してプロンプトを実行し、タスク完了後に終了できます。データをパイプで渡し、回答を保存してスクリプトから呼び出すことが可能です。本ガイドではこの機能を活用し、ヘルスエンドポイント、価格の見積もり計算、およびスクリプトで検証可能なレポートを用いたデプロイ検証について解説します。

この例では、/healthzがHTTP 200を返す一方で、実際のアプリケーションルートが503を返すという一般的な障害を捕捉します。再現可能なデモ、JSONレポート、およびアプリケーションの検証が失敗した場合のゼロ以外の終了コードを取得できます。

非対話型コマンドから始める

Claude Codeをインストールしてサインインした状態で、以下のコマンドを実行してください。

claude -p "Explain what an HTTP 503 response tells me in two sentences." \
  --tools ""

-pは、結果を出力して終了する指定です。--tools ""は、この質問に対する組み込みツールを無効化します。これにより、Claudeはリポジトリの読み取りやシェルコマンドの実行を行わず、プロンプトのみから回答を生成します。利用可能なフラグについては、Claude Code CLIリファレンスを参照してください。

デプロイ検証では、スクリプトがすでに収集した観察結果をモデルに提供します。これにより、各HTTPリクエストと合格条件の検査が容易になるほか、デプロイ用の認証情報がモデルの入力に含まれるのを防ぐことができます。

前提条件

Python 3.10以降、最新のClaude Code、および認証済みのアカウントが必要です。このデモではPythonの標準ライブラリを使用するため、追加のPythonパッケージは不要です。macOSまたはLinuxのBashまたはZsh環境でシェルの例を実行してください。

インストールされているCLIとその認証状態を確認します。

claude --version
claude auth status

保存されたセッションの期限切れによりリクエストが失敗した場合は、claude auth loginを実行して再試行してください。次のAPIリクエストで更新できない場合でも、保存されたログイン情報が残っている可能性があります。

オプションのホスト型検証を行うには、Lizard CLIをインストールし、自身のプロジェクトにサインインします。アプリケーションのデプロイがまだ済んでいない場合は、先にClaude Codeからのデプロイの手順に従ってください。

サンプルをダウンロードしてデモを開始する

新しいフォルダを作成し、6つのファイルをダウンロードします。実行前に内容を確認してください。このデモはGETリクエストを受け付けますが、顧客データは保持しません。

mkdir claude-deployment-check
cd claude-deployment-check
for file in demo.py collect.py gate.py run.py report.schema.json verify.py; do
  curl --fail --silent --show-error \
    "https://lizard.build/blog-examples/agent-deployment-checks/$file" \
    --output "$file"
done
python3 demo.py --port 8787

そのターミナルは実行したままにしておきます。別のターミナルを開き、同じフォルダに移動してください。デモは/healthzと/api/quote?quantity=3を公開します。各アイテムの価格は1,200セントです。3つのアイテムの見積もり計算はcurrency: USDとtotal_cents: 3600を返す必要があります。

これらはデモ用のルートです。独自のアプリケーションに適用する場合は、collect.pyとgate.pyのパスおよび期待されるフィールドを編集してください。シードされたレコードの読み取り、価格の計算、保存されたドキュメントの取得など、ユーザーが実際に必要とする小さな操作を選択します。「OK」を返すだけのルートでは、これらの操作を十分に検証できません。

Claudeに問い合わせる前に検証データを収集する

python3 collect.py http://127.0.0.1:8787 > evidence.json

コレクターは、それぞれ5秒のタイムアウトで2つのリクエストを実行します。リダイレクト、無効なJSON、および64 KiBを超えるレスポンスは拒否されます。HTTPステータスと期待されるJSONフィールドの両方を検証します。時間、期待値、およびチェック結果を記録しますが、任意のレスポンステキストをプロンプトにコピーすることはありません。

エンドポイントにユーザーテキストが含まれている場合、この最後の仕様が重要になります。サポートメッセージやデータベースの行には、エージェントに向けた指示が含まれる可能性があるためです。この例では、説明の目的で測定されたフィールドの小さなセットのみをClaudeに提供します。

コレクターは、失敗した検証のデータを含め、検証データを書き込むと正常に終了します。最終的な検証スクリプトが、ジョブが合格するかどうかを決定します。自動化の際は、これら2つの役割を区別してください。

構造化レポートを要求する

ダウンロードしたファイルが含まれるフォルダで以下のコマンドを実行します。

claude --safe-mode -p \
  "Explain the evidence on stdin. Use no tools. Copy its verdict. List the names of failed checks in failed_checks. Give a short summary and one next_step. Do not infer a root cause from HTTP status alone." \
  --tools "" \
  --no-session-persistence \
  --output-format json \
  --json-schema "$(cat report.schema.json)" \
  < evidence.json > claude-result.json

この例では、--safe-modeを使用して、レポートタスク中のフック、プラグイン、MCPサーバーなどのカスタマイズを無効化します。既存のアカウントログインはそのまま使用されます。フラグが認識されない場合は、インストールされているバージョンのヘルプを確認してください。

Claudeのレスポンスには外側の結果オブジェクトが含まれます。スキーマを提供すると、レポートはstructured_output内に配置されます。外側のオブジェクトには、実行メタデータとis_errorフィールドも含まれます。プレーンなJSONレスポンスとスキーマ制約のあるレスポンスは目的が異なります。コマンドが要求したフィールドを解析するようにしてください。

スキーマでは以下の4つのフィールドを要求します。

プログラム実行のドキュメントでは、これらの出力形式について説明しています。有効なJSONの形状であっても説明が正しいとは限らないため、ラッパーは測定結果と照らし合わせてレポートを検証します。

完全な検証を実行する

run.pyは新しい検証データを収集し、180秒のプロセスタイムアウトでClaudeを呼び出し、レポートを抽出して検証します。実行ごとに新しい出力ディレクトリを指定してください。

python3 run.py claude http://127.0.0.1:8787 runs/healthy

ディレクトリにはevidence.json、claude-result.json、report.json、およびstderr.logが生成されます。障害をデバッグする際は生の結果を保持しておいてください。認証エラーが標準出力の結果に表示される場合があります。

ラッパーは以下の3つの終了コードを使用します。

Claudeプロセスからの終了コード0は、エージェントの実行が完了したことを意味します。ラッパーはアプリケーションの状態について個別に判定を下します。無効なレポートによって、失敗したHTTP検証が成功したジョブとして扱われることはありません。

ヘルスチェックが見逃す障害を再現する

別のターミナルで2つ目のデモを開始します。

python3 demo.py --port 8788 --broken

次に以下を実行します。

python3 run.py claude http://127.0.0.1:8788 runs/broken

2つ目のデモは依然として/healthzに対してHTTP 200で応答しますが、見積もり計算ルートはHTTP 503を返します。したがって、検証データにはfailが記録され、失敗した検証としてquoteが記録されます。有効なClaudeのレスポンスが得られた場合、ラッパーは1で終了します。

モデルを呼び出さずに、HTTP検証と検証ロジックをテストすることも可能です。

python3 verify.py

これにより正常なデモと異常なデモを検証し、検証スクリプトが誤った成功レポートや不完全な検証データを正しく拒否することを確認します。Claudeのクレジットは消費されません。

Lizard上のアプリケーションに検証を適用する

プロジェクトからアプリケーションのURLを選択します。Lizard CLIを使用して、現在のプロジェクトコンテキストとサービス状態を確認します。

lizard skills get core --json
lizard status --json
lizard ps --project YOUR_PROJECT --json
lizard logs --project YOUR_PROJECT --service YOUR_SERVICE --tail 100 --json

lizard statusはローカルディレクトリに関連付けられたプロジェクトを表示します。lizard psは選択したプロジェクトのサービス状態を読み取ります。JSONログは一定期間のスナップショットを返して終了し、サービスを継続して追跡することはありません。

2つのルートアサーションをアプリケーションに合わせて調整した後、同じチェッカーでサービスのパブリックURLを使用します。提供されたデモ自体をホストする場合は、0.0.0.0にバインドし、一致するようにサービスのポートを設定してください。ローカルの例は127.0.0.1にバインドします。

ルートが失敗した場合は、記録された検証時間の前後のログを確認してください。HTTP 503というステータスだけでは、原因がデータベース接続、依存関係、アプリケーションコードのいずれであるかを特定できません。モデルのプロンプトに追加する前に、ログを確認して適切に編集してください。

保存されたデータに依存するアプリケーションの場合は、既知のレコードを使用したテストを追加します。Postgres MCPガイドではスコープ付きのデータベースアクセスについて、Redis MCPガイドでは制限付きのRedis読み取りについて解説しています。検証に適したテストデータと認証情報を使用してください。

ヘッドレスモード、認証、および無人ジョブ

ヘッドレスモードはコマンドの実行方法を指定するものです。無人ログインを作成したり、ツールの権限を削除したりするわけではありません。スケジュールされたジョブの場合は、ランナー側で認証を準備し、明示的なタイムアウトを設定してください。

Claudeは--bareも提供しており、通常の起動コンテキストの多くをスキップできます。この場合のAnthropic認証パスはANTHROPIC_API_KEYまたは設定されたAPIキーヘルパーを使用し、サブスクリプションのOAuth認証情報は読み取りません。そのため、今回のアカウントログインの例では--safe-modeを使用しています。認証のセットアップが異なる可能性があるCI環境へジョブを移行する前に、最新のドキュメントを確認してください。

ライブの進行状況の確認には、Claudeは--output-format stream-json --verboseをサポートしており、各行が1つのイベントを表します。この例のように最終結果が1つだけ必要な場合は、プレーンなjsonを使用します。独立したデプロイ検証のために古い会話を再開することは避けてください。実行ごとに新しい観察結果を使用する必要があります。

トラブルシューティング

テスト範囲と次のステップ

2026年9月28日に、Python 3.12.10環境でローカルHTTPテストとレポート検証テストを実行しました。正常な応答、見積もり計算ルートの障害、誤った成功レポート、検証データの欠落について確認済みです。コマンドのフラグはClaude Code 2.1.259、Lizard CLI 4.0.8、および公式ドキュメントと照合しました。Claudeモデルの応答は完了したテストには含まれません。上記のレポートの動作は、ドキュメントに記載された出力仕様に基づいています。このデモのテストは、本番アプリケーションの動作を保証するものではありません。

JSONLイベントと個別の最終レポートファイルを使用した同様のパターンについては、Codex Execデプロイ検証を参照してください。独自のアプリをオンラインにするには、Claude Codeデプロイガイドに従い、ユーザーが最も必要とする操作の検証を追加してください。