Autoavaliação do Agente

O que Autoavaliação do Agente faz?

Após concluir uma tarefa complexa, o agente pausa para avaliar sua própria saída com base em uma rubrica estruturada de 5 eixos. Isso NÃO é uma barreira de aprovação/reprovação — é uma etapa deliberada de reflexão que captura omissões, sinaliza excesso de confiança e revela áreas de melhoria antes que o usuário precise apontá-las.

Quando Ativar

• Depois de escrever código que abrange 3+ arquivos ou 50+ linhas
• Depois de concluir um fluxo de trabalho com várias etapas (implementar → testar → revisar)
• Depois de uma sessão de depuração que envolveu 3+ tentativas
• Depois de produzir um documento de design, decisão de arquitetura ou análise escrita
• Quando o usuário perguntar "quão bom foi isso?" ou "avalie-se"
• No final de qualquer sessão que tenha um gancho Stop configurado (se configurado — consulte references/hook-integration.md)

Conceitos Centrais

Os 5 Eixos de Avaliação

Eixo	Pergunta	O que captura
Precisão	Os fatos, alegações e saídas estão corretos?	Alucinações, nomes de API errados, sintaxe incorreta, declarações falsas
Completude	Cobriu tudo o que o usuário pediu?	Casos extremos perdidos, caminhos de erro não tratados, requisitos esquecidos, subtarefas ignoradas
Clareza	A explicação é compreensível e bem estruturada?	Explicações confusas, jargões sem definição, contexto ausente, divagações
Acionabilidade	O usuário pode agir imediatamente com base na saída?	Sugestões vagas, etapas ausentes, "você deveria X" sem mostrar como, sem caminho de verificação
Concisão	Usou o mínimo de palavras/tokens necessários?	Redundância, superexplicação, repetição da pergunta do usuário textualmente, conteúdo de preenchimento

Escala de Pontuação

5 — Excepcional: nenhuma melhoria razoável possível
4 — Bom: apenas pequenos detalhes, sem lacunas substanciais
3 — Adequado: atende à solicitação, mas tem uma fraqueza notável em pelo menos um eixo
2 — Fraco: tem uma lacuna clara que afeta a usabilidade ou a correção
1 — Ruim: falha fundamentalmente em atender à solicitação ou contém erros significativos

A Regra da Evidência

Toda pontuação abaixo de 5 DEVE citar evidências específicas. Uma nota 3 não pode simplesmente dizer "poderia ser melhor" — deve dizer exatamente o que está faltando ou errado. O lema: "Mostre a lacuna, não apenas a nomeie."

Fluxo de Trabalho

Etapa 1: Coletar o Material Bruto

Reúna o que será avaliado:

- A solicitação original do usuário (lida de volta da conversa)
- Sua resposta/saída final (a entrega)
- Quaisquer saídas de ferramentas que verifiquem a correção (resultados de teste, códigos de saída, saída de lint)
- Qualquer feedback do usuário recebido durante a tarefa (correções, "tente novamente", "isso não está certo")

Etapa 2: Pontuar Cada Eixo de Forma Independente

Trabalhe com os 5 eixos um de cada vez. Para cada um:

1. Leia a pergunta do eixo
2. Encontre evidência (ou falta dela) na saída
3. Atribua uma pontuação de 1 a 5
4. Se a pontuação for < 5, escreva uma nota de melhoria de uma frase citando a lacuna

NÃO calcule a média das pontuações primeiro e depois trabalhe de trás para frente. Pontue cada eixo do zero.

Etapa 3: Produzir o Relatório de Avaliação

Use o modelo de templates/evaluation-report.md. O relatório deve incluir:

- Resumo de uma linha
- Scorecard de 5 eixos (pontuação + evidência por eixo)
- Pontuação geral (média simples, arredondada para 1 decimal)
- 1 a 3 melhorias específicas classificadas por impacto
- Autoverificação: "O usuário concordaria com esta avaliação?"

Etapa 4: Aplicar a Melhoria

Se algum eixo pontuar 3 ou menos:

1. Declare o que você faria de diferente
2. Se a lacuna for corrigível em menos de 30 segundos (link ausente, redação pouco clara), corrija agora
3. Se a lacuna exigir retrabalho, sinalize explicitamente: "Este eixo pontuou [motivo] porque [evidência]. Reexecutar com [correção específica] provavelmente elevaria a pontuação para [nota]."

