Neste artigo
Debugar código gerado por IA é diferente de debugar código seu por um motivo: você não tem a memória de por que aquilo foi escrito assim. O método que funciona é diagnosticar a causa raiz na mão antes de pedir qualquer correção, porque pedir “conserta esse erro” faz o agente remendar o sintoma e deixar a causa viva.
Que ciclo parece produtivo e não é?
Todo mundo já fez isso: cola o stack trace no chat, o agente propõe uma mudança, o erro some, aparece outro. Cola de novo, muda de novo, some de novo. Três horas depois o código tem cinco remendos, ninguém entende mais o fluxo, e o bug original volta em outro formato.
Isso acontece porque o agente está otimizando para fazer o erro sumir, não para entender o sistema. Com contexto parcial, o caminho mais curto até o erro sumir quase sempre é um try/catch, um valor padrão ou uma checagem defensiva no lugar errado.
Por que diagnosticar antes de pedir?
A inversão que muda tudo: chegar no agente com a causa já identificada, e pedir a correção específica.
Compare os dois pedidos.
RUIM:
"Ta dando TypeError: cannot read property 'id' of undefined
na linha 42, arruma"
BOM:
"O findById devolve null quando o registro e de outro tenant,
porque o filtro de tenant entra na query. O controller assume
que sempre vem objeto. Quero 404 explicito nesse caso, nao
optional chaining."O segundo pedido produz a correção certa de primeira, porque a decisão já foi tomada por quem tem contexto.
Quais são os quatro passos?
1. Reproduzir com o menor caso possível. Antes de olhar código, achar a entrada mínima que dispara o erro. Metade dos bugs se explica sozinha aqui.
2. Descobrir onde o dado fica errado. Não onde o erro estoura, onde o valor deixou de ser o esperado. Costumam ser lugares diferentes, e o agente sempre olha o primeiro.
3. Perguntar por que aquilo foi escrito assim. Aqui o agente ajuda de verdade. Pedir para ele explicar a intenção do trecho, sem alterar nada, é a melhor pergunta que existe pra código que não é seu.
4. Só então pedir a correção, dizendo qual comportamento você quer.
Que prompt vale mais que dez tentativas?
Nao altere nada ainda.
Explique:
1. o que este trecho faz, passo a passo
2. quais suposicoes ele faz sobre a entrada
3. em quais casos essas suposicoes sao falsas
Depois espera minha resposta.O “não altere nada ainda” é o que faz funcionar. Sem isso, ele explica e já muda, e você perde o estado que estava investigando.
Onde o código de agente costuma quebrar?
| Padrão | Como aparece | Causa de fundo |
|---|---|---|
| Assume que sempre vem valor | undefined em produção |
Testou só o caminho feliz |
Engole erro em catch vazio |
Falha silenciosa, dado sumindo | Fez o teste passar |
| Race em operação assíncrona | Funciona local, quebra sob carga | Sem concorrência no ambiente de teste |
| Fuso e data | Um dia de diferença no relatório | Misturou local com UTC |
| Float pra dinheiro | Centavos somem na conciliação | Ninguém disse pra usar inteiro |
| Paginação esquecida | Lento com dado real | Seed tinha três registros |
Quando eu bato num desses, já sei que a correção real é na spec, não no arquivo. Senão volta no próximo módulo.
Quando parar de insistir com o agente?
Se o agente errou a mesma correção duas vezes, eu paro de pedir. Duas falhas seguidas quase sempre significam que ele não tem uma informação que eu tenho e não escrevi: uma regra de negócio, uma restrição de infra, um comportamento de biblioteca.
Insistir na terceira tentativa é como repetir mais alto para alguém que não fala a língua. Melhor escrever a informação que falta e recomeçar.
Que log serve para depurar depois?
O agente gera log genérico, do tipo “erro ao processar”. Isso não serve pra nada às duas da manhã. O que serve tem identificador do tenant, identificador do recurso, e a operação que estava em curso, sem dado pessoal dentro.
Vale pedir explicitamente, porque não sai por padrão. Sobre enxergar o que aconteceu depois que subiu, escrevi em observabilidade de agentes de IA em produção.
Perguntas frequentes
Vale pedir pro outro agente revisar?
Vale, mas com a ressalva de sempre: se os dois concordarem, isso não é prova, porque erram junto. O que prova é teste executado que reproduz o defeito.
E quando eu não entendo o código o suficiente?
Aí o passo 3 vira o principal. Pedir explicação sem alteração é a forma mais rápida de aprender a base do projeto, e ainda serve de checagem: se a explicação não bate com o que o código faz, achou o bug.
Faz sentido reescrever do zero?
Faz quando o trecho é pequeno e a spec está clara. Não faz quando o trecho carrega regra de negócio acumulada, porque a reescrita perde as decisões que ninguém documentou. Ordem de testes em testes automatizados em projeto tocado por agente.
