Prompts para desenvolvedores: do bug à revisão de código

Você cola um stack trace, escreve “corrija”, e o assistente devolve uma função reescrita que cala o erro. O teste passa, às vezes porque o try/except adicionado engole a exceção. O sintoma sumiu, o bug não.

Um desenvolvedor não precisa que lhe expliquem o que é um prompt. Precisa, sobretudo, de reflexos para impedir que a IA corra para a primeira solução plausível. Os modelos abaixo forçam essa desaceleração e funcionam tanto num chat quanto num assistente de código.

Depurar: separar o diagnóstico da correção

A instrução mais rentável cabe em uma linha: nenhum código antes do diagnóstico. Ela evita validar uma correção baseada numa causa presumida.

Bug em [LINGUAGEM/FRAMEWORK, VERSÃO SE FOR RELEVANTE].

Comportamento esperado: [O QUE DEVERIA ACONTECER]
Comportamento observado: [O QUE ACONTECE]
Reprodução: [PASSOS OU TESTE]
Erro completo:
[STACK TRACE]

Código envolvido:
[TRECHOS]

O que já tentei ou descartei: [LISTA]

Ainda não proponha correção.
1. Liste 3 hipóteses ordenadas por probabilidade.
2. Para cada uma, indique a observação do código ou do trace que a sustenta.
3. Indique a verificação mais rápida para confirmá-la ou excluí-la (log preciso, consulta, teste mínimo).

Vou executar essas verificações e passar os resultados a você. Se faltar um arquivo para raciocinar, peça-o em vez de supor o conteúdo.

Pense num desenvolvedor Rails diante de uma fatura criada em duplicidade: aqui, as hipóteses têm boa chance de apontar para um duplo envio do formulário, um webhook reenviado ou um job relançado, e cada uma se verifica em poucos minutos nos logs. Essa divisão em dois tempos retoma o princípio do raciocínio passo a passo, com um humano a mais fornecendo os fatos entre as duas etapas.

Revisar um diff, não um arquivo inteiro

Uma revisão pedida sem direcionamento devolve sobretudo observações de estilo. Forneça o diff, diga o que a mudança deve fazer e especifique o que interessa a você.

git diff main...HEAD > diff.txt

Você está revisando este pull request.

Objetivo da mudança: [TICKET OU DESCRIÇÃO]
Contexto: [STACK, CONVENÇÕES, RESTRIÇÕES DE DESEMPENHO]
Diff:
[COLE O DIFF]

Procure nesta ordem:
1. Bugs: casos-limite, erros não tratados, concorrência, valores nulos.
2. Segurança: injeção, controle de acesso, dados sensíveis nos logs.
3. Desvios em relação ao objetivo: o que falta e o que ultrapassa o escopo.

Para cada problema, indique o arquivo e a linha do diff, o cenário concreto que o dispara e a gravidade (bloqueante, a corrigir, menor). Ignore formatação e nomenclatura, o linter cuida disso. Se o diff lhe parecer correto em algum eixo, diga isso simplesmente em vez de inventar um problema.

A última frase importa. Sem ela, um modelo a quem se pedem problemas tende a encontrá-los a qualquer custo, inclusive em código saudável.

Proteger código legado antes de mexer nele

Você precisa modificar uma função de 300 linhas sem testes, escrita por alguém que saiu da empresa. Pedir “refatore” equivale a perder os comportamentos não documentados. A sequência certa começa por testes de caracterização, que congelam o que o código faz hoje, bugs incluídos.

Esta é uma função sem testes, em produção:
[CÓDIGO]

Framework de teste: [PYTEST, JEST, PHPUNIT...]

Antes de qualquer refatoração:
1. Descreva o comportamento real deste código, caso a caso, inclusive os comportamentos que lhe parecerem bugs.
2. Escreva testes de caracterização que documentem esse comportamento atual, sem corrigi-lo. Marque com um comentário os casos que parecem bugs.
3. Liste as dependências a simular (banco, relógio, API) e as áreas que você não consegue cobrir sem alterar o código.

Não modifique a função. A refatoração virá num segundo momento, em pequenas etapas, com os testes verdes entre cada uma.

Execute esses testes no código atual antes de ir adiante. Se falharem no código atual, foi o modelo que errou sobre o comportamento, e essas diferenças são justamente o que você queria descobrir. Depois divida a refatoração em uma cadeia de prompts: uma extração por mensagem, um commit por etapa.

Escrever testes que atacam o código

Quando se pedem testes depois de mostrar uma implementação, a IA muitas vezes escreve testes que descrevem essa implementação. Eles passam e não provam grande coisa. Oriente-a para a especificação e para os pontos de ruptura.

Especificação da função: [REGRAS DE NEGÓCIO]
Assinatura: [ASSINATURA]
Exemplo real de entrada e saída: [EXEMPLO]

Escreva os testes a partir da especificação, sem tentar refletir uma implementação.
Cubra os limites, as entradas inválidas, as duplicidades, os fusos horários e os arredondamentos, se for o caso.
Para cada teste, indique em uma linha que bug realista ele pegaria.
Descarte os testes que só poderiam falhar se a própria linguagem estivesse quebrada.

Para um aplicativo de reserva de restaurante, esse prompt tem boas chances de fazer aparecer o horário que atravessa a mudança do horário de verão, o tipo de caso que muitas vezes se esquece.

Migração SQL: fazer procurar o que pode dar errado

Uma migração funciona no ambiente local e trava a tabela em produção. A IA é uma boa revisora pessimista, desde que conheça o volume e o motor.

Motor e versão: [POSTGRESQL, MYSQL...]
Tamanho das tabelas envolvidas: [LINHAS]
Tráfego: [LEITURAS/ESCRITAS, JANELA DE MANUTENÇÃO]
Migração:
[SQL]
Código da aplicação que lê essas colunas: [TRECHOS]

Analise:
1. Os bloqueios (locks) tomados por cada instrução e seu efeito provável nesse volume.
2. A compatibilidade durante o deploy, quando o código antigo e o novo rodam juntos.
3. O plano de rollback e o que não pode ser desfeito.
4. Uma versão em várias etapas, se necessário.

Se algum comportamento depender da versão do motor, diga isso e indique o que devo verificar na documentação.

Três precauções antes de confiar no código gerado

Verifique se o que foi citado existe. Um modelo pode inventar um método, uma opção ou um pacote. O risco é real em segurança: o nome de um pacote inventado pode ser registrado por um terceiro mal-intencionado. Antes de instalar, olhe o registro, o autor e a atividade do projeto:

npm view [pacote]
pip index versions [pacote]

Não cole o que você não pode compartilhar. Chaves de API, strings de conexão, dados de clientes e código sob acordo de confidencialidade não têm nada a fazer numa ferramenta não aprovada pela sua empresa. Veja os termos do seu plano, pois variam de um produto para outro, e passe um scanner de segredos no que você envia.

Mantenha a responsabilidade da revisão. O código gerado se revisa como o de um colega, com a questão das licenças a mais se for um produto comercial. Se você trabalha com um agente que executa comandos por conta própria, as instruções dele merecem tanto cuidado quanto o seu código: tudo está no nosso guia de instruções para agentes.

Abra o seu último ticket de bug resolvido, passe-o de novo ao seu assistente com o primeiro prompt e compare as hipóteses dele com a causa verdadeira. Você logo saberá quanto a sua ferramenta vale na sua base de código.