code-reviewer

Visão geral da skill code-reviewer

O que a skill code-reviewer faz

A skill code-reviewer é um fluxo estruturado de revisão de PR e diff para tarefas de Code Review. Em vez de depender de um prompt genérico de uma linha como “review this code”, ela leva o agente a levantar os arquivos alterados, inspecionar o diff, entender os padrões locais do projeto e então revisar as mudanças em categorias concretas, como correção, segurança, performance, testes e manutenibilidade.

Quem deve instalar a code-reviewer

A code-reviewer skill é mais indicada para desenvolvedores, tech leads e revisores assistidos por IA que querem mais consistência do que um prompt genérico normalmente entrega. Ela é especialmente útil se você revisa pull requests com frequência, quer achados classificados por severidade ou precisa de um checklist repetível que cubra tanto problemas de lógica quanto riscos mais altos de segurança.

O trabalho real que ela resolve

A maioria dos usuários não quer apenas “feedback”. Quer uma revisão capaz de responder: o que mudou, o que é arriscado, o que deve bloquear o merge, o que pode esperar e quais evidências sustentam cada ponto. O fluxo de code-reviewer foi construído em torno dessa necessidade ao separar a coleta de contexto da análise, o que reduz comentários rasos baseados apenas em trechos soltos de código.

O que diferencia esta skill

O principal diferencial está na estrutura da revisão. O repositório não para em uma instrução ampla para inspecionar código. Ele inclui:

• um processo de revisão em fases
• um formato de saída orientado por severidade
• referências focadas para checklist, padrões de código e revisão de segurança
• um script auxiliar em scripts/review_checklist.py para gerar um checklist de revisão a partir das mudanças no Git

Isso torna code-reviewer for Code Review mais acionável do que um prompt simples e mais fácil de adaptar às práticas de revisão da equipe.

Quando a code-reviewer encaixa muito bem

Use code-reviewer quando você tiver:

• um diff de branch em relação à main
• um PR com vários arquivos ou mudanças transversais
• necessidade de separar bloqueios de merge de melhorias opcionais
• alterações sensíveis em segurança, como auth, tratamento de entrada ou acesso a dados
• uma base de código em que os padrões existentes importam tanto quanto boas práticas abstratas

Quando o encaixe é mais fraco

Esta skill é menos útil quando:

• não há diff nem conjunto de arquivos para inspecionar
• você quer apenas observações de estilo
• a tarefa é de arquitetura, não de code review
• o contexto do repositório não está disponível, então não dá para comparar padrões
• o pedido na prática é de debugging, reescrita ou planejamento de feature

Como usar a skill code-reviewer

Contexto de instalação da skill code-reviewer

O SKILL.md upstream não publica um comando direto de instalação, mas a skill fica em zhaono1/agent-playbook, dentro de skills/code-reviewer. Se o seu runtime de skills suporta instalação via GitHub a partir de um caminho do repositório ou de uma coleção, instale a partir desse repositório e selecione a skill code-reviewer.

Um padrão comum é:

npx skills add https://github.com/zhaono1/agent-playbook --skill code-reviewer

Se o seu ambiente usa outro instalador, o detalhe mais importante é o slug da skill: code-reviewer.

Leia estes arquivos primeiro antes de depender dela

Para o caminho mais rápido de avaliação, leia:

1. skills/code-reviewer/SKILL.md
2. skills/code-reviewer/README.md
3. skills/code-reviewer/references/checklist.md
4. skills/code-reviewer/references/security.md
5. skills/code-reviewer/references/patterns.md
6. skills/code-reviewer/scripts/review_checklist.py

Essa ordem importa. O SKILL.md mostra como o fluxo é acionado, as referências deixam claro quais padrões ele aplica, e o script revela como o fluxo espera reunir evidências do repositório.

Que entradas a code-reviewer precisa para funcionar bem

O uso de code-reviewer fica mais forte quando você fornece:

• a branch base, geralmente main
• o objetivo do PR ou o ticket vinculado
• os arquivos alterados ou o diff completo
• quais áreas de risco mais importam para você
• o contexto de framework ou linguagem
• se você quer uma passada rápida ou uma revisão voltada a bloquear merge

Sem isso, a revisão ainda pode rodar, mas tende a ficar genérica.

Como a skill reúne contexto de revisão

O repositório deixa explícito o fluxo de revisão esperado:

• obter os arquivos alterados com git diff main...HEAD --name-only
• inspecionar o histórico de commits com git log main...HEAD --oneline
• inspecionar o diff real com git diff main...HEAD
• ler documentação próxima e arquivos semelhantes para entender convenções locais

