Phase 14 - Lesson 39

Agente Revisor: Separe o Construtor do Avaliador

O agente que escreveu o código não pode avaliá-lo. Um revisor é um segundo loop com um prompt de sistema diferente, um objetivo diferente e acesso apenas de leitura a tudo o que o construtor produziu. A lacuna entre o construtor e o revisor é onde reside a maior parte da confiabilidade.

Type: Build Languages: Python (stdlib) Prerequisites: Phase 14 · 38 (Verification Gate) Time: ~55 minutes

Learning Objectives

• Explicar por que o mesmo agente não pode revisar seu próprio trabalho com confiabilidade.
• Construir um loop de agente revisor que consome artefatos do construtor e emite um relatório de revisão estruturado.
• Elaborar uma rubrica de revisor que avalia dimensões específicas, não impressões gerais.
• Conectar o revisor à bancada de trabalho (workbench) para que a etapa de revisão humana comece a partir de um artefato real.

The Problem

Você pede ao agente para corrigir um bug. Ele edita quatro arquivos, executa os testes e informa que terminou. O gate de verificação (Phase 14 · 38) confirma que o teste de aceitação foi executado e o escopo foi mantido. O gate diz passed: true. Você faz o merge. Dois dias depois, descobre que a correção resolveu a metade errada do bug.

A aceitação é necessária, mas não suficiente. O revisor faz as perguntas que a aceitação não pode fazer: isso resolveu o problema correto? Expandiu o escopo sem sinalizar? Documentou suposições que deveriam ter sido questionadas? Deixou a bancada de trabalho em um estado que a próxima sessão possa retomar?

The Concept

flowchart LR
  Builder[Agente Construtor] --> Artifacts[diff + state + feedback + verdict]
  Artifacts --> Reviewer[Agente Revisor]
  Reviewer --> Rubric[reviewer_checklist.md]
  Reviewer --> Report[review_report.json]
  Report --> Human[Aprovação Humana]

Reviewer rubric

Cinco dimensões, cada uma pontuada de 0 a 2.

Total de 10 pontos. Uma execução abaixo de 7 é um soft fail; uma execução abaixo de 5 é um hard fail.

The reviewer is a separate role, not a separate model

Você pode executar o revisor com o mesmo modelo que o construtor. A disciplina está na separação de papéis: prompt de sistema diferente, entradas diferentes, sem acesso de escrita ao diff. A mudança de postura é a mudança no sinal.

The reviewer cannot edit the diff

O revisor lê o diff, o estado, o feedback e o veredicto. Ele escreve um relatório. Ele não altera (patch) o diff. Se o relatório disser "corrija isso", o próximo turno do construtor faz a correção; o revisor volta a revisar. Misturar papéis destrói o distanciamento necessário.

Reviewer rubric versus verification gate

O gate (Phase 14 · 38) verifica fatos determinísticos: se o teste de aceitação foi executado, se as regras passaram, se o escopo foi mantido. O revisor faz julgamentos qualitativos: se este era o trabalho correto, se está documentado, se o handoff é utilizável. Ambos são necessários.

Build It

code/main.py implementa:

• Uma dataclass ReviewerInputs que agrupa os artefatos lidos pelo revisor.
• Um avaliador de rubrica com uma função por dimensão. Cada função é determinística e simplificada (stub-grade) para a lição; implementações reais chamariam um LLM.
• Um gravador de review_report.json com as cinco pontuações, o total e um veredicto (pass, soft_fail, hard_fail).
• Dois casos de demonstração: uma alteração limpa e uma alteração do tipo "testes certos, problema errado".

Execute-o:

python3 code/main.py

Saída: dois relatórios de revisão gravados no disco e uma tabela no console com as pontuações de cada dimensão.

Padrões de produção no mundo real

Os dados reais: O sistema de AI Code Review da Cloudflare em abril de 2026 executou 131.246 análises em 48.095 merge requests em 5.169 repositórios em 30 dias. A revisão mediana foi concluída em 3 minutos e 39 segundos. Até sete revisores especialistas (segurança, desempenho, qualidade do código, documentação, gerenciamento de versão, conformidade, Engineering Codex) foram executados em paralelo sob um Review Coordinator que deduplicou as descobertas e avaliou a gravidade. O modelo de primeira linha foi reservado exclusivamente para o coordenador; os especialistas rodaram em camadas mais baratas.

Quatro padrões fazem isso funcionar em escala.

Pool de especialistas, não um único grande revisor. Um revisor com uma rubrica de 5 dimensões funciona para repositórios individuais. Quando a base de código passa a ter superfícies críticas de segurança, críticas de desempenho e de documentação, divida em especialistas com prompts menores. O coordenador faz a deduplicação; os especialistas nunca executam a rubrica completa. A separação por camadas de modelo ocorre naturalmente: especialistas baratos, coordenador caro.

