Eu gosto de agentes escrevendo código. Gosto mais ainda quando eles fazem o trabalho tedioso de levantar arquivos afetados, executar testes e encontrar a documentação que ficou para trás. Mas existe uma etapa que eu não terceirizaria por inteiro: explicar o pull request para outra pessoa.
O agente pode produzir um excelente rascunho. A descrição final, porém, deveria carregar a voz de quem assume a mudança. Não é purismo artesanal. É um checkpoint de entendimento e responsabilidade.
Resumo do diff não é contexto
Modelos são bons em enumerar o que está visível: função adicionada, teste alterado, erro novo, endpoint atualizado. O revisor consegue descobrir boa parte disso abrindo a aba de arquivos. O que ele não encontra tão facilmente é por que a mudança existe agora, quais alternativas foram descartadas, onde está o risco e qual decisão precisa de atenção.
Uma descrição útil não precisa contar cada linha. Precisa responder quatro perguntas: qual problema motivou o PR, qual direção foi escolhida, como a mudança foi verificada e onde o autor ainda tem dúvida. Esse contexto mora na cabeça da pessoa responsável, não no diff.
Escrever expõe compreensão emprestada
Quando o agente implementa, testa, cria o commit e redige a justificativa, é fácil herdar sua confiança. Tudo parece coerente porque a mesma voz propôs e avaliou a solução. Tentar explicar a mudança sem copiar o relatório quebra esse ciclo. Se eu não consigo dizer com palavras simples o que mudou e por quê, ainda não terminei minha revisão.
Isso não prova que o código está correto. Mas revela uma categoria importante de falha: o autor que sabe pedir o resultado, mas não consegue defender o caminho escolhido. Para equipes trabalhando em várias frentes com agentes, essa checagem fica mais valiosa, não menos.
Minha regra não é proibir IA no PR
Proibir o rascunho automático desperdiça uma ferramenta útil. Eu pediria ao agente fatos verificáveis: arquivos centrais, testes executados, mudanças de contrato, migrações e pontos que ele considera arriscados. Depois, o autor reduziria isso à narrativa que o revisor precisa.
Por que
- Qual problema ou decisão motivou este PR?
O que muda
- Resumo curto da abordagem, sem repetir o diff.
Como foi verificado
- Testes, cenários manuais e limitações.
Onde revisar com atenção
- Riscos, escolhas não óbvias e dúvidas abertas.Um template ajuda a padronizar sem transformar a descrição em burocracia. Se uma seção não acrescenta nada, ela pode ficar vazia ou desaparecer. O pior resultado é um texto de 1.500 palavras que parece completo, mas obriga o revisor a localizar sozinho a decisão importante.
Descrição também direciona a revisão
O GitHub recomenda título e descrição claros para que revisores entendam problema, abordagem e resultado. Eu acrescentaria uma coisa: diga onde você quer discordância. “Gostaria de uma segunda opinião sobre a estratégia de cache” vale mais que uma lista automática de vinte arquivos.
Esse convite muda o review de inspeção genérica para conversa técnica. Também registra incerteza. Agentes frequentemente apresentam escolhas como inevitáveis; bons autores mostram quais eram as alternativas e qual compromisso aceitaram.
Autoria é assumir a explicação
Minha posição é simples: deixe o agente coletar material e até montar a primeira versão, mas reescreva o texto que outra pessoa vai usar para entender sua mudança. Remova inventário, adicione contexto e declare as dúvidas. O ganho não está na prosa humana ser magicamente melhor; está no ato de o responsável reconstruir o raciocínio antes de pedir aprovação.
Se o PR é seu, a explicação também é. A IA pode ajudar a lembrar os fatos. A responsabilidade por escolher quais fatos importam não deveria ser automática.
Um exemplo separa inventário de decisão
Um rascunho automático pode dizer: “adiciona cache, altera três arquivos e atualiza testes”. Isso descreve o diff, mas não ajuda a revisar. Uma versão assumida pelo autor seria:
As buscas repetiam a mesma consulta durante um request. Escolhi cache por request, não Redis, porque o dado muda a cada chamada e não deve atravessar usuários. Verifiquei o número de queries no fluxo de listagem e o comportamento quando a consulta falha. Revisem especialmente a chave do cache: ela inclui tenant e filtros, mas não a permissão calculada.
A segunda descrição declara problema, alternativa descartada, evidência e risco. O revisor sabe onde gastar atenção. Se um agente produziu esse texto, o autor ainda precisa confirmar cada fato: “testes executados” não pode significar testes sugeridos, e “sem mudança de contrato” exige olhar consumidores e migrações.
- Fato verificado: comando executado, resultado observado, contrato comparado.
- Inferência: efeito esperado a partir do código; declare como tal.
- Decisão: alternativa escolhida e custo aceito.
- Pendência: ponto que ainda precisa de revisão humana ou ambiente real.
Para mudanças que corrigem defeitos, indique também se o caso virou teste de regressão e por que vale mantê-lo. Em upgrades, o checklist de dependências oferece uma lista curta de evidências que pode entrar no PR sem virar inventário do lockfile.
Ferramentas como o Laravel Boost conseguem transformar convenções do repositório em contexto para agentes, mas contexto disponível não é entendimento garantido. A descrição continua sendo o lugar onde a pessoa demonstra que conferiu a mudança contra essas regras.