-p フラグでワンショット実行を行う

症状・対象

対話画面を開かず、差分レビューやログ分析の結果だけをシェルへ返したい人が対象です。-p / --print は一度の入力を処理して終了するため、スクリプトや CI の入出力を固定できます。

最短解決

1. 標準入力へ解析対象を渡す。
2. --output-format text で人が読む結果に固定する。
3. --max-turns で実行上限を設け、終了コードと出力を確認する。

コピペ例

ステージ済み差分を読み取り専用でレビューします。

git diff --staged | claude -p \
  --output-format text \
  --max-turns 1 \
  "この差分をレビューして。重大度、ファイルパス、理由を日本語で返して。ファイルは変更しないで。"

ログ分析では、標準エラーも入力へ含めます。

npm test 2>&1 | claude -p \
  --output-format text \
  --max-turns 1 \
  "最初に失敗したテストの根本原因と、次に確認する箇所を返して。"

機械処理する場合は JSON を選べます。

claude -p "このプロジェクトの主要ディレクトリを説明して" \
  --output-format json \
  --max-turns 1

期待結果

• 対話プロンプトを開かず、結果が標準出力へ返る。
• text はレビュー本文、json は実行情報を含む JSON になる。
• 指定ターン数へ達した場合は、それ以上処理を継続しない。

検証

まず小さな入力で終了コードと出力の両方を確認します。

claude -p "OK のみ返して" --output-format text --max-turns 1
echo $?

OK が出力され、直後の終了コードが 0 なら基本動作は成功です。自動化へ組み込む前に、空入力・認証エラー・API 制限時も job が失敗として扱われることを確認します。

落とし穴

• cat secret.env | claude -p ... のように秘密情報を標準入力へ流しません。
• 「修正して」と依頼するとツール実行が必要になります。レビューだけなら「ファイルは変更しない」と明記します。
• stream-json は行単位のイベント列です。単一 JSON として処理しないでください。
• パイプの前段が失敗しても後段が成功すると見逃すシェルがあります。CI スクリプトでは set -o pipefail を使います。

次の一手

• GitHub Actions で Claude Code を CI/CD に組み込む — Secret と権限を含む CI 設定へ進む
• パーミッションモードを使い分ける — 書き込みを伴う headless 実行の境界を決める