Revisar Diff Pr

Revisar Diff de PR

Analisar a branch atual contra dev e retornar somente achados relevantes e sustentados por evidência. Gerar comentários; nunca publicá-los no provedor do repositório.

Preparar a revisão

1. Confirmar que o diretório atual é um repositório Git.
2. Ler as instruções locais do projeto, incluindo AGENTS.md e equivalentes aplicáveis aos arquivos alterados.
3. Usar dev como base. Se ela não existir, usar origin/dev; se nenhuma existir, pedir a branch-base ao usuário.
4. Ler os commits exclusivos da branch e inspecionar base...HEAD: resumo, arquivos alterados e diff completo.
5. Informar se houver alterações locais não incluídas na revisão. Não misturá-las ao diff do PR.
6. Examinar o contexto necessário fora do diff: funções completas, chamadores, modelos, contratos, validações, transações e testes relacionados.

Ignorar dependências, artefatos de build, arquivos gerados, migrations automáticas e código de terceiros. Examinar uma migration escrita manualmente quando sua lógica fizer parte da mudança.

Procurar problemas

Verificar, conforme aplicável:

• exceções, nulos, limites, tipos, estados e fluxos de erro;
• validações ausentes, inconsistentes ou executadas na camada errada;
• autorização, exposição de dados, injeção e outros riscos de segurança;
• perda de dados, transações parciais, concorrência e falta de idempotência;
• regressões, incompatibilidades e violações de contratos existentes;
• consultas N+1, repetição de I/O, loops custosos e crescimento inadequado para o volume previsível;
• semântica enganosa que possa induzir uso incorreto;
• duplicação, complexidade ou acoplamento com impacto concreto na manutenção;
• testes ausentes para regra crítica, regressão ou caminho de erro introduzido pelo diff.

Não apontar problemas preexistentes fora do diff, exceto quando a mudança os introduzir, ampliar ou tornar alcançáveis. Ancorar o comentário na menor faixa alterada que causa o problema.

Verificar duplicação e reutilização

Para funções ou blocos relevantes adicionados:

1. Pesquisar no repositório nomes, chamadas, conceitos do domínio, mensagens, tipos e operações semelhantes; preferir rg.
2. Comparar comportamento, contrato de entrada e saída, efeitos colaterais, tratamento de erro e contexto transacional.
3. Sugerir uma função existente somente quando ela executar a mesma responsabilidade e puder ser reutilizada sem alterar o comportamento esperado.
4. Não confundir semelhança textual com equivalência funcional.
5. Não pedir abstração quando a separação refletir domínios distintos, evitar acoplamento ou tornar o fluxo mais claro.

Ao sugerir reutilização, citar a função existente e seu arquivo.

Aplicar o filtro de evidência

Publicar um achado somente quando for possível responder claramente:

1. Qual entrada, estado ou sequência aciona o problema?
2. Qual caminho do código demonstra que ele ocorre?
3. Qual é o impacto observável?
4. Por que o comportamento provavelmente não é intencional?

Para a quarta resposta, consultar testes, documentação, contratos, código vizinho, chamadores e padrões do projeto. Se faltar evidência ou houver uma explicação intencional plausível que não possa ser descartada, omitir o achado. Não preencher lacunas com suposições.

Não comentar preferências pessoais de formatação, ordem, nomes aceitáveis ou arquitetura. Aceitar melhorias semânticas, de performance, escalabilidade e manutenibilidade somente quando o benefício for concreto e explicável.

Classificar

Usar estas classificações:

• Crítica: permite comprometimento de segurança, corrupção/perda grave de dados ou indisponibilidade ampla.
• Alta: causa falha funcional importante, viola regra essencial ou produz dados incorretos em fluxo comum.
• Média: causa erro real em cenário limitado, regressão parcial ou risco relevante de manutenção.
• Baixa: defeito real de impacto restrito, mas que ainda deve ser corrigido.
• Sugestão: melhoria não bloqueante com ganho concreto de semântica, performance, escalabilidade, reutilização ou manutenibilidade.

Não reduzir uma incerteza a Baixa ou Sugestão; omitir achados incertos.

Escrever os comentários

Ordenar achados por severidade e depois por arquivo. Escrever em português, de forma direta, respeitosa e autocontida. Para cada achado, usar:

### [Alta] Possível acesso a valor nulo

**Arquivo:** `src/service.py:42`

`usuario.perfil.nome` pode falhar quando o usuário não possui perfil associado.

**Por que isso é um problema:** O fluxo aceita usuários sem perfil em [...], portanto essa leitura pode gerar [...] antes de [...].

**Sugestão:** Validar `usuario.perfil` antes do acesso ou ajustar a consulta para garantir o relacionamento.

No título, afirmar o problema de forma precisa; evitar talvez, pode ser e títulos genéricos. No corpo, explicar cenário e impacto sem exagerar. Oferecer uma direção de correção, sem exigir uma implementação específica quando houver alternativas válidas.

Se não houver achados que passem pelo filtro, responder exatamente:

Nenhum ponto relevante encontrado no diff.

Não adicionar elogios, resumo geral do PR ou comentários sem ação recomendada.