Engenharia de prompt: o guia honesto (sem fórmula mágica)

A internet está cheia de listas de "100 prompts mágicos que vão revolucionar seu trabalho". Pula essas. Engenharia de prompt de verdade não é decorar fórmula — é escrever instrução como quem escreve contrato: sem ambiguidade, com exemplo, e testável.

Quando você constrói software com IA, o prompt deixa de ser uma frase de chat e vira parte do sistema. Ele tem entrada, saída, contrato e custo. Tratar isso como sorte — "vamos ver o que o modelo cospe" — é a diferença entre uma demo bonita e uma feature que aguenta produção.

Neste guia eu mostro os quatro pilares que sustentam um prompt de produção: estrutura, instrução, exemplos e formato de saída. Sem hype, com o que a documentação oficial da Anthropic e da OpenAI realmente recomenda.

TL;DR

• O que é: engenharia de prompt é a prática de escrever instruções precisas para um LLM produzir a saída que você precisa, de forma confiável e repetível.
• Para quem constrói software: prompt é código. Tem contrato de entrada/saída, precisa de teste e versionamento.
• Os quatro pilares: estrutura clara, instrução sem ambiguidade, exemplos (few-shot) e formato de saída explícito.
• Não é: lista de prompts prontos, palavra mágica, "aja como um especialista" e rezar.
• Fontes: Prompt engineering — Claude Docs e Prompt engineering — OpenAI.

Engenharia de prompt: o que é, de verdade?

Vou tirar o glamour da coisa.

Engenharia de prompt é escrever a instrução que vai dentro da chamada do modelo. Só isso. O nome é pomposo, mas o trabalho é mundano: você descreve uma tarefa para uma máquina que lê literalmente o que você escreveu e não adivinha o que você quis dizer.

A confusão começa quando alguém vende "prompt" como truque. "Use essa palavra secreta e o ChatGPT obedece." Isso não é engenharia. Isso é superstição.

A documentação da Anthropic é direta nisso: o modelo "responde bem a instruções claras, diretas e detalhadas" e, quando uma instrução pode ser interpretada de mais de uma forma, você precisa explicar exatamente o que quer (Claude Docs). A OpenAI diz a mesma coisa com outras palavras: seja específico sobre papel, objetivo e formato.

Repara que nenhuma das duas fala em palavra mágica. Falam em clareza.

Quando você programa com IA, isso fica concreto. O prompt entra num arquivo, recebe variáveis interpoladas, é chamado mil vezes por dia e cada falha de ambiguidade vira um bug que aparece em 3% das requisições — o tipo de bug que ninguém consegue reproduzir no localhost. Por isso prompt de produção se trata como código: revisão, teste, versão.

Pilar 1 — Estrutura: separe instrução de dado

O erro número um de quem começa é jogar tudo num blob de texto. Instrução, contexto, dado do usuário, exemplo — tudo grudado num parágrafo só. O modelo então confunde o que é ordem com o que é conteúdo.

A solução que a Anthropic recomenda é estrutura explícita com tags XML. Elas existem para "separar as diferentes partes do prompt" e impedir que o Claude misture instrução com exemplo ou com dado (Claude Docs — XML tags).

Na prática:

<instrucoes>
Você classifica o sentimento de avaliações de produto.
Responda apenas com: positivo, negativo ou neutro.
</instrucoes>

<avaliacao>
{{texto_da_avaliacao}}
</avaliacao>

A <avaliacao> é dado do usuário. As <instrucoes> são suas. Com a fronteira marcada, fica muito mais difícil um usuário mal-intencionado escrever "ignore as instruções acima" dentro da avaliação e sequestrar seu prompt. Não é blindagem total contra prompt injection — mas é a primeira linha de defesa, e é de graça.

A ordem também conta. Coloque papel e contexto primeiro, depois a tarefa, por último o formato de saída. O modelo lê o prompt inteiro antes de responder, mas o contexto na frente ajuda a estabelecer o referencial certo.

Pilar 2 — Instrução: escreva como contrato, não como pedido

