requesting-code-review

Visão geral

O que esta skill faz

A skill requesting-code-review define um fluxo de trabalho claro e repetível para pedir que um subagente de revisão de código com IA inspecione suas alterações antes de elas serem incorporadas. Ela foi criada para projetos baseados em Git e ajuda você a:

• Decidir quando solicitar uma revisão (após tarefas, funcionalidades e antes do merge)
• Empacotar um contexto preciso para o revisor usando SHAs do Git e requisitos
• Manter o foco do revisor no diff de código, não no histórico privado da sua sessão
• Classificar o feedback por severidade para saber o que corrigir agora e o que pode ficar para depois

No fundo, requesting-code-review é sobre revisar cedo e revisar com frequência, para que problemas sejam identificados antes de se espalharem pelo código.

Para quem é

Esta skill é indicada se você:

• Trabalha com Git e cria regularmente branches de feature ou PRs
• Quer uma forma estruturada e repetível de pedir revisão de código assistida por IA
• Usa desenvolvimento orientado a subagentes (por exemplo, um agente dedicado code-reviewer)
• Se importa com prontidão para produção: correção, arquitetura, testes e alinhamento com a especificação

Ela é particularmente útil para:

• Desenvolvedores individuais que querem uma rede de segurança confiável
• Pequenas equipes sem revisores de código dedicados
• Projetos em que o histórico de commits e os diffs são a principal fonte da verdade

Quando não é uma boa opção

requesting-code-review pode não ser ideal se:

• Você não usa Git ou não tem acesso aos SHAs de commits
• Você quer ajuda geral de geração ou refatoração de código, e não revisão de alterações específicas
• Você não consegue fornecer um plano, especificação ou requisitos claros para as mudanças a serem revisadas

Nesses casos, pode ser melhor usar uma skill mais geral de codificação ou planejamento, em vez de um fluxo de trabalho focado em revisão.

Problemas que ela resolve

Sem um processo de revisão consistente, desenvolvedores frequentemente:

• Esquecem de pedir revisão em marcos importantes
• Compartilham contexto de menos (ou contexto demais com todo o histórico de sessão)
• Recebem feedback desestruturado e difícil de transformar em ações

A skill requesting-code-review resolve esses problemas ao:

• Definir pontos de checagem obrigatórios e opcionais para revisão
• Padronizar os insumos da revisão (faixa de commits no Git, requisitos, resumo)
• Trabalhar em conjunto com um subagente dedicado code-reviewer que retorna feedback ranqueado por severidade

---

Como usar

Instalação

Para instalar a skill requesting-code-review do repositório obra/superpowers, use o Skills CLI:

npx skills add https://github.com/obra/superpowers --skill requesting-code-review

Isso baixa a definição da skill e seus arquivos de suporte, incluindo o template do subagente code-reviewer.

Após a instalação, abra o diretório da skill e dê uma olhada nesses arquivos primeiro:

• SKILL.md – descrição em alto nível e passos do fluxo para solicitar revisão de código
• code-reviewer.md – o prompt/template do agente que de fato executa a revisão de código

Visão rápida do fluxo principal

O fluxo de trabalho de requesting-code-review tem três fases principais:

1. Decidir quando revisar
   • Após cada tarefa em um fluxo orientado por subagentes
   • Depois de concluir uma funcionalidade importante
   • Antes de fazer merge na sua branch principal
2. Preparar o contexto da revisão
   • Capturar a faixa de commits no Git com BASE_SHA e HEAD_SHA
   • Resumir o que foi implementado e o que isso deve fazer
   • Preencher os placeholders definidos em code-reviewer.md
3. Rodar a revisão e agir sobre o feedback
   • Disparar o subagente superpowers:code-reviewer
   • Corrigir imediatamente os problemas Critical, tratar os Important antes de seguir e registrar os Minor

Passo 1: Identifique o momento certo para revisão

De acordo com SKILL.md, use requesting-code-review em:

Pontos de checagem obrigatórios:

• Após cada tarefa em desenvolvimento orientado por subagentes
• Após concluir uma funcionalidade importante
• Antes do merge na sua branch principal (por exemplo, main, master)

Pontos de checagem opcionais, mas valiosos:

