CommunityEscrita e Ediçãogithub.com

Habilidades Claude - Code Review

Uma metodologia de revisão de código orientada a riscos, baseada no livro 'Effective Code Reviews' de Gregory Brown, para uso com claude.ai.

O que é Habilidades Claude - Code Review?

Esta skill implementa uma metodologia de revisão de código abrangente e estruturada, inspirada nas práticas de Gregory Brown descritas em 'Programming Beyond Practices' (2015). O objetivo é realizar revisões de código eficientes e orientadas a riscos, começando pela validação do problema que o código se propõe a resolver, antes mesmo de ler uma única linha de código. A skill suporta múltiplas plataformas de revisão, incluindo GitHub, GitLab e Bitbucket, e pode ser configurada para postar comentários inline ou gerar relatórios em stdout. Ela também oferece integração com CI/CD através de um workflow do GitHub Actions, permitindo revisões automáticas em cada Pull Request. Durante a configuração, o usuário pode personalizar aspectos como coleta de contexto, verificação de build, convenções de código, formato de saída e tratamento de threads em re-revisões. A skill é particularmente útil para equipes que desejam automatizar e padronizar o processo de revisão de código, garantindo que todas as alterações sejam avaliadas de forma consistente e que os riscos sejam identificados e mitigados precocemente.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add Agilefreaks/claude-skills

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  1. 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.
  2. 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.
  3. 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.
  4. Escreva .claude/rules/code-review.md contendo 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.
  5. 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 opus por --model <modelo-escolhido> se o usuário escolheu um modelo diferente. c. Se .github/workflows/code-review.yml já 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 adicionar CLAUDE_CODE_OAUTH_TOKEN como 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

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:

  1. 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.
  2. Respondida — o autor explicou ou contestou a descoberta. A resposta deles é autoritativa; não reabra. Responda reconhecendo e resolva a thread.
  3. 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:

  1. Este código realmente resolve o problema que se propõe a resolver?
  2. 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:

  1. A alteração consiste quase inteiramente de código novo, dependendo apenas de infraestrutura, frameworks, bibliotecas e objetos de acesso a dados genéricos
  2. A nova funcionalidade está isolada em sua própria área (sua própria página, namespace ou endpoint)
  3. Não introduz novos efeitos colaterais em todo o sistema (sem dependências alteradas, configurações ou carga em recursos compartilhados)
  4. Não está planejada para ser usada como bloco de construção para outras funcionalidades no roadmap
  5. Não é uma etapa intermediária em uma cadeia de workflow que conecta outros recursos
  6. As falhas não podem escapar para fora e causar instabilidade em outro lugar
  7. Qualquer falha concebível seria aceitável para as partes interessadas e não causaria danos significativos
  8. 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...

Habilidades Relacionadas