Code Review and Quality

ANÁLISE EDITORIAL

Code Review and Quality é uma Agent Skill para revisar mudanças de código antes do merge por cinco eixos: correção, legibilidade, arquitetura, segurança e desempenho. Em vez de produzir uma lista solta de preferências, ela organiza contexto, testes, implementação, gravidade dos achados e evidências de verificação.

A versão auditada pertence ao repositório addyosmani/agent-skills, commit be42637. Em 13 de agosto de 2026, às 14:03 no fuso America/Sao_Paulo, a API pública do GitHub registrava 86.824 estrelas. O repositório usa licença MIT.

Imagem editorial exclusiva do Bastidores da IA. Não é captura de tela, interface real nem prova de que uma revisão foi aprovada.

O que esta Skill faz de verdade

O SKILL.md auditado define um processo de revisão em cinco passos. Primeiro, o agente precisa entender objetivo, especificação e mudança esperada. Depois lê os testes para inferir comportamento e cobertura. Só então percorre a implementação pelos cinco eixos, classifica cada achado e verifica o que o autor realmente executou para sustentar a entrega.

O eixo de correção procura casos de borda, caminhos de erro, inconsistências de estado, condições de corrida e testes que não demonstram o comportamento prometido. Legibilidade examina nomes, fluxo, duplicação, condicionais repetidas e abstrações que custam mais do que entregam. Arquitetura observa fronteiras, dependências, responsabilidade de módulos e refatorações que apenas deslocam complexidade.

Segurança inclui validação de entrada, autenticação, autorização, segredos, consultas parametrizadas, saída codificada e tratamento de dados externos como não confiáveis. Desempenho procura consultas N+1, operações sem limite, paginação ausente, trabalho síncrono indevido e objetos grandes em caminhos críticos. A Skill não executa um scanner nem mede automaticamente cada risco. Ela cria perguntas e gates para uma revisão sustentada por código, testes e medições.

Para quem serve

Serve para desenvolvedores, líderes técnicos e equipes que usam agentes para escrever ou revisar código e precisam de uma estrutura repetível antes de aprovar uma mudança. É especialmente útil quando o diff veio de outra pessoa, de outro agente ou de um modelo que produziu código plausível, mas ainda não demonstrou aderência à especificação.

A finalidade é diferente das duas Skills de revisão já presentes no catálogo. Superpowers Requesting Code Review prepara o pedido, com escopo, risco e evidências. Superpowers Receiving Code Review ajuda o autor a interpretar e tratar comentários recebidos. Code Review and Quality ocupa a etapa central: lê a mudança, produz achados priorizados e propõe um veredito. As três podem compor um fluxo, mas não resolvem o mesmo problema.

Ela não substitui conhecimento do domínio, revisão humana responsável, ferramentas de análise estática, testes, avaliação de dependências ou aprovação de segurança. Um checklist generalista pode revelar sinais importantes, mas não conhece sozinho regras de negócio, dados reais, tolerância a risco nem o desenho aprovado da sua organização.

Compatibilidade e pré-requisitos

O README fixado no commit documenta uso por Skills CLI, Claude Code, Cursor, Gemini CLI, Windsurf, OpenCode, GitHub Copilot, Kiro e Codex. Para Codex, o mantenedor declara plugin nativo a partir do Codex CLI 0.122. Em qualquer cliente, compatibilidade real depende de o agente carregar o SKILL.md, receber acesso ao repositório e ter ferramentas adequadas para ler diffs e executar verificações autorizadas.

Antes do primeiro uso, tenha uma mudança delimitada, o objetivo ou especificação, convenções do projeto e os comandos de teste relevantes. A Skill pode avaliar melhor quando o agente conhece o comportamento esperado. Sem isso, há risco de confundir preferência pessoal com defeito ou aprovar algo que parece correto fora do contexto.

O arquivo principal cita duas referências compartilhadas do repositório: um checklist de segurança e outro de desempenho. O próprio README alerta que a instalação isolada pelo Skills CLI copia apenas a pasta da Skill e não inclui essas referências. O pacote auditado do Bastidores preserva os dois Markdown dentro de references/, junto do SKILL.md, LICENSE e ORIGEM.md. Nenhum executável, script, binário, pacote, token ou credencial foi incluído.

Instalação recomendada

Para avaliar somente esta Skill com o instalador universal indicado pelo mantenedor, comece em um projeto descartável:

npx skills add addyosmani/agent-skills --skill code-review-and-quality

Esse comando acessa a rede e grava arquivos. Leia a origem do pacote, mantenha a confirmação interativa e confira a pasta criada antes de permitir que o agente use o conteúdo. A instalação isolada pode deixar indisponíveis os checklists compartilhados, conforme a lacuna de portabilidade registrada pelo próprio projeto.

No Codex, o README também apresenta a instalação do plugin completo:

codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

O plugin reúne outras Skills, comandos e componentes do repositório. Portanto, não use esse caminho como se instalasse somente Code Review and Quality. Revise o manifesto e o conjunto incluído, fixe a versão aprovada quando o cliente permitir e mantenha a primeira execução limitada a um repositório de teste.

Configuração antes do primeiro uso

Defina o escopo que o agente pode ler. Para uma revisão de pull request, forneça a especificação, o diff, os testes alterados e somente os arquivos necessários para entender as fronteiras afetadas. Acesso a todo o repositório pode ser necessário em mudanças arquiteturais, mas amplia a exposição de código, configuração e possíveis segredos.

Escolha também quais comandos podem ser executados. Ler arquivos e produzir comentários é diferente de rodar testes, instalar dependências, abrir rede, editar código ou remover trechos mortos. A Skill manda identificar código sem uso e perguntar antes de excluir. Preserve essa separação: uma revisão não deve virar correção automática sem autorização.

