Форматы вывода: --output-format

Почему это важно именно вам

Когда Claude отвечает в браузере — вы читаете текст глазами. Когда Claude отвечает в терминале — результат может идти дальше: в скрипт, в таблицу, в другой инструмент. И вот тут формат становится критическим.

Если ответ — просто текст, а вам нужно извлечь из него конкретные поля (имя, сумма, дата), придётся разбирать текст вручную или писать сложный парсер. Если ответ приходит сразу в JSON с нужными полями — вы можете сразу передать его дальше.

Параметр --output-format — это способ сказать Claude: «мне не нужно красивое изложение, мне нужна машиночитаемая структура». Для директора, который строит хотя бы минимальные автоматизации — это разница между «работает» и «не работает».

Что это такое

Claude Code поддерживает три формата вывода:

• text — обычный текст (умолчание). Читается человеком, плохо подходит для автоматической обработки.
• json — структурированный JSON. Ответ Claude обёрнут в JSON-объект. Хорошо подходит для скриптов и автоматизации.
• stream-json — то же самое, но ответ приходит потоком по мере генерации. Нужен для интерфейсов, где важно показывать ответ в реальном времени.

Аналогия: text — это устный ответ коллеги. json — это заполненная форма с полями. Форму проще обработать программой, устный ответ — проще прочитать человеку.

Как работает на практике

Стандартный текстовый вывод

claude -p "напиши три вывода из этого отчёта" < отчёт.txt
# выводит красиво отформатированный текст

JSON вывод

claude -p "напиши три вывода из этого отчёта" --output-format json < отчёт.txt

Ответ придёт в виде JSON-объекта. Структура вывода включает поле result с текстом ответа и метаданные сессии.

{
  "result": "1. Продажи выросли на 12%...\n2. Основной...",
  "session_id": "...",
  "total_cost_usd": 0.003
}

Извлечение конкретного поля через jq

jq — это инструмент для работы с JSON в терминале. Устанавливается отдельно:

# macOS
brew install jq

# Ubuntu/Debian
apt install jq

После установки можно извлекать поля:

claude -p "дай ответ" --output-format json | jq '.result'

Практический пример: извлечение данных из документов

Допустим, нужно извлечь из каждого акта три поля: контрагент, сумма, дата. Попросите Claude вернуть JSON:

claude --model haiku \
  -p 'извлеки из этого акта три поля и верни ТОЛЬКО JSON без пояснений: {"contractor": "...", "amount": "...", "date": "..."}' \
  --output-format json \
  < акт.txt | jq '.result | fromjson'

Здесь:
- --output-format json — оборачивает ответ Claude в JSON
- jq '.result' — извлекает поле result (ответ Claude)
- fromjson — парсит JSON внутри строки result

Результат: чистый JSON с тремя полями, готовый к дальнейшей обработке.

Сборка реестра из нескольких документов

echo "[" > реестр.json
for f in акты/*.txt; do
  claude --model haiku \
    -p 'верни ТОЛЬКО JSON: {"contractor": "...", "amount": "...", "date": "..."}' \
    --output-format json < "$f" | jq '.result | fromjson'
  echo ","
done >> реестр.json
echo "]" >> реестр.json

Результат — JSON-массив, который можно открыть в Excel как структурированные данные или передать в любой инструмент аналитики.

Stream-JSON

claude -p "напиши длинный анализ" --output-format stream-json < документ.txt

Ответ будет приходить построчно по мере генерации. Каждая строка — отдельный JSON-объект с частью ответа. Используется в интерфейсах, которые показывают ответ в реальном времени. Для большинства задач директора достаточно json.

Частые ошибки

Ошибка 1. Путать --output-format json и «попросить вернуть JSON»

Это разные вещи. --output-format json — это оболочка вокруг ответа. Содержимое ответа (поле result) будет таким, каким попросите. Для структурированных данных нужно и то, и другое: флаг + инструкция в промте.

Ошибка 2. Парсить JSON вручную в bash

Не делайте этого. Используйте jq. Ручной парсинг через grep и sed сломается на первом же нестандартном ответе.

Ошибка 3. Ожидать стабильный JSON без явной инструкции

Если написать просто «проанализируй и верни результат», Claude вернёт текст. Для получения JSON нужна явная инструкция: «верни только JSON в формате {"поле": значение}».

Ошибка 4. Игнорировать поле total_cost_usd

В JSON-ответе есть поле total_cost_usd с реальной стоимостью запроса. Если вы обрабатываете много документов — полезно суммировать это поле, чтобы понимать расходы:

cat *.json | jq '.total_cost_usd' | awk '{s+=$1} END {print "Total: $" s}'

Когда нужно / когда нет

--output-format json нужен, если:
- Результат будет обрабатываться скриптом
- Нужно извлечь конкретные поля из ответа
- Строите автоматизацию или конвейер
- Нужно сохранить метаданные (стоимость, session_id)

text достаточно, если:
- Читаете ответ глазами
- Разовый запрос без дальнейшей автоматизации
- Сохраняете в файл для чтения человеком

stream-json нужен, если:
- Строите интерфейс с отображением ответа в реальном времени
- Длинный ответ и нужно начать обработку до его завершения

Связь с другими уроками

• День 5 — piping и stdin: JSON-вывод удобно комбинировать с пайпами
• День 25 — агент-аналитик CSV→отчёт: там будем использовать JSON-формат для структурированных данных
• День 44 — exit codes и JSON-вывод в hooks: похожая механика для hook-системы

Задание на сегодня

Выполните запрос с явной инструкцией вернуть JSON и посмотрите на структуру ответа:

echo "Встреча с подрядчиком 5 июня. Обсуждали смету 2.4 млн руб. Следующий шаг — проверить расчёты до 10 июня." | \
claude -p 'извлеки из текста: дату, сумму, дедлайн. Верни ТОЛЬКО JSON: {"date": "...", "amount": "...", "deadline": "..."}' \
--output-format json

Обратите внимание на структуру ответа: поле result содержит JSON-строку, вокруг — метаданные.

Критерий выполнено: получили JSON-ответ, нашли в нём поле result с нужными данными.

Резюме

• --output-format text — по умолчанию, для чтения человеком
• --output-format json — для автоматизации, оборачивает ответ в JSON-конверт с полем result
• --output-format stream-json — для интерфейсов реального времени
• Для структурированных данных: флаг + явная инструкция в промте «верни только JSON»
• jq — незаменимый инструмент для работы с JSON в терминале