Você não pode debugar o que não entende. Por que compreensão é a prática número um com IA

TL;DR

• Compreensão precede tudo: sem ela, o dev é custódia do código gerado por IA, não proprietário do sistema.
• Ler em voz alta é a prática central: obriga a formular afirmação por linha, e a falha na afirmação revela a ignorância.
• Refatorar para entender, não para limpar: a segunda versão é a que vai para produção; é nela que o dev documenta a própria compreensão.
• Pair review valida externamente: a pergunta que importa não é “este código funciona”, é “este código está certo para o nosso contexto”.
• Documentar o porquê, não o quê: código gerado por IA é compilável e executável, mas raramente comunica intenção.

Compreensão é defesa contra falha

A diferença entre um time que opera código gerado por IA e um time que opera código que ele próprio escreveu aparece no incidente. O segundo identifica a região do problema em minutos porque mapeia o código mentalmente. O primeiro procura no escuro até encontrar a função que gera o sintoma, depois passa horas entendendo o que aquela função deveria estar fazendo.

Quando o desenvolvedor compreende o código:

• Detecta anomalia mais rápido, porque sabe o que é esperado em cada caminho
• Sabe onde debugar quando algo quebra, porque o mapa mental aponta o nó
• Consegue otimizar porque entende o gargalo real, não o gargalo aparente
• Consegue explicar decisão para colega, porque a decisão tem autor — ele próprio

Quando o desenvolvedor apenas copia o que a IA devolveu:

• Surpresas em produção, porque o comportamento emergente não foi modelado
• Tempo de debug cresce exponencialmente, porque cada nova leitura do código começa do zero
• Não consegue otimizar, porque otimizar sem modelo é mexer em variáveis aleatórias
• Conhecimento fica preso em uma pessoa — a única que leu — e some quando ela sai

A segunda lista não descreve falha técnica. Descreve falha de processo que se apresenta como técnica.

Leitura de código é habilidade crítica

A prática é simples e quase ninguém faz: quando a IA gera um bloco, o primeiro passo não é commitar. É ler em voz alta. A leitura em voz alta obriga a formular uma afirmação por linha. Onde a afirmação falha — “isso aqui não sei explicar” — está o ponto de ignorância.

Durante a leitura, três perguntas guiam a investigação:

• O que essa variável representa no domínio do problema?
• Por que essa estrutura de controle foi escolhida em vez da alternativa óbvia?
• Qual é o invariante que esse loop mantém — e o que acontece se a entrada violar o invariante?
• Qual é o contrato da função: pré-condição, pós-condição, exceções previstas?

Se o desenvolvedor não responde nenhuma das quatro para uma linha específica, o código não está pronto para ser integrado. Estude o código até conseguir responder. Releia. Pesquise a função de biblioteca desconhecida. Desenhe o fluxo em guardanapo. Faça o que for preciso, mas não integre o que não se consegue explicar.

A voz alta importa mais do que parece. Ler mentalmente permite pular trechos; ler em voz alta obriga a processar cada token. É o equivalente a fazer TDD antes de escrever o código de produção: força o reconhecimento explícito do que está sendo assumido.

Refatoração é aprofundamento de compreensão

Refatorar com IA não é exercício estético de “ficar mais limpo”. É o mecanismo pelo qual o desenvolvedor documenta, dentro do próprio código, a sua compreensão do que ele faz.

A prática recomendada: depois que a IA entrega uma solução, o próximo passo é refatorar pelo menos uma vez. Não com o objetivo de “melhorar”. Com o objetivo de entender. Ao refatorar, o desenvolvedor descobre o que a sugestão original escondia:

• Casos extremos que a sugestão original não tratava, porque o prompt não os mencionava
• Código morto ou redundante, sintoma de que a IA alucinou estrutura sem necessidade
• Simplificações possíveis sem perder funcionalidade, sintoma de que a versão original era verbosa por default do modelo
• Comentários sobre o porquê, deixados pela refatoração, que cristalizam a compreensão para a próxima pessoa que abrir o arquivo

