Engenharia de prompt: exemplos de antes e depois em tarefas de programação

Pedir "melhora esse código" e pedir "atua como revisor, olha só este arquivo e devolve o diff, mais nada" são duas tarefas diferentes pro modelo, mesmo que na tua cabeça sejam a mesma coisa

Este post é uma coletânea de prompts fracos reescritos lado a lado, cada par isolando UMA alavanca (papel, contexto, formato de saída, restrição) e explicando por que o resultado muda

Nada de fórmula mágica nem prompt secreto, essas coisas toscas

É pra copiar, adaptar e usar na próxima tarefa de programação

Bora ver na prática? 😀

O que você precisa antes de reescrever seus prompts

Antes de sair mexendo no texto, vale entender o PORQUÊ da coisa toda

A documentação da Anthropic define a regra de ouro do prompt claro assim: trate o Claude como um funcionário brilhante, porém recém-chegado, que não tem contexto nenhum sobre suas normas e seus fluxos de trabalho

Ele é ótimo, só que acabou de sentar na cadeira e não sabe como as coisas funcionam aí

Quanto mais preciso o pedido, melhor o resultado

Com isso em mente, o checklist do que ter em mãos:

• Saber qual é a saída ideal: a orientação da OpenAI pra prompts de trabalho é descrever papel, público e formato antes de pedir qualquer coisa
• Ter o contexto que o modelo não infere lendo o código: comandos de terminal, estilo de código e regras de fluxo de trabalho, que é justamente o tipo de coisa que a Anthropic recomenda deixar escrito
• Aceitar que prompt é processo iterativo: a própria OpenAI trata assim, rodar, revisar a resposta e ajustar o texto, além de quebrar tarefa grande em passos menores

Se você quer a base teórica antes dos exemplos, tem um material mais longo sobre engenharia de prompt para devs aqui no blog

O teste do colega sem contexto:

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

Esse aqui é a melhor régua que eu conheço, e é da própria Anthropic

Mostre o prompt pra um colega que tem pouco contexto da tarefa e peça pra ELE executar a instrução

Se o colega se confunde, o modelo também se confunde

Simples assim, e funciona antes de você gastar uma rodada de execução pra descobrir que o pedido estava ambíguo

Exemplos de engenharia de prompt: antes e depois em tarefas de programação

Cada bloco abaixo muda UMA coisa

A ideia não é empilhar tudo de uma vez, é você ver qual alavanca resolve o teu problema específico

1. Trocar o pedido vago pelo verbo de execução

Antes:

você pode sugerir algumas mudanças nesse componente?

Depois:

Refatore o componente abaixo para extrair a lógica de fetch em um hook próprio
Aplique a mudança nos arquivos, não me devolva apenas sugestões

Por que muda: os modelos Claude 4.5 e posteriores são treinados pra seguir instruções de forma precisa e se beneficiam de direção explícita

A documentação registra esse comportamento de forma bem literal: pedir "você pode sugerir algumas mudanças" às vezes devolve sugestões em vez de implementar as mudanças, mesmo quando implementar era a intenção

Ou seja, o modelo respondeu exatamente o que você perguntou, o problema é que você perguntou errado 😛

O erro comum deste passo: achar que o conserto é escrever mais texto. O conserto é trocar o verbo

2. Definir papel, público e formato da saída

Antes:

explica esse erro de CORS

Depois:

Você é um dev backend explicando para alguém que nunca configurou servidor
Explique a causa deste erro de CORS e devolva a correção em um bloco de código do Express, com um comentário curto em cada linha alterada

Por que muda: descrever a saída ideal (papel, público e formato) está na orientação da OpenAI pra prompts de trabalho

Sem isso, o modelo escolhe o público sozinho, e a chance de vir uma resposta genérica demais ou técnica demais é alta

Esse mesmo ajuste de papel e público resolve muita coisa fora do código também, tipo quando você quer uma resposta do ChatGPT mais humana em vez do textão robotizado

O erro comum deste passo: inventar um papel decorativo ("você é um mestre lendário do JavaScript"). Papel serve pra recortar o público e o nível da resposta, não pra elogiar o modelo

