Prompt Engineering para desenvolvedores: como escrever instruções claras para IA

Um pedido como “crie uma tela de login” deixa várias decisões em aberto: qual framework usar, como funciona a autenticação, quais erros exibir e o que significa concluir a tarefa. Um assistente de programação pode preencher essas lacunas com escolhas razoáveis que ainda assim não servem ao seu projeto.

Prompt Engineering é a prática de escrever e aperfeiçoar instruções para deixar mais clara a tarefa desejada. Isso aumenta a chance de obter um resultado útil; não torna o código gerado determinístico nem correto por construção.

Este é o primeiro de seis artigos sobre agentes de programação: assistentes que podem inspecionar arquivos, usar ferramentas e propor ou fazer alterações no código. A série começa com a escrita de prompts e depois percorre temas conectados: instruções, roteamento de modelos, contexto, ferramentas, especificações e feedback. O exemplo recorrente ao longo da série é adicionar um desconto na finalização de uma compra (checkout).

Quatro elementos de um prompt de programação útil

1. Objetivo e escopo

Descreva o comportamento desejado e os limites da alteração. “Corrija o envio duplicado do formulário de checkout” é mais fácil de avaliar do que “melhore o checkout”. Para uma funcionalidade maior, peça ao agente que inspecione o repositório e divida o trabalho em etapas que possam ser revisadas.

Um papel como “revisor de backend” pode esclarecer a perspectiva, mas não substitui os requisitos nem dá ao modelo uma especialização que ele não tem.

2. Contexto relevante

Aponte a implementação, uma funcionalidade semelhante e o contrato relevante. Ao relatar uma falha, inclua a mensagem de erro exata e o comando que a produziu.

Um agente com ferramentas para acessar o repositório pode buscar os arquivos por conta própria. Uma interface de chat sem essas ferramentas precisa receber os trechos relevantes. Não se deve esperar que nenhum dos dois conheça detalhes privados do projeto que não foram disponibilizados.

3. Restrições e comportamento esperado

Liste as restrições que afetam a solução: ambiente de execução compatível, dependências permitidas, interfaces públicas e requisitos de compatibilidade. Prefira comportamentos que possam ser verificados a adjetivos vagos como “robusto” ou “seguro”.

Por exemplo, “devolva o mesmo resultado quando o mesmo ID de requisição for enviado novamente” dá ao agente uma regra concreta para implementar e testar. Evite prescrever um algoritmo antes de confirmar que ele atende aos dados e requisitos.

4. Critérios de aceitação e formato de entrega

Os critérios de aceitação descrevem o que precisa funcionar. O formato de entrega descreve como apresentar o resultado. São aspectos diferentes.

Peça ao agente para executar as verificações relevantes e informar o que realmente executou, eventuais falhas e as suposições restantes. Em um fluxo de trabalho baseado apenas em chat, peça a implementação e os testes, mas considere que talvez o modelo não consiga executá-los.

Exemplo: torne explícita uma política de validação

Considere este pedido:

Escreva uma função que valide endereços de e-mail em TypeScript.

Ele não especifica o tipo da entrada, a política para espaços em branco nem os formatos de endereço aceitos. Pedir uma “regex totalmente compatível com o padrão” ainda esconde uma decisão complexa de política em um detalhe de implementação.

Para uma aplicação que aceita deliberadamente um formato limitado, um prompt mais útil seria:

Tarefa: Adicione isValidEmail(input: unknown): boolean como uma exportação nomeada.

Contexto:
- Inspecione os utilitários existentes e a configuração de testes antes de editar.
- Reutilize a configuração de TypeScript e o test runner do projeto.

Política do produto:
- Retorne false para entradas que não sejam strings.
- Rejeite strings vazias e qualquer espaço em branco; não remova espaços da entrada.
- Aceite apenas letras ASCII, dígitos, pontos, sublinhados, sinais de mais
  e hífens na parte local.
- Rejeite uma parte local que comece ou termine com ponto ou tenha pontos consecutivos.
- Exija exatamente um @ e pelo menos dois rótulos de domínio não vazios.
- Os rótulos do domínio podem conter letras ASCII, dígitos e hífens,
  mas não podem começar nem terminar com hífen.
- Rejeite todos os outros caracteres. Não faça requisições de rede.

Exemplos de aceitação:
- true: alex@example.com, alex+shop@sub.example.com
- false: null, 42, "", " alex@example.com", alex..lee@example.com,
  alex@localhost, alex@-example.com

