Como escrever prompts melhores para gerar código com IA

Fala aí, beleza? Todo mundo já viu esse filme: a IA devolve um código que parece certo, você cola, roda, e ele quebra num caso de borda que ninguém tinha pedido

Não é impressão sua

Na pesquisa do Stack Overflow de 2025, 66% dos respondentes apontaram a solução "quase certa, mas não totalmente" como a MAIOR frustração com IA

E 45% citam gastar mais tempo depurando código gerado por IA, a segunda maior frustração da mesma pesquisa

Se liga no diagnóstico: na maioria das vezes o gargalo não é o modelo… é o pedido

Prompt sem contexto do projeto, sem restrição de stack, sem formato de saída e sem critério de aceite gera código genérico, e código genérico em cima de base real vira retrabalho

Neste post eu vou destrinchar o passo a passo pra escrever prompt para gerar código com IA aplicado a tarefa de código de verdade, não a texto genérico 🙂

O que você precisa antes de escrever o prompt:

Antes de digitar qualquer coisa, junte cinco insumos que já existem no seu projeto

Pensa assim: você não pediria uma tarefa dessas pra um dev novo no time sem passar nada, né? Com o modelo é igual

• O alvo: o trecho, a função ou o arquivo que vai ser alterado, colado ou apontado por caminho
• A stack e as versões: linguagem, framework, gerenciador de pacotes e as versões que o repositório realmente usa
• A convenção do repositório: padrão de nome, camadas, onde mora teste, como se trata erro por lá
• O comando que valida: o build, o lint ou a suíte de teste que o seu projeto roda pra dizer se ficou de pé
• A definição de pronto: o que precisa acontecer pra tarefa estar encerrada, em frase verificável

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

E por que isso tudo antes?

Porque quando falta insumo, o modelo não trava: ele COMPLETA

Ele assume uma versão de biblioteca, inventa um padrão de pasta, escolhe um jeito de tratar erro que não é o seu

O resultado sai plausível, e plausível é exatamente aquele "quase certo, mas não totalmente" que morde 66% da galera na pesquisa

Tome cuidado com um detalhe chato: versão errada é o erro mais silencioso de todos, porque o código compila e só quebra depois

Como escrever prompts melhores para gerar código: passo a passo

A estrutura abaixo funciona em qualquer chat de modelo e em qualquer agente de código

É menos "prompt secreto" e mais briefing de tarefa, beleza?

1. Descreva o contexto e o PORQUÊ da tarefa

A documentação da Anthropic recomenda ser explícito e dar o contexto ou a motivação por trás da instrução: explicar por que aquele comportamento importa ajuda o modelo a entregar uma resposta mais alinhada

A mesma doc sugere pedir explicitamente o comportamento "acima do esperado", em vez de torcer pro modelo inferir sozinho

Contexto: API de pedidos em produção, usada por um app mobile que não pode receber 500
Motivo: qualquer erro não tratado aqui derruba a tela de checkout do cliente
Por isso, trate o caminho de falha com o mesmo cuidado do caminho feliz

O erro comum deste passo: escrever só a tarefa ("corrige esse bug") e deixar o motivo na sua cabeça

2. Fixe as restrições de stack e o que NÃO pode ser tocado

Restrição é o que impede a IA de "melhorar" o que você não pediu

Diga a versão, diga a biblioteca que já está no projeto e liste o que fica congelado

Restrições:
- usar apenas as dependências que já estão no package.json, não instalar nada novo
- manter a assinatura pública da função intacta
- não renomear arquivos nem mover pastas
- não alterar o schema do banco

O erro comum deste passo: proibir de forma vaga ("não mexe em muita coisa") em vez de nomear o que é intocável

3. Defina o formato da saída

Diff, arquivo inteiro, só a função, com explicação ou sem explicação: escolha e diga

Isso muda MUITO o tempo que você gasta depois pra aplicar o resultado

Formato da resposta:
1. uma frase com a causa raiz
2. o diff dos arquivos alterados, sem reescrever o arquivo inteiro
3. nada além disso

