receiving-code-review

Visão geral da skill receiving-code-review

Para que serve a skill receiving-code-review

A receiving-code-review skill ajuda uma IA a responder a feedback de code review com disciplina técnica, em vez de concordar automaticamente. A proposta é simples, mas valiosa: quando um revisor sugere mudanças, o agente deve primeiro entender o pedido, conferir se ele faz sentido no codebase real e só então implementar a alteração ou contestá-la com fundamento.

Ela é especialmente útil quando os comentários de review são ambíguos, parcialmente incorretos, entram em conflito entre si ou trazem risco se aplicados no automático. A receiving-code-review skill não existe para soar educada em uma thread de PR. Ela existe para evitar mudanças ruins causadas por reflexos sociais como “você tem razão, vou corrigir” antes de validar se o problema de fato procede.

Para quem essa skill é mais indicada

Esta skill é uma ótima escolha para:

• desenvolvedores que usam IA para ajudar a processar comentários de PR
• times que querem menos concordância performática e mais precisão técnica
• agentes atuando em codebases maduros, em que sugestões de revisores nem sempre se encaixam nas restrições locais
• usuários que querem um fluxo repetível para responder reviews, e não só um prompt mais simpático

Se o seu principal problema é “o modelo implementa o feedback do reviewer rápido demais e quebra coisas”, esta skill ataca exatamente esse modo de falha.

O trabalho real que precisa ser resolvido

Em geral, o usuário não precisa de ajuda para ler um comentário. O que ele precisa decidir é:

• o que o reviewer quis dizer de fato
• se a sugestão está correta para este repositório
• se é preciso pedir esclarecimento antes de mudar qualquer coisa
• como responder quando o reviewer está enganado ou foi incompleto
• como implementar com segurança quando o feedback for válido

Esse é o valor prático da receiving-code-review skill: transformar a entrada de feedback de review em um fluxo de verificação.

O que diferencia esta skill de um prompt genérico de review

Um prompt comum costuma empurrar o modelo para a conformidade: resumir o feedback, agradecer ao reviewer e começar a editar. Esta skill, em vez disso, impõe um padrão de resposta:

1. ler o feedback completo
2. reformular o requisito
3. verificar contra a realidade do codebase
4. avaliar o encaixe técnico
5. responder com reconhecimento, perguntas ou contraposição fundamentada
6. implementar um item de cada vez

Ela também proíbe explicitamente respostas comuns de baixo valor, como elogios exagerados ou compromisso imediato antes da validação.

O que saber antes de instalar

Esta é uma skill leve e com foco bem específico. Ela não inclui scripts auxiliares, referências nem regras específicas por repositório. Isso é positivo se você quer algo fácil de adotar, mas também significa que a qualidade da saída depende bastante do comentário de review e do contexto de código que você fornecer.

Encare esta skill como uma proteção comportamental para fluxos de Code Review, e não como um framework completo de automação de review de código.

Como usar a skill receiving-code-review

Como instalar a skill receiving-code-review

Instale a partir do repositório obra/superpowers:

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

Se o seu ambiente usa outro carregador de skills, adicione a skill a partir de:

https://github.com/obra/superpowers/tree/main/skills/receiving-code-review

Como o repositório só expõe SKILL.md para esta skill, a instalação e a inspeção são diretas.

O que ler primeiro no repositório

Para decidir sobre a receiving-code-review install, comece por:

• skills/receiving-code-review/SKILL.md

Esse arquivo concentra praticamente todo o comportamento útil:

• o princípio central
• o padrão de resposta
• as respostas proibidas
• a regra para lidar com feedback pouco claro

Não há rules/, resources/ nem scripts de apoio extras para aprender antes, então o tempo até entender como ela funciona é baixo.

Quando acionar receiving-code-review na prática

Use a receiving-code-review skill no momento em que o feedback chega, antes de começar qualquer mudança no código.

Bons gatilhos de uso:

• “Please simplify this logic.”
• “This should use a transaction.”
• “Fix comments 1–6.”
• “Why not just cache this?”
• “Use pattern X instead.”

Acione especialmente quando:

• os comentários vierem em lote
• alguns itens estiverem pouco claros
• o reviewer talvez não conheça as restrições arquiteturais locais
• a IA estiver tentada a sair aplicando patches imediatamente

Que entrada a skill precisa

A skill funciona melhor quando você fornece quatro coisas:

1. o feedback exato do review
2. os caminhos dos arquivos afetados ou o diff
3. as restrições relevantes do codebase
4. o próximo passo que você quer tomar

Entradas úteis incluem:

