7 padrões de prompt para gerar código

A qualidade do código gerado por um modelo não é função de quão bom é o modelo. É função de quão bem você formula o problema. O mesmo Claude, GPT ou Cursor vai cuspir um boilerplate medíocre ou exatamente o que você precisa, e a diferença está nas três ou quatro frases do início. Um prompt não é um feitiço: é a especificação de um contrato. Cada lacuna que você deixa, o modelo preenche por você, e ele sempre preenche na direção da solução “mais típica” do treinamento dele, não na direção do seu repositório.

A seguir, sete padrões que eu uso todos os dias. Cada um tem uma justificativa (por que funciona) e um exemplo curto de prompt. Eles não são mutuamente exclusivos: os melhores resultados vêm da combinação entre eles. O texto foi escrito da perspectiva de um desenvolvedor que trata o modelo como um júnior muito rápido e muito literal.

Padrão 1: spec-first (a spec antes do código)

Antes de pedir uma implementação, peça um plano. Faça o modelo descrever as assinaturas das funções, os edge cases e o contrato de entrada/saída, e só escrever código depois da sua aprovação. Funciona porque um modelo que planeja separadamente não mistura decisões de design com detalhes de sintaxe, e é justamente nessa junção que nasce a maioria dos bugs. Você também ganha um ponto de controle: um plano barato de corrigir, em vez de um código caro de reescrever.

Exemplo: Before writing any code, describe in bullet points: the function signature, input and output types, 3 edge cases and the error-handling approach. Then stop and wait for my OK.

Na prática, a falha mais comum é pular a seção “o que NÃO vamos fazer”. Deixe o escopo negativo explícito: sem ele, o modelo enfia cache, retries e logging que você nunca pediu.

Padrão 2: few-shot com as convenções do seu repo

O modelo não conhece o seu estilo até você mostrá-lo. Cole 1-2 funções que já existem no seu código e diga: “siga exatamente esta convenção”. Funciona porque o modelo é excelente em imitar um padrão presente no contexto, muito melhor em “faça assim” do que em “siga o nosso styleguide documentado em outro lugar”. Nomenclatura, retorno de erros, organização dos imports, testes: ele absorve tudo isso a partir do exemplo.

Exemplo: Here is how we write handlers in this project [paste a sample handler]. Write the createInvoice handler in the identical style: same Zod validation pattern, same Result structure, same naming conventions.

Dois bons exemplos valem mais do que dez frases de descrição. Se você tem um arquivo exemplar no repo, esse é o seu melhor prompt.

Padrão 3: test-first (testes falhando antes do código)

Inverta a ordem: peça primeiro os testes que descrevem o comportamento desejado e só depois a implementação que os satisfaz. Funciona porque testes são um contrato sem ambiguidade: o modelo não consegue “quase” satisfazer uma asserção. Você também ganha verificabilidade: depois que o código é gerado, basta rodar os testes em vez de lê-lo linha por linha.

Exemplo: First write a test suite for parsePolishDate, including malformed formats and leap years. The tests must start red. Show them to me, and after I approve, write the implementation that passes all of them.

A armadilha: quando a implementação falha, o modelo gosta de “consertar” o teste em vez do código. Acrescente: “não altere os testes sem a minha aprovação”.

Padrão 4: restrições explícitas (stack, nenhuma dependência nova, escopo de arquivos)

Diga com todas as letras o que o modelo NÃO pode fazer. Versão da linguagem, framework, “nenhum pacote novo do npm”, “edite só estes dois arquivos”. Funciona porque, por padrão, o modelo recorre às bibliotecas mais populares do treinamento dele: vai adicionar lodash, axios ou moment, mesmo que você tenha o fetch nativo e os seus próprios utils. As restrições estreitam o espaço de soluções para aquele que se encaixa no seu repo.

Exemplo: Constraints: TypeScript strict, React Server Components, no new dependencies (use native fetch), change only the file api/users.ts. Do not touch any config.

Escopo de arquivos não é detalhe. Sem ele, o modelo “aproveita para corrigir” módulos vizinhos, e você recebe um diff de meia tela em vez de um de cinco linhas.

Padrão 5: papel + formato de saída (“retorne apenas um unified diff”)

Defina um papel e force um formato exato de resposta. “Você é um revisor”, “retorne apenas um diff”, “nenhum texto fora do código”. Funciona de duas formas: o papel define uma perspectiva (um revisor caça bugs, um arquiteto pensa em fronteiras), e um formato de saída rígido elimina a parede de texto que, de outra forma, você teria de garimpar. Um diff você aplica direto com git apply; um arquivo inteiro você teria de comparar à mão.

Exemplo: Act as a senior reviewer. Return ONLY a unified diff (git format), no explanations, no fenced block. If no change is needed, return an empty diff.

“Só o diff” tem mais um efeito colateral: o modelo reescreve o arquivo inteiro com menos frequência, porque precisa mostrar a mudança mínima. Você recebe PRs menores e mais fáceis de revisar.

Padrão 6: chain-of-thought para lógica difícil (“primeiro raciocine, depois implemente”)

Em um algoritmo não trivial (concorrência, fusos horários, parsing personalizado), faça o modelo expor o raciocínio passo a passo antes de escrever o código. Funciona porque o modelo gera token por token: se ele primeiro “pensa” o problema em texto, os tokens de código seguintes se apoiam em um raciocínio correto, e não na primeira associação. Para um CRUD simples, é exagero; para uma lógica cheia de edge cases, faz uma diferença real.

Exemplo: This is tricky. First walk through step by step how to handle the summer/winter clock change and zones without DST, list the pitfalls, and ONLY THEN write the implementation.

Bônus: quando o raciocínio é explícito, fica fácil apontar o passo errado e corrigi-lo, em vez de depurar um código pronto e calado.

Padrão 7: refinamento iterativo (“critique o seu próprio código”)

Depois da primeira versão, não escreva “conserte isso”. Escreva: “revise o seu próprio código como um revisor rigoroso, liste os 3 pontos mais fracos e depois corrija”. Funciona porque o modelo, no modo crítico, avalia de um jeito diferente do modo de geração: ele enxerga a falta de tratamento de erros, um vazamento de recurso, uma race condition que deixou passar enquanto estava “só escrevendo”. É uma segunda passada barata sobre o mesmo contexto.

Exemplo: Put on the hat of a demanding reviewer and find problems in your own code: security, edge cases, performance. List them, then return the corrected version.

Limite as iterações a duas ou três. Depois da terceira rodada, o modelo mais anda em círculos do que melhora de fato; nesse ponto, é melhor voltar ao Padrão 1 e reescrever a spec.

Antipadrões que você deve evitar

Os três pecados mais comuns. Primeiro: “crie um app para mim” sem nenhum contexto. Você recebe o esqueleto mais genérico que existe. Segundo: despejar o repo inteiro no contexto na esperança de que “o modelo se vire”. O sinal relevante se afoga no ruído e a qualidade cai. Terceiro: aceitar código que você não entende. Se você não consegue revisar o resultado, nenhum prompt vai salvar você. Um prompt acelera a escrita; ele não dispensa você de pensar.

TL;DR

Sete padrões: spec-first (o plano antes do código), few-shot com as suas convenções, test-first (testes vermelhos, depois o código), restrições explícitas (stack, nenhuma dependência nova, escopo de arquivos), papel + formato de saída (só o diff), chain-of-thought para lógica difícil e autocrítica iterativa. Combine os sete. A qualidade do prompt pesa mais do que a qualidade do modelo: o mesmo Claude ou GPT vai entregar um boilerplate ou exatamente o seu código, dependendo de como você formula o contrato.