O erro comum deste passo: aceitar o arquivo inteiro reescrito em tarefa pequena, e depois passar dez minutos comparando linha a linha pra achar o que mudou de fato

4. Escreva o critério de aceite verificável

Essa é a parte que quase ninguém escreve, e é a que evita discussão

Critério de aceite não é "funcionar bem": é uma condição que dá pra checar

Critério de aceite:
- o comando de teste do projeto passa sem falha nova
- existe um teste cobrindo o caso do pedido sem itens
- nenhum arquivo fora da pasta do módulo foi alterado
- o retorno em caso de erro é 422 com mensagem, nunca 500

O erro comum deste passo: definir aceite por sensação em vez de por comando que você mesmo consegue rodar

5. Separe as partes do prompt com tags XML

A doc da Anthropic recomenda usar tags XML pra separar instrução, exemplo e contexto, evitando que o modelo misture tudo

A recomendação inclui manter nomes de tag consistentes e aninhar quando houver hierarquia, com tags como <instructions>, <example> e <formatting>

<contexto>
API em TypeScript, testes na suíte que já existe no repositório
O endpoint de pedidos responde 500 quando o pedido chega sem itens
</contexto>

<instructions>
Corrija a causa raiz, sem alterar a assinatura pública do handler
Adicione um teste para o caso do pedido vazio
</instructions>

<formatting>
Uma frase com a causa raiz, depois o diff dos arquivos alterados
</formatting>

Se você conhece HTML, é a mesma sensação: a tag não é enfeite, ela delimita o que é o quê

O erro comum deste passo: trocar o nome das tags no meio do caminho (<instructions> numa hora, <regras> na outra) e perder a consistência que faz a separação funcionar

6. Dê exemplos do padrão que você quer

A doc chama isso de multishot: exemplos reduzem má interpretação e uniformizam a estrutura da resposta

A régua é simples: o exemplo tem que refletir o comportamento desejado e minimizar o indesejado

Em código, o exemplo mais barato do mundo é colar um trecho do próprio repositório que já está no padrão

<example>
Aqui está um handler já no padrão do projeto, use exatamente esse estilo
de tratamento de erro e de nomeação:

{cole aqui uma função real do seu repositório}
</example>

O erro comum deste passo: dar exemplo de outro projeto ou de tutorial da internet, e ensinar o modelo a fugir do seu padrão

Aliás, essa lógica não é exclusiva de um modelo: é a mesma régua que aparece quando você monta prompts para o Gemini ou pede algo pra qualquer outro assistente

7. Aplique o teste do colega antes de enviar

A doc da Anthropic sugere mostrar o prompt pra alguém sem contexto: se a pessoa ficaria confusa, o modelo também fica

Lê o seu prompt e pergunta: um dev que entrou no time ontem conseguiria fazer essa tarefa só com isso?

Se a resposta for não, falta contexto, e não falta "prompt mágico"

O erro comum deste passo: achar que informação óbvia pra você é óbvia pro modelo

Onde cada ferramenta guarda as instruções do projeto

Depois de escrever um prompt bom, vem a pergunta natural: preciso repetir isso toda vez?

Não

Cada ferramenta tem um lugar próprio pra instrução persistente do projeto

E aqui vai o aviso duro: detalhe de uma ferramenta NÃO vale pra outra, cada uma lê o arquivo dela do jeito dela

Detalhes que valem ouro na hora de configurar

No Claude Code, o CLAUDE.md é lido no início de cada sessão, então é ali que moram comandos de build, convenções, layout do projeto e as regras do tipo "sempre faça X"

No Cursor, arquivo .md simples largado na pasta de regras é ignorado: tem que ser .mdc

E a ordem de aplicação lá é Team Rules, depois Project Rules, depois User Rules, com AGENTS.md na raiz como alternativa pros casos simples

No Copilot, dá pra CONFERIR se as instruções entraram mesmo: o arquivo .github/copilot-instructions.md aparece na lista de References da resposta no Chat

