Controle de formato de saída: obtendo JSON, markdown e dados estruturados com confiabilidade

Claude é incrivelmente flexível com formatos de saída, mas flexibilidade não significa consistência. Peça por JSON sem orientação adequada e você pode receber markdown envolvido em blocos de código. Solicite dados estruturados sem restrições e Claude pode decidir que prosa é mais útil.

A solução não é rezar para que Claude acerte — é engenheirar seus prompts para eliminar ambiguidade. Veja como obter exatamente o formato que você precisa, toda vez.

O problema central: desvio de formato

Quando você pede JSON ao Claude, na verdade está pedindo uma de várias coisas:

JSON puro (sem markdown, sem blocos de código)
JSON em um bloco de código markdown com três backticks
JSON com texto explicativo antes ou depois
JSON com comentários (tecnicamente inválido, mas às vezes útil)

Claude não sabe qual você quer a menos que seja explícito. Isso importa porque sistemas downstream esperam formatos específicos. Um parser que lida com blocos de código markdown vai quebrar com JSON puro. Uma API esperando JSON simples vai falhar se você receber markdown.

A correção é declarar exatamente o que você quer em seu prompt, depois reforçar isso estruturalmente.

Técnica 1: declarações explícitas de formato

Comece com uma seção de especificação de formato. Coloque-a no início, antes da descrição da tarefa:


Você fará output APENAS de JSON válido. Não inclua blocos de código markdown,
explicações ou qualquer texto fora do JSON. O output deve ser analisável
por um parser JSON padrão sem pré-processamento.

Isso funciona melhor que menções casuais porque é inequívoco. Compare:

Fraco: "Por favor, me dê JSON com os dados" Forte: "Output APENAS JSON válido sem texto adicional ou formatação"

A segunda versão elimina a lacuna de interpretação. Claude sabe que você não está pedindo uma explicação útil com JSON incluído — você está pedindo apenas JSON.

Para markdown, inverta a lógica:


Formate sua resposta como markdown. Use hierarquia apropriada de títulos
(# para seções principais, ## para subseções). Inclua blocos de código com
identificadores de linguagem quando apropriado. Não inclua conteúdo fora
da formatação markdown.

Técnica 2: prompting com schema primeiro

Para dados estruturados, mostre ao Claude exatamente o que você quer antes de pedir. Use um template:


Você fará output de JSON correspondendo exatamente a este schema:

{
"findings": [
{
"category": "string",
"severity": "low|medium|high",
"description": "string",
"actionItems": ["string"]
}
],
"summary": "string"
}

Preencha este schema com base na seguinte análise...

Ao fornecer o schema primeiro, você está eliminando adivinhação. Claude vê a estrutura e segue-a. Isso é mais efetivo que descrever o que você quer porque estrutura é mais clara que prosa.

Exemplo real: analisando logs de segurança. Em vez de "me dê um sumário JSON de vulnerabilidades", forneça:

{
  "scanDate": "data ISO 8601",
  "vulnerabilities": [
    {
      "cveId": "string",
      "affectedSystem": "string",
      "riskScore": "número 0-10",
      "remediation": "string"
    }
  ],
  "criticalCount": "número"
}

Agora Claude tem um template claro para preencher. Sem ambiguidade sobre níveis de aninhamento, nomes de campos ou tipos de dados.

Técnica 3: isolamento baseado em delimitadores

Alguns casos de uso se beneficiam de marcar onde a saída começa e termina:

Sua resposta deve seguir esta estrutura:

=== INÍCIO JSON ===
[JSON válido aqui]
=== FIM JSON ===

Nenhum outro texto deve aparecer fora desses marcadores.

Isso é exagerado para a maioria dos cenários, mas é útil quando Claude é prolixo ou quando você está encadeando múltiplas requisições. Os delimitadores atuam como âncoras que sua lógica de parsing pode usar para extrair o conteúdo exato.

Para markdown, você pode usar:

Formate como markdown entre estes marcadores:

=== INÍCIO MARKDOWN ===
[seu conteúdo markdown]
=== FIM MARKDOWN ===

Técnica 4: restrições negativas

Diga ao Claude o que não fazer. Isso geralmente funciona melhor que instruções positivas:

O output deve ser JSON válido. NÃO:
- Inclua blocos de código markdown (```)
- Adicione texto explicativo antes ou depois
- Use comentários dentro do JSON
- Pretty-print com espaços em branco excessivos
- Inclua vírgulas finais

Output JSON minificado, em uma única linha se o objeto for simples.

Restrições negativas funcionam porque abordam erros comuns diretamente. Claude sabe exatamente quais padrões evitar.

Técnica 5: validação através de exemplos

Mostre ao Claude exemplos funcionais do formato que você quer:

Output JSON neste estilo exato:

Exemplo 1 (correto):
{"name":"Alice","age":30,"tags":["engineer","python"]}

Exemplo 2 (incorreto):
```json
{"name": "Bob", "age": 25}

Sua tarefa: analise [input] e faça output de JSON combinando o formato do Exemplo 1.


Exemplos são poderosos porque contornam interpretação. Claude vê o padrão e o replica.

## Testando seus prompts

Antes de implantar prompts críticos de formato, teste-os com parsing real:

```python
import json

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": seu_prompt}]
)

try:
    parsed = json.loads(response.content[0].text)
    print("✓ JSON válido")
except json.JSONDecodeError as e:
    print(f"✗ Parse falhou: {e}")
    print(f"Response bruto: {response.content[0].text}")

Isso revela falhas de formato imediatamente. Se o output do Claude não fizer parse, ajuste seu prompt antes de colocá-lo em produção.

Armadilhas comuns a evitar

Misturando instruções: "Me dê JSON ou markdown dependendo do que fizer sentido" cria ambiguidade. Claude vai escolher, mas você não vai gostar. Seja prescritivo.

Assumindo formatação em blocos de código: Muitos desenvolvedores esperam blocos de código markdown porque copiam-colam da interface de chat. Mas uso programático raramente quer os três backticks. Especifique formato puro.

Confiando em espaços em branco: Não assuma que o JSON do Claude está minificado ou pretty-printed. Se importa para parsing, diga explicitamente.

Esquecendo conteúdo final: Claude pode adicionar "Aqui está seu JSON:" antes do JSON real. Previna isso com "Output APENAS o JSON sem preâmbulo."

Template para o mundo real

Aqui está uma estrutura de prompt que funciona na maioria dos cenários:

Você é um [papel] analisando [domínio]. Sua tarefa é [objetivo].

FORMATO DE OUTPUT:
Você fará output APENAS de JSON válido correspondendo a este schema:
[schema aqui]

REGRAS:
- Sem markdown, blocos de código ou texto explicativo
- JSON minificado em linha única
- Todos os campos obrigatórios devem estar presentes
- Valores numéricos devem ser números, não strings

ANÁLISE:
[sua descrição de tarefa real aqui]

Este template cobre especificação (papel), declaração de formato, restrições e tarefa. Funciona porque é estruturado consistentemente.

O resultado final

Controle de formato não é sobre lutar contra a natureza do Claude — é sobre ser preciso no que você pede. Os melhores prompts eliminam lacunas de interpretação através de declarações explícitas, exemplos concretos e restrições claras.

Teste seus prompts de formato com parsing real antes de usá-los em escala. O que funciona na interface de chat pode falhar programaticamente. Trate formato como um requisito a validar, não um pensamento posterior.