Como revisar um PR de agente de IA e remover mudanças desnecessárias

Um agente de programação pode corrigir erros ou entregar uma funcionalidade rapidamente, mas também formatar arquivos alheios, criar abstrações, alterar configuração ou reescrever mais código do que a tarefa exige. Antes do merge, o objetivo não é simplesmente ter menos linhas. O objetivo é um conjunto em que cada mudança importante corresponda a um requisito aceito, possa ser explicada por quem mantém o sistema e seja verificada com testes ou outras evidências.

Um desenvolvedor relatou no X uma prática pessoal: depois que o agente abre um PR, ele inicia outro agente em contexto novo e pede que encontre o que pode ser cortado. O próprio autor apresentou isso como trabalho e tokens extras, não como solução garantida. Outro usuário afirmou que o Codex corrigiu muitos erros, mas mudou tanto o código que ele deixou de entendê-lo. Esses relatos caracterizam o problema; não provam que um segundo agente sempre melhora o PR.

No processo abaixo, o segundo agente é um revisor cético, não uma autoridade. A pessoa responsável pelo código continua dona do escopo, das evidências, dos riscos e da decisão de merge.

O fluxo completo em sete etapas

1. Escrever um contrato de aceite: comportamento esperado, o que não pode mudar, escopo permitido, riscos e comandos de validação.
2. Montar o inventário real usando Conversation, Commits, Checks, Files changed e comandos locais do Git.
3. Dar a um agente com contexto novo uma primeira rodada apenas de revisão, sem edição.
4. Classificar cada achado como manter, simplificar, remover, separar ou escalar, sempre com evidência.
5. Aplicar somente reduções aprovadas por uma pessoa, em lotes pequenos e reversíveis.
6. Rodar o mesmo conjunto relevante de testes antes e depois da redução.
7. Revisar o diff final desde o início e fazer merge apenas quando todo o conjunto for explicável.

1. Defina o contrato de aceite antes da segunda revisão

“Deixe este PR mais limpo” é vago demais e convida outra reescrita subjetiva. O contrato deve registrar:

• Problema e resultado observável: o que usuário ou caller deve perceber.
• Comportamento preservado: interfaces, falhas, compatibilidade e semântica de dados.
• Escopo permitido: módulos, APIs, schemas, configuração e testes esperados.
• Não objetivos explícitos: sem upgrade de framework, formatação global, renome alheio, abstração especulativa ou migração não exigida.
• Restrições de risco: segurança, permissões, migração, desempenho, observabilidade, rollback e compatibilidade.
• Validação: comandos reais do projeto para formato, lint, tipos, testes, build, migração ou E2E.

Sem uma definição do resultado correto, não há base confiável para afirmar que um trecho é desnecessário. Esclareça o contrato antes de apagar.

2. Estabeleça o diff completo, não o resumo do agente

O GitHub distribui as evidências do PR entre várias áreas. Conversation traz descrição e discussão; Commits mostra a evolução; Checks exibe validações automáticas; Files changed contém o diff. O fluxo oficial permite comentários em linhas, sugestões, marcação Viewed por arquivo e decisão final Comment, Approve ou Request changes.

Para executar ou modificar o PR localmente, o GitHub documenta:

gh pr checkout <PR_NUMBER>
git fetch origin

Troque origin/main pela branch base real e examine as mudanças desde o ancestral comum até HEAD:

git diff --stat origin/main...HEAD
git diff --name-status origin/main...HEAD
git log --oneline origin/main..HEAD

O Git define git diff A...B como as mudanças do merge base de A e B até B. Depois do resumo, leia o diff completo e os caminhos suspeitos:

git diff origin/main...HEAD
git diff origin/main...HEAD -- path/to/suspicious-file

Não remova nada nesta fase de inventário. Separe os arquivos:

Grupo	Pergunta
Implementação central	Implementa diretamente um item do contrato?
Suporte necessário	Testes, docs, migração ou configuração são realmente exigidos?
Expansão suspeita	Há formatação global, renomes amplos, abstrações alheias ou upgrade?
Saída gerada	Precisa ser versionada com a origem ou entrou por engano?
Risco incerto	Toca segurança, dados, compatibilidade ou domínio desconhecido?

Complexidade não prova redundância. Validações defensivas, migrações e caminhos de compatibilidade podem ser longos e necessários.