3. Colocar a instrução na primeira linha, sem enfeite

Antes:

## Contexto do projeto
Esse projeto é um monorepo com web, worker e db
A gente usa Drizzle
Enfim, queria que você olhasse a query de listagem que tá lenta

Depois:

Otimize a query de listagem de posts que está lenta

Contexto:
Monorepo com web, worker e db
ORM: Drizzle
Banco: Postgres

Por que muda: a OpenAI orienta colocar a instrução concisa da tarefa como primeira linha do prompt, sem cabeçalho de seção, e usar delimitadores pra separar as partes distintas da entrada

A tarefa aparece antes do contexto, e o contexto vira apoio em vez de enterrar o pedido

O erro comum deste passo: contar a história do projeto por três parágrafos e deixar o pedido real na última linha

4. Separar as partes do prompt com delimitadores

Antes:

revisa esse código e usa o padrão do outro arquivo que eu te mandei antes

Depois:

<instructions>
Revise a função abaixo procurando bug de borda e devolva o código corrigido
</instructions>

<code>
... cole aqui a função ...
</code>

<formatting>
Devolva apenas o código final, sem explicação antes nem depois
</formatting>

Por que muda: a Anthropic documenta o uso de tags XML pra separar as partes do prompt, com exemplos de tags como instructions, example e formatting

A recomendação é manter os MESMOS nomes de tag ao longo do prompt, e as tags podem ser aninhadas

A OpenAI vai na mesma direção no guia do GPT-4.1: títulos markdown pras seções principais, crases (inline ou em bloco) pro código, e observa que XML também funciona bem porque delimita início e fim de uma seção, aceita metadados na tag e permite aninhamento

O erro comum deste passo: trocar o nome da tag no meio do caminho (<code> vira <codigo> três linhas depois) e achar que o modelo vai adivinhar que é a mesma coisa

5. Colocar exemplo dentro do prompt

Antes:

escreve os testes desse service

Depois:

<instructions>
Escreva os testes do service abaixo seguindo exatamente o mesmo estilo do exemplo
</instructions>

<example>
describe('slugify', () => {
  it('troca espaço por hífen', () => {
    expect(slugify('hora de codar')).toBe('hora-de-codar')
  })
})
</example>

<code>
... cole aqui o service ...
</code>

Por que muda: a Anthropic documenta o multishot prompting (prompt com exemplos) como técnica própria, e recomenda combinar tags XML com blocos de exemplos e de raciocínio

Um exemplo bom vale mais que três parágrafos descrevendo o estilo que você quer

Se você conhece snippet de editor, é a mesma lógica: em vez de explicar o padrão, você MOSTRA o padrão

O erro comum deste passo: colar um exemplo que não é do teu projeto. Aí o modelo copia o estilo do exemplo, que é exatamente o que você pediu, só que o exemplo estava errado

6. Amarrar formato de saída e restrição

Antes:

me ajuda a arrumar esse componente

Depois:

Corrija o bug de re-render do componente abaixo

Restrições:
Não adicione biblioteca nova
Não mexa em nenhum arquivo fora deste
Mantenha a assinatura do componente igual

Saída:
O arquivo completo em um único bloco de código, e três linhas explicando o que mudou

Por que muda: restrição é o que impede a resposta de crescer pros lados

E o formato explícito é o que te deixa colar o resultado direto no editor sem ficar garimpando o código no meio do textão

O erro comum deste passo: confundir restrição com tamanho de prompt. O blog oficial da Claude é direto nisso: o melhor prompt não é o mais longo nem o mais complexo, e sim o que atinge o objetivo de forma confiável com a estrutura mínima necessária

7. Transformar fluxo de vários passos em etapas condicionais

Antes:

faz o deploy funcionar de novo

Depois:

Siga estas etapas na ordem:

1. Rode o build
2. Quando o build falhar, leia o erro e corrija apenas o arquivo apontado
3. Quando o build passar, rode a suíte de testes
4. Quando um teste falhar, corrija e volte para a etapa 1
5. Quando tudo passar, pare e me mostre o resumo do que mudou