• Quando você estiver travado e precisar de uma visão externa
• Antes de refatorar, como checagem de base do comportamento atual
• Depois de corrigir um bug complexo, para garantir ausência de regressões ou novos problemas

Crie o hábito de acionar esta skill nesses momentos, para que as revisões se tornem automáticas em vez de algo deixado para depois.

Passo 2: Capture a faixa de commits no Git

O revisor precisa de um diff limpo e bem delimitado. Use os SHAs do Git para especificar a faixa:

BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)

• BASE_SHA deve apontar para o commit que representa seu ponto de partida, como o commit anterior ou a ponta de origin/main.
• HEAD_SHA deve ser o commit que contém seu trabalho mais recente.

Você pode ajustar HEAD~1 ou escolher outra base de acordo com sua estratégia de branches, desde que a faixa capture com precisão as mudanças que você quer revisar.

Passo 3: Prepare o template de solicitação de revisão

O arquivo code-reviewer.md define como conversar com o Code Review Agent. Ele usa placeholders que você precisa preencher antes de disparar o subagente.

Placeholders principais:

• {WHAT_WAS_IMPLEMENTED} – Uma descrição concisa do que você acabou de construir ou alterar
• {PLAN_OR_REQUIREMENTS} – A especificação, ticket ou requisitos de negócio que a implementação deve atender
• {BASE_SHA} – O SHA do commit inicial do diff
• {HEAD_SHA} – O SHA do commit final do diff
• {DESCRIPTION} – Um breve resumo do conjunto de mudanças (por exemplo, "Add verification function and tests for user signups")
• {PLAN_REFERENCE} – Uma referência ao seu plano ou documento de requisitos

Na sua própria ferramenta, preencha esses placeholders antes de disparar o subagente superpowers:code-reviewer com o Task tool.

Passo 4: Dispare o subagente code-reviewer

Com os SHAs do Git e o template preenchido:

1. Use o Task tool do seu ambiente de orquestração (como descrito no framework superpowers) com o tipo superpowers:code-reviewer.

2. Passe o conteúdo renderizado de code-reviewer.md, com os placeholders substituídos pelos valores reais.

3. Garanta que o agente consiga acessar o diff do Git para a faixa:

   git diff --stat {BASE_SHA}..{HEAD_SHA}
   git diff {BASE_SHA}..{HEAD_SHA}
   

   O template indica esses comandos para que o revisor foque estritamente nas mudanças entre BASE_SHA e HEAD_SHA.

O design desta skill garante que o agente de revisão veja apenas o resultado do trabalho (commits e diff), não o histórico mais amplo da sessão nem contexto irrelevante.

Passo 5: Interprete e aja sobre o feedback

O template code-reviewer.md instrui o agente a:

• Avaliar a qualidade do código (separação de responsabilidades, tratamento de erros, DRY, casos de borda)
• Avaliar a arquitetura (design, escalabilidade, performance, segurança)
• Verificar testes (cobertura, pontos de integração, qualidade dos testes)
• Verificar requisitos (alinhamento com a especificação, ausência de scope creep, breaking changes documentadas)
• Julgar a prontidão para produção (migrações, compatibilidade retroativa, documentação)

O feedback é categorizado em:

• Critical (Must Fix) – Bugs, problemas de segurança, risco de perda de dados, funcionalidade quebrada
• Important (Should Fix) – Problemas de arquitetura, funcionalidades faltando, tratamento de erros deficiente, lacunas de testes
• Minor (Nice to Have) – Estilo, otimizações, melhorias de documentação

O fluxo correspondente em SKILL.md é:

• Corrigir problemas Critical imediatamente antes de continuar
• Corrigir problemas Important antes de seguir com mais trabalho ou fazer merge
• Anotar problemas Minor para limpeza posterior ou tarefas de follow-up
• Contestar, com justificativa, se o revisor estiver errado ou sem contexto suficiente

Ao seguir essa triagem, você transforma o feedback da IA em uma lista de ações concretas, em vez de um conjunto vago de sugestões.

Exemplo de uso

Um uso típico de requesting-code-review pode ser:

1. Você conclui a "Task 2: Add verification function" na sua branch de feature.

2. Você captura os SHAs:

   BASE_SHA=$(git rev-parse origin/main)
   HEAD_SHA=$(git rev-parse HEAD)
   