3. Use contexto novo para uma primeira rodada sem editar

O contexto novo permite dar um objetivo diferente: questionar escopo e evidência, em vez de terminar a implementação. É uma técnica de revisão e um relato de prática, não uma exigência oficial nem garantia medida.

Forneça contrato, diff completo, callers relevantes, testes e instruções do repositório. Um prompt útil:

Você é o revisor de segunda rodada deste pull request. Seu objetivo não é reescrever o código, mas encontrar o menor conjunto explicável que ainda cumpra o contrato de aceite.

Primeira rodada: somente revisão. Não altere arquivos.
Leia o objetivo do PR, diff completo, callers relevantes, testes e restrições do repositório.

Para cada achado, devolva:
1. arquivo e hunk ou símbolo exato;
2. requisito atendido;
3. evidência: caller, teste, contrato de interface, documentação ou falta de evidência;
4. risco de remover ou simplificar;
5. ação: MANTER / SIMPLIFICAR / REMOVER / SEPARAR / DECISÃO HUMANA;
6. validação exata após a mudança.

Regras:
- não recomende remoção apenas por comprimento ou estilo;
- testes verdes não são a única prova de requisitos corretos;
- priorize formatação alheia, abstrações duplicadas, helpers sem uso, refactors fora do escopo e mudanças de dependência/configuração sem explicação;
- preserve segurança, compatibilidade, migrações, tratamento de erro e observabilidade sem evidência contrária;
- declare incerteza e não invente regras de negócio;
- termine com plano do menor ao maior risco. Ainda não escreva código.

O relatório antes da edição evita que o revisor crie outra grande reescrita. Toda recomendação precisa apontar para arquivo, hunk e evidência.

4. Uma pessoa classifica cada achado com evidência

Decisão	Quando usar	Evidência a confirmar
Manter	Implementa o contrato ou obrigação de segurança, compatibilidade, migração ou operação	Mapeamento para requisito, call path, teste, interface ou restrição documentada
Simplificar	O comportamento é necessário, mas há branches, wrappers ou camadas duplicadas	Equivalência de comportamento e cobertura de limites importantes
Remover	A mudança é alheia, sem uso, sem contrato ou só formato/renome acidental	Busca, build e testes relevantes não mostram dependência
Separar	Pode ter valor, mas está fora do contrato atual	Pode ser descrita, testada, revisada e revertida de forma independente
Escalar	Envolve domínio desconhecido, segurança, migração ou regra oculta	Precisa de code owner, especialista ou teste de caracterização

Investigue, sem apagar automaticamente: várias camadas para um caller; caminhos antigo e novo sem período de compatibilidade; formatação, imports, nomes ou movimentos alheios; nova dependência, lockfile ou configuração sem explicação; testes de detalhes internos; captura silenciosa de exceções; helpers sem caller; código “para o futuro”.

Falta de teste também não significa falta de uso. Pode ser lacuna de cobertura. Adicione um teste de caracterização ou consulte quem mantém o módulo antes de remover comportamento incerto.

5. Reduza em lotes pequenos e preserve recuperação

Antes de editar, confira o working tree e crie uma referência local:

git status --short
git branch backup/ai-pr-before-trim

Para restaurar um arquivo inteiro ao estado base:

BASE=$(git merge-base origin/main HEAD)
git restore --source="$BASE" -- path/to/unrelated-file

Para hunks selecionados:

git restore -p --source="$BASE" -- path/to/file

A documentação do Git avisa que, se um caminho rastreado não existir na fonte, a restauração o remove para corresponder à fonte. Verifique $BASE e caminho, depois inspecione o diff imediatamente. Edição manual também serve; o importante é não iniciar outro refactor fora do escopo.

Processe um grupo aprovado por vez:

git diff
git add -p
git diff --cached
git commit -m "Remove unrelated changes from AI-generated PR"

Commits pequenos mostram o que foi removido, por quê e qual validação sustenta a decisão. Não esconda o processo com reescrita destrutiva do histórico durante a revisão.

6. Rode validações comparáveis antes e depois

O teste deve mostrar que o comportamento aceito sobreviveu, não que o diff encolheu. Registre uma linha base do PR original quando possível e repita os mesmos checks relevantes após cada lote:

