# 出力フォーマット：json / text / stream-json

スクリプトや CI/CD、自動化パイプラインで必要なのは「人間が読める」回答だけではなく、**プログラムが解析できる構造化データ**です。Claude Code のヘッドレスモード（`claude -p`）は `--output-format` で 3 種類の出力フォーマットを提供し、Claude Code を通常の CLI ツールのようにパイプラインへ組み込めます。

> これは Claude Code 自身の機能で、**アップストリームには依存しません**。Claude Code が公式 API を指していても QCode を指していても、`--output-format` は同じように動きます。本ページは出力フォーマットに焦点を当てます。ヘッドレスの全引数や CI テンプレートは [自動化と CI/CD](/docs/advanced/headless) を参照してください。

---

## 一、3 つのフォーマット早見

| フォーマット | 引数 | 出力の形 | 用途 |
|------|------|---------|---------|
| プレーンテキスト | `--output-format text`（デフォルト） | 1 つのプレーンテキストの回答 | 人間が読む、簡単なパイプ |
| JSON | `--output-format json` | **1 つの**構造化 JSON オブジェクト | スクリプト解析、コスト/使用量/セッション ID の取得 |
| ストリーミング JSON | `--output-format stream-json` | **改行区切り**の JSON イベントストリーム | リアルタイム進捗、逐次消費、長時間タスク |

```bash
# text がデフォルトなので、次の 2 行は等価
claude -p "冪等性を一文で説明して"
claude -p "冪等性を一文で説明して" --output-format text
```

---

## 二、text：デフォルトのプレーンテキスト

`--output-format` を付けないと `text` になり、標準出力はモデルの最終回答そのものです。そのまま読んだり、簡単なパイプに流したりするのに向いています。

```bash
# そのまま読む
claude -p "この関数を async 形式に書き換えて"

# 他のツールへパイプ
claude -p "コミットメッセージ候補を 5 つ生成して" | head -5

# ファイルへ書き出す
claude -p "このリポジトリの README 概要を書いて" > intro.txt
```

**制限**：text は「回答」しか返さず、コスト・トークン使用量・セッション ID などのメタデータは取れません。多段タスクでも途中経過と最終結果を区別できません。これらが必要なら `json` か `stream-json` に切り替えます。

---

## 三、json：1 つの構造化オブジェクト

`--output-format json` はタスク**完了後**に**1 つの** JSON オブジェクトを出力し、最終結果と一連のメタデータフィールドを含みます。スクリプトで最もよく使うフォーマットです。

```bash
claude -p "src/ 配下の TODO コメント数を数えて" --output-format json
```

返るオブジェクトの代表的なフィールド（実際のフィールドは利用中のバージョンの出力に従ってください）：

| フィールド | 意味 |
|------|------|
| `result` | 最終回答のテキスト |
| `total_cost_usd` | この呼び出しのコスト（USD） |
| `usage` | トークン使用量（入力 / 出力 / キャッシュなど） |
| `session_id` | セッション ID。`--resume` で継続に使える |

### jq で解析する

