Loop de Revisão
Ciclo iterativo trabalhador-revisor dentro de uma única sessão. Você faz o trabalho, cria um subagente revisor para criticá-lo, revisa com base no feedback, repete até que o patamar de qualidade seja atingido.
Princípio central: Rascunhos iniciais nunca são finais. A crítica iterativa produz melhores resultados do que uma única passagem.
Nota sobre a plataforma: Esta habilidade funciona melhor com agentes que suportam a criação de subagentes. Em plataformas sem essa capacidade, simule a etapa de revisor abrindo um novo contexto de chat, colando apenas o produto do trabalho (sem raciocínio anterior) e pedindo para avaliar de 1 a 10 com feedback específico.
Início Rápido
- Diga:
"implemente X, use review-loop"ou"execute review-loop no arquivo que acabei de escrever" - O agente faz o trabalho (ou lê o trabalho existente)
- Um subagente crítico separado avalia de 1 a 10 com feedback específico
- O agente revisa e repete até que a pontuação seja >= 8 (patamar de qualidade padrão)
- Um resumo do loop é entregue com o resultado final
Quando Usar
- O usuário diz "use review-loop", "polir isso", "iterar nisso", "/review-loop"
- Implementações complexas onde a qualidade importa mais que a velocidade
- Documentos de design, especificações ou escrita técnica
- Código que precisa ser robusto (segurança, pipelines de dados, lógica financeira)
- Quando o usuário deseja uma crítica adversarial incorporada ao processo
Quando NÃO Usar
- Correções simples, edições rápidas, alterações de uma linha
- Tarefas onde os testes são o patamar de qualidade (use TDD + CI)
- Quando o usuário só quer que seja feito rapidamente
- Trabalho exploratório/protótipo onde o objetivo é aprender, não entregar
- Tarefas sem critérios de aceitação claros — defina-os primeiro, depois use review-loop
Padrões
| Configuração | Padrão |
|---|---|
| Mínimo de loops | 2 |
| Máximo de loops | 4 |
| Patamar de qualidade | 8/10 |
| Modelo trabalhador | (seu modelo atual) |
| Modelo revisor | (seu modelo atual ou alternativo rápido/equilibrado) |
Seleção de Modelo
A tarefa do revisor avalia lógica e restrições. A tarefa do trabalhador escreve e modifica código. Escolha as capacidades do subagente de acordo.
REGRRA CRÍTICA: O Revisor deve ser sempre IGUAL OU MAIS PODEROSO que o Trabalhador. Se o revisor for mais fraco que o trabalhador, ele não conseguirá criticar adequadamente a lógica complexa ou capturar regressões sutis.
| Complexidade da Tarefa | Capacidade do Trabalhador | Capacidade do Revisor | Justificativa |
|---|---|---|---|
| Simples/mecânica (CRUD, formatação, boilerplate) | Rápido / Leve | Equilibrado | Trabalhador leve é rápido, revisor equilibrado detecta problemas facilmente |
| Padrão (funcionalidades, refatorações, docs) | Equilibrado | Equilibrado | Bom equilíbrio entre custo, velocidade e qualidade |
| Complexa (multiarquivo, integração, design) | Equilibrado | Avançado / Raciocínio | Revisor avançado detecta problemas de arquitetura sutis, trabalhador equilibrado pode implementá-los |
| Muito complexa (segurança, quant, sistemas distribuídos) | Avançado / Raciocínio | Avançado / Raciocínio | Ambos precisam de contexto completo e poder de raciocínio. O revisor DEVE ter o mesmo poder do trabalhador. |
A regra de ouro: O trabalhador deve ser inteligente o suficiente para AGIR com base no feedback do revisor. Se o revisor disser "corrija a condição de corrida com um semáforo baseado em canal" e o trabalhador não consegue raciocinar sobre concorrência, o loop não convergirá.
Sinal de escalada: Se a pontuação não melhorar após 2 loops consecutivos com o mesmo feedback, o modelo trabalhador é muito fraco. Escale:
- Opção A: Peça ao usuário para mudar para um modelo mais capaz
- Opção B: Abaixe temporariamente o patamar de qualidade e anote a lacuna para o usuário
- Opção C: Divida a tarefa em subtarefas menores e execute review-loop em cada uma
Comportamento padrão: Como você (o agente principal) É o trabalhador, crie um subagente revisor que corresponda ou exceda sua capacidade atual com base na tarefa:
- A maioria das tarefas → Revisor Padrão/Equilibrado
- Tarefas especializadas/difíceis → Revisor Avançado/Raciocínio
- Verificações rápidas → Revisor Rápido/Leve (apenas se você também estiver atuando como trabalhador leve)
Substituições do Usuário
Usuários podem substituir qualquer padrão embutido em sua solicitação. Analise-os naturalmente:
"implemente X com review-loop, patamar de qualidade 9, use modelo avançado para revisão, máx 5 loops"
"polir isso, mínimo 2 loops, patamar em 8"
"execute review-loop com revisor rápido, máx 2 loops"
"use review-loop, revisor de raciocínio, patamar de qualidade 9, mín 3 máx 6"
Regras de análise:
- "patamar de qualidade N" ou "gate N" → quality_gate = N
- "revisor [modelo]" ou "revisar com [modelo]" → substituição do modelo revisor
- "máx N loops" → max_loops = N
- "mín N loops" → min_loops = N
- Se o usuário não especificar, use os padrões
- Se o usuário disser "completo" ou "rigoroso" → interpretar como quality_gate 8, min_loops 2
- Se o usuário disser "rápido" ou "veloz" → interpretar como max_loops 2, quality_gate 6
O Processo
flowchart TD
A[Faça o trabalho] --> B[Crie subagente revisor]
B --> C{Loops mínimos cumpridos?}
C -- não, sempre continue --> E[Revise com base no feedback]
C -- sim --> D{Pontuação >= patamar de qualidade?}
D -- sim --> F[Passo de polimento final]
D -- não --> G{Máximo de loops atingido?}
G -- sim, pare mesmo assim --> F
G -- não --> E
E --> B
F --> H([Concluído])
Passo a Passo
Passo 1: Faça o Trabalho
Complete a tarefa como faria normalmente. Escreva o código, crie a especificação, implemente a funcionalidade. Não se segure — produza sua melhor primeira tentativa.
Passo 2: Crie o Subagente Revisor
Use a ferramenta Agente para despachar um revisor. O revisor deve:
- Ser um subagente separado (contexto fresco, sem ancoragem ao seu raciocínio)
- Receber apenas o produto do trabalho (arquivos, diffs) — não seu processo de pensamento
- Avaliar de 1 a 10 com feedback específico e acionável
- Usar um modelo equilibrado/padrão por padrão (ou um modelo de raciocínio avançado para tarefas complexas/especializadas)
Modelo de prompt do revisor:
Você é um revisor crítico. Avalie o seguinte trabalho de 1 a 10 e forneça feedback específico e acionável.
## O que foi feito
{breve descrição da tarefa}
## Critérios de revisão
{critérios específicos da tarefa — o que importa para ESTA tarefa}
Exemplos de critérios bem escritos:
Para um endpoint de API REST:
- Códigos de status HTTP corretos usados
- Validação de entrada presente em todos os parâmetros
- Autenticação aplicada; sem acesso não autenticado
- Sem padrões de consulta N+1
Para um documento de design:
- Declaração do problema é inequívoca
- Alternativas consideradas com trade-offs
- Sem generalizações sobre complexidade de implementação
- Métricas de sucesso são mensuráveis
Para um pipeline de dados:
- Idempotente — seguro para reexecutar
- Alterações de esquema tratadas graciosamente
- Modos de falha documentados
- Tratamento de PII abordado
## Instruções
1. Leia o trabalho cuidadosamente
2. Avalie de 1 a 10 onde:
- 1-3: Fundamentalmente quebrado ou faltando requisitos importantes
- 4-6: Funciona, mas tem problemas significativos
- 7-8: Bom, apenas problemas menores
- 9-10: Excelente, pronto para entrega
3. Liste problemas específicos com referências de arquivo:linha quando aplicável
4. Para cada problema, explique POR QUE é importante e O QUE corrigir
5. Não seja educado — seja honesto e direto
6. Declare sua pontuação claramente como "Pontuação: N/10"
## Arquivos para revisar
{cole o conteúdo do arquivo ou liste os caminhos dos arquivos com trechos relevantes}
Passo 3: Analise o Feedback
Da resposta do revisor, extraia:
- Pontuação (o número)
- Problemas (categorizados como Crítico / Importante / Menor)
- Correções específicas (o que mudar)
Relate ao usuário:
Loop {N}/{max}: Pontuação {X}/10
- {resumo dos principais pontos de feedback}
Passo 4: Verifique as Condições de Parada
Nesta ordem:
- Se loops concluídos < min_loops → continue (sempre)
- Se pontuação >= patamar de qualidade → pare, vá para o polimento final
- Se loops concluídos >= max_loops → pare, vá para o polimento final
- Caso contrário → revise e faça o loop
Passo 5: Revise
Aborde o feedback do revisor. Corrija problemas Críticos e Importantes. Problemas Menores são opcionais. Em seguida, volte ao Passo 2.
Importante: Cada revisão deve ser direcionada. Não reescreva tudo — corrija o que o revisor sinalizou. Mantenha uma lista mental de TODO o feedback anterior para evitar regressões.
Passo 6: Polimento Final
Assim que o loop sair (patamar de qualidade atingido ou máximo de loops alcançado):
- Aborde quaisquer problemas menores restantes, se triviais
- Verifique se o resultado final é coerente (sem artefatos dos ciclos de revisão)
- Relate a pontuação final e o número de loops ao usuário
Adaptando Critérios do Revisor por Tipo de Tarefa
| Tipo de Tarefa | O Revisor Deve Focar Em |
|---|---|
| Código | Correção, casos extremos, tratamento de erros, legibilidade, sem problemas de segurança |
| Especificação/Design | Completude, viabilidade, sem generalizações, implementabilidade |
| Refatoração | Sem alterações de comportamento, sem regressões, mais limpo que antes |
| Escrita | Clareza, estrutura, adequado ao público, sem floreios |
| Correção de bug | Causa raiz abordada, teste de regressão existe, sem efeitos colaterais |
| Infraestrutura / IaC | Idempotência, privilégio mínimo, sem segredos codificados, segurança de destruição |
| Migração de banco de dados | Reversibilidade, estratégia de índices, risco de perda de dados, desempenho em escala |
| Design de API | Compatibilidade backward, autenticação, versionamento, contrato de erros |
| Suíte de testes | Cobertura de casos extremos, sem interdependência de testes, asserções significativas |
Dois Modos de Operação
Modo A: "Fazer e Revisar" (ciclo completo)
Usuário dá uma tarefa + diz para usar review-loop. Você faz o trabalho E executa o loop de revisão.
Usuário: "Implemente a camada de cache. Use review-loop, patamar de qualidade 8."
Você:
1. Implementa a camada de cache
2. Cria revisor → Pontuação 6, feedback: falta despejo, sem TTL
3. Revisa: adiciona despejo + TTL
4. Cria revisor → Pontuação 8, feedback: pequena questão de nomenclatura
5. Polimento final, concluído
Modo B: "Revisar Existente" (apenas revisão)
Usuário já fez o trabalho ou você já fez o trabalho. Apenas execute o loop de revisão sobre o que existe.
Usuário: "Execute review-loop no módulo de autenticação que acabei de escrever"
Você:
1. Lê o módulo de autenticação
2. Cria revisor → Pontuação 5, feedback: injeção de SQL, sem limite de taxa
3. Corrige: parametriza consultas, adiciona limitador de taxa
4. Cria revisor → Pontuação 8, aprovado
5. Concluído
Sinais de Alerta
Nunca:
- Auto-revisar em vez de criar um subagente (viés de ancoragem)
- Pular um ciclo de revisão porque "o feedback está errado" sem justificativa
- Inflar sua própria pontuação ("Acho que isso é na verdade um 9")
- Continuar além de max_loops sem consentimento do usuário
- Criar o revisor com seu raciocínio/histórico completo (eles devem revisar o TRABALHO, não sua intenção)
Se o revisor estiver errado:
- Contra-argumente com evidências (mostre código/testes que refutem o feedback)
- Pule esse ponto específico na revisão
- Anote em seu relatório ao usuário
- NÃO abaixe o padrão de qualidade para compensar
Exemplo de Formato de Relatório
--- Loop de Revisão: {nome da tarefa} ---
Loop 1/4: Pontuação 6/10
Revisor: Validação de entrada ausente, sem tratamento de erro para timeout de rede,
função muito longa (80 linhas).
Ação: Corrigindo todos os três problemas.
Loop 2/4: Pontuação 8/10
Revisor: Limpo. Menor: o nome da variável `d` poderia ser mais descritivo.
Ação: Patamar de qualidade atingido (8 >= 8). Polimento final.
Resultado: 8/10 em 2 loops. Concluído.
Limitações Conhecidas
- O subagente revisor não tem memória de loops anteriores — inclua contexto de feedback anterior explicitamente em cada prompt do revisor para evitar repetir problemas resolvidos
- A inflação de pontuação é possível se os critérios do prompt do revisor forem muito vagos — invista tempo escrevendo critérios específicos e mensuráveis
- Esta habilidade não substitui a revisão humana de código para código crítico de segurança ou sensível a conformidade; trate o resultado como uma primeira passagem forte
- A convergência do loop não é garantida se a tarefa for subespecificada — defina critérios de aceitação claros antes de começar
Custo e Velocidade
- Cada loop = 1 chamada de subagente revisor
- Orçamento aproximadamente 1–2x o tempo de uma única passagem de implementação para um ciclo completo de 3 loops
- Isso é barato comparado a enviar código com bugs, especificações vagas ou desencadear um ciclo de revisão tardio
- Use seu modelo padrão/equilibrado para a maioria das revisões; atualize apenas para modelos de raciocínio avançado para domínios especializados (auditorias de segurança, sistemas distribuídos, finanças quantitativas)
Licença
MIT — livre para usar, adaptar e redistribuir com qualquer ferramenta ou plataforma de IA. Atribuição apreciada. Contribuições bem-vindas.