eval-harness

Habilidade Eval Harness

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

Quando Ativar

• Configurando desenvolvimento orientado por avaliação (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 testes de regressão para alterações em prompts ou agentes
• Avaliando o desempenho do agente em diferentes versões de modelo

Filosofia

Desenvolvimento Orientado por Avaliação trata 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
• Rastreie regressões a cada alteração
• Use métricas pass@k para medição de confiabilidade

Tipos de Avaliação

Avaliações de Capacidade

Testa se o Claude consegue fazer algo que não conseguia 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 alterações 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 Avaliador

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 compilação é 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 alteração de código:
1. Ela resolve o problema declarado?
2. É 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"

• Padrão 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 com segurança

### 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-usuario:     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-sessao:    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 de avaliação

Armazenamento de Avaliações

Armazene avaliações no projeto:

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

Melhores Práticas

1. Defina avaliações ANTES de codificar - Força a pensar claramente sobre critérios de sucesso
2. Execute avaliações com frequência - Pegue 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 verificações de segurança completamente
6. Mantenha avaliações rápidas - Avaliações lentas não são executadas
7. Versionar avaliações com o código - Avaliações são artefatos de primeira classe

Exemplo: Adicionando Autenticação

## AVALIAÇÃO: adicionar-autenticacao

### 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 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 acessíveis
- [ ] Respostas da API inalteradas
- [ ] Esquema do banco de dados compatível

### Fase 2: Implementar (varia)
[Escrever código]

### Fase 3: Avaliar
Executar: /eval check adicionar-autenticacao

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

Utilitários Locais da Estrutura

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

node scripts/eval-harness.js exemplo

• Capsule: snapshot com hash, cinco linhagens e verificações de integridade local.
• Inspeção: resumos de fonte, caminhos de variante validados e avisos sintáticos.
• Replay: ferramentas declaradas e fixtures com endereçamento de conteúdo. Fixtures ausentes falham fechado; SE3 e superiores são recusados no replay. O modo gravação invoca a implementação registrada, portanto registre apenas funções confiáveis.
• Recibo: verificação offline de bytes de capsule e artefato, com verificações nomeadas.
• Preparação retrospectiva: node scripts/eval-harness.js capsule group <dir> [<dir> ...] agrupa de 1 a 100 snapshots de capsule local selecionados explicitamente e verificados de uma família de tarefas pela versão declarada da estrutura. Snapshots repetidos contam uma vez; identidades conflitantes ou capsules inválidas rejeitam o relatório inteiro. Esta é uma contagem de registros somente leitura, sem novos lançamentos, pontuações ou promoções. Use capsules pequenas e quiescentes. Cargas úteis, argumentos de diretório e IDs brutos de execução/capsule são omitidos, mas os rótulos de família de tarefas/versão são literais e as 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 direto de filho e o efeito preterido preload recusam com gate.isolation_required. Nenhum sinalizador de confiança ou executor fornecido pelo chamador pode ignorar a recusa. O exemplo registra essa recusa e inspeciona a fonte sem executá-la ou pontuá-la.

Não apresente avisos estáticos, um recibo de capsule 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 independentemente, 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 Avaliador

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

Orientação pass@k

• pass@1: confiabilidade direta
• pass@3: confiabilidade prática sob novas 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 prompts para exemplos de avaliação conhecidos
• Medir apenas saídas de caminho feliz
• Ignorar deriva de custo e latência ao buscar taxas de aprovação
• Permitir avaliadores instáveis em gates de lançamento

Layout Mínimo de Artefato de Avaliação

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