Isso é importante porque muitas revisões fracas feitas por IA pulam a coleta de contexto e vão direto para boas práticas abstratas. Esta skill funciona melhor quando primeiro se ancora no que de fato mudou.

Um template prático de prompt para code-reviewer

Use um prompt mais próximo disto:

Review this branch with the code-reviewer skill.

Base branch: main
Goal: add password reset flow for users
Priority areas: security, correctness, test gaps
Constraints: keep current API shape, do not request large refactors
Please classify findings by severity: critical, high, medium, low.
For each finding, cite the file, explain the risk, and suggest the smallest safe fix.

Isso funciona melhor do que “review my code” porque informa à skill o alvo da branch, a intenção de negócio, as prioridades da revisão e o formato esperado de feedback.

Entradas mais fortes vs. entradas mais fracas

Entrada fraca:

Review this PR

Entrada mais forte:

Use code-reviewer on the diff against main.
Focus on auth flows, input validation, and regression risk.
Check whether tests cover unhappy paths and whether any existing project patterns were broken.
Flag only issues that are actionable before merge unless clearly marked as low severity.

A versão mais forte melhora materialmente a qualidade da saída porque restringe o escopo da revisão, nomeia as áreas de risco e diz ao agente quão opinativo ele deve ser.

Fluxo recomendado para revisão real de PR com code-reviewer

Um code-reviewer guide prático se parece com isto:

1. Levante os arquivos alterados e o diff.
2. Leia a descrição do PR ou o ticket.
3. Consulte arquivos adjacentes para aprender as convenções.
4. Faça a revisão por categoria: correção, segurança, performance, qualidade de código, testes, documentação e manutenibilidade.
5. Agrupe os achados por severidade.
6. Peça uma segunda passada nos arquivos de maior risco se a primeira revisão encontrar problemas sérios.

Esse padrão em duas passadas funciona bem porque a primeira encontra riscos amplos e a segunda melhora a precisão.

Use as referências para deixar a revisão menos genérica

Os arquivos de apoio são o principal motivo para escolher esta skill em vez de um prompt comum:

• references/checklist.md mantém a revisão sistemática
• references/security.md adiciona checagens orientadas por OWASP
• references/patterns.md traz exemplos concretos de implementações boas e ruins

Se uma revisão parecer vaga, peça ao agente para aplicar explicitamente uma ou mais dessas referências durante a análise do diff.

Use o script auxiliar quando quiser um esqueleto de revisão

O repositório inclui:

python scripts/review_checklist.py

Isso é útil se você quer um checklist gerado por máquina a partir do estado atual do Git antes de pedir ao agente achados em formato narrativo. É uma ponte prática entre a inspeção bruta do diff e uma revisão escrita completa.

Formato de saída que funciona melhor na prática

Peça que a skill retorne:

• um resumo curto do que mudou
• bloqueios de merge primeiro
• achados agrupados por severidade
• referências em nível de arquivo
• justificativa, não apenas vereditos
• uma avaliação final de “safe to merge?” com ressalvas

Esse formato de saída combina com o modelo de severidade do repositório e torna a revisão mais fácil de usar em fluxos reais de equipe.

FAQ da skill code-reviewer

A code-reviewer é melhor do que um prompt normal de revisão?

Em geral, sim, se você tiver contexto real do repositório. O valor de code-reviewer não está apenas em uma profundidade “mágica” de análise. Ele vem da combinação entre sinais de ativação, fluxo em fases, cobertura por checklist e material de referência, que empurra a revisão para mais completude e consistência.

A code-reviewer é amigável para iniciantes?

Sim, com uma ressalva: iniciantes ainda precisam fornecer contexto. A skill oferece uma estrutura forte, mas não consegue inferir requisitos, comportamento esperado ou convenções da equipe do nada. Usuários novos terão resultados melhores se incluírem logo de início o objetivo do PR e a branch base.

A code-reviewer só funciona para pull requests?

Não. O uso de code-reviewer também se aplica a diffs de branch local, a um conjunto de arquivos alterados ou a um pedido de revisão por pasta, como “review the code in src/auth/”. Ainda assim, ela fica mais forte quando existe um diff claro em relação a uma branch base conhecida.

Que tipos de problema a skill code-reviewer procura?

As evidências do repositório mostram cobertura para:

• correção e edge cases
• problemas de segurança, incluindo preocupações no estilo OWASP
• problemas de performance, como queries ou chamadas desnecessárias
• qualidade de código e manutenibilidade
• lacunas de teste
• lacunas de documentação

