Objetivo: ao final, o consultor obtém JSON conforme um schema para alimentar outro sistema, e divide um trabalho longo em dois scripts que compartilham a mesma sessão.
--output-format json devolve result, session_id e o custo da chamada; com --json-schema, o objeto que obedece ao schema vem num campo separado, structured_output — não no result.session_id da primeira chamada e retome com --resume "$session_id" na segunda: a segunda passada tem o contexto inteiro da primeira. Ambas precisam rodar do mesmo diretório.--bare garante o mesmo resultado em toda máquina e --max-turns põe teto no loop, encerrando com erro ao bater o limite.| Formato | O que entrega |
|---|---|
text (padrão) |
Texto puro |
json |
JSON com result (o texto), session_id, uso e custo (total_cost_usd, com quebra por modelo) |
stream-json |
Uma linha JSON por evento, para consumo em tempo real. Combine com --verbose e --include-partial-messages; a última linha é a mensagem result |
claude -p "leia a pasta de controle e liste o status de cada RICEFW do Meridiano" \
--bare \
--output-format json \
--json-schema '{"type":"object","properties":{"ricefw":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tipo":{"type":"string"},"status_transporte":{"type":"string"},"pendencia":{"type":"string"}},"required":["id","status_transporte"]}}},"required":["ricefw"]}' \
--allowedTools "Read,Glob,Grep" \
| jq '.structured_output.ricefw'
| Ponto | Detalhe |
|---|---|
| Onde o objeto cai | Em structured_output, ao lado dos metadados. O result continua sendo o texto |
| Schema inválido | Error: --json-schema is not a valid JSON Schema, seguido do diagnóstico do validador, e encerra com erro. Em versões anteriores à 2.1.205, um schema inválido era ignorado silenciosamente e você recebia texto solto |
A palavra format |
Aceita, mas tratada como anotação: "format": "email" não é validado por você |
| Só em print mode | --json-schema funciona apenas com -p |
Daí para a planilha de RICEFW é um passo: jq extrai o array, e qualquer conversor de JSON para CSV monta as colunas. O valor aqui não é o Claude "gerar uma planilha" — é a saída ter forma garantida, para que o passo seguinte do processo não precise adivinhar.
O padrão que resolve trabalho longo com revisão humana no meio:
# 01-planejar.sh — primeira passada: produz o plano, não executa
session_id=$(claude -p "leia as 3 especificações novas da Fase 2 e proponha um plano de ajuste na documentação de integração. Não altere nenhum arquivo ainda." \
--bare \
--output-format json \
--allowedTools "Read,Glob,Grep" \
| tee plano.json | jq -r '.session_id')
echo "$session_id" > .sessao-atual
jq -r '.result' plano.json > plano.md
# 02-executar.sh — segunda passada: retoma com o contexto inteiro
session_id=$(cat .sessao-atual)
claude -p "o plano foi aprovado com os comentários em plano-revisado.md. Execute-o." \
--resume "$session_id" \
--bare \
--max-turns 15 \
--permission-mode dontAsk
| Regra | Por quê |
|---|---|
| Mesmo diretório nas duas chamadas | A busca por session_id é limitada ao diretório do projeto e às suas worktrees |
--resume "$session_id" vs --continue |
--resume escolhe uma sessão específica; --continue pega a mais recente, sem precisar guardar identificador. Com mais de uma conversa em andamento, use --resume |
| A segunda passada não reexplica a tarefa | Ela já tem o contexto da primeira — inclusive o que foi lido e concluído. Reexplicar gasta contexto e cria a chance de contradizer a primeira passada |
| Flag | O que faz |
|---|---|
--bare |
Pula a descoberta do ambiente local (aula 3.5.2): mesmo resultado em toda máquina, porque as fontes locais nunca são lidas |
--max-turns N |
Teto de turnos agênticos, só em print mode. Encerra com erro ao bater o limite — sem limite por padrão |
Junto com --output-format json, esses dois dão a um passo de pipeline as três coisas que um passo de pipeline precisa: resultado previsível, teto de execução e custo visível por chamada.
Regra Wayon Passo de pipeline que alimenta planilha, ticket ou relatório de cliente usa
--json-schemaobrigatoriamente. Parser de texto livre quebra em silêncio no dia em que a redação muda, e a quebra só aparece no relatório errado que chega ao cliente. E todo-pde CI leva--max-turns: sem teto, um loop que não converge consome orçamento até alguém notar.
📖 Get structured output · Continue conversations · CLI reference
claude -p com --output-format json e --json-schema, e o script seguinte quebrou ao tentar ler o objeto estruturado em .result.structured_output; .result continua sendo o textoCorreto. São dois campos distintos, e é o erro mais comum de quem usa schema pela primeira vez.
--json-schema não funciona junto com --output-format jsonFuncionam juntos — é justamente a combinação exigida.
.result, mas como string escapada, que precisa de um segundo fromjsonNão é o caso: existe um campo próprio para o objeto estruturado.
O formato pedido em prosa é uma tendência forte, não uma garantia — e a quebra é silenciosa.
A diferença de custo é irrelevante; o risco real é de outra natureza.
--json-schema amarra a forma de verdadeCorreto. É a diferença entre pedir um formato e restringir a saída a um schema.
--resume busca a sessão pelo identificador em qualquer diretórioA busca por identificador de sessão é limitada ao diretório do projeto e às suas worktrees.
Correto. É a pegadinha mais comum do padrão de duas passadas.
Quando encontra a sessão, --resume traz o contexto inteiro; o problema aqui é não encontrar.
--max-turns N, que encerra com erro ao bater o limiteCorreto. Sem essa flag não há limite por padrão.
--bare, que reduz o escopo do que o Claude pode fazer--bare resolve reprodutibilidade e tempo de partida, não põe teto no número de turnos.
--output-format json, que expõe o custo e permite abortarO custo aparece ao final da chamada, o que é útil para acompanhar gasto, mas não interrompe uma execução em andamento.