<format-check-command>
<lint-command>
<typecheck-command>
<targeted-unit-test-command>
<relevant-integration-test-command>
<build-or-e2e-command>

Use comandos da documentação ou CI, não palpites do agente. Cubra caminho normal, limites, falhas, permissões, vazios, concorrência, timeout, retry, interfaces públicas, formatos serializados, migrações, build, tipos, lint, segurança e Checks obrigatórios do commit mais recente.

Se um recorte quebrar teste, reverta o lote ou recupere do backup e investigue. Não altere teste e implementação juntos só para ficar verde, salvo quando o contrato declara a expectativa antiga incorreta e uma pessoa aprova a nova.

Testes verdes são evidência necessária, mas a suíte pode ser incompleta. A compreensão humana continua obrigatória.

7. Releia o diff final e registre a decisão

Depois da redução, reabra Files changed e revise tudo. O GitHub remove a marca Viewed quando um arquivo já visto muda, ajudando a identificar o que precisa de nova passagem. Confira novamente Commits e Checks para garantir que pertencem à revisão mais recente.

Um último review em contexto novo pode olhar só contrato e diff final, com condição de parada: apenas problemas com evidência, sem loop infinito de estilo. Então uma pessoa envia:

• Approve: contrato cumprido, mudanças explicáveis, riscos tratados e validação exigida aprovada.
• Request changes: ainda há escopo alheio, lógica opaca ou checks falhos. O bloqueio depende das regras e proteção da branch.
• Comment: feedback útil sem aprovar nem solicitar mudanças formalmente.

Checklist antes do merge

• Cada arquivo alterado mapeia para o requisito, teste necessário ou suporte explícito.
• Quem mantém consegue explicar os hunks importantes sem repetir o resumo do agente.
• Dependências, configuração, permissões, migrações e arquivos gerados sem explicação foram removidos, separados ou escalados.
• PR original e reduzido usaram validações comparáveis.
• Testes locais, build e checks do último commit atendem ao projeto.
• Riscos de segurança, dados e compatibilidade foram vistos pelo responsável adequado.
• Se o diff segue amplo, trabalho independente foi separado.
• Decisão e follow-ups foram registrados.

Falhas comuns e recuperação

O segundo agente reescreve o módulo

Pare. Volte ao relatório sem edição, limite arquivos e exija hunk, requisito e validação em cada sugestão. Rejeite refactor estético sem evidência.

Os agentes discordam

Não vote. Compare callers, contratos, caminhos de falha, testes e restrições históricas. Se faltar evidência, mantenha temporariamente, adicione cobertura ou chame quem domina a área.

Testes passam, mas o código segue opaco

Cobertura não é design compreensível. Separe o PR, documente ou peça explicação do caminho crítico. Não faça merge de código opaco apenas porque o CI está verde.

Não há testes confiáveis

Adicione teste mínimo de caracterização ou verificação manual repetível com resultado registrado. Em código de alto risco, ausência de evidência pede pausa, não palpite.

O PR é grande demais

Separe comportamento central, refactor, upgrades, formatação e migrações em mudanças independentes. Unidades menores são mais fáceis de verificar e reverter.

Prompt para executar achados aprovados

Implemente somente estes IDs aprovados: [LISTA].
Não altere arquivos fora da lista e não faça refactoring oportunista.
Para cada grupo lógico:
1. mostre o diff real;
2. execute os comandos designados;
3. informe comando, código de saída e resumo de falhas;
4. liste incertezas restantes.
Pare e peça decisão humana se um item mudar contrato, interface pública, segurança ou migração.

A ideia central não é “usar mais agentes”. É separar geração e revisão: um contexto propõe a implementação, outro questiona escopo e evidência, e uma pessoa é dona da decisão. O resultado correto não é o menor diff, mas a menor mudança explicável e verificada que resolve a tarefa.

Fontes e limites

• Relato de prática: post e respostas de Arnav Gupta no X sobre revisão de redução em contexto novo; é anedótico.
• Relato de usuário: um desenvolvedor disse que deixou de entender o código após mudanças amplas do Codex; o original não inclui repositório, diff ou testes.
• Documentação do GitHub: revisar mudanças propostas, obter PR localmente, referência de pull requests.
• Documentação do Git: git diff e git restore.