Exemplos de Código

Exemplo: Avaliação Boa (Pontuação 4+)

Tarefa: Adicionar lógica de repetição ao cliente HTTP

Scorecard:
  Precisão:     5 — Todas as chamadas de API corretas. Verificado: as repetições usam
                   backoff exponencial. Nenhum método alucinado.
  Completude:   4 — Coberto caminho feliz + 3 casos de erro. Ausente:
                   tratamento de timeout para conexões pendentes.
  Clareza:      5 — Comentários no código explicam a fórmula de backoff.
                   A descrição do PR vincula ao incidente que motivou isso.
  Acionabilidade:5 — Único merge. Nenhuma tarefa de acompanhamento. Testes passam.
  Concisão:     4 — 47 linhas no total. O loop de repetição poderia ser extraído
                   para um helper para reduzir ~8 linhas.

Geral: 4,6 — Uma lacuna (tratamento de timeout). Corrigir antes do merge.

Exemplo: Avaliação Fraca (Pontuação 2-3)

Tarefa: Adicionar lógica de repetição ao cliente HTTP

Scorecard:
  Precisão:     2 — Usou urllib3 que não corresponde à nossa
                   base de código baseada em httpx. Biblioteca errada.
  Completude:   3 — Funciona para GET. POST/PUT não tratados (usuário
                   disse "todas as requisições HTTP").
  Clareza:      4 — Código legível. Bons nomes de variáveis.
  Acionabilidade:2 — "Adicionar testes" mencionado, mas nenhum arquivo de teste criado.
                   O usuário precisa escrever testes antes de fazer o merge.
  Concisão:     3 — 120 linhas. A configuração de repetição está duplicada em
                   3 lugares em vez de um único objeto RetryConfig compartilhado.

Geral: 2,8 — Biblioteca errada usada. Precisa reescrever para httpx.
  Corrigir precisão primeiro (mudar para httpx), depois estender para todos os
  métodos HTTP, depois consolidar a configuração.

Antipadrões

"Tudo é nota 5"

FALHA: Precisão:     5 — Tudo certo.
   Completude:   5 — Tudo coberto.
   Clareza:      5 — Claro.

Nenhuma evidência citada. Isso é autoparabenização, não avaliação. Um verdadeiro 5 exige provar que não há nada a melhorar.

Penalizar excessivamente por aumento de escopo

FALHA: Completude:   2 — Não tratou conexões WebSocket ou
   streaming gRPC (usuário não pediu isso)

Avalie apenas o que o usuário realmente solicitou, não o que você poderia ter construído adicionalmente.

Usar a avaliação para rediscutir

FALHA: "Como eu disse antes, esta abordagem está errada. Nota: 1"

A avaliação é sobre a saída entregue, não sobre reargumentar decisões de design que já foram tomadas. Se a abordagem estivesse errada, isso deveria ter sido capturado antes da entrega.

Misturar preferência pessoal com lacunas objetivas

FALHA: "Nota: 3. Não gosto de decoradores Python."

"Não gostar" não é evidência. Cite uma preocupação concreta de legibilidade, testabilidade ou correção, ou deixe a nota em 4+.

Melhores Práticas

• Avalie a saída, não o processo. O usuário se importa com o que você entregou, não com quantas iterações você fez.
• Uma melhoria por eixo fraco. Não liste 5 coisas para um eixo — escolha a lacuna de maior impacto.
• Vincule melhorias ao impacto no usuário. "A ausência de tratamento de erro significa que a chamada de API do usuário falhará silenciosamente" é melhor do que "adicione tratamento de erro."
• Seja específico sobre como é a 'correção'. "Reexecutar com transporte httpx configurado para repetições" é melhor do que "corrija o problema da biblioteca."
• Use saídas de ferramentas como evidência. Se os testes passaram, cite-os. Se o lint está limpo, cite-o. Não adivinhe — busque a prova.
• Se não conseguir encontrar lacunas, tente mais. Uma pontuação perfeita em todos os 5 eixos é rara. Pergunte: "Se eu fosse o usuário, o que me irritaria nesta saída?"

Habilidades Relacionadas

• agent-eval — Comparação direta de diferentes agentes de codificação em tarefas de benchmark
• verification-loop — Verificação sistemática de saídas em relação aos resultados esperados
• security-review — Lista de verificação de revisão de código focada em segurança