Agentic Quality Loop — construir, provar, julgar e aprender

O problema da prova corrigida pelo próprio autor

Um agente cria uma página, lê o próprio código e responde “está profissional”. Porém, o menu não abre por teclado e o formulário perde dados ao recarregar. A produção ocorreu; a avaliação real não.

O princípio deste capítulo é: quem produz não deve ser a única entidade que decide se o resultado está correto. Isso não exige sempre múltiplos agentes. Para uma função pequena, teste automatizado e revisão de diff podem fornecer separação suficiente. Para design subjetivo ou tarefa crítica, um avaliador com contexto separado pode ser necessário.

Ao final, você deverá conseguir classificar a tarefa, definir a prova antes do código, executar o fluxo adequado e encerrar com estado honesto.

Termos e papéis

• Builder ou construtor: produz ou corrige o artefato.
• Preparer ou preparador: transforma critérios em uma receita executável e verifica se as ferramentas de avaliação funcionam.
• Judge ou juiz: aplica a receita ao artefato sem depender da justificativa do construtor.
• Preflight: ensaio curto que comprova que a ferramenta de avaliação está disponível.
• Rubric: critérios explícitos para um aspecto que não possui resposta binária simples.
• Critical gate: falha que reprova a entrega independentemente da média.
• Best-of-N: criação de candidatos independentes para posterior seleção.
• Gauntlet: ciclo de refinamento subjetivo com rubrica, crítico e limite de rodadas. Não é um padrão universal.
• Ralph loop: nome comunitário para ciclos persistentes de implementação guiados por plano e testes. Só faz sentido com trabalho claro, estado durável e parada.
• Regressão: teste permanente criado para impedir o retorno de uma falha.

A sequência correta

O fluxo não autoriza repetição infinita. maxRounds, orçamento e condição de parada são definidos antes da primeira construção.

Roteamento S0 a S3

S0 — resposta direta

Use para explicação, busca pequena ou transformação de baixo risco. O agente principal responde e explicita incerteza. Não há justificativa para construtores paralelos.

S1 — alteração pequena

Use quando o resultado é objetivo e localizado. Exemplo: corrigir texto de botão e atualizar um teste. Fluxo: entender → alterar → check determinístico → revisar diff.

S2 — funcionalidade completa

Use para uma fatia vertical. Exige especificação, EvalRecipe, implementação, testes de integração e revisão independente proporcional. O primeiro projeto web do capítulo anterior é S2.

S3 — tarefa longa, crítica ou subjetiva

Use quando há alto impacto, muitas dependências, grande espaço de solução ou julgamento subjetivo relevante. Pode empregar preparador e juiz em contextos separados, Best-of-N para uma parte crítica e aprovação humana. S3 não significa permissão ampla.

Preparar antes de construir

Uma EvalRecipe mínima responde:

artifactKind: web
objective: registrar uma observação sintética em OS-101
preflight:
  - servidor inicia em porta local
  - navegador abre uma página de teste
deterministicChecks:
  - lint
  - typecheck
  - testes de vazio e persistência
subjectiveRubric:
  - hierarquia deixa clara a OS selecionada
adversarialCases:
  - texto vazio
  - texto longo
  - recarregar durante salvamento
criticalFailures:
  - perda de dado após confirmação
  - erro de console no fluxo principal
evidenceRequired:
  - comandos e códigos de saída
  - captura dos três estados
maxRounds: 2

O preparador não adapta os critérios para fazer o resultado existente parecer bom. Ele usa a especificação e verifica a própria ferramenta. Se o navegador não abrir, o problema da ferramenta não deve ser contado como bug do produto nem como aprovação.

Checks determinísticos antes do juiz

Use código para aquilo que código prova melhor:

• schema válido;
• IDs únicos;
• função retorna valor esperado;
• endpoint responde status correto;
• autorização nega usuário indevido;
• interface não possui overflow medido;
• build termina com código zero.