Por que muda: pra fluxos de vários passos, a OpenAI recomenda estrutura explícita de etapas no formato "quando X acontecer, faça Y", com seções separadas por delimitadores claros

Repara que cada linha amarra uma condição a uma ação, em vez de descrever um objetivo solto e torcer pro modelo montar a ordem sozinho

Isso casa com a outra orientação dela, de quebrar tarefas grandes em passos menores

O erro comum deste passo: escrever as etapas sem dizer onde PARA. Sem a linha final, o agente continua achando trabalho pra fazer

8. Dar permissão explícita de dizer "não sei"

Antes:

qual função desse projeto está causando o vazamento de memória?

Depois:

Qual função deste projeto está causando o vazamento de memória?
Se os arquivos que você leu não forem suficientes para afirmar, diga que não sabe e liste o que precisaria ver para responder
Não chute

Por que muda: o material da Claude sobre boas práticas recomenda dar ao modelo permissão explícita pra declarar incerteza em vez de chutar, o que reduz alucinação e aumenta confiabilidade

Em debug isso é ouro, porque um palpite confiante te faz perder meia hora refatorando o arquivo errado

Já me ferrei uma vez por causa disso

O erro comum deste passo: perguntar "tem certeza?" depois que a resposta ruim já veio. A permissão tem que estar no pedido, não na bronca

9. Pedir o comportamento extra em vez de esperar que ele venha sozinho

Antes:

cria a tela de listagem

Depois:

Crie a tela de listagem
Além do caminho feliz, trate estado vazio, estado de carregamento e erro de rede
Inclua os tipos e deixe a tela acessível por teclado

Por que muda: a Anthropic orienta que comportamento "acima do esperado" precisa ser pedido explicitamente nos modelos mais novos, já que eles não inferem esse extra a partir de prompts vagos como versões anteriores faziam

Se você quer o capricho, escreve o capricho

O erro comum deste passo: virar uma lista de 40 exigências que você nem vai testar. Peça o extra que importa pra ESTA entrega, não o mundo inteiro

Onde guardar o prompt que deu certo: CLAUDE.md e o prompt improver

Reescrever prompt é ótimo, mas reescrever o MESMO prompt toda semana é desperdício

A parte que se repete (comandos, estilo, regra de fluxo) tem que virar contexto persistente

Como o CLAUDE.md entra nessa:

No Claude Code, o arquivo CLAUDE.md é lido no início de toda conversa

E ele pode morar em lugares diferentes, dependendo de quem você quer que aquelas regras alcancem:

Pra começar sem folha em branco, o comando /init gera um CLAUDE.md inicial analisando o projeto atual (sistema de build, framework de testes, padrões de código), e aí você refina em cima

A orientação da Anthropic é manter o arquivo curto e denso em sinal, na faixa de menos de cerca de 200 linhas

O motivo é bem prático: cada linha entra no contexto a cada requisição, e um arquivo longo faz as regras importantes se perderem no ruído

O conteúdo indicado são comandos de terminal, estilo de código e regras de fluxo de trabalho, ou seja, contexto que o modelo não consegue inferir só lendo o código

E tem uma régua muito boa pra saber o que adicionar: quando o Claude erra a mesma coisa duas vezes, é sinal de que falta uma regra no arquivo

O erro comum aqui: despejar a documentação inteira do projeto lá dentro. Isso é o oposto do que o arquivo faz de bom

E o prompt improver?

O Console da Anthropic oferece uma ferramenta chamada prompt improver, que pega um prompt existente e reescreve preservando as variáveis do template

Ela adiciona uma seção de raciocínio passo a passo e aplica organização em tags XML e formatação padronizada de exemplos, exatamente as alavancas que a gente viu ali em cima

Nos testes reportados pela Anthropic, o prompt improver elevou a acurácia em 30% em um teste de classificação multirrótulo e levou a aderência à contagem de palavras a 100% em uma tarefa de sumarização

