Como Escrever Prompt Para Gerar Código Que Funciona

Por que o mesmo pedido gera código bom ou lixo

A IA não adivinha o que você não disse. Quando o pedido é vago, ela preenche as lacunas com o padrão mais comum da internet: um exemplo genérico, feito com bibliotecas que talvez você nem use, sem tratamento de erro, sem conexão com o seu banco de dados. Não é burrice do modelo. É falta de informação.

Prompt, aqui, é simplesmente o texto que você escreve pedindo algo para a IA. E um bom prompt técnico não é um pedido bonito nem cheio de palavras mágicas. Ele é um briefing: a mesma coisa que você mandaria para um programador freelancer que nunca viu seu projeto. Se o freelancer conseguiria entregar certo lendo só aquilo, a IA também consegue. Se ele voltaria com cinco perguntas, a IA vai chutar as cinco respostas.

A anatomia: quatro partes que todo prompt técnico precisa ter

Depois de muita tentativa e erro, dá para reduzir um prompt que funciona a quatro blocos. Nenhum deles é opcional se você quer código aproveitável.

1. Contexto: onde esse código vai morar

A IA precisa saber o ambiente. Linguagem, versão, framework (o "esqueleto" pronto que o projeto usa, tipo Laravel, React, WordPress), banco de dados e onde o arquivo vai ficar. Sem isso ela escolhe por você, e a escolha dela costuma ser a mais popular do mundo, não a que está rodando no seu servidor.

• Linguagem e versão: "PHP 7.4" é muito diferente de "PHP 8.3" — funções que existem numa quebram na outra.
• Framework ou "sem framework, PHP puro".
• Banco e nomes de tabelas e colunas relevantes.
• Trechos de código que já existem e vão ser tocados. Colar o arquivo atual vale mais que descrever ele.

2. Objetivo em uma frase

Uma frase só, começando com um verbo, dizendo o que o código faz do ponto de vista de quem usa. "Cadastrar cliente" é objetivo. "Melhorar o sistema" não é. Se você não consegue dizer em uma frase, o pedido está grande demais e precisa ser quebrado em dois ou três.

3. Restrições: o que ela não pode fazer

Essa é a parte que quase todo mundo esquece e é a que mais economiza retrabalho. Restrição é o cercadinho.

• "Não instale bibliotecas novas."
• "Não altere nenhum arquivo além do que eu colei."
• "Use consultas preparadas no banco" (é a forma segura de conversar com o banco, que evita um ataque clássico chamado SQL injection).
• "Não invente nomes de coluna: use exatamente os que estão no schema acima."
• "Mantenha o estilo do código existente."

4. Critério de aceite: como saber que funcionou

Descreva o teste antes de pedir o código. "Quando eu enviar o formulário com e-mail vazio, deve aparecer a mensagem X e nada é gravado no banco." Isso muda o comportamento do modelo: ele passa a escrever para passar naquele cenário, em vez de escrever algo que apenas parece certo. E te dá um jeito objetivo de conferir a entrega sem saber programar.

Antes e depois do mesmo pedido

Veja o mesmo problema real: um formulário de orçamento no site que precisa salvar o contato e avisar o dono por e-mail.

Prompt ruim

"Faz um formulário de contato pro meu site que salva no banco e manda e-mail."

O que volta: um HTML genérico, um script que usa uma função de e-mail que talvez nem esteja habilitada na sua hospedagem, uma tabela chamada contacts que não existe no seu banco, zero validação e nenhuma proteção contra robô de spam. Bonito na tela, quebrado no servidor.

Prompt bom

"Contexto: site em PHP 7.4 sem framework, hospedagem compartilhada, MySQL. Já existe a tabela quotes com as colunas id, nome, email, telefone, mensagem, criado_em. A conexão vem de config/database.php, que devolve um objeto PDO chamado $pdo. O envio de e-mail já está funcionando pela função enviarEmail($para, $assunto, $corpo) em includes/mail.php.
Objetivo: receber o formulário de orçamento, gravar uma linha em quotes e avisar o dono por e-mail.
Restrições: não instale bibliotecas, não crie tabelas, use consultas preparadas com PDO, valide os campos no servidor, e não altere nenhum arquivo além de um novo receber_orcamento.php.
Critério de aceite: (1) e-mail inválido devolve erro e não grava nada; (2) envio válido grava uma linha e dispara um e-mail; (3) se o e-mail falhar, o registro continua salvo e o usuário vê mensagem de sucesso; (4) o código roda em PHP 7.4 sem funções exclusivas do PHP 8.
Formato: me devolva só o arquivo completo, com comentários curtos."

O segundo prompt é mais longo, sim. Mas ele substitui três ou quatro rodadas de "não é isso, tenta de novo". Na prática, escrever leva dois minutos a mais e economiza meia hora.

Tabela de tradução: do pedido vago para o pedido útil

Cinco erros que estragam prompt de código

• Pedir tudo de uma vez. Quanto maior o pedido, maior a chance de a IA inventar peças. Peça uma função por vez e vá encaixando.
• Descrever o arquivo em vez de colar o arquivo. Resumo humano perde detalhe; código colado não.
• Não dizer a versão. É a causa número um de erro fatal em servidor mais antigo.
• Aceitar "funciona" sem testar o caminho torto. Sempre teste campo vazio, valor duplicado e usuário sem permissão.
• Continuar corrigindo no mesmo chat depois de muitas idas e vindas. Quando o histórico vira uma bagunça, a IA passa a se contradizer. Abra uma conversa nova com o código atual colado.

Onde o prompt bom ainda não resolve

Vale ser honesto: prompt bem escrito melhora muito a saída, mas não transforma IA em engenheiro responsável pelo seu negócio. Limitações que continuam existindo em qualquer ferramenta — Codex, Cursor, Copilot, Windsurf, Lovable, Gemini CLI, o que for:

• Ela não conhece o seu servidor. Permissão de pasta, versão real do PHP, firewall e limite de memória só aparecem quando quebra.
• Ela erra em segurança com confiança. Código gerado costuma passar validação superficial e esquecer controle de permissão: qualquer usuário logado consegue ver dados de outro. Isso precisa de revisão humana.
• Ela não decide regra de negócio. Se você não definiu se o desconto é antes ou depois do frete, ela escolhe uma e nunca te avisa.
• Custo cresce com o contexto. Colar arquivos gigantes a cada mensagem consome tokens (as unidades cobradas pelas ferramentas pagas). Cole só o que é relevante.
• Consistência entre arquivos é fraca. Ela acerta o arquivo pedido e esquece que outros três dependiam dele.

Por isso a regra prática: use IA para escrever, e use pessoa para decidir o que entra em produção. Quanto mais dinheiro passa pelo sistema, mais essa segunda parte importa.

Um modelo pronto para copiar

Guarde este esqueleto num bloco de notas e preencha antes de cada pedido:

• Contexto: linguagem + versão, framework, banco, arquivos envolvidos (colados).
• Objetivo: uma frase com verbo.
• Restrições: o que não pode mudar, o que não pode instalar, padrões obrigatórios.
• Critério de aceite: 3 a 5 cenários, incluindo pelo menos um de erro.
• Formato da resposta: arquivo completo ou só o trecho alterado; com ou sem explicação.

Depois de receber o código, faça três perguntas de volta para a própria IA: "quais suposições você fez que eu não te dei?", "o que quebra se o campo vier vazio?" e "que parte disso eu deveria revisar com um desenvolvedor?". As respostas costumam revelar exatamente onde o pedido estava frouxo — e é assim que você melhora o próximo prompt.