Um modelo julgador é apropriado para clareza, coerência, utilidade ou qualidade visual, desde que exista rubrica e que seu parecer não substitua portões críticos.

Exemplo: design 9, acessibilidade 8 e autenticação 0 não produz média 5,7 aceitável. Autenticação quebrada é critical gate e resulta em FAIL.

Independência sem teatro

Independência pode ser obtida por diferentes meios:

1. teste escrito a partir do requisito antes do código;
2. revisão humana do diff;
3. agente revisor com contexto limpo, recebendo spec, artefato e receita;
4. ferramenta externa que mede o comportamento.

Não crie um “juiz” que apenas repete o resumo do construtor. O avaliador deve ver o artefato e executar a prova.

Quando paralelizar

Paralelize trabalhos sem escrita sobreposta: pesquisar fontes distintas, testar plataformas diferentes ou gerar dois candidatos para uma decisão visual crítica. Evite dividir por arquivo quando as decisões são compartilhadas.

O custo é real. A documentação atual do Codex informa que subagentes consomem mais tokens que uma execução comparável de um único agente. Experimentos de harness da Anthropic também registram ganhos acompanhados de horas de execução e custos muito maiores. A escolha precisa considerar qualidade, latência e custo.

Segurança e autoridade

O juiz não concede permissão operacional ao construtor. Para ação crítica:

modelo propõe
→ política determinística verifica ator, recurso e parâmetros
→ pessoa aprova quando necessário
→ executor isolado age
→ trace registra
→ eval confirma o efeito

Enviar e-mail, alterar permissão, implantar produção, excluir dados ou movimentar dinheiro exige um portão explícito. Um prompt dizendo “tenha cuidado” não é esse portão.

Falha, correção e regressão

Suponha que clicar duas vezes reserve duas peças. O juiz registra:

entrada: dois envios com a mesma chave
esperado: uma reserva
observado: duas reservas
estado: FAIL

O construtor adiciona idempotência. Antes de aprovar, o mesmo caso é executado novamente. Depois, o caso permanece na suíte. A retrospectiva não termina em “o agente errou”; identifica a capacidade ausente e a torna legível e obrigatória.

Condições de parada

O ciclo encerra quando ocorrer o primeiro:

• todos os critérios e portões passam;
• maxRounds é alcançado;
• o orçamento termina;
• a melhoria entre rodadas fica abaixo do limiar definido;
• surge dependência que exige autoridade ou decisão humana;
• a ferramenta essencial permanece indisponível.

Nunca interprete “continue até ficar perfeito” como autorização infinita. Perfeição não é critério executável.

Um caso completo: corrigir duplicação de ordens

Considere uma falha real: ao clicar duas vezes em “Criar”, o aplicativo grava duas ordens idênticas. A correção atravessa interface, API e banco. O roteador classifica S2 porque há comportamento ponta a ponta, risco operacional e mais de uma fronteira.

Antes do código, o preparador define a prova:

• enviar duas requisições simultâneas com a mesma chave de idempotência;
• confirmar uma única ordem persistida;
• confirmar que as respostas apontam para o mesmo identificador;
• repetir com chaves diferentes e confirmar duas ordens;
• verificar que logs não registram token ou dado sensível;
• preservar a criação única normal.

O construtor pode bloquear o botão no frontend, tratar a chave na API e criar uma restrição no banco. Bloquear o botão melhora experiência, mas não protege contra repetição de rede; a API coordena a intenção; o banco protege a invariável final. Nenhum prompt substitui essas fronteiras.

Checks determinísticos executam concorrência, regressão, typecheck e schema. Se falharem, o trabalho volta ao construtor antes de gastar julgamento subjetivo. Depois, um revisor independente verifica especificação e escopo. Só existe PASS quando as evidências obrigatórias estão presentes. Se o banco de teste estiver indisponível, use UNVERIFIED; se outra equipe precisa liberar credencial, use BLOCKED.

Como o juiz deve trabalhar

