requesting-code-review

Visão geral da skill requesting-code-review

A skill requesting-code-review é um fluxo leve para acionar uma revisão de código focada no momento certo, com o diff certo e com contexto de implementação suficiente para que um agente revisor dê feedback realmente útil. Em vez de pedir algo vago como “revise meu código”, ela força você a informar um intervalo de commits, um resumo do que mudou e os requisitos esperados.

O que a skill requesting-code-review realmente faz

Na prática, requesting-code-review orienta você a acionar o subagente superpowers:code-reviewer usando um template pronto em code-reviewer.md. O diferencial aqui não é automação sofisticada; é o enquadramento da revisão. O revisor enxerga o trabalho entregue e o plano, não todo o histórico da sua sessão, o que deixa a revisão mais delimitada e mais fácil de transformar em ação.

Quem deve instalar requesting-code-review

Esta skill é mais indicada para desenvolvedores e usuários de agentes de IA que:

• trabalham com fluxos baseados em commits
• entregam features em etapas
• querem um checkpoint repetível de “revisar antes de continuar”
• usam subagentes e precisam de um handoff mais limpo do que um prompt genérico

Ela é especialmente útil se você costuma pedir revisão tarde demais, quando várias tarefas já viraram um diff grande e difícil de analisar.

O trabalho real que ela resolve

As pessoas não instalam requesting-code-review só para “receber uma review”. Elas instalam para reduzir retrabalho evitável:

• identificar problemas antes do merge
• validar a implementação contra o plano original
• receber feedback priorizado por severidade
• preservar o contexto da tarefa principal enquanto um agente revisor inspeciona o código em separado

Por que essa skill é mais útil do que um prompt simples de review

A requesting-code-review skill adiciona uma estrutura prática que muitos prompts improvisados deixam passar:

• orientação de timing da revisão: após cada tarefa, após grandes features, antes do merge
• entradas explícitas de BASE_SHA e HEAD_SHA
• um template de review com checagens de qualidade de código, arquitetura, testes, aderência aos requisitos e prontidão para produção
• categorias de severidade que facilitam o acompanhamento

Isso torna o resultado muito mais acionável do que um simples “dá uma olhada nas minhas últimas mudanças”.

O que mais importa antes de adotar

A principal questão de adoção é encaixe: esta skill funciona melhor quando o seu trabalho está representado como um intervalo de git limpo e quando você consegue descrever brevemente o comportamento esperado. Se a branch estiver bagunçada, o plano estiver mal definido ou suas mudanças estiverem misturadas com edições sem relação, a qualidade da review cai.

Limitação importante para saber desde o início

requesting-code-review for Code Review não é, por si só, um sistema completo de revisão. Ela não traz scripts, regras de enforcement nem verificações específicas do repositório. É um padrão disciplinado de prompt e handoff. Isso tem valor, mas a qualidade vai depender bastante do intervalo de commits escolhido e da clareza dos requisitos.

Como usar a skill requesting-code-review

Instale requesting-code-review no seu setup de skills

Se você usa o padrão de Skills CLI adotado em todo o repositório, instale com:

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

Se o seu ambiente já tiver a coleção obra/superpowers disponível, basta ativar ou referenciar a skill requesting-code-review desse pacote.

Leia estes arquivos primeiro

Para uma avaliação rápida, comece por:

1. skills/requesting-code-review/SKILL.md
2. skills/requesting-code-review/code-reviewer.md

O SKILL.md explica quando acionar a review. Já o code-reviewer.md é o arquivo mais importante se você se preocupa com a qualidade da saída, porque mostra exatamente o que o revisor foi instruído a avaliar.

Entenda os gatilhos previstos para a skill requesting-code-review

A skill foi pensada para ser usada:

• após cada tarefa em um fluxo de desenvolvimento com subagentes
• após uma feature relevante
• antes de fazer merge para a main

Momentos opcionais, mas de alto valor, incluem:

• quando você travou e quer um olhar novo
• antes de um refactor arriscado
• depois de corrigir um bug complexo

Se você só usar isso no fim de uma branch grande, perde boa parte do benefício.

Reúna os insumos mínimos antes de chamar a skill

A skill funciona melhor quando você informa:

• o que foi implementado
• o plano ou os requisitos
• BASE_SHA
• HEAD_SHA
• uma descrição breve da mudança

Comandos git típicos:

BASE_SHA=$(git rev-parse HEAD~1)
HEAD_SHA=$(git rev-parse HEAD)

Em feature branches, origin/main pode ser uma base melhor do que HEAD~1 se você quiser uma janela de revisão mais completa.

Use um intervalo de diff limpo, não um pedido vago de “trabalho recente”

Esta é a parte de maior impacto no padrão de requesting-code-review usage. Uma review vinculada a BASE_SHA..HEAD_SHA é muito superior a pedir que um agente adivinhe o que mudou a partir da sua working tree ou do histórico do chat.

Bom:

• “Review commits from feature start to current head against the signup flow requirements.”

