MÓDULO 1.7

👀 Revisão de código com agentes

Como pedir e receber revisões de código de forma estruturada — revisando contra o plano, não contra intuição.

📋6 tópicos ⏱️~25 min 🎯Intermediário 📖Teoria + Prática
1

📝 requesting-code-review: checklist pré-revisão

Antes de solicitar uma revisão de código, o agente executa um checklist pré-revisão para garantir que o código está em condições de ser revisado. Solicitar review de código sujo não economiza tempo — apenas transfere o trabalho de limpeza para o revisor.

Checklist pré-revisão

  • □Todos os testes passando (npm test sem falhas)
  • □Sem console.log de debug deixados no código
  • □Sem código comentado sem explicação
  • □Nomes de variáveis e funções claros e descritivos
  • □Documentação atualizada se houver mudança de API
  • □Diff limitado ao escopo da feature (sem mudanças extras)

O checklist pré-revisão é responsabilidade do agente que implementou. Você pode pedir: "Execute o checklist pré-revisão antes de me apresentar o código".

2

🔄 receiving-code-review: feedback com rigor técnico

Receber feedback de code review corretamente é uma habilidade. Agentes frequentemente implementam o primeiro entendimento do feedback — que pode não ser o que o revisor quis dizer. O processo correto exige confirmação antes de implementação.

1.

Entender: Reformular o feedback com suas próprias palavras para confirmar o entendimento

2.

Confirmar motivo: Entender por que o revisor apontou isso — qual problema está sendo evitado

3.

Propor solução: Apresentar a abordagem de correção antes de implementar

4.

Implementar: Só então implementar a correção aprovada

3

🎯 Revisar contra o plano, não contra intuição

O critério objetivo de uma revisão de código no Superpowers é o plano aprovado. Cada linha do código é avaliada contra: "Isso estava no plano? Isso cumpre o critério de aceitação da spec?" — não contra "Eu teria feito diferente?" ou "Isso não parece certo".

Review baseado em intuição

  • • "Eu usaria uma classe aqui"
  • • "Prefiro o padrão X ao Y"
  • • "Isso não me parece Pythônico"
  • • "Eu nomearia diferente"

Inconsistente, subjetivo, cria conflito

Review contra o plano

  • • "O critério #3 da spec não está coberto"
  • • "A tarefa 5 especificou o caminho X, está Y"
  • • "O caso de borda 'email vazio' não tem handler"
  • • "O teste de verificação da tarefa 3 falha"

Objetivo, verificável, produtivo

4

🚦 Severidade de issues: bloqueadores vs. sugestões

Nem toda issue de review tem a mesma urgência. Classificar issues por severidade evita que o desenvolvimento seja paralisado por feedback estilístico enquanto problemas reais esperam na fila.

BLOQUEADORImpede o merge. Deve ser corrigido.
  • • Bug de segurança ou dados
  • • Critério de aceitação não cumprido
  • • Teste que falha na CI
  • • Regressão em funcionalidade existente
IMPORTANTEDeve ser corrigido mas não bloqueia o merge.
  • • Problema de performance relevante
  • • Falta de tratamento de erro
  • • Código duplicado significativo
SUGESTÃOMelhoria opcional para o futuro.
  • • Preferência estilística
  • • Otimização prematura
  • • Alternativa de naming
5

🤖 O code reviewer autônomo

Para code review mais objetivo, use um agente separado como revisor — um agente que não participou da implementação e não tem o viés de quem escreveu o código. O revisor autônomo recebe apenas o diff e a spec, sem o histórico da implementação.

Como configurar o revisor autônomo

  1. 1.Abra uma nova sessão (contexto limpo, sem histórico de implementação)
  2. 2.Passe a spec aprovada e o diff do código
  3. 3.Instrua: "Você é o revisor. Revise contra a spec. Classifique cada issue por severidade."
  4. 4.O revisor não sabe o que o implementador quis fazer — apenas o que está escrito

Por que contexto separado importa

O agente que implementou sabe o que tentou fazer e tem dificuldade de ver o que realmente está no código. Um agente sem esse contexto vê o código como qualquer desenvolvedor novo veria — e encontra issues que o implementador ignoraria.

6

🛠️ Prática: ciclo completo de revisão em um PR real

Usando o código do módulo anterior, execute o ciclo completo de code review: checklist pré-revisão, review por agente externo, classificação de issues, correção e confirmação de merge.

Roteiro do exercício

  1. 1.Execute o checklist pré-revisão no código do módulo anterior
  2. 2.Abra nova sessão e configure o revisor autônomo com spec + diff
  3. 3.Receba o relatório de review com issues classificadas por severidade
  4. 4.Corrija todos os bloqueadores seguindo o processo de receiving-code-review
  5. 5.Documente as sugestões para o futuro
  6. 6.Confirme que o código está pronto para merge

Critério de conclusão

Zero bloqueadores pendentes, todos os testes passando, checklist pré-revisão completo. O código está pronto para merge ou abertura de PR.

Resumo do Módulo 1.7

✓Sei executar o checklist pré-revisão antes de solicitar review
✓Processo de receber feedback com rigor: entender → confirmar → propor → implementar
✓Reviso contra o plano, não contra intuição
✓Classifico issues por severidade: bloqueador, importante, sugestão
✓Sei usar agente externo como revisor autônomo sem viés de implementação
✓Completei o ciclo completo de review em um PR real
Próximo módulo: 1.8 — Git Worktrees e branches paralelos
← Voltar para Trilha Próximo Módulo →