Dois números medidos em tarefas específicas, então não trate como promessa universal, trate como sinal de que estrutura importa 🙂

Prompt bom também é saber quando pedir o plano antes do código

Tem um caso em que a melhor reescrita do prompt é não pedir código nenhum ainda

A orientação da Anthropic é clara sobre quando planejar: o modo de planejamento compensa quando a abordagem é incerta, quando a mudança toca vários arquivos ou quando o código é desconhecido

Pra escopo claro e correção pequena (corrigir um typo, adicionar um log, renomear variável), o certo é pedir a execução direta

A régua que eu gosto: se o diff cabe em uma frase, pula o plano

No Claude Code, o modo de planejamento é acessado pelo atalho Shift+Tab, que cicla entre os modos (a primeira pressionada entra em acceptEdits)

O fluxo típico é entrar em plan mode, refinar o plano e só então executar

Como eu fiz isso na prática:

No vídeo abaixo eu testo uma IDE de programação assistida por IA que começa justamente pela etapa de planejamento, e montei um projeto do zero pra avaliar: um encurtador de URL full stack com login, redirecionamento, registro de cliques e dashboard com gráficos

Em vez de já pedir código, meu primeiro prompt descreve o produto inteiro (o que o usuário faz, o que o sistema salva, o que aparece no dashboard), fecha a stack desejada e termina pedindo ajuda pra planejar antes de codar

Liguei o modo de planejamento na opção de performance, em que mais de um modelo debate o projeto antes de qualquer linha de código, e dá pra subir o nível de raciocínio ao máximo nessa etapa

O planejador devolveu objetivo do projeto, estrutura de pastas sugerida e esquema do banco, e depois comparou os planos gerados por cada modelo pra chegar numa estrutura final

Aí vem a parte que eu acho mais importante: eu NÃO mandei construir o plano inteiro de uma vez

Preferi escrever meus próprios prompts, particionando o plano em tarefas menores, por dois motivos práticos: limite de tokens e o risco de o plano completo gerar um monte de coisa que eu não quero no MVP

O segundo prompt já foi tarefa fechada de estruturação (criar o projeto Next.js, configurar o banco com as tabelas planejadas e deixar o middleware protegendo as páginas do dashboard)

Depois pedi só a camada de autenticação num prompt específico: tela de login com e-mail e senha, tela de registro e header do dashboard com nome do usuário e botão de sair

E deixei o coração do projeto pra depois da base pronta, detalhando comportamento (colar URL grande, escolher slug ou gerar automático, redirecionar, registrar o clique com informação de quem clicou) e interface (lista de links com total de cliques, botão de copiar, editar e excluir)

Eu faço assim em qualquer ferramenta, não é coisa de uma só: entregas parciais concretas, porque eu sei exatamente o que testar a cada etapa e o resultado fica previsível

Na execução eu baixei o esforço e o modo do agente, depois de ter usado o modo mais caro no planejamento

Pedi pra própria ferramenta iniciar o projeto pra eu testar, e reforço: testar por conta continua sendo necessário mesmo com os testes automáticos da ferramenta

O servidor caiu no meio de uma etapa, inclusive, e eu resolvi pedindo pra ferramenta colocar o projeto no ar de novo

Conclusão

Se você olhar os nove pares de novo, dá pra ver que quase tudo se resume a poucas alavancas

Verbo de execução em vez de pedido vago, papel e público, contexto no lugar certo, delimitadores, exemplo dentro do prompt, formato de saída, restrição e permissão explícita de dizer "não sei"

E por cima de tudo isso o princípio que o material oficial da Claude repete: a estrutura mínima necessária pra atingir o objetivo de forma confiável, não o prompt mais longo

Seu próximo passo é bem concreto

Pega o último prompt que te deu resultado ruim, aplica DUAS alavancas dessa lista (não as nove), roda de novo e compara

O que funcionar e for se repetir, move pro CLAUDE.md e para de redigitar

E quando a tarefa for daquelas incertas, que tocam vários arquivos, peça o plano antes do código

até o próximo post! 😀