Fraco:

• “Can you review my recent auth changes?”

A versão mais forte reduz o escopo e diminui a necessidade de o revisor ficar inferindo contexto.

Transforme um objetivo genérico em um pedido forte de review

Um pedido raso como este é insuficiente:

Please review my new feature.

Uma versão melhor, baseada na skill, fica assim:

Review the password reset implementation for production readiness.

What was implemented:
- Added reset token generation and validation
- Added reset email endpoint
- Added UI flow for requesting and completing reset

Plan/requirements:
- Tokens expire after 30 minutes
- Single-use tokens only
- No user enumeration from the request endpoint
- Existing login flow must remain unchanged

Base SHA: abc1234
Head SHA: def5678
Description:
Task 2 of auth hardening. Main changes are in API handlers, email service, and reset form.

Isso dá contexto suficiente para o revisor julgar correção, e não apenas estilo.

Acione o subagente revisor do jeito que a skill requesting-code-review espera

A orientação do repositório diz para usar a ferramenta Task com o tipo superpowers:code-reviewer e preencher o template em code-reviewer.md. Esse template pede que o revisor:

• compare implementação e plano
• inspecione o git diff
• verifique qualidade, arquitetura, testes e prontidão para produção
• devolva achados classificados por severidade

Se a sua plataforma de agentes suporta subagentes, mantenha a review isolada em vez de misturá-la na mesma conversa de execução.

O que o template do revisor está otimizado para encontrar

O checklist embutido é mais forte para trazer à tona:

• requisitos não atendidos
• lacunas óbvias de readiness para produção
• problemas de cobertura de testes
• preocupações de arquitetura
• edge cases perigosos
• omissões de compatibilidade retroativa ou migração

Ele é menos especializado para compliance de domínio, convenções específicas do repositório ou verificação profunda em runtime, a menos que você acrescente isso explicitamente.

Fluxo sugerido da skill requesting-code-review em projetos reais

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

1. concluir uma tarefa com escopo bem definido
2. identificar o intervalo exato do diff
3. resumir intenção e critérios de aceite
4. acionar o revisor com o template
5. corrigir problemas críticos e importantes
6. rodar nova review se as correções forem substanciais
7. continuar o desenvolvimento ou fazer o merge

Esta skill é mais eficaz como checkpoint entre etapas de implementação, não só como portão final.

Dicas que melhoram de fato a qualidade da saída

Para obter uma review melhor:

• use um intervalo de diff que contenha uma única mudança lógica
• inclua critérios de aceite, não apenas o nome da feature
• mencione áreas de risco como migrations, auth, concorrência, cache ou contratos de API
• diga se testes foram adicionados e de que tipo
• informe se breaking changes são esperadas ou proibidas

Esses detalhes ajudam o revisor a distinguir tradeoffs intencionais de omissões acidentais.

Mau uso comum que reduz o valor da skill

A decisão de requesting-code-review install faz menos sentido se o seu time costuma:

• colocar muitas mudanças sem relação no mesmo intervalo
• trabalhar sem requisitos escritos
• não usar limites de git minimamente úteis
• esperar que a skill substitua aprovação humana ou CI

Nesses casos, primeiro arrume o fluxo de trabalho — ou espere reviews mais ruidosas.

FAQ da skill requesting-code-review

requesting-code-review é boa para iniciantes?

Sim, desde que você já entenda conceitos básicos de git, como commits e SHAs. A skill é simples, mas pressupõe que você consegue definir o que mudou e o que aquilo deveria fazer. Iniciantes que pulam esse contexto ainda vão receber feedback, mas ele tende a ser menos confiável.

Essa skill revisa mudanças não commitadas?

Não por padrão. O fluxo foi construído em torno de BASE_SHA e HEAD_SHA, então funciona melhor sobre trabalho já commitado. Dá para adaptar para mudanças unstaged ou não commitadas, mas isso foge da estrutura central da skill e normalmente torna a revisão menos reproduzível.

Em que requesting-code-review difere de simplesmente pedir para uma IA revisar meu código?

Um prompt comum costuma gerar uma review genérica porque o modelo precisa inferir escopo, intenção e critérios de aceite. requesting-code-review melhora isso ao exigir:

• um diff explícito
• um resumo claro da implementação
• o plano original ou os requisitos
• um formato de saída baseado em severidade

O resultado costuma ser mais confiável e mais fácil de transformar em ação.

Quando eu não deveria usar requesting-code-review?

Evite usar quando:

• sua mudança ainda está incompleta demais para ser avaliada
• o diff mistura várias features sem relação
• você ainda não sabe qual comportamento espera
• você precisa mais de checks estáticos específicos do repositório do que de uma review baseada em julgamento

Também é um encaixe ruim se o seu time nunca trabalha com intervalos de commits do git.

Ela substitui code review humana?

Não. O melhor uso é como pré-review ou como gate de qualidade entre etapas. Ela pode pegar problemas cedo e deixar a revisão humana posterior mais fluida, mas não substitui conhecimento de domínio, convenções do time nem exigências organizacionais de aprovação.

