Construtor de Prompt JSON

Por que texto corrido quebra código e JSON não

Peça a um modelo "o nome do candidato, o salário e a data de início" e você recebe um parágrafo bem escrito. Peça duas vezes e recebe dois parágrafos diferentes. Um diz "cerca de R$ 8 mil", o outro "8.000 reais por mês", o terceiro começa com "Claro! Veja o que encontrei". Seu parser não tem chance.

O problema não é precisão — o modelo pode estar certo todas as vezes. É que texto livre não tem contrato. Nada garante que o salário venha antes da data, que um campo ausente seja omitido em vez de descrito, ou que a resposta pule o preâmbulo. Cada regex que você escreve para contornar isso é um bug esperando uma frase ligeiramente diferente.

JSON te dá o contrato. As chaves são fixas, os tipos são fixos, null significa "não encontrado" sempre. Seu código lê data.salary em vez de caçar cifrão. Quando o modelo erra, você descobre no parse, não três funções adiante.

Se quem lê é uma pessoa, texto corrido serve. Se quem lê é código, use JSON.

Projete um esquema que o modelo consiga acertar

Modelos atendem esquemas simples com confiabilidade e esquemas complexos de vez em quando. Regras que se sustentam:

• Plano ganha de aninhado. Dois níveis é confortável. No quarto, as chaves começam a fechar no lugar errado. contact_email é mais seguro que contact.channels.email.primary.
• Seja explícito sobre tipos. Diga "salary deve ser número, não string". Na dúvida, o modelo cai para string.
• Use null, nunca omita. Chave faltando quebra data.x.y de um jeito que valor faltando não quebra.
• Trave seus enums. "status deve ser exatamente um de: open, closed, pending" devolve três valores. "status: o status atual" devolve quinze formulações dos mesmos três.
• Nomeie chaves como um dev nomearia. snake_case, sem espaços. O modelo já escreveu muito JSON.
• Descarte campos que você não vai usar. Cada chave extra é mais uma chance de inventar valor.

Mostre o formato em vez de descrevê-lo. Um exemplo literal com placeholders vale mais que um parágrafo de especificação:

Instruções que matam prosa solta e blocos de código

Três falhas causam quase toda resposta que não dá para parsear: um preâmbulo, uma cerca de markdown, uma explicação no fim. Coloque estas linhas perto do final, onde são lidas por último:

• "Retorne SOMENTE o objeto JSON. Sem prosa, sem explicação, sem blocos de código markdown."
• "Sua resposta inteira deve começar com uma chave de abertura e terminar com uma chave de fechamento."
• "Não envolva a saída em crases."

A segunda linha é a que mais trabalha. É uma checagem que o modelo consegue verificar contra o próprio primeiro token, bem mais confiável que um "sem texto extra" genérico.

Ajude-se também do lado do parsing. Remova cercas no começo e no fim antes de parsear — três linhas defensivas que economizam uma nova chamada. E baixe a temperatura para 0. Amostragem criativa é justamente o oposto do que se quer aqui.

Se um modelo específico insiste em preâmbulos, geralmente é mania de formulação, não limitação de capacidade. O gerador de prompts para ChatGPT e o gerador para Gemini cuidam do fraseado por modelo, e o analisador aponta instruções que convidam comentário sem você perceber.

Arrays, campos opcionais e o caso vazio

Arrays são onde prompts de extração ficam desleixados. Diga quantos, e o que acontece quando não há nenhum.

"Retorne [] se nenhuma se aplicar" impede o modelo de escrever "nenhuma" dentro de um array. O limite máximo impede que ele encha um documento curto para parecer completo. Para objetos opcionais, prefira null à omissão — um caminho no seu código em vez de dois.

Validar, tentar de novo e onde entram os modos nativos

Nunca confie no primeiro parse. O ciclo que sobrevive em produção:

1. Parseie. Se der erro, remova cercas e espaços e parseie de novo.
2. Valide contra um esquema de verdade — Zod, Pydantic, JSON Schema. Cheque tipos e chaves obrigatórias, não só se é JSON válido.
3. Na falha, tente uma vez mais com o erro anexado: "Sua saída anterior falhou na validação: esperado número em salary, recebido string. Retorne apenas o JSON corrigido."
4. Depois de duas falhas, registre a saída bruta e caia no plano B. Não fique em loop.

Essa nova tentativa resolve a maioria das falhas de primeira, porque você transformou um erro vago em uma correção específica.

Agora a parte que costuma ser ignorada: quase todo provedor oferece saída estruturada nativa — modo JSON, esquemas de resposta, function calling. Use onde existir. A API restringe a decodificação, então JSON malformado vira algo quase impossível. Mas ela impõe forma, não sentido. Uma resposta válida pelo esquema ainda pode colocar o nome do recrutador em company. A semântica vem do prompt: o que cada campo significa, quando null se aplica, qual enum encaixa. Os dois se complementam. A documentação da OpenAI cobre o lado da API; o guia de fundamentos cobre os padrões por trás de tudo isso, e o otimizador enxuga um prompt de extração inchado sem derrubar as restrições que importam.