Entrega:
- Implemente a política e adicione testes para os limites.
- Execute os testes relevantes se houver ferramentas de execução disponíveis.
- Informe os arquivos alterados, os comandos e resultados, e as suposições não resolvidas.

Esta é uma política de produto ilustrativa, não uma afirmação de conformidade integral com o padrão de e-mail ou de propriedade da caixa postal. Um fluxo real de cadastro deve escolher deliberadamente os formatos aceitos e verificar a propriedade do endereço separadamente. A melhoria é que agora um revisor pode comparar a implementação com decisões explícitas.

Erros comuns

• Instruções conflitantes: “Retorne apenas código” entra em conflito com “explique as concessões”. Decida qual resultado você precisa.
• Trabalho não relacionado em excesso: uma tarefa ampla pode exigir plano e pontos de revisão. Divida-a onde o comportamento puder ser avaliado de forma independente.
• Falta de exemplos: casos de limite muitas vezes comunicam melhor a intenção do que mais um parágrafo de adjetivos.
• Tratar a primeira resposta como verificada: revise o diff e execute as verificações. Uma explicação convincente não é evidência de execução.

Um prompt como “use Clean Architecture, CQRS e event sourcing” escolhe uma solução antes de explicar o problema. A menos que essas escolhas sejam requisitos definidos, peça ao agente para comparar alternativas com restrições concretas e mudanças futuras. O artigo sobre Spec-Driven Development aborda o custo de manutenção de arquiteturas fáceis de gerar.

Qual idioma devo usar?

Use o idioma em que você consegue explicar o objetivo, as restrições e os detalhes com clareza. Não é necessário traduzir primeiro o que você pensa para o inglês. Em trabalhos no Brasil, peça português brasileiro (pt-BR) e especifique o público-alvo e o grau de formalidade quando isso for importante. Um prompt de programação pode usar texto em português e manter código, identificadores, campos de API, mensagens de erro e documentação original exatamente como estão.

Os resultados podem variar conforme o idioma, o modelo e a tarefa. Em um teste de conhecimento da OpenAI de 2025, feito sem exemplos prévios no prompt, o modelo o1 acertou 92,3% das questões originais em inglês e 89,5% das questões traduzidas profissionalmente para o português brasileiro. A diferença de 2,8 pontos percentuais vale para esse teste de múltipla escolha. Ela não mede apenas o efeito do idioma da instrução, nem avalia conversas naturais ou tarefas de programação.

Para uma tarefa importante ou repetida, compare prompts equivalentes em inglês e português brasileiro com o mesmo modelo, contexto, ferramentas e critérios de avaliação. Verifique se a resposta está correta e se soa natural para o público brasileiro. Use o idioma que funciona para a sua tarefa e especifique claramente o idioma da resposta. O artigo sobre Context Engineering discute os limites das estimativas públicas de proporção por idioma e o custo dos tokens.

Revise um prompt com base em uma falha observada

Para o exemplo contínuo, comece com “Adicione suporte a códigos de desconto no checkout”. Suponha que uma implementação experimental calcule descontos no navegador e persista o total original. Essa é uma falha hipotética a ser investigada, não um resultado medido de um modelo. Usar palavras mais enfáticas deixaria sem resposta a mesma decisão sobre responsabilidade.

Depois de confirmar o comportamento desejado com a pessoa responsável pelo produto e consultar o contrato de pricing existente, revise o pedido:

Tarefa: Adicione um código de desconto opcional ao checkout.
Contexto: Localize o contrato de pricing atual e rastreie o fluxo da cotação
entre web, orders e pricing. Registre as revisões usadas.
Comportamento:
- Pricing é responsável pela elegibilidade e pelo cálculo; web exibe sua cotação.
- Orders persiste a cotação aceita em vez de recalcular o desconto.
- Sem código, o comportamento atual do checkout permanece.
- Um código inválido ou expirado exibe o erro acordado e não pode criar
  um pedido com total com desconto.
Verificação:
- Derive testes de limite destas regras e do contrato de pricing.
- Verifique a exibição da cotação e os totais persistidos pelo checkout.
- Informe as verificações realmente executadas, os limites não cobertos e as decisões pendentes.

A revisão corrige a lacuna de responsabilidade observada. Também deixa os detalhes de arredondamento e elegibilidade sob responsabilidade do contrato autoritativo. Se esse contrato estiver ausente ou for contraditório, resolva a decisão antes de pedir ao agente que implemente uma suposição. Uma falha de comando causada por dependências ausentes exige um ajuste no harness, não mais uma instrução sobre pricing.

Reutilize um exemplo funcional e um registro de decisões