requesting-code-review serve só para features grandes?

Não. Na verdade, é justamente em diffs menores que ela mais brilha. A skill incentiva explicitamente revisão cedo e com frequência, o que costuma ser mais eficaz do que esperar por uma única passada final sobre um bloco grande de mudanças.

Que tipo de encaixe de ecossistema eu devo esperar?

Esta skill se encaixa melhor dentro do fluxo obra/superpowers, especialmente se você já usa subagentes. Ela é mais leve do que um framework completo de review e mais fácil de adotar do que construir automação própria de revisão, mas isso também significa menos guardrails.

Como melhorar a skill requesting-code-review

Dê requisitos melhores ao revisor, não apenas código melhor

O modo de falha mais comum é contexto fraco de plano. Se você só disser “implemented notifications”, o revisor não tem como saber se a ausência de uma estratégia de retry é um bug ou algo fora de escopo. Acrescente expectativas concretas:

• condições de disparo
• comportamento em caso de erro
• expectativas de compatibilidade retroativa
• requisitos de performance ou segurança

Requisitos melhores geram julgamentos de review melhores.

Use o menor recorte de review que ainda faça sentido

A requesting-code-review skill funciona melhor sobre uma tarefa única ou um conjunto de mudanças fortemente relacionadas. Se o diff inclui trabalho de schema, mudanças de API, ajustes de UI e limpeza sem relação, os achados ficam amplos demais e menos acionáveis. Sempre que possível, quebre o trabalho em unidades revisáveis.

Escolha o commit base correto

Um BASE_SHA ruim gera feedback enganoso. Se você usa HEAD~1, mas a feature ocupa seis commits, o revisor vê pouco demais. Se você usa uma base antiga demais, ele enxerga ruído em excesso. Escolha a base que corresponda à unidade lógica de trabalho que você quer avaliar.

Troque placeholders por detalhes que o revisor consiga testar mentalmente

O template incluído usa placeholders como:

• {WHAT_WAS_IMPLEMENTED}
• {PLAN_OR_REQUIREMENTS}
• {BASE_SHA}
• {HEAD_SHA}
• {DESCRIPTION}

Não preencha isso com resumos de uma linha se a mudança tiver risco. Descreva o comportamento esperado de forma concreta. Por exemplo, “prevents user enumeration and invalidates token after first successful reset” é muito mais forte do que “added password reset.”

Diga ao revisor onde está o risco

Se você já sabe quais são as superfícies arriscadas, diga isso:

• “Please pay special attention to race conditions around token reuse.”
• “Check backward compatibility for existing API consumers.”
• “Focus on whether tests cover the error path and expiry boundary.”

Isso direciona a atenção e aumenta a chance de surgirem achados úteis.

Fortaleça a review depois da primeira passada

Depois da saída inicial:

1. corrija os problemas críticos claramente corretos
2. questione os achados que parecerem errados
3. esclareça requisitos que estavam faltando
4. rode uma segunda review no diff atualizado se as mudanças forem substanciais

A própria skill incentiva contestar o revisor quando ele estiver errado. Isso é um bom sinal: ela foi feita para apoiar julgamento, não para substituí-lo.

Adicione critérios de review específicos do repositório quando necessário

O code-reviewer.md padrão cobre bem dimensões comuns de review, mas muitos times precisam de mais. Melhore requesting-code-review for Code Review adicionando checks específicos do projeto, como:

• regras de rollout de migration
• requisitos de observabilidade
• expectativas de acessibilidade
• pontos de revisão de segurança
• convenções de linguagem ou framework

Esse é o maior upgrade se você quer uma saída menos genérica.

Fique atento a estes modos de falha recorrentes

As quedas de qualidade mais comuns costumam vir de:

• requisitos ausentes ou vagos
• intervalos de commits ruidosos
• nenhuma menção ao comportamento não funcional esperado
• pedido de review só depois que tarefas demais já se acumularam
• tratar sugestões menores como obrigatórias enquanto problemas críticos de design passam batido

Se a saída parecer superficial, revise primeiro as entradas.

Melhore a saída pedindo decisões, não só defeitos

Um padrão de requesting-code-review usage mais forte é pedir que o revisor avalie tradeoffs também. Exemplo:

• “Flag any unnecessary complexity.”
• “Call out if this should be split before merge.”
• “Assess whether current tests justify production readiness.”

Isso empurra a review para além de comentários estilo lint e a aproxima de uma avaliação real de qualidade para release.

Forma prática de evoluir a skill no seu próprio setup

Se você for adotar esta skill a sério, personalize primeiro três coisas:

1. sua regra preferida de escolha do commit base
2. um formato padrão para requisitos e critérios de aceite
3. itens extras de checklist para sua stack e seu processo de release

Esses acréscimos preservam a simplicidade de requesting-code-review e, ao mesmo tempo, tornam a skill muito mais útil no dia a dia de entrega.