Essa amplitude a torna adequada para revisão geral de PR, e não apenas para revisão de segurança ou de estilo.

Quando eu não devo usar code-reviewer?

Evite code-reviewer quando a tarefa for principalmente:

• gerar código novo
• depurar uma falha em runtime
• planejar arquitetura em larga escala
• fazer apenas limpeza de formatação ou lint
• revisar código sem acesso ao contexto alterado

Nesses casos, uma skill mais especializada ou um prompt direto focado na tarefa tende a encaixar melhor.

Ela impõe um único estilo de código?

Não. O repositório incentiva verificar padrões já existentes em arquivos semelhantes antes de julgar a mudança. Isso é um bom sinal para adoção, porque reduz recomendações genéricas que entram em conflito com convenções locais.

Como melhorar a skill code-reviewer

Dê à code-reviewer a intenção por trás da mudança

O maior ganho de qualidade vem de explicar o que o código deveria fazer. A qualidade da revisão cai rápido quando o agente vê apenas a implementação. Inclua o resumo do ticket, critérios de aceitação ou uma nota curta explicando a intenção para que a skill consiga julgar correção, e não só estilo e sintaxe.

Restrinja as áreas de revisão de maior risco

Se o que mais importa para você é auth, billing, migrations ou concorrência, diga isso. A skill já cobre várias categorias, mas prioridades bem definidas aumentam a profundidade onde ela realmente importa. Isso é especialmente importante em PRs maiores, em que uma revisão ampla demais pode ficar superficial.

Forneça contexto suficiente do repositório para comparar padrões

Este repositório orienta explicitamente o revisor a buscar convenções existentes. Ajude indicando arquivos ou módulos comparáveis:

Compare the new handler to the existing patterns in src/api/users/ and src/api/sessions/.
Prefer consistency with those files unless there is a clear bug.

Isso reduz falsos positivos e torna as sugestões mais fáceis de adotar.

Peça apenas achados baseados em evidência

Um modo comum de falha em revisões com IA é a crítica especulativa. Melhore a saída de code-reviewer definindo uma regra como:

Only report an issue if you can point to a specific file change, missing case, or concrete risk. Avoid hypothetical style advice unless it affects maintainability or correctness.

Isso mantém a revisão com alto sinal e pouco ruído.

Divida revisões grandes em passadas

Para PRs grandes, não peça tudo de uma vez. Use passadas em etapas:

1. correção e segurança
2. performance e manutenibilidade
3. testes e documentação

Isso espelha a estrutura por categorias da skill e costuma produzir achados melhores do que uma solicitação única e sobrecarregada.

Peça recomendações de correção menores

Se a primeira saída estiver abstrata demais, peça para a skill reescrever os achados como correções mínimas e seguras:

Revise the review. For each high or critical issue, suggest the smallest code change or test addition that would reduce the risk before merge.

Isso deixa a revisão mais acionável para equipes ocupadas.

Fique atento aos modos de falha mais comuns

As formas mais comuns de a saída da code-reviewer skill ficar fraca são:

• nenhuma branch base especificada
• nenhum diff fornecido
• nenhuma explicação do comportamento pretendido
• PRs enormes sem prioridades
• nenhuma referência a padrões do projeto
• pedir “tudo” e receber de volta conselhos genéricos

Na maioria dos casos, esses são problemas de entrada, não da skill.

Use explicitamente o checklist e as referências de segurança

Se a primeira revisão vier ampla demais, peça uma segunda passada usando referências específicas do repositório:

• references/checklist.md para completude
• references/security.md para mudanças sensíveis
• references/patterns.md para consistência e detecção de anti-patterns

Essa é uma das formas mais simples de melhorar o code-reviewer guide no uso do dia a dia.

Itere depois da primeira revisão

Um bom segundo prompt é:

Now re-review only the files with high-severity findings.
Assume the author wants merge-blocking issues only.
Double-check whether each finding is a real defect, a security exposure, or a missing test that hides regression risk.

Esse follow-up muitas vezes elimina comentários de baixo valor e deixa a recomendação final mais precisa.

Adapte a code-reviewer ao fluxo da sua equipe

Se você pretende adotar code-reviewer com frequência, alinhe a skill à cultura de merge do seu time:

• defina o que conta como blocker vs suggestion
• deixe claro qual é a convenção de branch base
• inclua suas expectativas de teste
• adicione checagens de segurança específicas da equipe
• aponte a skill para arquivos representativos do estilo local

É assim que você transforma um code-reviewer install em melhoria real de fluxo de trabalho, e não apenas em mais um atalho de prompt.