Em Patterns for Reducing Friction in AI-Assisted Development, Rahul Garg propõe apresentar exemplos do projeto ao assistente durante a integração e preservar decisões entre sessões. Ele apresenta os benefícios esperados como hipóteses, não como ganhos de produtividade medidos.

Para o checkout, acrescente ao prompt uma pequena etapa de orientação:

Encontre uma alteração existente no checkout que siga as convenções atuais.
Identifique pelo caminho o trecho que recebe a requisição, o cliente de pricing e os dados de teste relevantes.
Explique quais partes se aplicam aos descontos e onde o comportamento é diferente.
Antes de implementar, sinalize qualquer conflito com o contrato de pricing atual.
Mantenha as decisões confirmadas e as perguntas em aberto no registro de alterações da funcionalidade.

Uma implementação de referência só é útil depois de confirmar que ainda corresponde ao contrato. Registre convenções reutilizáveis nas instruções do projeto; mantenha a política de desconto e as anotações temporárias de investigação junto à funcionalidade. Ao retomar o trabalho, confira os caminhos e as revisões registrados no checkout em vez de tratar o resumo de uma sessão anterior como evidência atual.

Aprimore prompts com evidências

Versione os prompts, mantenha consistentes os dados e as métricas de avaliação e avalie as mudanças no sistema inteiro. Para saber mais sobre iteração de prompts e avaliação, consulte os capítulos 5, “Prompt Engineering”, e 3, “Evaluation Methodology”, de Chip Huyen em AI Engineering. Aplique essa abordagem ao exemplo de checkout neste exercício:

1. Prepare casos de teste para um código válido, um código expirado, a ausência de código e uma divergência entre o total exibido e o valor salvo. Registre os commits iniciais e as verificações de aceitação independentes.
2. Use alguns casos para revisar o prompt A e criar o prompt B. Reserve outros casos até a avaliação; os dois prompts devem receber os mesmos requisitos de produto quando forem testados.
3. Execute A e B em cópias limpas das mesmas revisões iniciais, com o mesmo modelo, ferramentas, permissões e limite de tempo. Altere somente o prompt. Se não for possível fixar o roteamento, registre os modelos realmente selecionados e considere isso um possível fator de confusão.
4. Quando viável, repita cada tarefa para cada versão, alternando a ordem de execução. Informe a quantidade de tarefas e execuções; uma única tentativa bem-sucedida não demonstra confiabilidade.
5. Avalie as duas versões com as mesmas verificações de aceitação e os mesmos critérios de revisão. Inclua execuções que falharam ou excederam o tempo limite, não apenas alterações entregues.

Registre uma linha por execução. Este é um modelo em branco, não dados de benchmark:

Tarefa / commits iniciais	Versões do prompt / modelo / harness	Casos de aceitação aprovados / exigidos	Regressões	Tentativas de correção	Minutos de revisão	Segundos decorridos	Custo total cobrado
Preencha com o registro da execução	Preencha com configuração e log da execução	Preencha com verificações independentes	Preencha com testes de regressão	Preencha com o log da execução	Registre o tempo de revisão	Meça o tempo decorrido	Inclua tentativas com falha

Analise os resultados por tipo de tarefa antes de combiná-los: um desempenho melhor com códigos válidos pode esconder piora nos expirados. Mantenha qualidade, esforço de revisão, latência e custo separados. Se uma amostra pequena produzir resultados mistos, relate a incerteza e colete mais evidências em vez de declarar um prompt vencedor.

Para avaliar prompts repetidamente, defina os critérios de revisão e dê uma nota separada para cada um. Uma ferramenta que devolve notas estruturadas, como a primitiva Score do Jev, da TypeSafe, pode avaliar se os requisitos foram atendidos, se as verificações sustentam o resultado e se a mudança é fácil de revisar. Forneça sempre o mesmo resumo da tarefa, critérios de aceitação, alteração no código, resultados reais das verificações e relatório de conclusão. Mantenha fixos a versão da ferramenta e os critérios ao comparar prompts. Combine as notas apenas quando os pesos forem claros, seguindo o padrão de pontuação composta. Uma média alta não substitui um caso de aceitação que falhou nem a revisão humana.

O protocolo de Loop Engineering amplia este exercício para mudanças nas ferramentas e no ambiente de execução.

Instruções claras dão direção à tarefa. Em seguida, AI Gateways e roteamento de modelos explicam como a infraestrutura seleciona modelos elegíveis e aplica políticas configuradas. Depois, Context Engineering acompanha a funcionalidade de checkout em seus arquivos-fonte e contratos.