• comentários de PR copiados literalmente
• a implementação atual
• falhas de teste ou restrições de performance
• regras de arquitetura que possam entrar em conflito com a sugestão
• se você quer um rascunho de resposta, uma avaliação ou ajuda para implementar

Sem contexto do codebase, a skill ainda pode ajudar a interpretar comentários, mas não conseguirá validar bem o encaixe técnico.

Como transformar um objetivo vago em um prompt forte

Prompt fraco:

Handle this review feedback.

Prompt mais forte:

Use the receiving-code-review skill.

Review feedback:
"Please combine these queries and move validation into the controller."

Context:
- Files: app/services/order_sync.rb, app/controllers/orders_controller.rb
- Current pattern: validation is intentionally kept out of controllers
- This code handles retry behavior and partial failures
- I want to know whether the suggestion is correct for this codebase

Please:
1. Restate what the reviewer is asking
2. Identify any ambiguity
3. Verify the suggestion against the current design
4. Recommend whether to implement, ask a question, or push back
5. If valid, propose the smallest safe change

Isso funciona melhor porque dá material suficiente para a skill executar a etapa mais importante: verificar, e não só parafrasear.

Um fluxo prático de receiving-code-review

Um fluxo confiável de receiving-code-review usage costuma ser assim:

1. cole a thread completa de review ou o lote de comentários
2. peça ao agente para separar o que está claro do que está obscuro
3. exija a reformulação de cada mudança solicitada
4. faça com que ele cheque cada item contra o codebase
5. peça uma recomendação: implementar, esclarecer ou discordar
6. só então passe para as edições, um problema por vez

Isso evita o erro comum de implementar parcialmente um lote de comentários enquanto o restante ainda está sendo mal interpretado.

Como lidar com comentários vagos ou agrupados na receiving-code-review

Uma das ideias mais fortes desta skill é: se qualquer item estiver pouco claro, pare antes de implementar.

Isso importa em PRs reais porque os comentários frequentemente são interdependentes. Se um reviewer diz “Fix points 1–6” e os pontos 4–5 não estão claros, implementar 1–3 e 6 pode te prender na direção errada.

Um bom prompt aqui é:

Use receiving-code-review. Group this feedback into:
- clear and ready to verify
- unclear and needs clarification
Do not recommend implementation until all linked items are understood.

Como deve ser uma boa saída desta skill

Um bom resultado não é “Thanks, great catch.” Ele deve incluir:

• uma reformulação limpa do pedido técnico do reviewer
• quaisquer premissas ou ambiguidades
• verificação contra o código real
• uma decisão com justificativa
• ou uma pergunta de esclarecimento, ou uma contraposição respeitosa, ou um plano seguro de implementação

Se a saída pula direto do comentário para a mudança no código, a skill não está sendo usada do jeito certo.

Padrões de prompt recomendados para trabalho de Code Review

Use estes padrões conforme o seu objetivo.

Para avaliação apenas:

Use the receiving-code-review skill to evaluate whether this review comment is technically correct for this repository. Do not implement yet.

Para redigir uma resposta:

Use the receiving-code-review skill to write a concise technical reply to this PR comment. Avoid praise language. Ask for clarification if needed.

Para implementação após validação:

Use the receiving-code-review skill. First verify the reviewer's request against the codebase. If valid, propose the smallest testable change and list risks before editing.

Dicas práticas que melhoram a qualidade da saída

Pequenas melhorias na entrada fazem bastante diferença:

• inclua as palavras exatas do reviewer, não a sua paráfrase
• inclua o código ao redor, não apenas a função-alvo
• diga se o reviewer está falando de estilo, corretude, performance ou arquitetura
• informe ao modelo o que é inegociável no seu codebase
• peça que ele identifique onde o reviewer pode estar assumindo fatos que não foram demonstrados

Esta skill fica melhor quando o agente consegue comparar a mudança pedida com a realidade do repositório.

FAQ da skill receiving-code-review

A receiving-code-review serve só para responder humanos em comentários de PR?

Não. Ela é igualmente útil para avaliação interna antes mesmo de você responder qualquer coisa. Em muitos casos, o melhor primeiro uso de receiving-code-review é privado: determinar se o comentário está correto, incompleto ou inseguro antes de redigir qualquer resposta pública.

Esta skill é amigável para iniciantes?

Sim, com uma ressalva. O fluxo é fácil de entender, mas iniciantes ainda podem não ter o contexto técnico necessário para julgar se o feedback faz sentido para o codebase. A skill melhora a disciplina; ela não substitui julgamento de engenharia.

