Habilidade de Revisão de Código
Metodologia de revisão de código orientada de fora para dentro, baseada em riscos, conforme Gregory Brown em "Effective Code Reviews" (Programming Beyond Practices, 2015).
A integração com a plataforma e as verificações específicas do projeto são definidas separadamente nas regras do seu projeto.
Configuração
Quando solicitado a configurar, definir, integrar ou criar um arquivo de regras para esta habilidade:
- Leia todas as regras de projeto existentes (
.claude/rules/,CLAUDE.md) para entender o que já está configurado. Não duplique convenções, comandos ou verificações que já existam na configuração do projeto. - Inspecione o projeto em busca de convenções de vinculação de issue/PR, configuração de CI, configurações de linter/formatter e indicadores de plataforma de revisão de código.
- Apresente ao usuário opções interativas para cada decisão específica da habilidade, usando um diálogo de escolha com opções para cada:
- Coleta de Contexto — como localizar o issue ou ticket relevante para um PR (nomeação de branch, palavras-chave no corpo do PR, integração com gerenciamento de tarefas)
- Verificação de Build — como verificar se o build está passando (verificações de status de CI, comandos específicos)
- Convenções de Código — verificações específicas do projeto além dos padrões da habilidade (regras de arquitetura, regras de estilo já impostas por linters)
- Formato de Saída — estrutura personalizada para a saída da revisão, ou usar o formato integrado
- Mecânica de Postagem — como postar a revisão (comentário no PR do GitHub, comentários inline, stdout)
- Tratamento de Threads em Re-revisão — em uma re-revisão, o que fazer com suas próprias threads de descobertas anteriores: Responder e resolver (padrão — responder na thread e resolver threads que foram corrigidas ou respondidas), Apenas responder (responder na thread, mas deixar a resolução para humanos) ou Apenas resumo (nunca tocar em threads anteriores; relatar seu status apenas no resumo)
- Integração com CI — oferecer-se para gerar um workflow do GitHub Actions que execute esta revisão automaticamente em cada PR. Sempre pergunte isso, mesmo que o diretório
.github/workflows/ainda não exista — este pode ser o primeiro workflow do projeto. Apresente opções de modelo: Opus (recomendado) / Sonnet / Pular. Padrão: Opus.
- Escreva
.claude/rules/code-review.mdcontendo apenas as escolhas do usuário. Omita qualquer decisão onde o usuário aceite o padrão — o comportamento integrado da habilidade cuida disso. - Se o usuário optou pela Integração com CI:
a. Leia
assets/code-review.yml(incluído nesta habilidade) como o template do workflow. b. Substitua--model opuspor--model <modelo-escolhido>se o usuário escolheu um modelo diferente. c. Se.github/workflows/code-review.ymljá existir no projeto, mostre um diff e peça confirmação antes de sobrescrever. d. Escreva o workflow em.github/workflows/code-review.yml(crie.github/workflows/se não existir). e. Lembre ao usuário de adicionarCLAUDE_CODE_OAUTH_TOKENcomo um segredo do repositório:- Gere o token localmente com:
claude setup-token - Adicione-o em: GitHub repo → Settings → Secrets and variables → Actions → New repository secret
- Gere o token localmente com:
O que delegar a um humano (Integração com CI): O usuário deve adicionar o segredo CLAUDE_CODE_OAUTH_TOKEN e verificar se as regras de proteção de branch permitem que a ação poste comentários de revisão. A configuração não pode verificar ou configurar isso.
Se o usuário aceitar todos os padrões e nenhuma escolha for feita, confirme que nenhum arquivo de regras é necessário e pare.
Fase 0: Estado de Revisão Anterior (re-revisões)
Antes de revisar, descubra o que já foi dito.
Reúna a conversa de revisão existente sobre esta alteração:
- Todas as threads de discussão inline, incluindo respostas e seu estado resolvido/não resolvido — tanto suas quanto de revisores humanos.
- Seu próprio resumo de revisão anterior, se existir (identificado por seu marcador oculto — veja a Fase 6).
Se seu projeto define mecânicas de postagem de plataforma, use-as para buscar este estado. Se nenhuma mecânica de plataforma estiver configurada (por exemplo, a revisão vai para stdout), trate isso como uma primeira revisão e observe no resumo que o estado da revisão anterior não pôde ser verificado.
Se nenhum estado de revisão anterior existir, esta é uma primeira revisão — prossiga para a Fase 1 e pule as etapas de re-revisão na Fase 6.
Leia cada thread; aja apenas nas suas. As threads dos revisores humanos informam a revisão — nunca levante uma preocupação que um revisor humano já levantou, seja ela respondida ou não. Identifique suas próprias threads pelo marcador oculto incorporado em cada descoberta que você postar (veja a Fase 6), nunca pela conta de postagem — a conta difere entre execuções de CI e locais.
Para cada uma de suas próprias descobertas anteriores, classifique-a e leve a disposição para o resto da revisão:
- Correção enviada — o autor alterou o código em resposta. Verifique a correção no diff atual durante a revisão. Realmente corrigido: responda na thread confirmando (por exemplo, "Correção verificada em <revisão>") e resolva a thread. Reivindicado mas não corrigido: responda explicando o que ainda está faltando e deixe a thread aberta.
- Respondida — o autor explicou ou contestou a descoberta. A resposta deles é autoritativa; não reabra. Responda reconhecendo e resolva a thread.
- Ainda aberta — sem resposta, sem correção. Não poste um comentário duplicado. Deixe a thread intocada e liste-a sob "Descobertas anteriores" no novo resumo.
Novas descobertas genuínas desta revisão são postadas normalmente na Fase 6.
Se seu projeto configura um modo de tratamento de threads de re-revisão (veja Configuração), siga-o — algumas equipes reservam a resolução de threads para humanos. O padrão é responder e resolver.
O que delegar a um humano: Julgar disputas — quando um autor contesta, esta habilidade se retira; se o ponto disputado ainda for importante, um revisor humano deve decidir. Se um revisor automatizado pode ou não resolver threads é uma convenção da equipe — humanos são responsáveis por isso (configure via Configuração).
Fase 1: Validação do Problema
Comece aqui — antes de ler uma única linha de código.
Faça duas perguntas:
- Este código realmente resolve o problema que se propõe a resolver?
- O envio desta melhoria aumentará o valor do projeto como um todo?
Se a resposta para qualquer uma for não — pare. Não revise o código. Entre em contato com quem decide o que será construído e discuta o assunto. Revisar código que não sobreviverá em produção é perda de tempo.
Para responder a estas perguntas: leia o issue ou ticket vinculado, a documentação de apoio e qualquer discussão relevante. Se seu projeto define como localizar o issue ou ticket relevante (integração com gerenciamento de tarefas, convenções de nomeação de branch), siga isso. Se nenhum issue existir ou nenhuma integração estiver configurada, use o título e a descrição do PR como fonte da verdade. Verifique se o diff aborda plausivelmente o que foi descrito.
O que delegar a um humano: Executar a funcionalidade de fato e verificar se ela funciona da perspectiva do usuário. Você pode validar o alinhamento lógico entre o problema declarado e o diff; um humano deve verificar se realmente funciona.
Fase 2: Build & Executabilidade
- O build está passando? Se não, pause a revisão. Um build quebrado não é confiável. Mesmo que a nova alteração funcione corretamente, outras coisas podem estar quebradas. Não assuma que uma falha de build é inócua.
- O código está sendo executado em algum lugar que não seja a máquina do autor? Um ambiente de produção é ideal; um ambiente de staging ou outra máquina do desenvolvedor é um teste de fumaça aceitável.
- Foi necessário pedir ajuda a alguém para executar o código? Se sim, a documentação está faltando ou a configuração precisa ser automatizada — ou ambos.
Se seu projeto define como verificar o status do build (sistema de CI, verificações de status), use isso. Caso contrário, verifique se há indicadores de build disponíveis no contexto da alteração.
O que delegar a um humano: Executar o código localmente ou em staging, testar a funcionalidade da perspectiva das pessoas que a usarão e levantar quaisquer preocupações sobre usabilidade, tratamento de erros ou comportamento surpreendente.
Fase 3: Auditoria de Testes
Testes modificados ou excluídos são uma bandeira vermelha — investigue antes de qualquer outra coisa.
Ao ver alterações em testes existentes, vá devagar. Pergunte: por que eles foram modificados? Entenda o motivo antes de formar qualquer opinião.
Muitas modificações são relativamente inocentes — remover um teste para um comportamento que era incorreto, alterar a granularidade do teste ou substituir algo que este PR substitui. Nada disso é inerentemente perigoso, mas requer reflexão. A questão principal é: esta modificação altera um contrato do qual outras partes do código dependem?
- Alterações em testes para código isolado e autocontido = relativamente seguro
- Alterações em testes para código compartilhado ou reutilizado = risco maior; precisa de justificativa explícita
Se você não conseguir responder à pergunta apenas com o diff, pause e pergunte ao autor. Essas conversas constroem entendimento compartilhado e revelam suposições equivocadas antes que causem danos reais.
Fase 4: Avaliação de Cobertura
Categorize a alteração e aplique expectativas apropriadas ao risco. Um conjunto de testes aprovado é tão bom quanto os comportamentos que descreve — você não pode automatizar o processo de revisão de testes.
Correção de Bug
Toda correção de bug deve ser acompanhada de testes de regressão. No mínimo, um teste de aceitação de alto nível que siga o mesmo caminho descrito no relatório de bug — mapeando para ações que um usuário real poderia tomar, não apenas um gatilho direto da falha interna.
Testes de unidade devem complementar os testes de aceitação para qualquer coisa complexa ou grave, para fornecer feedback mais granular quando algo quebrar no futuro.
Também procure o padrão de canário na mina: este bug é verdadeiramente único, ou é um sinal de um problema mais profundo e generalizado? Verifique se padrões semelhantes existem em outras partes do código. Se existirem, registre tickets — você não precisa corrigi-los todos agora, mas trazê-los à tona é uma contribuição importante.
Nova Funcionalidade
Aplique o experimento mental de zero teste: se todas as seguintes condições forem atendidas, a cobertura mínima de teste é aceitável:
- A alteração consiste quase inteiramente de código novo, dependendo apenas de infraestrutura, frameworks, bibliotecas e objetos de acesso a dados genéricos
- A nova funcionalidade está isolada em sua própria área (sua própria página, namespace ou endpoint)
- Não introduz novos efeitos colaterais em todo o sistema (sem dependências alteradas, configurações ou carga em recursos compartilhados)
- Não está planejada para ser usada como bloco de construção para outras funcionalidades no roadmap
- Não é uma etapa intermediária em uma cadeia de workflow que conecta outros recursos
- As falhas não podem escapar para fora e causar instabilidade em outro lugar
- Qualquer falha concebível seria aceitável para as partes interessadas e não causaria danos significativos
- Testes poderiam ser escritos posteriormente sem custo ou atraso inaceitáveis
Para cada condição que não for atendida, espere testes que abordem especificamente esse risco. Um recurso que pode falhar, totalmente isolado e fácil de testar depois não é um risco importante. Um recurso que se conecta a workflows existentes, pode causar falhas em outro lugar ou será ampliado — é.
Melhoria: Extensão
Código novo que coexiste com uma funcionalidade existente. Aplique os critérios de nova funcionalidade acima e vá além: como ele coexiste com a funcionalidade existente, o isolamento de falhas é a principal preocupação.
Uma falha na extensão pode derrubar a funcionalidade existente? Pense nos piores cenários de falha. Os casos de borda e condições de contorno estão cobertos?
Melhoria: Extensão
Constrói sobre comportamento existente reutilizando componentes existentes. Antes de avaliar o código novo, conduza uma mini-auditoria do que está sendo reutilizado:
- Os componentes reutilizados têm testes?
- Eles estão documentados no nível de negócios e/ou código?
- Eles foram projetados pensando em reutilização, ou estão sendo esticados além de seu propósito original?
- Eles apareceram em relatórios de bugs recentes ou não resolvidos?
- Qual a probabilidade de mudarem? Se mudarem, isso quebrará esta extensão?
Você não precisa gastar mais do que alguns minutos nisso — é um experimento mental, não uma investigação aprofundada. Mas riscos conhecidos e calculados são sempre melhores do que surpresas. Registre tickets para qualquer coisa que valha a pena rastrear.
Melhoria: Refinamento
Modifica o comportamento existente do sistema. Categoria de maior risco. Comece aplicando tudo da revisão de extensão acima. Depois, vá além.
Encontre todas as funcionalidades que dependem do código que está sendo modificado. Cada dependente está potencialmente afetado. Idealmente, você executaria cada um através do processo de revisão completo, mas na prática isso raramente é viável. No mínimo: identifique os dependentes, verifique se seus testes ainda são válidos e sinalize a lista completa para o revisor humano testar manualmente.
Fase 5: Verificações Específicas do Projeto
Se seu projeto define convenções de codificação, padrões de arquitetura ou regras de estilo, aplique-as ao diff e verifique violações.
Se nenhuma convenção de projeto for definida, verifique: nomenclatura inconsistente dentro do diff, código morto introduzido pela alteração, duplicação óbvia, tratamento de erros ausente nos limites do sistema e preocupações de segurança (entrada não sanitizada, segredos codificados, permissões excessivamente amplas).
Se seu projeto definiu mecânicas de postagem específicas da plataforma (como postar uma revisão, formato para comentários inline, etc.), siga-as na próxima fase.
Fase 6: Avaliação de Risco e Saída
Atribua um nível de risco:
- Baixo — alteração isolada, nenhum código compartilhado tocado, testes limpos e apropriados para o tipo de alteração
- Médio — toca comportamento existente ou código compartilhado, mas bem testado e as dependências são compreendidas
- Alto — modifica componentes compartilhados com dependentes, testes alterados ou ausentes para o tipo de alteração, segurança ou autenticação envolvida
Produza um resumo da revisão que inclua:
- Contexto: o que o PR faz, qual problema resolve
- O que está bom
- Preocupações encontradas (gerais e em nível de linha, quando aplicável)
- Em uma re-revisão: uma seção Descobertas anteriores listando cada uma de suas descobertas anteriores com seu status — resolvida (correção verificada), respondida (resposta do autor aceita) ou ainda aberta — antes das novas preocupações. Revisões pela primeira vez omitem esta seção.
- Nível de risco e justificativa
**Produza uma revisão...