Esse tipo de conferência é mais útil do que parece, porque instrução que você acha que está valendo e não está é a pior das duas situações

Como transformar o prompt bom em contexto permanente do repositório

Se você digita o mesmo parágrafo de contexto toda santa sessão, esse parágrafo não é prompt: é documentação do projeto no lugar errado

Bora mover isso pro disco

1. Gere o guia do projeto

No Claude Code, o comando /init gera o CLAUDE.md

A partir dali você tem um ponto de partida pra editar, em vez de encarar arquivo em branco

O erro comum deste passo: aceitar o gerado sem revisar, e ficar com um guia que descreve o projeto pela metade

2. Coloque no arquivo o que se repete

Comandos de build, convenções de código, layout do projeto e as regras "sempre faça X" são exatamente o material desse arquivo

O teste é bom: se você explicaria aquilo pra qualquer pessoa nova no repositório, é contexto permanente

O erro comum deste passo: despejar decisão de uma tarefa específica ali dentro, e o arquivo virar diário de bordo

3. Enxugue, de verdade

A doc do Claude Code recomenda mirar menos de 200 linhas por arquivo, porque arquivo longo consome mais contexto e reduz a aderência às instruções

Parece contraintuitivo, né? Mas é isso: instrução demais concorre com instrução

O erro comum deste passo: achar que quanto mais regra escrita, mais obediência

4. Quebre em regras por caminho

Pra instrução que só faz sentido em parte do repositório, dá pra organizar vários arquivos no diretório .claude/rules, com escopo por caminho pelo campo paths no frontmatter

Assim a regra de front não carrega quando você está mexendo em migration

O erro comum deste passo: empilhar tudo no arquivo principal e pagar o custo de contexto em toda sessão, mesmo quando aquilo não tem nada a ver com a tarefa

5. Revise antes de escrever no disco

O plan mode do Claude Code deixa o modelo ler arquivos e propor um plano SEM editar nada até você aprovar

O atalho Shift+Tab cicla entre default, acceptEdits e plan

É o equivalente a ler o PR antes do merge, e economiza os rollbacks da vida

O erro comum deste passo: deixar o agente escrever direto numa tarefa que você ainda nem entendeu

6. Considere um formato aberto ou uma especificação antes do código

O AGENTS.md é um formato aberto em markdown, na raiz do repositório, que diz ao agente como buildar, testar e contribuir no projeto

A especificação foi doada para a Agentic AI Foundation, da Linux Foundation, em dezembro de 2025

Já quem quer ir pro caminho de especificação antes do código pode olhar o Spec Kit, toolkit open source da GitHub pra desenvolvimento guiado por especificação

A CLI é distribuída como specify-cli no PyPI, começa com specify init e o fluxo é Spec, Plan, Tasks, Implement

O erro comum deste passo: adotar processo de especificação numa tarefa de dez minutos, e criar burocracia onde não precisava

7. Use as ferramentas de prompt no lugar certo

A Anthropic tem prompt generator e prompt improver, e eles ficam no Claude Console (console.anthropic.com), não dentro do Claude Code

Detalhe pequeno, mas é o tipo de coisa que faz gente procurar menu que não existe

O erro comum deste passo: confundir recurso de um produto com o do outro

Modelos de prompt para as tarefas de código mais comuns

Bora ver na prática? Todos os modelos abaixo carregam as mesmas cinco partes: contexto, restrição, formato, exemplo e critério de aceite

Substitua o que está entre chaves pelo que existe no SEU projeto

Corrigir bug em código existente

<contexto>
Projeto: {stack e versões que o repositório usa}
Arquivo alvo: {caminho do arquivo}
Sintoma: {o que acontece hoje} quando {condição}
Esperado: {o que deveria acontecer}
Motivo: {impacto real desse bug em quem usa}
</contexto>

<instructions>
Encontre a causa raiz antes de propor qualquer alteração
Não altere a assinatura pública nem instale dependência nova
</instructions>

<formatting>
1. causa raiz em uma frase
2. diff dos arquivos alterados
</formatting>

