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 pega omissões, sinaliza excesso de confiança e revela áreas de melhoria antes que o usuário precise fazê-lo.

Quando Ativar

• Após escrever código que abrange 3+ arquivos ou 50+ linhas
• Após concluir um fluxo de trabalho de várias etapas (implementar → testar → revisar)
• Após uma sessão de depuração que envolveu 3+ tentativas
• Após 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"
• Ao final de qualquer gancho de parada de sessão (se configurado — veja references/hook-integration.md)

Conceitos Principais

Os 5 Eixos de Avaliação

Eixo	Pergunta	O que pega
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ário?	Redundância, explicação excessiva, repetição da pergunta do usuário na íntegra, conteúdo de enchimento

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 correção
1 — Ruim: falha fundamentalmente na 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 pontuação 3 não pode apenas dizer "poderia ser melhor" — deve dizer exatamente o que está faltando ou errado. O mantra: "Mostre a lacuna, não apenas a nomeie."

Fluxo de Trabalho

Etapa 1: Coletar o Material Bruto

Reúna o que você avaliará:

- A solicitação original do usuário (lida de volta da conversa)
- Sua resposta/saída final (o entregável)
- 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 Independentemente

Percorra os 5 eixos um de cada vez. Para cada um:

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

NÃO calcule a média das pontuações mentalmente 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ências por eixo)
- Pontuação geral (média simples, arredondada para 1 casa 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 pontuou 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-a agora
3. Se a lacuna exigir retrabalho, sinalize-a explicitamente: "Este eixo pontuou [motivo] porque [evidência]. Reexecutar com [correção específica] provavelmente elevaria para [pontuação]."

Exemplos de Código

Exemplo: Boa Avaliação (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 — Cobertos o caminho feliz + 3 casos de erro. Ausente: 
                  tratamento de timeout para conexões penduradas.
  Clareza:      5 — Comentários de código explicam a fórmula de backoff. 
                  A descrição do PR referencia o incidente que motivou isso.
  Acionabilidade:5 — Merge único. 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 (o usuário 
                  disse "todas as solicitações HTTP").
  Clareza:      4 — Código legível. Bons nomes de variáveis.
  Acionabilidade:2 — "Adicione testes" mencionado, mas nenhum arquivo de teste criado. 
                  O usuário precisa escrever testes antes do 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 de reescrita com 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 bem.
   Completude: 5 — Tudo coberto.
   Clareza:      5 — Claro.

Nenhuma evidência citada. Isso é autoparabéns, não avaliação. Uma nota 5 de verdade exige provar que não há nada a melhorar.

Penalizar Excessivamente por Escopo Aumentado

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

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

Usar a Avaliação para Reabrir Discussões

FALHA: "Como eu disse antes, esta abordagem está errada. Pontuação: 1"

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

Misturar Preferência Pessoal com Lacunas Objetivas

FALHA: "Pontuação: 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 pontuação 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ê levou.
• Uma melhoria por eixo fraco. Não liste 5 coisas para um eixo — escolha a lacuna de maior impacto.
• Relacione melhorias ao impacto no usuário. "Tratamento de erro ausente significa que a chamada de API do usuário vai travar silenciosamente" é melhor que "adicione tratamento de erro."
• Seja específico sobre como é a 'correção'. "Reexecutar com transporte httpx configurado para repetições" é melhor 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 — procure a prova.
• Se você não 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
• verificação-loop — Verificação sistemática de saídas em relação aos resultados esperados
• revisão-de-segurança — Checklist de revisão de código focado em segurança