Se o projeto usa um modelo remoto, confirme a política para código proprietário e dados de clientes. O padrão de revisão com modelos diferentes pode ampliar a diversidade da análise, mas também pode enviar o mesmo conteúdo para mais de um provedor. Use essa opção somente quando contratos, retenção, região e classificação da informação permitirem.

Primeiro uso seguro

Comece com uma mudança pequena, conhecida e sem segredo. Um pedido útil inclui objetivo, limite e forma de saída:

Revise este diff antes do merge.
Especificação: corrigir o cálculo de desconto sem mudar a API pública.
Priorize correção e segurança.
Leia os testes primeiro.
Não altere arquivos nem execute comandos sem pedir.
Classifique os achados e cite arquivo e linha.

O resultado esperado é uma lista curta de achados acionáveis, ordenada por impacto. Cada problema deve dizer o que pode falhar, em qual condição e qual mudança ou teste reduziria o risco. Comentários cosméticos precisam ficar separados de bloqueios. Se nenhum defeito material for encontrado, o agente deve explicar o que revisou e quais verificações não conseguiu executar, em vez de responder apenas “aprovado”.

As referências incluídas ampliam o checklist, mas alguns números são sinais de investigação, não regras universais. Tamanho de diff, limite de arquivo, tempo de resposta ou métrica de desempenho precisam ser avaliados no contexto do sistema. Um arquivo grande pode ser gerado ou exigir divisão. Um endpoint pode ter objetivo diferente do valor citado. Meça antes de transformar uma heurística em bloqueio.

Permissões e riscos

O pacote local contém somente texto, mas as instruções podem levar o agente a ler código, testes, manifestos, lockfiles, changelogs e relatórios de build. Conforme as ferramentas conectadas, o agente também pode tentar executar testes, auditorias de dependência ou consultas externas. Instalar a Skill não concede essas permissões por si só, mas o runtime do agente pode já tê-las.

A referência de segurança inclui comandos e políticas que mudam com versões de npm, pnpm e Yarn. Ela mesma trata o quadro como retrato temporal e manda consultar a documentação oficial do gerenciador fixado. Não aplique uma regra de outra versão nem execute correção automática de vulnerabilidades em produção.

A referência de desempenho cita Core Web Vitals, limites e comandos para Lighthouse e análise de bundle. Esses exemplos podem baixar pacotes, acessar rede, criar relatórios e consumir recursos. Rode apenas no ambiente correto, com a versão aprovada e sem expor URLs privadas ou dados de produção.

Há ainda o risco de excesso de confiança. Cinco eixos bem escritos não provam ausência de defeitos. Uma revisão depende da qualidade da especificação, do código visível, das ferramentas disponíveis e da capacidade do modelo de seguir fluxos entre arquivos. Achado plausível precisa ser confirmado. Ausência de achado precisa ser tratada como limite da revisão, não como certificação.

Erros comuns

A Skill foi instalada, mas as referências não abrem

A instalação de uma única Skill pode não copiar os arquivos compartilhados do repositório. Use o pacote documental do Bastidores para consultar os dois checklists preservados ou adote a integração completa após revisar seu escopo. Não altere silenciosamente os caminhos no arquivo original sem registrar a mudança.

A revisão devolve dezenas de observações sem prioridade

Peça para ordenar por correção, segurança, regressão estrutural e simplificação. Exija condição de falha e evidência. Preferência de estilo deve ser marcada como opcional ou nit. Um problema real não pode ficar escondido sob comentários cosméticos.

O agente tenta corrigir durante a revisão

Separe os modos. Primeiro produza o relatório, depois decida quais mudanças estão autorizadas. Código morto, dependências, testes ou refatorações podem parecer óbvios e ainda assim ter consumidores fora do diff. Revisão não é permissão automática para editar ou excluir.

Os testes passaram e o agente aprovou sem ler o contexto

Testes são evidência necessária, mas podem não cobrir regra de negócio, autorização, dados externos ou arquitetura. Forneça a especificação e pergunte quais riscos continuam fora da suíte. O objetivo é melhorar a saúde geral do código, não transformar verde no CI em carimbo automático.

Versão auditada e download local

O pacote local corresponde ao commit be42637c5af93fdc8526b68ec2f2651b930f316c. Ele contém cinco arquivos permitidos: SKILL.md, LICENSE, ORIGEM.md e os dois checklists Markdown citados. Tamanho do ZIP: 19.210 bytes. SHA-256: 2f9a1bcc7d1da141bf53a27e1bf22be8fa93a46ece40dde40f2f1a84458f0e99.

O download do Bastidores é uma cópia auditável para leitura e comparação. Ele não substitui o repositório oficial, não atualiza sozinho e não inclui instalador. Antes de instalar ou atualizar, compare o commit, leia o diff e repita a revisão de licença, referências e permissões.

Resultado esperado e limite final

Usada com contexto, a Skill ajuda a transformar uma revisão vaga em um gate compreensível: intenção identificada, testes examinados, implementação percorrida por cinco eixos, achados priorizados e verificação documentada. O resultado útil não é uma lista longa, mas poucos comentários que expliquem risco, condição e remédio.

O limite final é humano e técnico. A Skill pode disciplinar a leitura, mas não conhece todo o sistema, não mede o que não foi executado e não assume responsabilidade pelo merge. Trate o veredito como uma contribuição para a decisão, confirme os pontos materiais no código e mantenha um responsável humano para aceitar risco e promover a mudança.

Fontes primárias

• Pasta oficial da Skill no commit auditado.
• README oficial com instalação e compatibilidade.
• Licença MIT do repositório.
• Issue oficial sobre referências ausentes na instalação isolada.
• Documentação oficial do GitHub sobre Agent Skills.