"Resuma esse texto" é um pedido. Um contrato é diferente:

Resuma o texto abaixo em no máximo 3 frases. Foque nas decisões tomadas, não na discussão. Não inclua opinião. Se o texto não contiver nenhuma decisão, responda exatamente: "Nenhuma decisão registrada."

Cada frase ali fecha uma porta de ambiguidade. Tamanho: 3 frases. Foco: decisões. Proibição: opinião. E — o detalhe que separa amador de profissional — o caso de borda: o que fazer quando não há nada para resumir.

Esse último ponto é onde quase todo prompt quebra em produção. O modelo sempre devolve alguma coisa. Se você não disse o que fazer no caso vazio, ele inventa. Especificar o comportamento de borda não é preciosismo — é a diferença entre um sistema previsível e um que alucina quando a entrada foge do feliz caminho.

Dois reforços simples e baratos:

• Diga o que fazer, não só o que evitar. "Não seja informal" é vago. "Use tratamento na terceira pessoa e tom técnico" é acionável.
• Dê o porquê. Explicar a motivação — "isso vai num e-mail para um cliente" — ajuda o modelo a calibrar decisões que você não previu. Tanto a Anthropic quanto a OpenAI batem nessa tecla.

Pilar 3 — Exemplos (few-shot): mostre, não só descreva

Tem comportamento que é mais fácil mostrar do que explicar. É aí que entra o few-shot: você inclui alguns exemplos de entrada e saída no próprio prompt, e o modelo extrai o padrão.

<instrucoes>
Extraia nome e valor de cada item. Devolva uma linha por item no formato: nome | valor.
</instrucoes>

<exemplos>
Entrada: "2 cafés a 5 reais cada"
Saída: café | 10.00

Entrada: "três pães franceses, 0,75 a unidade"
Saída: pão francês | 2.25
</exemplos>

<pedido>
{{pedido_do_usuario}}
</pedido>

O segundo exemplo não é decorativo. Ele ensina, sem uma linha de instrução extra, que "três" vira número, que o cálculo é quantidade × valor unitário, e que a saída usa ponto decimal. Tente descrever tudo isso em prosa e o prompt fica três vezes maior e ainda ambíguo.

A Anthropic chama o few-shot de prática "fortemente recomendada" — mas com um aviso que quase ninguém respeita: não despeje uma lista enorme de casos de borda. Curadoria vale mais que volume. Escolha exemplos diversos e canônicos que representem o comportamento esperado (effective context engineering). Três exemplos bem escolhidos batem vinte exemplos repetidos — e ainda gastam menos token.

Para tarefas de raciocínio, existe o primo do few-shot: o chain-of-thought, o famoso "pense passo a passo". Forçar o modelo a expor o raciocínio antes da resposta final melhora tarefas de lógica de múltiplos passos, porque cria uma espécie de memória de trabalho onde ele referencia os próprios passos (Prompting Guide — CoT). Mas custa token e latência. Não use para tarefa que uma resposta direta já resolve.

Pilar 4 — Formato de saída: a saída é uma API

Aqui é onde o prompt de chat e o prompt de software se separam de vez.

Num chat, você lê a resposta com os olhos. Num sistema, outro código vai consumir essa saída. Se o modelo devolve JSON num dia e prosa com "Claro! Aqui está:" no outro, seu parser quebra e a feature cai.

Então trate a saída como contrato de API. Especifique o formato exato:

<formato_saida>
Responda apenas com JSON válido, sem texto antes ou depois, neste schema:
{"sentimento": "positivo|negativo|neutro", "confianca": 0.0}
</formato_saida>

Duas dicas que economizam dor:

• Combine com few-shot. Um exemplo de JSON bem-formado vale mais que três parágrafos descrevendo o schema.
• Valide sempre. Modelo erra formato. Faça uma checagem binária — JSON parseou? Campos obrigatórios estão lá? — e tenha um retry ou fallback. Confiar cegamente na saída é onde o sistema quebra silencioso.