Critério de aceite: {comando de teste do projeto} passa e existe teste cobrindo {condição}

Refatorar sem mudar comportamento

Refatore {arquivo ou função} para {objetivo: legibilidade, remover duplicação, extrair camada}

Restrição dura: comportamento observável não pode mudar, nada de renomear API pública
Proibido: mudar dependência, mover arquivo, alterar formato de retorno

Formato: diff, mais uma lista curta do que mudou e por quê

Critério de aceite: os testes existentes passam SEM nenhuma alteração nos testes

Esse último critério é o pulo do gato da refatoração: se o teste precisou mudar, não foi refatoração

Criar feature nova em base legada

<contexto>
Base antiga, padrão do módulo está no arquivo de exemplo abaixo
A feature precisa conviver com o código atual, sem reescrita
</contexto>

<example>
{cole aqui uma função real do repositório que já está no padrão desejado}
</example>

<instructions>
Implemente {a feature} seguindo EXATAMENTE o estilo do exemplo
Não introduza padrão novo de arquitetura nesta tarefa
</instructions>

Critério de aceite: {comando de build ou teste} passa e nenhum arquivo fora de {pasta do módulo} foi tocado

Escrever teste

Escreva testes para {função ou arquivo} usando {a ferramenta de teste que já está no projeto}

Cubra: caminho feliz, {caso de borda 1}, {caso de borda 2} e o caminho de erro
Proibido: alterar o código de produção para facilitar o teste

Formato: apenas o arquivo de teste, no caminho onde os testes já moram neste repositório

Critério de aceite: os testes falham se eu reverter a correção de {comportamento corrigido}, ou seja, o teste tem que ser sensível ao bug

Revisar código gerado

Revise o diff abaixo como se fosse code review de um PR

Procure, nesta ordem: comportamento diferente do descrito, caso de borda não tratado,
dependência nova escondida, e desvio da convenção do projeto

Formato: lista de achados, cada um com arquivo, linha e severidade
Não reescreva o código, só aponte

{cole o diff aqui}

Esse último é o mais subestimado da lista, e é justamente o que ataca os 45% de tempo extra depurando

A mesma disciplina de pedido detalhado aparece em qualquer chat, inclusive nos pedidos bem escritos pro Grok, porque o problema nunca foi o botão, é o briefing

E tem um limite honesto aqui

O relatório DORA 2025, com quase 5.000 respondentes e 90% dos profissionais de tecnologia usando IA, conclui que a IA AMPLIFICA o sistema que já existe

O maior retorno vem do sistema organizacional (plataforma, clareza de fluxo), não da ferramenta em si

Traduzindo pro seu dia: prompt bom não conserta repositório sem convenção… ele só acelera o que já estava lá, pro bem e pro mal

Conclusão

A adoção é enorme e a confiança não acompanha

Na pesquisa do Stack Overflow 2025, 84% dos desenvolvedores usam ou planejam usar ferramentas de IA no fluxo de trabalho, mas 46% desconfiam da precisão contra 33% que confiam, e só 3% dizem confiar muito

E tem o dado que mais dói: num estudo randomizado da METR, com 16 devs experientes e 246 tarefas em repositórios que eles já conheciam, a medição apontou 19% MAIS LENTOS com IA, enquanto os mesmos participantes estimaram ter ficado 20% mais rápidos

Justiça seja feita: a própria METR classifica hoje esse resultado como histórico, ou seja, não necessariamente um retrato das ferramentas e fluxos atuais

Mesmo assim, a lição que sobra é atemporal: sensação de velocidade não é medição

Por isso critério de aceite e revisão continuam sendo SEUS, não do modelo

O próximo passo é bem concreto: pega a próxima tarefa da sua fila, escreve o prompt com as cinco partes (contexto, restrição, formato, exemplo e critério de aceite) e, o que se repetir na segunda vez, move pro arquivo de instruções do projeto

É menos glamouroso que prompt mágico, e funciona muito mais 😀

até o próximo post!