Em que isso difere de prompts comuns do tipo “analyze this PR feedback”?

A principal diferença é a recusa embutida em concordar de imediato. O receiving-code-review guide em SKILL.md coloca no centro a verificação, o esclarecimento e a contraposição justificada. Prompts genéricos costumam otimizar mais para uma linguagem socialmente fluida do que para correção técnica.

Quando eu não devo usar a skill receiving-code-review?

Pode pular quando a tarefa já estiver totalmente especificada e for mecanicamente segura, como:

• aplicar uma correção óbvia de typo
• renomear um símbolo sem impacto comportamental
• seguir uma convenção de time já confirmada e documentada

Ela também não é a ferramenta certa para fazer um code review completo e ativo no código de outra pessoa. Esta skill trata especificamente de receber feedback bem.

A receiving-code-review ajuda quando o reviewer está errado?

Sim. Na verdade, esse é um dos casos de uso mais fortes. A skill incentiva uma resposta técnica fundamentada em vez de um tom defensivo ou conformidade automática. Se a sugestão do reviewer conflitar com o codebase, o esperado é que o agente explique por quê e proponha uma resposta mais clara.

Ela dá suporte a feedback de review em lote?

Sim, mas só se você fornecer o lote completo e deixar a skill separar os itens claros dos pouco claros. A skill sugere com força que entendimento parcial deve bloquear a implementação. Isso é especialmente útil em situações de “fix all of these comments”.

Como melhorar a skill receiving-code-review

Dê à skill a realidade do repositório, não só o texto do reviewer

A forma mais rápida de melhorar a saída da receiving-code-review é combinar os comentários com:

• caminhos de arquivos
• trechos da implementação atual
• restrições
• testes
• padrões arquiteturais relevantes

Uma sugestão de review não pode ser avaliada no abstrato quando depende de decisões locais de design.

Peça uma decisão, não só um resumo

Muitas execuções fracas acontecem porque o prompt só pede ao agente para “processar” o feedback. Prompts melhores forçam uma escolha:

• implementar
• fazer uma pergunta de esclarecimento
• contestar com justificativa
• adiar por falta de contexto

Isso torna a skill operacional, e não apenas descritiva.

Evite o modo de falha mais comum

O maior modo de falha é a implementação prematura. O modelo vê a sugestão do reviewer e começa a editar antes de checar:

• se o reviewer entendeu o código atual
• se as restrições tornam a sugestão inválida
• se outros comentários mudam o significado
• se a mudança pedida tem efeitos colaterais ocultos

Diga explicitamente ao agente: “Do not implement until verification is complete.”

Forneça entradas melhores para threads de review ambíguas

Se o feedback for vago, adicione você mesmo a moldura que está faltando:

Use receiving-code-review.

The reviewer says: "This flow should be simplified."
Please identify at least 3 plausible interpretations, map each to the current code, and tell me what clarification question would unblock implementation safely.

Isso é muito melhor do que pedir ao modelo para adivinhar um único significado e seguir em frente.

Faça a contraposição ser técnica e concisa

Se o reviewer estiver errado, a melhor saída é curta, específica e baseada em evidência. Peça:

• qual premissa o reviewer parece estar fazendo
• qual fato do codebase entra em conflito com essa premissa
• qual é a menor resposta respeitosa que explica esse desencontro

Isso mantém o fluxo de receiving-code-review for Code Review útil, em vez de confrontacional.

Itere depois da primeira resposta

Depois da primeira rodada, melhore o resultado fornecendo justamente a peça que ainda estiver faltando:

• intenção pouco clara do reviewer
• trecho de código ausente
• restrição arquitetural
• evidência de testes
• contexto do diff

Um bom prompt de segunda passada é:

Re-run receiving-code-review with this added context. Update your recommendation and tell me whether the original review comment is now clear enough to implement.

Combine a skill com implementação só depois da validação

O melhor padrão de adoção tem duas etapas:

1. usar receiving-code-review para avaliar o comentário
2. só então pedir edições no código

Essa separação melhora a confiança porque você consegue inspecionar o raciocínio antes de o modelo começar a alterar arquivos.

Use a skill como padrão de equipe

Se o seu time quer comportamento consistente de IA em fluxos de PR, transforme a skill em uma instrução padrão para tratamento de feedback recebido em review:

• nada de respostas que começam com elogio
• nada de implementação cega
• perguntar quando não estiver claro
• verificar contra o código local
• contestar quando houver justificativa técnica

É aí que a receiving-code-review skill entrega mais valor no longo prazo: não como um prompt avulso, mas como um hábito operacional repetível.