Claude Codeの出力形式を選ぶ方法｜テキスト・JSON・ストリームを安全に扱う

2026-08-25時点の[Anthropic公式ドキュメント](https://code.claude.com/docs/en/headless)では、Claude Codeの非対話モードで`--output-format`に`text`、`json`、`stream-json`を指定できます。`text`は既定のプレーンテキスト、`json`は結果やセッションID、メタデータを含む構造化JSON、`stream-json`は改行区切りのJSONです。違いは見た目ではなく、受け手がどの単位で出力を確定できるかにあります。

人がターミナルで回答を読むなら、プレーンテキストのままが扱いやすいでしょう。単発の実行結果を別の処理へ渡すなら、文書全体を一度に検証できる`json`が合います。生成途中から表示や集計を始めたい場合は、一行を一イベントとして扱える`stream-json`を選びます。

では、機械処理なら常にJSONでよいのでしょうか。そうではありません。逐次性が不要なのにストリームを選ぶと、行ごとの読み取りとイベント選別が必要になります。反対に、途中経過が必要なのに通常のJSONを選べば、文書全体が揃うまで処理を確定できません。人がそのまま読む用途は`text`、単発の実行結果を検証して利用する用途は`json`、生成途中のイベントを一行ずつ処理する用途は`stream-json`。形式は出力側の好みではなく、後続処理が結果を受け取る単位から決めるべきです。

通常の`--output-format json`では、テキスト応答が`result`フィールドに入ります。2026-08-25時点の公式例も、`jq -r '.result'`でこの値を抽出しています。後続処理が回答本文だけを必要とする場合でも、最初から抽出結果だけを保存するのではなく、まずJSON文書全体をパースし、`result`が期待する型かを確認してから取り出す設計にすると、形式の取り違えを検出できます。

一方、`--output-format json`と`--json-schema`を併用すると、指定したJSON Schemaに適合する出力を要求でき、構造化された値は`structured_output`フィールドに入ります。通常応答と同じつもりで`result`だけを参照すると、必要な構造化データを取り出せません。実行時のオプションと参照フィールドは対で管理する必要があります。

この差は小さな実装詳細に見えますが、保存先へ誤った値を渡す境界になります。後続スクリプトには「通常JSONなら`result`」「スキーマ指定なら`structured_output`」という分岐を明示し、どちらのモードで実行したか分からない状態を作らないことが重要です。

安全側に倒す処理順は、終了コードの確認、JSONパース、必須フィールドと型の検証、保存です。2026-08-25時点の仕様では、`claude -p`は成功時に終了コード`0`、失敗時に非`0`を返します。また、無効なフラグは実行前に標準エラーへ報告される一方、認証不足など実行中の失敗は結果として標準出力へ出ます。標準エラーが空かどうかだけでは、成否を判定できません。

次は、通常のJSON応答を受け取る後続処理の最小例です。`stdout`をいきなり保存せず、終了コードとパース結果を確認し、`result`が文字列であることを保存条件にしています。コマンド実行部分が返す`exitCode`と`stdout`を受け取った後の境界として読んでください。

```ts function extractResult(exitCode: number, stdout: string): string { if (exitCode !== 0) { throw new Error(`Claude Code failed (exit ${exitCode})`); } let value: unknown; try { value = JSON.parse(stdout); } catch { throw new Error("Claude Code output was not valid JSON"); } if (typeof value !== "object" || value === null || !("result" in value)) { throw new Error("result field was missing"); } const result = (value as { result: unknown }).result; if (typeof result !== "string") { throw new Error("result field was not a string"); } return result; } ```

保存処理は、この関数が値を返した後に置きます。コマンド失敗、壊れたJSON、フィールドの欠落、型違いを成功経路へ流さないためです。必要なのはJSONという名前ではなく、保存直前まで失敗を失敗として扱える境界です。

`--json-schema`は、構造化された値を要求するための有力な手段です。たとえば、後続処理が文字列の`summary`を必要とするなら、その型と必須項目をスキーマで示し、返された`structured_output`を検証対象にできます。出力の約束をプロンプトの文章だけに置かず、機械が読める形に移せる点が重要です。

ただし、2026-08-25時点の[CLIリファレンス](https://code.claude.com/docs/en/cli-reference)によると、`--json-schema`へ有効なJSON Schemaでない値を渡すとエラー終了し、検証器の診断が表示されます。つまり、スキーマ自体の誤りも通常の失敗経路で受け止めなければなりません。終了コードを見ずに`structured_output`を探す実装では、この失敗をデータ欠損と取り違えます。

さらに、`format`キーワードは注釈として受理され、Claude Codeのクライアント側では強制検証されません。形式らしい文字列が返ることと、実際の適合は別です。保存先がその形式を要求するなら、後続処理でも追加検証し、不適合な値を保存しない設計が必要です。

たとえば応答全体を`parsed`へパースした後も、`structured_output`を取り出して終わりにはしません。`isExpectedOutput`に必須項目、型、必要な形式制約を実装し、成功した値だけを保存関数へ渡します。

```ts const output = (parsed as { structured_output?: unknown } | null)?.structured_output; if (!isExpectedOutput(output)) throw new Error("schema validation failed"); await saveValidatedOutput(output); ```

処理順は、終了コード、応答全体のパース、`structured_output`の存在と型、強制されない制約の検証、保存です。JSON Schemaは検証の終点ではなく、出力側と受け手の約束を揃える起点になります。

`stream-json`では、標準出力全体を一度だけ`JSON.parse`してはいけません。各行が一つのJSONオブジェクトを表すため、改行単位で読み、空行を除外して個別にパースします。一行でも壊れていれば処理を止め、未検証のイベントを保存済みデータへ混ぜないようにします。

2026-08-25時点の公式仕様では、トークン生成中の部分メッセージを受け取るには、`--output-format stream-json`に`--verbose`と`--include-partial-messages`を組み合わせます。公式例は、各JSON行を評価し、`type`が`stream_event`かつdeltaの`type`が`text_delta`であるイベントだけを選んでテキストを取り出しています。すべての行を本文として連結するのではなく、イベント種別を確認して選別する必要があります。

最後の行は、最終応答テキスト、コスト、セッションメタデータを含む`result`メッセージです。逐次表示が終わったように見えても、最終結果を確認する前に処理成功として確定しない設計が適切です。部分イベントは途中経過、最後の`result`は完了確認という役割に分けると、画面表示と確定保存を混同しません。

ストリームをファイルへ残す場合も、受信した生の一行、パース済みイベント、抽出した本文を同じものとして扱わないことが大切です。後で再評価する必要があるなら検証済みのイベント列を保持し、本文だけが必要なら対象イベントから抽出した値を、最終`result`の確認後に確定します。

実装レビューでは、`--output-format`の指定だけでなく、失敗がどこで止まるかを追います。特に、JSONパースの例外を握りつぶして空文字列へ置き換える処理や、フィールドがなければ任意の値へフォールバックする処理は、コマンド失敗とデータ欠損を正常終了に見せてしまいます。保存前の検証に失敗したら、保存しないまま呼び出し元へ失敗を返す方針を揃えます。

保存を許可する条件として、用途に合う`text`、`json`、`stream-json`を選んでいるか、標準エラーの有無ではなく終了コードで成否を確認しているかを見ます。続いて、通常の`json`は文書全体、`stream-json`は行単位でパースしているか、通常JSONの`result`とスキーマ指定時の`structured_output`を分けているか、期待するフィールドの存在と型を検証しているかを確認します。

さらに、`format`など強制されない条件を後続処理で検証しているか、ストリームでは対象イベントを選別して最後の`result`を確認しているかも必要です。これらすべての検証が成功するまで確定保存を行わないことが、形式の違いを実際の安全性へ結びつけます。

出力形式の選択は、プロンプトを書く人だけで完結しません。コマンドを実行する層、JSONを検証する層、保存する層の境界を決め、スキーマと失敗条件を同じ変更単位で管理する必要があります。Claude Codeの利用方法をチームへ広げる際は、Claude Code研修で学ぶ内容と選び方も参考に、操作方法だけでなく検証と保存のルールまで共通化すると運用へつなげやすくなります。

処理を役割ごとに分ける場合でも、最終的な保存条件の責任が曖昧になってはいけません。Claude Codeのサブエージェント活用方法で役割分担を検討するときも、機械可読な出力を受け取る側が終了コード、パース、フィールド、型を検証する境界は明示しておく必要があります。

人が読むなら`text`、単発の後続処理なら`json`、生成途中を扱うなら`stream-json`という選択が出発点です。そして冒頭に残した条件、つまり安全に保存できるかどうかは、形式名だけでは決まりません。終了コードを先に確認し、形式に合う単位でパースし、参照先と型を検証し、強制されない制約も確認した後にだけ保存する。この一連の条件が揃って、Claude Code JSON 出力を後続処理へ安全に渡せます。