Boa parte das APIs hoje já oferece structured outputs nativos, que forçam o schema na decodificação. Use quando disponível — é mais robusto que pedir JSON na unha e torcer.

O elo com engenharia de contexto e tool calling

Aqui está a parte que as listas de "prompt mágico" nunca contam: prompt é só o começo.

A própria Anthropic já trata engenharia de prompt como um subconjunto de algo maior — a engenharia de contexto, definida como "o conjunto de estratégias para curar e manter o conjunto ótimo de tokens durante a inferência" (Anthropic). Construir com modelo deixou de ser só achar as palavras certas e virou decidir qual configuração de contexto gera o comportamento desejado.

Isso fica óbvio quando você sai do prompt único e entra em agentes. Um agente roda em loop e gera, a cada passo, mais dados que podem importar no próximo. Aí o trabalho não é mais escrever uma frase perfeita — é gerenciar o que entra e o que sai da janela de contexto, e descrever bem as ferramentas que o modelo pode chamar. A descrição de uma tool é, no fundo, mais um prompt: nome claro, parâmetros sem ambiguidade, exemplo de uso. Os mesmos quatro pilares, aplicados a outra camada.

Ou seja: dominar prompt não é o destino. É o pré-requisito. Quem não escreve uma instrução clara não vai escrever uma boa descrição de ferramenta, nem montar um contexto enxuto para um agente.

Limitações e pontos de atenção

Engenharia de prompt resolve muita coisa, mas não tudo. Onde você vai se queimar:

• Prompt não conserta modelo fraco. Tarefa que exige raciocínio pesado num modelo pequeno não vira mágica com a instrução certa. Às vezes a resposta é trocar o modelo, não polir o prompt.
• Prompt não substitui conhecimento. O modelo não sabe do seu banco de dados, da sua doc interna, da sua regra de negócio. Isso é RAG e contexto — não é prompt.
• Saída não é determinística. Mesmo com o melhor prompt, o modelo varia. Por isso teste e validação não são opcionais. Monte um conjunto de casos e rode o prompt contra ele toda vez que mudar algo.
• Cuidado com dado sensível. Não jogue dado de cliente cru no prompt sem necessidade e sem mascarar. O que entra no contexto pode ir parar em log.

FAQ rápido

Engenharia de prompt vai virar profissão? Como cargo isolado, provavelmente não. Como habilidade de quem constrói software com IA, é tão básico quanto saber escrever uma query SQL. Não é o futuro — é o presente.

Preciso de uma lista de prompts prontos? Não. Listas prontas resolvem o caso de quem escreveu, não o seu. Aprenda os quatro pilares e você escreve o prompt que o seu problema pede.

Few-shot ou chain-of-thought, qual uso? Few-shot quando importa o formato e a consistência do padrão (classificação, extração, geração estruturada). Chain-of-thought quando a tarefa exige raciocínio de múltiplos passos. Dá para combinar os dois.

Como sei se meu prompt está bom? Você testa. Monte de 10 a 50 casos com a saída esperada e meça quantos passam — é exatamente o que mostro em prompts resilientes com 50 casos adversariais. "Pareceu bom" não é métrica. Taxa de acerto num conjunto de teste é.

Conclusão

Engenharia de prompt não tem fórmula mágica porque não precisa. Precisa de disciplina: estrutura que separa instrução de dado, instrução escrita como contrato com casos de borda fechados, exemplos canônicos no lugar de descrição infinita, e formato de saída tratado como uma API que outro código vai consumir.

Faz isso e o prompt para de ser sorte e vira engenharia. Aí você está pronto para o próximo nível — engenharia de contexto, tool calling, agentes que aguentam produção.

E é exatamente esse pulo, do prompt isolado para a arquitetura de uma solução de IA inteira, que a gente coloca na mesa no Workshop Arquitetando Soluções de IA: como sair do prompt bonito e desenhar software que roda com agents de verdade. Se você já entendeu que prompt é só o começo, é o lugar de continuar a conversa.