🔍 Revise além do diff
Um agente revisor pode explorar arquivos relacionados, verificar contratos, analisar testes, encontrar duplicações, identificar riscos, comparar com os padrões do repositório, revisar arquitetura, procurar falhas de segurança, avaliar desempenho e verificar compatibilidade. O diff é o ponto de partida, não o limite.
🎯 O que o code review deve avaliar
🆕 Novo aqui?
Diff é o conjunto de linhas adicionadas e removidas por uma mudança. Duplicação semântica é quando duas partes do sistema fazem a mesma coisa escrita de formas diferentes — invisível para busca de texto, mas achável por um agente que lê o repositório. Aderência ao escopo é conferir se a mudança fez só o que foi pedido.
Contexto
O repo inteiro, se preciso
Contrato
Quem consome não pode quebrar
Duplicação
Semântica, não textual
Escopo
Fez só o que foi pedido?
👥 Separe implementador e revisor
O agente que revisa não deve depender totalmente das conclusões do agente que implementou. A separação reduz o risco de ambos repetirem a mesma suposição incorreta — e é a diferença entre revisão de verdade e um segundo carimbo.
Como ler: à esquerda, a seta volta para o mesmo agente — ele revisa carregando o raciocínio que produziu o erro. À direita, o revisor recebe só especificação + diff, sem o histórico do autor: é isso que o torna capaz de discordar.
🧪 Exercício copiável — revisor independente
Objetivo: rodar uma revisão de verdade sobre uma mudança sua. Abra uma sessão nova do agente (contexto limpo, sem o histórico da implementação) e cole:
Você é o revisor independente. Não implementou nada disto e não deve confiar em nenhuma afirmação de quem implementou. Especificação da tarefa: <cole a spec> Diff a revisar: <cole a saída de: git diff origin/main...HEAD> Revise nesta ordem e leia os arquivos relacionados antes de concluir: 1. a mudança cumpre a spec? o que ficou faltando? 2. algo FORA do escopo foi alterado? 3. algum contrato/comportamento existente muda para quem consome? 4. o tratamento de erro cobre timeout, duplicidade e permissão negada? 5. existe duplicação semântica com algo que já existe no repositório? 6. os testes provam o comportamento novo ou só executam o código? Formato da resposta: lista de achados, cada um com [severidade: bloqueante | importante | menor] · arquivo:linha · por que é problema · como verificar. No máximo 7 achados — priorize. Se não houver bloqueante, diga isso explicitamente.
Como verificar: pegue cada achado "bloqueante" e tente reproduzi-lo. Se dois de três não se sustentam, seu revisor está gerando ruído — aperte o prompt (menos achados, mais evidência exigida) antes de plugar isso no fluxo do time.
Contexto limpo
Sessão nova, sempre
Spec + diff
Não o raciocínio do autor
Severidade
Achado sem ela é ruído
Teto de achados
Força priorização
🏛️ Faça revisão arquitetural
É o tipo de defeito que nenhum teste pega: a mudança funciona perfeitamente e mesmo assim está errada — porque fura uma fronteira, duplica uma capacidade ou cria um acoplamento que vai cobrar juros depois.
✓ Perguntas que revelam problema real
- ✓Esta camada deveria conhecer aquela?
- ✓Já existe algo no repositório que faz isso?
- ✓Quantos módulos precisam mudar juntos por causa disto?
- ✓Essa abstração tem mais de um caso de uso hoje?
✗ Sinais de violação arquitetural
- ✗Import atravessando fronteira de domínio
- ✗Regra de negócio dentro do controlador/handler
- ✗Terceira implementação da mesma coisa, com outro nome
- ✗Módulo novo que só um lugar usa e ninguém pediu
💡 Dica prática
Regra arquitetural repetida três vezes na revisão deve virar teste: uma verificação de dependências que falha o build quando alguém importa através da fronteira. É o tema do módulo 3.3 — regra em texto vira gate.
Fronteira
Import é evidência
Acoplamento
Conte quem muda junto
Abstração
Precisa de 2+ usos
Regra 3x
Vira teste
🔐 Cubra segurança, desempenho e manutenção
Um revisor genérico encontra estilo. Um revisor com uma lente por passagem encontra o que dói. Rode a mesma mudança três vezes, cada uma com um foco.
Lente de segurança
Entrada não validada, injeção, autorização ausente, segredo no código, dado sensível em log, permissão ampla demais, dependência com CVE conhecida.
Lente de desempenho
Consulta dentro de laço (N+1), ausência de índice, carga de coleção inteira em memória, chamada externa sem timeout, retentativa sem espera crescente.
Lente de manutenção
Nome que não diz o que faz, condicional aninhada demais, configuração espalhada, teste que testa a implementação em vez do comportamento, documentação que já nasceu desatualizada.
Uma lente
Por passagem
Segredo
Bloqueio, não sugestão
N+1
Clássico e caro
Manutenção
Custo que chega depois
🚧 Conheça os limites da revisão automática
O revisor automático não conhece a intenção de negócio, o acordo feito na reunião nem a razão histórica de uma gambiarra. E tem um vício: gerar volume. Trinta comentários de ninharia por PR ensinam o time a ignorar revisão — inclusive a boa.
⚠️ Atenção
Na revisão automática, precisão vale mais que abrangência. É melhor um revisor que aponta três coisas certas do que um que aponta trinta, das quais cinco são reais. O custo do falso positivo não é o tempo de ler — é a confiança perdida.
Como calibrar o ruído
- • Limite o número de achados por revisão (5 a 7).
- • Exija severidade e "como verificar" em cada achado.
- • Proíba comentários de estilo — isso é trabalho do lint, automático e silencioso.
- • Meça: de cada dez achados, quantos viraram mudança? Abaixo de metade, aperte o prompt.
Precisão
Acima de abrangência
Estilo
É lint, não revisão
Falso positivo
Custa confiança
Medir
Achado → mudança
🧑⚖️ Preserve o papel da revisão humana
A IA filtra, explora e prepara. A decisão continua humana — não por formalidade, mas porque intenção, prioridade e aceitação de risco não são propriedades do código; são escolhas de quem responde pelo sistema.
👤 O que só o humano decide
- •Se o problema resolvido era mesmo o problema certo.
- •Se o risco residual é aceitável para este negócio, neste momento.
- •Se vale pagar dívida agora ou registrar e seguir.
- •Quem responde se der errado.
Checagem rápida: qual arranjo produz a revisão mais confiável?
Intenção
Só o humano sabe
Risco
Aceitar é decisão
PR pequeno
Torna revisão possível
Responsabilidade
Não se delega
📌 Resumo do Módulo
Próximo Módulo:
3.3 - Quality Gates: transformar regra escrita em verificação obrigatória.