A primeira versão é da IA. A segunda versão é do desenvolvedor. A segunda é a que vai para produção.

Pair review como validação externa

A crença “parece certo” é uma das mais perigosas em engenharia de software. Com código escrito à mão, a crença passa pelo crivo do autor que tem contexto. Com código gerado por IA, “parece certo” é a única validação que existe — até que outra pessoa leia.

A prática: quando código gerado por IA entra no sistema, o primeiro review não é o automático do CI. É conversa com um colega que questiona “por que a IA fez assim?”. O colega não é um segundo par de olhos; é um segundo par de perguntas. A pergunta que importa não é “este código funciona”, é “este código está certo para o nosso contexto”.

Se o desenvolvedor consegue explicar a decisão para o colega — e defender as alternativas descartadas — a compreensão existe. Se a explicação depende de “a IA sugeriu” ou “pareceu razoável”, a compreensão não existe. O código pode estar correto mesmo assim, mas a equipe não tem como evoluí-lo com segurança.

Documentar a explicação no pull request — em texto, não em conversa de chat — é o que transforma pair review em propriedade compartilhada.

Documentação é cristalização de compreensão

A postura “código é auto-explicativo” funciona em sistemas pequenos, escritos por uma pessoa, mantidos por anos pela mesma pessoa. Em sistemas que recebem contribuição de IA, a afirmação é falsa. A IA gera código que compila e que executa, mas não gera código que comunica intenção.

A prática: escrever comentário que explique não o quê — o código já mostra o quê — mas o porquê. O porquê é o que falta. O porquê é o que custa a recuperar seis meses depois, quando ninguém lembra.

Exemplo típico:

“`javascript // Ruim: valida email com regex const isValid = /^[…]+$/.test(email) “`

“`javascript // Bom: RFC 5322 rejeita IPs entre colchetes; nosso serviço legacy não suporta // Então usamos subset mais restritivo que válida subdomínios mas não IPs const isValid = validateEmailRFC5322Subset(email) “`

A segunda versão custa o mesmo para escrever. Economiza horas da próxima pessoa que abrir o arquivo tentando entender por que o regex não cobre um caso que ela assumiu óbvio.

Documentação inline é a forma mais barata de memória organizacional. Sem ela, cada nova leitura do código recomeça do zero. Com ela, a leitura começa do ponto em que a última pessoa parou.

Conclusão operacional

Código que o desenvolvedor não compreende é código que ele não consegue defender. Quando produção quebra às três da manhã, ninguém tem tempo de aprender o que o código faz antes de consertar. O conserto tem que partir de quem já sabia.

Com IA gerando a primeira versão de tudo, a compreensão não é mais um subproduto natural da escrita. É uma disciplina separada, com práticas próprias: ler em voz alta, refatorar para entender, validar com colega, documentar o porquê. As quatro práticas existem porque nenhuma substitui as outras.

O teste antes de commitar código gerado por IA: explicar em voz alta, para uma segunda pessoa ou para um gravador, o que cada seção faz e por que foi escrita assim. Se a explicação falha em qualquer trecho, o trecho não está pronto. Estude-o até que a explicação flua. Depois commite. A primeira versão da IA é insumo. A versão commitada é a versão que o time entende — e portanto a versão que o time consegue defender, manter, e evoluir.

Se a compressão de tempo entre geração por IA e deploy em produção encolheu de dias para minutos, a compressão correspondente tem que acontecer na compreensão. Caso contrário, o time ganha velocidade de produção e perde velocidade de domínio. O segundo efeito domina o primeiro a partir do segundo incidente.

Leitura relacionada

• Dependência de IA na revisão de código — mostra o par oposto: como a confiança na revisão assistida por IA degrada a capacidade de julgar código que o próprio dev não escreveu.
• Programação em par com IA: aceleração evolutiva — o post de referência que define as Quatro Camadas e em que ponto de cada uma a IA acelera versus atrapalha.
• Vibe code com IA é desastre: como o desenvolvimento com IA exige rigor — o diagnóstico do oposto: o que acontece quando compreensão não é a primeira prática.