Mitigação de viés como requisito de design, não otimização. Juízes de LLM mostram quatro vieses confiáveis (Adnan Masood, abril de 2026): viés de posição (GPT-4 40% inconsistente na ordenação (A,B) vs (B,A)), viés de verbosidade (15% de inflação de pontuação em direção a saídas mais longas), autopreferência (juízes preferem saídas da mesma família de modelos), autoridade (juízes supervalorizam referências a autores conhecidos). Mitigações: avaliar ambas as ordenações e contar apenas vitórias consistentes; usar escalas de 1 a 4 que recompensem explicitamente a concisão; rotacionar juízes entre famílias de modelos; remover nomes de autores antes da pontuação.

Conjunto de calibração, não impressões vagas. Um conjunto histórico de 10 a 20 tarefas com veredictos corretos conhecidos. Execute o revisor sobre ele a cada alteração de prompt. Se a concordância com o registro histórico cair abaixo de 80%, a rubrica precisará de revisão antes que o revisor seja implantado. Isso é o que toda equipe eventualmente redescobre; é melhor começar com isso.

Norma híbrida com o gate. O gate de verificação (Phase 14 · 38) lida com as verificações determinísticas (o teste de aceitação foi executado, os testes passaram, o escopo foi mantido). O revisor lida com as verificações semânticas (este era o trabalho correto, as suposições estão documentadas, o handoff é utilizável). As diretrizes da Anthropic para 2026 são explícitas sobre essa divisão: não peça ao revisor para refazer o que o gate já comprova.

Use It

Padrões de produção:

• Subagentes do Claude Code. Um subagente revisor é executado após o construtor fechar uma tarefa. Ele posta um comentário no PR com as pontuações da rubrica.
• Handoffs do OpenAI Agents SDK. O construtor passa a tarefa (handoff) para o Revisor na conclusão da tarefa. O Revisor pode devolver com uma lista de descobertas ou encaminhar para um ser humano.
• Emparelhamento de dois modelos. O construtor roda em um modelo mais rápido e barato. O revisor roda em um modelo mais forte com contexto menor, focado em julgamento.

O revisor é o segundo par de olhos que a bancada de trabalho desenvolve quando os humanos não podem fazer todas as revisões por si mesmos.

Ship It

outputs/skill-reviewer-agent.md gera uma rubrica de revisor específica do projeto, um esboço (stub) de agente revisor conectado aos artefatos do construtor e uma integração com o gate de verificação para que a revisão humana comece a partir de um relatório por escrito em vez de uma página em branco.

Exercises

1. Adicione uma sexta dimensão específica ao domínio do seu produto. Defenda por que ela não é absorvida pelas cinco existentes.
2. Execute o revisor com dois prompts de sistema diferentes (conciso, detalhado). Qual deles produz um relatório que um humano tem mais probabilidade de ler?
3. Adicione um campo confidence por dimensão. Recuse-se a enviar o relatório quando a confiança na dimensão mais baixa estiver abaixo de 0.6.
4. Construa um conjunto de calibração: 10 encerramentos de tarefas históricas com veredictos corretos conhecidos. Execute o revisor sobre eles. Onde ele discorda do registro histórico?
5. Adicione um recurso de "solicitar mais evidências": o revisor pode pedir ao construtor uma execução de teste específica antes de pontuar. Qual é a estratégia de recuo (back-off) correta para que isso não entre em loop?

Key Terms

Further Reading

• OpenAI Agents SDK handoffs
• Anthropic Claude Code subagents
• Cloudflare, Orchestrating AI Code Review at Scale — arquitetura com 7 especialistas + coordenador, 131 mil execuções / 30 dias
• Agent-as-a-Judge: Evaluating Agents with Agents (OpenReview / ICLR) — benchmark DevAI, 366 requisitos hierárquicos de solução
• Adnan Masood, Rubric-Based Evaluations and LLM-as-a-Judge: Methodologies, Biases, Empirical Validation — os 4 vieses e mitigações
• MLflow, LLM-as-a-Judge Evaluation — ferramentas de produção para construtor/avaliador separados
• LangChain, How to Calibrate LLM-as-a-Judge with Human Corrections — fluxo de trabalho de conjunto de calibração
• Evidently AI, LLM-as-a-judge: a complete guide
• Arize, LLM as a Judge — Primer and Pre-Built Evaluators
• Phase 14 · 05 — Self-Refine e CRITIC (baseline de autorrevisão de agente único)
• Phase 14 · 30 — Desenvolvimento de agentes direcionado por avaliação (gerador de conjunto de calibração)
• Phase 14 · 38 — o gate de verificação que o revisor lê
• Phase 14 · 40 — o pacote de handoff que o relatório do revisor alimenta