3. Você preenche os placeholders de code-reviewer.md com:

   • {WHAT_WAS_IMPLEMENTED} = "Verification function for user email flow"
   • {PLAN_OR_REQUIREMENTS} = Link ou resumo do ticket/requisitos
   • {BASE_SHA} e {HEAD_SHA} = Os valores retornados pelo Git
   • {DESCRIPTION} = "Implement email verification and add tests for edge cases"

4. Você dispara o subagente superpowers:code-reviewer usando seu Task tool.

5. Você recebe feedback estruturado, agrupado em Critical, Important e Minor.

6. Você resolve os problemas Critical e Important e, se quiser, roda o processo novamente antes do merge.

---

FAQ

requesting-code-review é apenas para repositórios GitHub?

Não. A skill requesting-code-review é baseada em Git, não específica do GitHub. Ela depende de SHAs de commits e comandos git diff, portanto funciona com qualquer remoto Git (GitHub, GitLab, Bitbucket ou self-hosted), desde que você consiga fornecer BASE_SHA e HEAD_SHA.

Preciso compartilhar todo o histórico da minha sessão de desenvolvimento?

Não. Um princípio central de design de requesting-code-review é que o revisor recebe apenas um contexto bem delimitado: o que foi implementado, os requisitos e o diff do Git. Seu histórico geral de sessão e seu raciocínio interno permanecem privados, enquanto o revisor foca nas mudanças reais de código.

Quando devo acionar requesting-code-review no meu fluxo?

Use requesting-code-review:

• Após cada tarefa em desenvolvimento orientado por subagentes
• Depois de concluir uma grande funcionalidade
• Antes de fazer merge na sua branch principal

Você também pode acioná-la quando estiver travado, antes de grandes refatorações ou após correções de bugs complexos, para detectar riscos ocultos com antecedência.

Como isso se integra com minhas revisões de pull request existentes?

requesting-code-review complementa, em vez de substituir, revisões de PR feitas por humanos. Você pode:

• Rodar a skill antes de abrir um PR para capturar problemas óbvios
• Usá-la junto com revisores humanos para melhorar cobertura e consistência
• Aplicar as categorias de feedback (Critical/Important/Minor) aos comentários de PR

Como a skill é baseada em faixas de commits no Git, ela se encaixa naturalmente em fluxos de trabalho centrados em PR.

Posso personalizar o comportamento do agente code-reviewer?

Sim. O arquivo code-reviewer.md é um template que você pode adaptar:

• Ajuste as checklists de qualidade de código, arquitetura, testes ou segurança
• Adicione preocupações específicas do projeto (por exemplo, regras de domínio, metas de performance)
• Refine o formato de saída se quiser níveis de severidade diferentes ou seções adicionais

Apenas mantenha a estrutura central (tarefa clara, faixa de commits no Git e categorias de severidade) para que a revisão continue focada e acionável.

E se o revisor sugerir algo incorreto?

A skill incentiva explicitamente que você questione com argumentos quando o revisor estiver errado ou sem contexto. Trate a revisão como uma recomendação forte, não como um veredito inquestionável. Esclareça restrições, explique trade-offs ou atualize seu plano para que revisões futuras fiquem melhor alinhadas.

requesting-code-review gera testes ou mudanças de código para mim?

Não. Esta skill é sobre revisão, não geração. Ela ajuda você a:

• Pedir revisões direcionadas de mudanças específicas
• Receber feedback estruturado sobre qualidade, arquitetura e testes

Você continua responsável por implementar correções e escrever testes, embora possa combinar esta skill com outras skills de codificação ou geração de testes no seu toolchain.

Como começo rapidamente?

1. Instale a skill:

   npx skills add https://github.com/obra/superpowers --skill requesting-code-review
   

2. Leia SKILL.md para entender os pontos de checagem da revisão.

3. Revise code-reviewer.md para conhecer a checklist do agente e o formato de saída.

4. Toque a próxima tarefa ou feature, capture BASE_SHA e HEAD_SHA e dispare o subagente superpowers:code-reviewer.

A partir daí, ajuste o template e o fluxo de trabalho para que requesting-code-review reflita os hábitos e o nível de qualidade da sua equipe.