O juiz recebe especificação, rubrica, evidências e artefato — não apenas “avalie se está bom”. Cada achado aponta critério, impacto e reprodução. Preferências sem vínculo com o objetivo não pertencem ao gate.

Use código para fatos objetivos: schema válido, teste passou, link existe, resposta contém campo. Use pessoa ou modelo julgador para clareza, coerência visual ou adequação de uma explicação, calibrando o julgamento com exemplos aprovados e reprovados.

Há duas conformidades. Conformidade com a especificação pergunta se a solução resolve o problema e respeita o escopo. Conformidade de engenharia pergunta se é segura, testável, operável e compatível. Uma solução pode funcionar e vazar segredo; outra pode ser elegante e não resolver a jornada.

Orçamento e rodadas são controles

Mais rodadas não garantem resultado melhor. Defina máximo de tentativas, tempo ou custo, falhas que encerram imediatamente e pessoa responsável por exceções. Quando o limite termina sem prova, preserve UNVERIFIED. Isso é mais confiável que continuar até os créditos acabarem ou até o modelo declarar vitória.

Para S3, persista plano, estado, testes e decisões no repositório. Sessões frescas podem revisar de forma independente, mas recebem handoff pequeno e verificável. Copiar todo o histórico tende a transportar ruído e as mesmas premissas que causaram o erro.

Como era e como funciona atualmente

Uma revisão tradicional frequentemente acontece depois da implementação: alguém abre o diff, procura problemas e decide se aprova. Esse fluxo continua útil, mas chega tarde quando ninguém definiu antes como demonstrar sucesso. Em desenvolvimento com agentes, o risco aumenta porque o mesmo sistema pode produzir código, executar testes e escrever uma justificativa convincente.

O loop atual desloca parte da revisão para antes da construção. O preparador transforma critérios em casos e gates; o construtor trabalha contra essa prova; checks objetivos filtram falhas; um contexto independente avalia o restante. Isso não significa criar quatro agentes para toda mudança. Em S1, a mesma pessoa pode preparar um teste simples, implementar e pedir revisão curta. A separação mais forte aparece conforme risco e subjetividade aumentam.

Revisão humana continua indispensável quando existe responsabilidade legal, impacto financeiro, mudança de permissão ou julgamento de produto. Um modelo julgador pode organizar evidência e localizar incoerências, mas não recebe autoridade por parecer confiante. O desenho profissional separa capacidade de sugerir, política de autorizar e mecanismo de executar.

Falhas comuns

Falha	Diagnóstico	Controle
critérios após a construção	receita favorece o candidato	definir aceite e eval primeiro
juiz lê apenas relatório	não houve teste real	executar artefato e ferramenta
média esconde risco crítico	gate mal modelado	reprovação imediata por categoria
rodadas intermináveis	sem saturação ou orçamento	maxRounds e stop condition
agentes editam o mesmo ponto	decomposição por arquivo	dividir por responsabilidade ou serializar
não testado aparece como aprovado	estados colapsados	preservar UNVERIFIED

Laboratório de mesa

Escolha uma tarefa S2. Escreva a spec e a EvalRecipe antes de mostrar qualquer solução ao construtor. Depois simule quatro resultados: um PASS, um FAIL, uma ferramenta ausente e uma dependência externa. Classifique-os como PASS, FAIL, UNVERIFIED ou BLOCKED e justifique.

Crie ainda uma regressão para o FAIL. A evidência final é um pacote contendo requisito, caso, comando ou procedimento, esperado, observado, estado e decisão. “O juiz gostou” não é suficiente.

Recuperação ativa

Por que o preparador atua antes do construtor? Quando um teste substitui um juiz LLM? O que diferencia S2 de S3? Por que Best-of-N não deve ser usado em tudo? O que é um critical gate? Quando o ciclo precisa parar? Como uma falha ensina a próxima execução?

O último capítulo transforma essas regras em documentos curtos e copiáveis.