`json` フォーマットは [`jq`](https://jqlang.org/) と相性抜群です：

```bash
# 最終回答だけ取り出す
claude -p "今回の変更を一文でまとめて" --output-format json | jq -r '.result'

# この呼び出しのコストを取り出す
claude -p "auth.py をレビューして" --output-format json | jq '.total_cost_usd'

# 複数フィールドをまとめて取得
claude -p "アーキテクチャを分析して" --output-format json \
  | jq '{cost: .total_cost_usd, session: .session_id, tokens: .usage}'
```

### スクリプトで分岐＆コスト集計

```bash
#!/usr/bin/env bash
set -euo pipefail

out=$(claude -p "UserService の単体テストを書いて" \
        --output-format json --max-turns 8)

result=$(echo "$out" | jq -r '.result')
cost=$(echo "$out"   | jq -r '.total_cost_usd')
sid=$(echo "$out"    | jq -r '.session_id')

echo "結果：$result"
echo "今回のコスト：\$$cost"
echo "セッション ID：$sid（claude --resume $sid で継続）"
```

> **ヒント**：`json` はタスク終了後にオブジェクトを一括で吐き出すため、長時間タスクの間は何も出力されません。進捗をリアルタイムで見たい場合は下記の `stream-json` を使います。

---

## 四、stream-json：リアルタイムのイベントストリーム

`--output-format stream-json` は実行過程を**改行区切りの JSON イベント**（NDJSON）に分解し、1 行 1 イベントで即座に書き出します。長時間タスクのリアルタイム進捗、ストリーミング UI、出力を生成しながら消費するパイプラインに向いています。

```bash
claude -p "utils ディレクトリ全体をリファクタしてテストを追加して" \
  --output-format stream-json --max-turns 20
```

出力は次のような形です（各行は独立した JSON。フィールドは実際のバージョンに従う）：

```
{"type":"system","subtype":"init","session_id":"..."}
{"type":"assistant","message":{...}}
{"type":"assistant","message":{...}}
{"type":"result","result":"...","total_cost_usd":0.0123,"usage":{...}}
```

### 1 行ずつ消費する

各行は正しい JSON なので、ストリームしながら処理できます：

```bash
# 各イベントのタイプをリアルタイムで表示
claude -p "新しい API へ移行して" --output-format stream-json \
  | jq -r '.type'

# 最終イベントが出たときだけ結果とコストを取り出す
claude -p "新しい API へ移行して" --output-format stream-json \
  | jq -r 'select(.type == "result") | "\(.result)\nコスト $\(.total_cost_usd)"'
```

```bash
# while ループで 1 行ずつ処理し、進捗をリアルタイムで返す
claude -p "リポジトリ全体のコードレビュー" --output-format stream-json | \
while IFS= read -r line; do
  type=$(echo "$line" | jq -r '.type')
  case "$type" in
    system) echo "▶ 開始…" ;;
    assistant) echo "… 思考中" ;;
    result) echo "✓ 完了：$(echo "$line" | jq -r '.result')" ;;
  esac
done
```

> **`json` vs `stream-json`**：`json` はタスク終了を待って**1 つの**完全なオブジェクトを返すため解析が簡単。`stream-json` は全体を通して**複数の**イベントをストリームし、リアルタイムなフィードバックができる反面、1 行ずつの解析が必要です。CI では最終結果に `json`、進捗ログに `stream-json` を使います。

---

## 五、CI / パイプライン実例

### GitHub Actions で結果を取得してコメント投稿

```yaml
- name: Claude レビュー
  env:
    ANTHROPIC_BASE_URL: https://api.qcode.cc/api
    ANTHROPIC_AUTH_TOKEN: ${{ secrets.QCODE_API_KEY }}
  run: |
    out=$(claude -p "この PR の diff をレビューして問題点を挙げて" \
            --output-format json --max-turns 6 --allowedTools Read,Glob,Grep)
    echo "$out" | jq -r '.result' > review.md
    echo "今回のレビューのコスト \$$(echo "$out" | jq -r '.total_cost_usd')"
```

### コストゲートを設ける（予算超過なら失敗）

```bash
out=$(claude -p "リリースノートを生成して" --output-format json)
cost=$(echo "$out" | jq -r '.total_cost_usd')
# awk で浮動小数点比較：0.5 ドルを超えたら CI を失敗させる
awk -v c="$cost" 'BEGIN{ exit (c > 0.5) ? 1 : 0 }' \
  || { echo "コスト \$$cost は予算超過"; exit 1; }
echo "$out" | jq -r '.result'
```

### 複数回の呼び出しのコストを合算

```bash
total=0
for f in src/*.py; do
  out=$(claude -p "$f に docstring を書いて" --output-format json)
  c=$(echo "$out" | jq -r '.total_cost_usd')
  total=$(awk -v t="$total" -v c="$c" 'BEGIN{ printf "%.4f", t + c }')
done
echo "全ファイルの合計コスト \$$total"
```

> **QCode を指す**：上記コマンドは公式 API でも QCode でも完全に同じです。`ANTHROPIC_BASE_URL` を `https://api.qcode.cc/api`（**末尾にスラッシュなし**に注意）に、`ANTHROPIC_AUTH_TOKEN` にあなたの `cr_` キーを設定するだけ。CN ユーザーは `asia.qcode.cc` を使えます。詳しくは [接続先と API フォーマット](/docs/getting-started/endpoints-and-api-paths) を参照。

---

## 六、よくある落とし穴

- **`json` は長時間タスク中は無音**：終了時に 1 回だけ出力するので、進捗が見えないのは正常。進捗が欲しければ `stream-json` を。
- **`stream-json` を一括 `jq` できない**：NDJSON なので、複数オブジェクトは単一の JSON ドキュメントになりません。行ごとの `jq`、`jq -c`、`--stream` を使い、ストリーム全体に `jq '.'` を流さないこと。
- **`--max-turns` を忘れない**：自動化ではターン数を制限し、タスクの暴走と課金の暴発を防ぐ。
- **BASE_URL の末尾にスラッシュを付けない**：`https://api.qcode.cc/api` が正しく、余分な `/` は誤ったパスを作ります。
- **メタデータフィールドはバージョンで変わる**：自分のマシンの `claude -p ... --output-format json` の実出力を信頼し、まず `jq 'keys'` で何があるか確認を。

---

## 次のステップ

- [自動化と CI/CD](/docs/advanced/headless) — ヘッドレスモードの全引数と CI/CD 実例
- [サブエージェント](/docs/advanced/subagents) — Claude Code にバックグラウンドエージェントを並列編成させる
- [コスト最適化](/docs/usage/cost-optimization) — `total_cost_usd` でコストを管理する
- [接続先と API フォーマット](/docs/getting-started/endpoints-and-api-paths) — 4 つのドメインとプロトコルパス

> Claude Code をパイプラインに組み込めば、コストは出力にそのまま表示されます —— [QCode のプランと料金を見る](https://qcode.cc/pricing) で、あなたの自動化ボリュームに合うプランを選びましょう。