Skill de code review que só reporta falha demonstrada

TL;DR

• A regra que separa a skill da maioria das revisões com IA: nada é reportado sem falha demonstrada — todo achado nomeia a entrada, o estado ou a sequência que produz o resultado errado, e o que não se liga a um é descartado em silêncio.
• Ela revisa na ordem em que um sênior revisa de verdade: design, aderência à spec, correção, complexidade, testes, nomes, raio de impacto — porque problema de design é o caro.
• Ela lê os comentários já existentes no PR depois da própria auditoria, nunca antes, para não ser ancorada pelo enquadramento de outra pessoa.
• É um arquivo Markdown mais um arquivo de referência carregado sob demanda — cerca de 1.700 palavras de julgamento, não um checklist de 2.000 itens.

O que é e para quem

O Code Review Skill é uma skill de revisão de código para agentes de IA — Claude Code, Cursor, Codex, Gemini CLI e qualquer coisa que leia SKILL.md. O README descreve o alvo em uma linha: um agente, uma passada, cerca de 1.700 palavras.

É para quem parou de ler a saída de revisão de IA. O diagnóstico do README é que a maior parte da revisão automática produz um bloco de achados plausíveis em que metade é real e metade é chute, e o leitor não consegue distinguir — então para de ler. Esta skill faz a troca oposta.

O que ela faz diferente

Evidência ou silêncio. Sem cenário de falha, sem achado. Não existe apêndice de "problemas possíveis, não verificados" — esse apêndice é o ruído que o leitor estava evitando, com outro nome.

Nunca chuta onde consegue ler. Achado condicionado a pesquisa inacabada — "isso quebra a menos que o backend valide" — não vale quando o backend está ali no repositório.

Severidade honesta. Impacto vezes probabilidade, com piso explícito, porque um rótulo Critical num problema pequeno custa mais credibilidade do que o achado valia.

Design antes de detalhe. E aplica um contra-teste a toda refatoração: conte os conceitos que o leitor precisa segurar. Se a versão "mais limpa" deixa essa contagem igual, a complexidade foi movida de lugar, não reduzida.

Olhar novo primeiro. Comentários já existentes no pull request são lidos depois da auditoria, nunca antes, porque ler antes ancora o revisor e custa os achados que só olhar novo produz.

Só o escopo do diff. Problema pré-existente em arquivo não tocado não é achado.

As classes que escapam. Autorização checada no login mas não neste objeto específico. Aumento de escopo reportado como achado, não como bônus. Migração que não é reversível no meio do rollout. Variável de ambiente ou porta alterada que quebra o build local de todo mundo. Bump de dependência em massa sem ler o changelog.

Apaga os próprios achados fracos. Um passe final descarta o que o revisor não defenderia em voz alta para o autor — e o README diz que isso remove mais achados ruins do que qualquer checklist acrescenta bons.

Obedece ao seu repositório. CONTRIBUTING.md, CLAUDE.md, AGENTS.md, .cursor/rules/ e a config de lint superam a skill, e o que o linter ou o type checker já reporta sai da mesa.

Como usar

No Claude Code, pelo marketplace de plugins:

/plugin marketplace add artificialguybr/code-review-skill
/plugin install code-review

Para outro agente, a skill é um arquivo Markdown sem dependência, sem chave de API e sem serviço externo:

git clone https://github.com/artificialguybr/code-review-skill /tmp/crs
cp -r /tmp/crs/skills/code-review ~/.claude/skills/code-review   # ou .claude/skills para um projeto

O Cursor lê .cursor/skills/, o Codex .codex/skills/, o Gemini CLI .gemini/skills/ — mesmo diretório, destino diferente.

Depois peça no formato que você já usa:

review my changes
review this branch against main
review PR #418
is this safe to merge?
review my changes and fix what you find

Número de PR passa pelo gh. Caso contrário, a skill fixa o merge base com o seu branch de rastreio e revisa git diff <base>...HEAD com três pontos, para commit que caiu no branch base não poluir a revisão.

Por que ela é curta

A skill inteira são dois arquivos: skills/code-review/SKILL.md, sempre carregado, e references/traps.md, que traz defeitos por linguagem mais revisão de dependência e carrega só quando necessário. O argumento do README é que as skills de revisão mais pesadas não são as melhores, e que um checklist de 2.000 itens faz o modelo trabalhar a lista em vez de ler o código.

Aprovar como um colega

Duas regras cobrem o julgamento que ferramenta costuma errar. Aprove quando a mudança melhora de forma clara a saúde do código, mesmo imperfeita — "não é como eu teria escrito" não é defeito. Mas sem carimbo: um "LGTM" não merecido diz a todo mundo abaixo que a mudança foi checada quando não foi.

Nunca corrige por supressão. Quando a skill é pedida para corrigir os próprios achados, cada correção ganha o teste de regressão que teria pegado o problema, e nada de catch mais largo, regra de lint desativada ou asserção afrouxada.

Quando usar, quando não usar

Use para revisão real de um branch ou pull request, principalmente quando você quer saber quais dos achados são defeito de verdade, e quando o diff mexe em autorização, migração ou dependências, onde as classes que escapam são caras.

Não use como substituto de suíte de teste. A skill lê código e propõe o teste que teria pegado cada achado; ela não roda a sua suíte. E não espere que pegue problema pré-existente em arquivo que a mudança não toca — o limite de escopo é deliberado, e é o que mantém a revisão barata.

Sources

1. Code Review Skill — repositório — regras, ordem de revisão, comandos de instalação, estrutura de arquivo e licença citados acima.
2. README.md — comandos de instalação e uso, licença.

Página do projeto: Code Review Skill

A skill tem licença MIT e aceita issues e pull requests; a preferência declarada no README é uma regra que pegou um bug real, não uma que parece completa.

FAQ

Quanto tempo dura a revisão? Uma passada, cerca de 1.700 palavras de julgamento no SKILL.md, mais um arquivo de referência que carrega só quando aparece dúvida de linguagem ou de dependência.

Por que ela descarta achados? Porque achado que não se liga a falha demonstrada é chute; descartar é o que mantém o relatório legível, e o README diz que isso remove mais achado ruim do que um checklist acrescenta bom.

Ela lê os comentários já existentes no PR? Sim, mas só depois da própria auditoria, para não ser ancorada pelo enquadramento de outra pessoa.

Ela corrige o que encontra? Quando pedida, sim. Cada correção vem com o teste de regressão que teria pegado o achado, sem catch mais largo, regra de lint desativada ou asserção afrouxada.