Revisão
Julgue uma mudança em dois eixos separados: ela construiu a coisa certa (especificação) e está bem construída (qualidade), com novos olhos, descobertas apoiadas por evidências e gravidade avaliada com base no que um usuário real encontraria. Em seguida, aja sobre as descobertas com rigor técnico, não deferência.
Princípio central: Aprove uma mudança quando ela definitivamente melhora a saúde do código-fonte e faz o que foi solicitado, mesmo que não seja como você a teria escrito. Nunca aprove uma mudança que você não leu e verificou de fato.
Posição no pipeline: spec → plan → build (+ test) → review → merge.
Passo 1: Definir o escopo
- O usuário nomeia o escopo (PR, branch, intervalo de commits, arquivos). Caso contrário: a branch atual contra sua base de mesclagem com a branch padrão, mais as alterações não commitadas.
- Resolva o ponto fixo e confirme que o escopo não está vazio antes de fazer qualquer outra coisa:
git rev-parse <ref>,git log <ref>..HEAD --oneline,git diff <ref>...HEAD --statpara trabalho commitado, egit diff --cached --stat(staged),git diff --stat(unstaged) egit status --short(untracked) para alterações não commitadas. Revise a união de ambos, e quando alterações não commitadas estiverem no escopo, informe cada revisor (o prompt do revisor tem uma linha para isso). Uma referência inválida ou um escopo vazio em ambos os casos falha aqui. - Para um PR, leia sua descrição e issues vinculadas.
Passo 2: Coletar a intenção
Encontre, em ordem: a especificação e o plano que a mudança implementa (specs/<slug>/, links em commits/PR, um caminho que o usuário forneceu), as linhas Ruling: do ledger de construção, e a issue que ela encerra. Reafirme a intenção em duas ou três frases. Se não houver especificação, diga isso: o eixo de especificação então julgará com base na descrição do PR e nas expectativas razoáveis de um usuário.
Encontre também os padrões: CONTRIBUTING.md, CODING_STANDARDS.md, CLAUDE.md/AGENTS.md, configurações de lint, ADRs, o glossário.
Verificação de tamanho. ~100 linhas alteradas é o ideal, ~300 é aceitável para uma única mudança lógica, ~1000 é grande demais para revisar bem: recomende uma divisão (empilhamento, por grupo de arquivos ou fatias verticais) como uma descoberta. Refatoração misturada com trabalho de funcionalidade são duas mudanças.
Passo 3: Revisar com contexto novo
O autor é cego para suas próprias suposições, e a sessão que escreveu o código também. Quando uma ferramenta de subagente estiver disponível, despache revisores com contexto fresco usando revisor-prompt.md: forneça a eles o diff (como um arquivo ou comando exato), os caminhos da especificação/plano, os arquivos de padrões e as decisões do ledger. Nunca seu histórico de sessão. Os revisores são somente leitura e não geram seus próprios revisores.
Execute em paralelo, para que um eixo não possa mascarar o outro:
- Revisor de especificação: faltando, extra, mal interpretado.
- Revisor de qualidade: correção, testes, design, segurança, desempenho.
- (Opcional, para mudanças arriscadas ou amplas) Revisor de raio de explosão: o que isso quebra em algum lugar que o grep não mostraria.
Use o modelo mais capaz disponível para uma revisão de branch inteira. Sem uma ferramenta de subagente, faça cada eixo você mesmo como uma passagem separada e rotule o resultado como uma auto-revisão: mais fraca do que um revisor fresco, e o usuário decide se isso é suficiente.
Revisar sua própria branch recém-terminada inline não substitui este passo.
O eixo de especificação
Compare o diff com o que foi solicitado:
- Faltando: requisitos ou critérios de sucesso ignorados, parciais, ou reivindicados mas não implementados. Cite a linha da especificação.
- Extra: comportamento que ninguém pediu, opções especulativas, hooks ou abstrações (scope creep, YAGNI).
- Mal interpretado: funcionalidade certa construída da maneira errada, ou o problema errado resolvido.
- Não verificável pelo diff: requisitos que residem em código não alterado ou abrangem mudanças. Liste o que verificar em vez de adivinhar.
A especificação é um documento de visão, não uma lista exaustiva. Onde ela é silenciosa, a expectativa razoável de um usuário é o requisito. O silêncio sobre uma entrada não é permissão para ela travar.
O eixo de qualidade
Leia os testes primeiro: eles revelam intenção e cobertura.
Testes
- Cada novo comportamento tem um teste que falharia se o comportamento quebrasse? Responda por experimento onde puder: inverta uma condição que a mudança adiciona e execute a suíte, em uma worktree ou cópia descartável para que o checkout revisado nunca mude. Uma mutação que permanece verde é uma descoberta: nomeie o teste faltante.
- Comportamento através de seams públicos, não internos; nenhuma asserção em mocks; nenhum valor esperado computado pelo código sob teste; mocks apenas em fronteiras do sistema.
- Correções de bugs têm um teste de regressão. Nada ignorado ou desabilitado. Saída do teste limpa.
Correção
- Corresponde à especificação; casos de borda (null, vazio, zero, máximo, unicode, concorrente); caminhos de erro, não apenas o caminho feliz; off-by-one, condições de corrida, estado que pode ficar dessincronizado.
Legibilidade e simplicidade
- Nomes dizem o que as coisas são e fazem. O fluxo de controle é direto. Poderia ser em menos linhas? Cada abstração ganha seu sustento (sem generalizar antes do terceiro uso)?
- Código morto, variáveis no-op, comentários
// removed, shims de compatibilidade que ninguém precisa. - Comentários explicam por que, não o que. Um comentário narrando uma solução alternativa geralmente marca uma causa raiz deixada sem correção.
Design
- Encaixa-se nos padrões existentes; um novo padrão precisa de um motivo.
- Uma refatoração reduz os conceitos que um leitor deve manter, ou apenas os move? Prefira a versão onde branches, modos ou camadas desaparecem.
- Lógica de funcionalidade vazando para um módulo compartilhado; um quase-duplicado de um helper existente; um condicional aparafusado a um fluxo não relacionado; switches repetidos na mesma forma (um modelo ou dispatcher faltante); um segundo booleano que deve permanecer sincronizado com o primeiro (uma máquina de estado faltante).
- Wrappers de um único chamador e camadas de passagem (inline eles). Estado mutável mais amplo do que o necessário.
- Validação nas fronteiras, confiança internamente. Nenhum fallback silencioso mascarando um invariante pouco claro; nenhum
any/cast gratuito. - Crescimento de arquivo: uma mudança que empurra um arquivo muito além de um tamanho saudável deve ser decomposta primeiro.
Segurança
- Entrada não confiável (HTTP, CLI, arquivos, env, saída de LLM, respostas de terceiros) validada na fronteira. Consultas parametrizadas. Saída codificada. Authn/authz verificados onde necessário. Segredos fora do código, logs e VCS. Novas dependências justificadas, mantidas, licenciadas de forma compatível; diff do lockfile revisado.
Desempenho
- Consultas N+1, loops ou buscas ilimitados, paginação faltante, trabalho síncrono que bloqueia, grandes alocações em caminhos quentes, re-renderizações desnecessárias. Quantifique quando puder ("~50ms por linha para 1k linhas").
Linha de base de maus cheiros (julgamentos; os padrões documentados do repositório substituem): Nome Misterioso, Código Duplicado, Inveja de Funcionalidade, Aglomerados de Dados, Obsessão por Primitivos, Switches Repetidos, Cirurgia de Espingarda, Mudança Divergente, Generalidade Especulativa, Cadeias de Mensagens, Homem do Meio.
O eixo de raio de explosão (mudanças arriscadas ou amplas)
Listar chamadores não é o trabalho; o grep faz isso em um segundo. O trabalho é a quebra que o grep não mostrará:
- Encontre o único fato pelo qual a mudança é segura ("esta chamada apenas descarta entradas que já estão mortas"). Prove executando código: um script que importa a biblioteca real na versão fixada e chama a função exata em questão.
- Veja onde a busca de símbolos para: código-fonte da biblioteca e patches locais, temporização de execução (ordenação async, desmontagem), formatos serializados (formas JSON, colunas de BD, protocolos de fio, outras linguagens lendo os mesmos bytes), flags de funcionalidade, consumidores a três saltos de distância.
- Para cada risco: como quebra,
file:line, probabilidade, custo e a verificação mais barata. Liste os riscos verificados e descartados separadamente.
Passo 4: Verificar cada descoberta
Uma descoberta que parece correta não é uma descoberta até ser verificada.
- Verifique contra os chamadores, guardas e testes que alcançam o código. Descarte se eles a descartarem.
- Prove as importantes: um teste com falha, um script de reprodução ou saída de comando mostrando o comportamento errado. Prefira descobertas comprovadas por uma execução em vez de plausíveis.
- Rotule defeitos preexistentes separadamente de regressões que esta mudança introduz.
- Mescle descobertas que compartilham uma causa raiz.
- Zero descobertas é um resultado válido. Não invente uma para parecer completo.
A barreira para bloquear uma mesclagem
Uma descoberta pode ser Crítica ou Importante, e portanto bloquear a mesclagem, apenas quando for estabelecida por evidências:
- uma execução (teste, script ou comando) que mostra o comportamento errado, ou
- uma entrada concreta rastreada passo a passo através do código até uma saída errada, com
file:lineem cada passo.
Uma preocupação plausível que você não pôde estabelecer desta forma ("isso pode quebrar X", "casos de borda podem não ser tratados") é classificada como Menor e rotulada como não verificada. Ela não bloqueia. Liste-a para que o autor possa verificá-la.
Passo 5: Classificar e relatar
Classifique pelo efeito em uma pessoa razoável usando o software se ele for enviado, não se a especificação menciona o gatilho.
| Severidade | Significado | Ação necessária |
|---|---|---|
| Crítico | Falha de segurança, perda de dados, funcionalidade principal quebrada | Bloqueia mesclagem |
| Importante | Comportamento errado ou frágil, requisito perdido, comportamento não testado, erros engolidos, duplicação ou design prejudiciais | Corrigir antes de mesclar |
| Menor | Polimento, pequenas simplificações, cobertura mais ampla | Decisão do autor; registrar se adiado |
| Nit | Preferência de estilo | Opcional |
| FYI | Contexto, nenhuma ação | Nenhuma |
Lidere com alavancagem: correção e segurança primeiro, depois problemas estruturais e simplificações perdidas, depois o resto. Se há um problema estrutural e dez nits, o problema estrutural é a revisão. Proponha a mudança, não apenas o problema: "substitua esta cadeia de ifs por uma busca indexada por kind", "inline este wrapper de um único chamador", "reutilize formatDate de utils/date.ts".
Seja honesto: nenhum "LGTM” de carimbo, nenhum suavizar um bug real em "pode ser uma preocupação menor", nenhum inflar nits para Crítico. Reconheça o que foi bem feito, especificamente.
Use o formato em revisor-prompt.md: veredito da especificação, pontos fortes, problemas por severidade (cada um com file:line, o que está errado, por que importa, como corrigir, evidências), notas de raio de explosão, recusou-se a julgar (comportamentos considerados e deixados de lado, com por quê), e um veredito: Aprovar, Aprovar com correções ou Solicitar alterações. Mantenha as seções de especificação e qualidade separadas; não reordene entre elas.
Regra do veredito: solicite alterações apenas quando pelo menos uma descoberta Crítica ou Importante atingir a barra de evidências acima. Uma mudança que faz o que foi solicitado e tem apenas preocupações Menores ou não verificadas é aprovada, com essas preocupações listadas. Rejeitar uma mudança correta custa ao autor tanto quanto aprovar uma quebrada.
Passo 6: Agir sobre as descobertas (quando você é o autor)
O feedback da revisão é uma entrada para avaliar, não ordens para executar.
- Leia tudo antes de reagir. Se algum item não estiver claro, pergunte sobre ele antes de implementar qualquer coisa: os itens geralmente estão relacionados.
- Reafirme cada item como um requisito técnico e verifique contra o código. Está correto para este código-fonte? Quebra alguma coisa? Houve uma razão para o código atual? O revisor tem o contexto completo?
- Responda com evidências quando estiver errado: um teste, um
file:line, uma medição. Se uma sugestão adiciona uma funcionalidade "adequada" não utilizada, verifique o uso; YAGNI se aplica também aos revisores. Escale para o usuário qualquer coisa que entre em conflito com decisões anteriores dele. - Corrija na ordem: Crítico/bloqueador → simples → complexo. Cada correção obtém um teste com falha que reproduz a descoberta primeiro (via
test), depois a correção, depois uma suíte completa verde. Uma passagem de correção focada, não um loop infinito. - Menores que você não corrige vão para uma lista "Adiado" em sua mensagem final. Uma descoberta que você decide não corrigir é uma decisão registrada com um motivo.
- Sem concordância performática. Sem "Você está absolutamente certo!", "Ótima captura!" ou agradecimentos. Diga o que você mudou ("Corrigido: linhas vazias agora emitem um CSV apenas com cabeçalho; teste
exports header for empty view") ou por que o código permanece. Se você respondeu e estava errado, diga isso em uma linha e corrija.
No GitHub, responda no fio de comentário inline, não como um comentário de nível superior.
Antes de mesclar (Definição de Pronto)
- Cada critério de sucesso da especificação foi atendido e verificado no sistema em execução
- O novo comportamento tem testes que falham sem a mudança; suíte completa verde, saída limpa
- Nenhuma descoberta Crítica ou Importante aberta; adiamentos registrados com motivos
- Sem código morto, saída de depuração ou blocos comentados; mudanças com escopo na tarefa
- Lint, typecheck, build passam
- Migrações, configuração e flags considerados; caminho de rollback existe para mudanças arriscadas
- Interfaces públicas e comportamento visível ao usuário documentados; ADR para decisões difíceis de reverter
- Mensagens de commit e descrição do PR dizem o que mudou e por que, em termos independentes
- O humano aprovou onde o projeto exige
Racionalizações comuns
| Pensamento | Realidade |
|---|---|
| "Testes passam, então está bom" | Testes não pegam design errado, falhas de segurança ou uma especificação mal interpretada. |
| "Eu escrevi, eu sei que está certo" | Mesmo autor, mesmos pontos cegos. Consiga novos olhos. |
| "Código gerado por IA é provavelmente bom" | É confiante e plausível quando está errado. Precisa de mais escrutínio, não menos. |
| "A refatoração está mais limpa" | Se o leitor mantém o mesmo número de conceitos, ela apenas moveu. |
| "Limparemos depois" | Depois raramente vem. Corrija agora ou registre explicitamente. |
| "A especificação não mencionou essa entrada" | Silêncio não é permissão. Classifique pelo que o usuário obtém. |
| "O revisor disse Menor, então é Menor" | Reclassifique pelo efeito. |
| "A correção é óbvia, não precisa de teste" | O teste com falha é a única prova de que a descoberta era real e agora se foi. |
| "O revisor provavelmente está certo" | Verifique contra o código primeiro. |
Bandeiras vermelhas
- "LGTM" sem evidência de leitura
- Descobertas sem
file:line, ou reivindicadas sem verificar chamadores e guardas - Descobertas de especificação e qualidade mescladas em uma lista classificada
- Nits enterrados acima de um bug de correção
- Um revisor recebeu o histórico de sessão do autor
- Corrigir descobertas de revisão sem um teste com falha primeiro
- Implementar alguns itens de feedback enquanto outros ainda estão abertos