Revisão de PR
Estas regras são para qualquer revisor, humano ou agente (Copilot code review, Claude, e outros).
O skill irmão github cobre o lado do autor: corrigir comentários,
responder e solicitar a próxima revisão. Onde as regras de revisão do próprio repositório (AGENTS.md,
CONTRIBUTING.md, um guia de estilo) entrarem em conflito com este skill, as regras do repositório prevalecem.
O objetivo de uma revisão é obter um PR correto mesclado. Não é encontrar algo para dizer. "Nenhum problema encontrado" é um bom resultado.
A barra para uma constatação
Publique uma constatação somente se você puder nomear uma falha realística: um chamador real, entrada ou configuração, e o resultado incorreto que ela produz. Se você não conseguir escrever esse cenário em uma ou duas frases, não o publique.
| Severidade | Use para |
|---|---|
| Bloqueante | Resultados incorretos em um caminho comum, falhas de segurança, perda de dados, um build ou testes quebrados, uma mudança que quebra uma API pública, ou uma clara quebra de uma regra documentada no repositório |
| Deve corrigir | Um bug real em um caminho menos comum, um teste ausente para um novo comportamento, ou documentação ou instruções que levariam um leitor a fazer a coisa errada em um caso normal |
| Nit | Nomenclatura, redação ou pequenas correções de clareza. Opcionais por definição. No máximo três por revisão, e apenas na primeira rodada |
Não publique:
- Hipóteses que exigem entrada irrealista, um ambiente mal configurado ou um invasor que já tem o acesso que o ataque lhe daria.
- Código defensivo para um caso que nenhum chamador pode alcançar ("considere adicionar uma verificação nula").
- Qualquer coisa que um formatador, linter ou verificador de tipos no repositório já imponha.
- Preferência pessoal entre duas abordagens razoáveis.
- Preocupações de desempenho sem um caminho crítico ou medição por trás delas.
- Solicitações para ampliar o PR: funcionalidades, refatorações ou limpezas que ele não se propôs a fazer.
- Problemas em código que o PR não alterou, a menos que o PR os torne piores. Se algo sério estiver lá de qualquer forma, mencione uma vez, marcado como pré-existente, não bloqueante.
Para documentações, skills e outras instruções, faça uma pergunta: um leitor seguindo este texto faria a coisa errada em um caso normal? Lacunas para configurações raras são no máximo nits. Não peça para cada caso extremo ser detalhado.
Convergindo entre rodadas
Um PR deve ficar mais silencioso a cada revisão, não mais barulhento.
- Rodada 1 (primeira revisão): o diff completo, todas as severidades, nits limitados conforme acima.
- Rodada 2 e posteriores (novos commits desde sua última revisão):
- Revise apenas o que mudou desde sua última revisão e verifique se suas constatações anteriores foram corrigidas.
- Não levante novas constatações sobre código que você já revisou e que não mudou. Se você perdeu algo lá, publique apenas se for bloqueante.
- Sem nits.
- Não re-levante uma constatação que o autor respondeu com um motivo, a menos que você tenha novas evidências de que o motivo está errado. Discordância sozinha não é nova evidência.
- Se nada atender à barra, diga isso em uma linha e pare. Não preencha a revisão.
Escrevendo constatações
- Um problema por comentário, ancorado na linha sobre a qual se refere.
- Comece com a severidade:
Bloqueante:,Deve corrigir:, ouNit:. - Em seguida, o cenário de falha em uma ou duas frases, depois a menor correção que funciona.
- No máximo cinco constatações por revisão, as mais severas primeiro. Se houver mais, liste o restante brevemente no resumo. Mescle duplicatas em um comentário que liste todos os lugares.
- Seja específico e neutro. Sem elogios de preenchimento, sem "você pode querer considerar".
O resumo
Termine com um resumo curto:
- Um veredito: Aprovar, Aprovar com nits ou Alterações solicitadas (apenas quando houver pelo menos uma constatação bloqueante).
- Contagens por severidade.
- Na rodada 2 ou posteriores: quais constatações anteriores foram corrigidas agora e quais ainda estão abertas.
Revisando como um agente em um loop
Quando outro agente estiver corrigindo suas constatações e solicitando a próxima revisão:
- Trate as respostas do autor como parte da revisão. "Corrigido em abc1234" significa verificar esse commit. "Deixando como está, porque…" significa que a constatação está encerrada, a menos que o motivo esteja errado.
- Após três rodadas, publique apenas constatações bloqueantes e diga que os itens restantes ficam a critério do autor.