ClaudePR

【Claude Code】の出力形式を使いこなす――text・json・stream-jsonの違いと実践

Claude Codeのprintモード（claude -p）には、出力形式を切り替える --output-format オプションがあります。デフォルトのテキスト出力だけでなく、JSON形式やストリームJSON形式を選べることで、自動化パイプラインの幅が大きく広がります。この記事では3つの出力形式の違いを整理し、jqと組み合わせた実践的な使い方まで紹介します。

Claude Codeのプリントモードについて知りたい人は、【Claude Code】printモード入門｜パイプ連携とスクリプト活用の基本 を参考にしてください。

目次

output-formatはprintモード専用

output-formatはprintモード（-p）でのみ使えます。対話モードで指定するとエラーになります。必ず-pと組み合わせて使ってください。

3つの出力形式の比較

形式説明主な用途
text平文テキスト（デフォルト）人間が直接読む場合
json完了時に1つのJSONオブジェクトを出力プログラムでの後処理
stream-json逐次JSONチャンクをストリーム出力リアルタイム処理

text形式（デフォルト）

シンプルで読みやすいですが、プログラムから解析しようとすると構造が曖昧です。

作業結果を人間が知りたいような時は、textで出力するのが便利です。

json形式

応答テキスト（result）に加えてコスト情報、所要時間、エラー有無などのメタデータが含まれます。後続のスクリプト処理に最適です。

json形式の出力例：

{
  "type": "result",
  "subtype": "success",
  "cost_usd": 0.003,
  "is_error": false,
  "result": "応答テキスト...",
  "session_id": "abc123..."
}

stream-json形式

複数行のJSONが逐次出力されます。1行1JSONなのでgrepやjqのselectで特定行を抽出できます。

jqと組み合わせてJSON出力を加工する

応答テキストだけを取り出すにはjq -r '.result'を使います。コスト情報だけならjq '.cost_usd'で取得できます。

エラー判定もプログラム的に行えます。is_errorフィールドを確認することで、エラーと正常結果を明確に区別でき、自動化パイプラインの信頼性が向上します。

どの形式を選ぶべきか

  • 人間が目で確認 → text
  • スクリプトで後処理 → json
  • リアルタイム進捗表示 → stream-json

迷ったらjsonを選んでおけば、jqでテキストだけ取り出すこともできるので柔軟です。

さらに深く学びたい方へ
Claude Codeの Skills・MCP・Agent・Hooks・Plugin を体系的に学べる有料教材を Zenn で公開しています。
Claude Code 実践ガイド（Zenn Book）

アーカイブ