eval-harness

Habilidade de Eval Harness

Um framework formal de avaliação para sessões do Claude Code, implementando princípios de desenvolvimento orientado por avaliações (EDD).

Quando Ativar

• Configurando desenvolvimento orientado por avaliações (EDD) para fluxos de trabalho assistidos por IA
• Definindo critérios de aprovação/reprovação para conclusão de tarefas do Claude Code
• Medindo a confiabilidade do agente com métricas pass@k
• Criando suítes de teste de regressão para alterações em prompts ou agentes
• Avaliando o desempenho do agente entre versões de modelo

Filosofia

O Desenvolvimento Orientado por Avaliações trata as avaliações como os "testes unitários do desenvolvimento de IA":

• Defina o comportamento esperado ANTES da implementação
• Execute avaliações continuamente durante o desenvolvimento
• Acompanhe regressões a cada mudança
• Use métricas pass@k para medição de confiabilidade

Tipos de Avaliação

Avaliações de Capacidade

Testam se o Claude pode fazer algo que não podia antes:

[AVALIAÇÃO DE CAPACIDADE: nome-da-funcionalidade]
Tarefa: Descrição do que o Claude deve realizar
Critérios de Sucesso:
  - [ ] Critério 1
  - [ ] Critério 2
  - [ ] Critério 3
Saída Esperada: Descrição do resultado esperado

Avaliações de Regressão

Garantem que mudanças não quebrem funcionalidades existentes:

[AVALIAÇÃO DE REGRESSÃO: nome-da-funcionalidade]
Linha de Base: SHA ou nome do checkpoint
Testes:
  - teste-existente-1: PASS/FAIL
  - teste-existente-2: PASS/FAIL
  - teste-existente-3: PASS/FAIL
Resultado: X/Y aprovados (anteriormente Y/Y)

Tipos de Avaliadores

1. Avaliador Baseado em Código

Verificações determinísticas usando código:

# Verifica se o arquivo contém o padrão esperado
grep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"

# Verifica se os testes passam
npm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"

# Verifica se a build é bem-sucedida
npm run build && echo "PASS" || echo "FAIL"

2. Avaliador Baseado em Modelo

Use o Claude para avaliar saídas abertas:

[PROMPT DO AVALIADOR DE MODELO]
Avalie a seguinte mudança de código:
1. Ela resolve o problema declarado?
2. Está bem estruturada?
3. Os casos de borda são tratados?
4. O tratamento de erros é adequado?

Pontuação: 1-5 (1=ruim, 5=excelente)
Justificativa: [explicação]

3. Avaliador Humano

Sinalizar para revisão manual:

[REVISÃO HUMANA NECESSÁRIA]
Alteração: Descrição do que mudou
Motivo: Por que a revisão humana é necessária
Nível de Risco: BAIXO/MÉDIO/ALTO

Métricas

pass@k

"Pelo menos um sucesso em k tentativas"

• pass@1: Taxa de sucesso na primeira tentativa
• pass@3: Sucesso dentro de 3 tentativas
• Alvo típico: pass@3 > 90%

pass^k

"Todas as k tentativas são bem-sucedidas"

• Critério mais alto para confiabilidade
• pass^3: 3 sucessos consecutivos
• Use para caminhos críticos

Fluxo de Trabalho de Avaliação

1. Definir (Antes de Codificar)

## DEFINIÇÃO DE AVALIAÇÃO: funcionalidade-xyz

### Avaliações de Capacidade
1. Pode criar nova conta de usuário
2. Pode validar formato de e-mail
3. Pode hash de senha de forma segura

### Avaliações de Regressão
1. Login existente ainda funciona
2. Gerenciamento de sessão inalterado
3. Fluxo de logout intacto

### Métricas de Sucesso
- pass@3 > 90% para avaliações de capacidade
- pass^3 = 100% para avaliações de regressão

2. Implementar

Escreva código para passar nas avaliações definidas.

3. Avaliar

# Executar avaliações de capacidade
[Executar cada avaliação de capacidade, registrar PASS/FAIL]

# Executar avaliações de regressão
npm test -- --testPathPattern="existente"

# Gerar relatório

4. Relatar

RELATÓRIO DE AVALIAÇÃO: funcionalidade-xyz
========================

Avaliações de Capacidade:
  criar-usuário:     PASS (pass@1)
  validar-email:  PASS (pass@2)
  hash-senha:   PASS (pass@1)
  Geral:         3/3 aprovados

Avaliações de Regressão:
  fluxo-login:      PASS
  gerenciamento-sessão:    PASS
  fluxo-logout:     PASS
  Geral:         3/3 aprovados

Métricas:
  pass@1: 67% (2/3)
  pass@3: 100% (3/3)

Status: PRONTO PARA REVISÃO

Padrões de Integração

Pré-Implementação

/eval define nome-da-funcionalidade

Cria arquivo de definição de avaliação em .claude/evals/nome-da-funcionalidade.md

Durante a Implementação

/eval check nome-da-funcionalidade

Executa as avaliações atuais e relata o status

Pós-Implementação

/eval report nome-da-funcionalidade

Gera relatório completo da avaliação

Armazenamento de Avaliações

Armazene avaliações no projeto:

.claude/
  evals/
    funcionalidade-xyz.md      # Definição da avaliação
    funcionalidade-xyz.log     # Histórico de execução da avaliação
    baseline.json       # Linhas de base de regressão

Melhores Práticas

1. Defina avaliações ANTES de codificar - Força pensamento claro sobre critérios de sucesso
2. Execute avaliações com frequência - Detecte regressões cedo
3. Acompanhe pass@k ao longo do tempo - Monitore tendências de confiabilidade
4. Use avaliadores de código quando possível - Determinístico > Probabilístico
5. Revisão humana para segurança - Nunca automatize completamente verificações de segurança
6. Mantenha as avaliações rápidas - Avaliações lentas não são executadas
7. Versionar avaliações com código - Avaliações são artefatos de primeira classe

Exemplo: Adicionando Autenticação

## AVALIAÇÃO: adicionar-autenticação

### Fase 1: Definir (10 min)
Avaliações de Capacidade:
- [ ] Usuário pode se registrar com e-mail/senha
- [ ] Usuário pode fazer login com credenciais válidas
- [ ] Credenciais inválidas são rejeitadas com erro apropriado
- [ ] Sessões persistem após recarregar a página
- [ ] Logout limpa a sessão

Avaliações de Regressão:
- [ ] Rotas públicas ainda estão acessíveis
- [ ] Respostas da API inalteradas
- [ ] Esquema do banco de dados compatível

### Fase 2: Implementar (variável)
[Escrever código]

### Fase 3: Avaliar
Executar: /eval check adicionar-autenticação

### Fase 4: Relatar
RELATÓRIO DE AVALIAÇÃO: adicionar-autenticação
==============================
Capacidade: 5/5 aprovados (pass@3: 100%)
Regressão: 3/3 aprovados (pass^3: 100%)
Status: PODE PUBLICAR

Utilitários Locais do Framework

Os utilitários mecânicos são fornecidos em scripts/lib/eval-harness/:

node scripts/eval-harness.js example

• Cápsula: diário vinculado por hash com cinco linhagens e verificações de integridade local.
• Inspeção: resumos de origem, caminhos de variantes validados e avisos sintáticos.
• Reprodução: ferramentas declaradas e fixtures endereçadas por conteúdo. Fixtures ausentes falham fechadas; SE3 e superiores são recusados na reprodução. O modo de gravação invoca a implementação registrada, portanto, registre apenas funções confiáveis.
• Recibo: verificação offline de cápsula e bytes de artefato, com verificações nomeadas.
• Preparação retrospectiva: node scripts/eval-harness.js capsule group <dir> [<dir> ...] agrupa de 1 a 100 snapshots de cápsula local explicitamente selecionados e verificados de uma família de tarefas pela versão declarada do harness. Snapshots repetidos contam uma vez; identidades conflitantes ou cápsulas inválidas rejeitam todo o relatório. Isto é contagem de registros somente leitura, sem novos lançamentos, pontuações ou promoções. Use cápsulas pequenas e quiescentes. Cargas úteis, argumentos de diretório e IDs brutos de execução/cápsula são omitidos, mas rótulos de família de tarefas/versão são textuais e referências de resumo são vinculáveis; revise-os antes de compartilhar. A validação operacional permanece pendente.

A execução de candidatos está desabilitada em todos os SOs porque nenhum backend de contenção de SO verificado está implementado. gate run, runGate, runVariant, lançamento filho direto, e o efeito obsoleto preload recusam com gate.isolation_required. Nenhuma flag de confiança ou executor fornecido pelo chamador pode contornar a recusa. O exemplo registra essa recusa e inspeciona a origem sem executá-la ou pontuá-la.

Não apresente avisos estáticos, um recibo de cápsula ou testes de utilitário bem-sucedidos como evidência de contenção ou promoção de candidato. Um gate futuro requer um limite de SO revisado de forma independente, verificador protegido e canais de auditoria, e rejeição fatal de linha de base. Consulte docs/architecture/eval-harness-frameworks.md.

Avaliações de Produto (v1.8)

Use avaliações de produto quando a qualidade do comportamento não puder ser capturada apenas por testes unitários.

Tipos de Avaliadores

1. Avaliador de código (asserções determinísticas)
2. Avaliador de regras (restrições de regex/esquema)
3. Avaliador de modelo (rubrica LLM-como-juiz)
4. Avaliador humano (arbitragem manual para saídas ambíguas)

Orientação pass@k

• pass@1: confiabilidade direta
• pass@3: confiabilidade prática sob tentativas controladas
• pass^3: teste de estabilidade (todas as 3 execuções devem passar)

Limiares recomendados:

• Avaliações de capacidade: pass@3 >= 0.90
• Avaliações de regressão: pass^3 = 1.00 para caminhos críticos de lançamento

Anti-Padrões de Avaliação

• Ajustar excessivamente prompts para exemplos de avaliação conhecidos
• Medir apenas saídas de caminho feliz
• Ignorar deriva de custo e latência enquanto persegue taxas de aprovação
• Permitir avaliadores instáveis em gates de lançamento

Layout Mínimo de Artefatos de Avaliação

• .claude/evals/<funcionalidade>.md definição
• .claude/evals/<funcionalidade>.log histórico de execução
• docs/releases/<versão>/eval-summary.md snapshot de lançamento