Neste artigo
- Por que revisar código de agente é um ofício novo
- O checklist, item por item
- O que fazer quando o próprio volume vence
- Os modos de falha que o checklist precisa caçar
- O revisor como profissão, não como castigo
- Revisar PR de agente é diferente de revisar PR de colega?
- O que é leitura adversarial do diff?
- Testes gerados pelo próprio agente valem como garantia?
- Como convencer o time de que revisão leva tempo?
Quem aprova pull request gerado por agente de IA vive uma tentação diária: o código parece bom, os testes existem, a descrição está bonita, e a fila anda cheia. Apertar o botão de aprovar sem ler virou o gesto mais perigoso do desenvolvimento moderno. Os relatos que motivam este guia explicam o porquê. Num deles, um desenvolvedor que operava várias sessões de agentes ao mesmo tempo descobriu, dias depois, que um conserto pedido três dias antes nunca aconteceu: a sessão longa simplesmente pulou a instrução e seguiu em frente, sem avisar ninguém. Em outro, um engenheiro descreveu a entropia crescente de codebases com uso alto de IA, a desordem de um sistema que cresce mais rápido do que qualquer pessoa consegue acompanhar.
E há o conselho que virou fio condutor desta casa sobre o tema, relatado na thread sobre desenvolvimento com Claude Code no r/programacao: na visão de um engenheiro com 16 anos de carreira, todos viraram revisores de código, e o caminho é estudar para saber o que revisar. Este guia transforma esse princípio em checklist. Não é uma lista burocrática para fingir diligência; é o conjunto mínimo de perguntas que separa o revisor do carimbador.
Por que revisar código de agente é um ofício novo
A revisão tradicional parte de uma premissa que o agente quebra: um humano escreveu aquilo com intenção. Código de colega carrega o raciocínio de quem escreveu, os atalhos assumidos, as partes que ele sabe que são frágeis. Código de agente carrega plausibilidade: ele parece certo em cada linha, e é exatamente por isso que os erros se escondem melhor. O relato do conserto pulado ilustra o modo de falha característico: não é código errado, é escopo incompleto entregue como completo. A sessão avança, o relatório final celebra o que foi feito, e o que ficou de fora simplesmente não aparece.
O segundo modo de falha é o sistêmico. Cada PR aceito sem leitura do contexto adiciona um pouco de desordem ao todo: padrões duplicados, convenções locais ignoradas, dependências novas onde o projeto tinha regra antiga. A aceleração do código que trava o pull request já era um problema quando a IA sugeria pedaços; com o agente entregando branches inteiras, a revisão virou o coração do processo, como mostra o panorama de como os agentes redesenharam o ciclo de desenvolvimento.
O checklist, item por item
1. A intenção do ticket antes do diff. Releia o ticket ou a tarefa original e formule em uma frase o que o PR deveria resolver. Só então abra o diff. Quem começa pelo diff é capturado pela solução apresentada e perde a capacidade de notar o que faltou, exatamente o erro do relato do conserto pulado. Se o PR resolve um problema diferente do pedido, por melhor que seja, ele não resolve o seu.
2. O mapa do que deveria ter mudado. Antes de ler linhas, liste mentalmente os arquivos e pontos do sistema que uma solução correta tocaria. Compare com a lista de arquivos do PR. Arquivo esperado ausente é o sinal mais barato de incompletude; arquivo surpresa presente é o sinal mais barato de escopo vazado. Os dois merecem pergunta antes de qualquer aprovação.
3. Leitura adversarial do diff. Leia o diff procurando ativamente o que está errado, não confirmando o que está certo. Os pontos frágeis de código gerado são conhecidos: tratamento de erro genérico que engole exceções, validação de entrada esquecida na borda, chamada concorrente sem proteção, convenção do projeto ignorada em favor do padrão mais comum da internet. Grandes plataformas já embatem esse problema com automação, e a cobertura do sistema multiagente de revisão do LinkedIn e dos recursos agentivos de merge request do GitLab 19 mostra que a indústria inteira percebeu o mesmo gargalo.
4. Os testes que faltam, não os que existem. Agente gera teste para o caminho feliz com facilidade impressionante. O trabalho do revisor é perguntar pelos outros: o caso de borda com valor limite, a entrada vazia, a falha da dependência externa, o comportamento em concorrência. Se o PR introduz regra de negócio nova sem teste do caso de borda que a motivou, o teste mais importante ficou de fora.
5. O registro do porquê. Cada decisão não óbvia do PR deveria ter uma justificativa rastreável, na descrição, nos comentários ou no próprio código. Quando ninguém registra por que uma mudança foi feita, a manutenção futura vira arqueologia, e a entropia relatada pela comunidade se instala: o sistema cresce sem que ninguém consiga mais dizer o motivo de cada pedaço existir.
💡 Dica: transforme o checklist em template de revisão do repositório. Cinco caixas de verificação na descrição do PR custam segundos por entrega e mudam o comportamento de todo o time, inclusive o dos agentes, que passam a receber devolutivas estruturadas.
O que fazer quando o próprio volume vence
Há um limite honesto: quando o time gera PRs mais rápido do que consegue revisar, o checklist vira teatro. Os relatos de quem opera várias sessões em paralelo mostram o sintoma, mensagens perdidas, sessões esquecidas, consertos que evaporam. A resposta não é carimbar mais rápido, é reduzir a vazão: menos agentes simultâneos por revisor, PRs menores com escopo único e automação dos checks mecânicos, estilo, sintaxe, cobertura, para sobrar atenção humana para o que só humano julga. A prática se conecta diretamente aos princípios de construir sistemas robustos com agentes de IA, onde a verificação é parte da arquitetura e não etapa final.
Os modos de falha que o checklist precisa caçar
Os relatos da comunidade permitem catalogar os erros típicos de código produzido por agentes, e o revisor experiente aprende a procurá-los nesta ordem. O primeiro é o escopo silencioso: a tarefa parcialmente feita com o relatório final celebrando só a parte concluída, modo de falha do conserto pulado que abriu este guia. O segundo é a convenção ignorada: o modelo reproduz o padrão mais comum dos repositórios públicos em que foi treinado, e não o padrão do seu projeto, o que explica imports estranhos, nomenclatura fora da casa e arquitetura paralela surgindo em arquivos novos. O terceiro é a borda invisível: valor limite, coleção vazia, fuso horário, concorrência, o território inteiro que separa a demonstração do software em produção. E o quarto é a reversão acidental: em sessões longas, o agente resolve um problema novo desfazendo um conserto antigo, e só quem olha o diff inteiro, e não só a parte nova, percebe.
Essa catalogação tem um efeito colateral valioso: ela vira material de devolutiva. Quando o PR é devolvido com o modo de falha nomeado, a instrução do agente melhora na rodada seguinte, e o time acumula um arquivo de instruções cada vez mais afiado. A revisão deixa de ser defesa e vira treinamento do próprio fluxo.
O revisor como profissão, não como castigo
O fechamento é o conselho de carreira embutido no relato dos 16 anos de estrada: se todos viraram revisores, a habilidade de revisar virou o ofício. Isso não é rebaixamento; é o mesmo movimento que outras engenharias fizeram quando máquinas tomaram a execução, deixando ao profissional a especificação, a verificação e a responsabilidade. Quem estuda o que revisa, intenção, escopo, borda, registro, fica mais valioso a cada agente novo. Quem carimba fica substituível pela própria ferramenta que aprova. O próximo passo prático é abrir o PR mais recente da sua fila e aplicar os cinco itens acima, hoje, antes de aprovar qualquer coisa.
Perguntas frequentes
Revisar PR de agente é diferente de revisar PR de colega?
Sim, na natureza dos erros. Código de colega costuma falhar onde o raciocínio humano falha: pressa, cansaço, desconhecimento. Código de agente falha em plausibilidade: ele entrega escopo incompleto como completo, ignora convenções locais e gera testes do caminho feliz. O checklist precisa mirar esses modos de falha específicos.
O que é leitura adversarial do diff?
É ler a mudança tentando quebrá-la, em vez de tentar confirmá-la. Em vez de perguntar "isso parece certo?", pergunte "onde isso falha?". Os pontos de atenção recorrentes em código gerado são tratamento de exceção genérico, validação esquecida nas bordas e padrões estranhos ao projeto, como relatado em threads de entropia de codebases.
Testes gerados pelo próprio agente valem como garantia?
Valem como verificação parcial. O teste tende a validar o que foi implementado, não o que deveria ter sido implementado. Por isso o checklist separa os dois: os critérios de aceitação e os casos de borda vêm do ticket e do revisor, e a automação de testes da máquina cobre a mecânica.
Como convencer o time de que revisão leva tempo?
Com o argumento que os próprios relatos fornecem: o conserto pulado numa sessão longa só foi percebido dias depois, porque ninguém conferiu. Cada PR carimbado transfere custo da revisão barata de hoje para a caça ao bug cara de amanhã, e a conta aparece no incidente de produção, não no painel de velocidade.