Eval Harness Skill

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

Quando Ativar

• Configuração do desenvolvimento orientado a evals (EDD) para fluxos de trabalho assistidos por IA
• Definição de critérios de aprovação/reprovação para a conclusão de tarefas do Claude Code
• Medição da confiabilidade do agente com métricas pass@k
• Criação de suítes de testes de regressão para alterações de prompt ou agente
• Benchmarking do desempenho do agente em diferentes versões de modelos

Filosofia

O Desenvolvimento Orientado a Evals trata os evals como os "testes unitários do desenvolvimento de IA":

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

Tipos de Eval

Evals de Capacidade

Testam se o Claude consegue fazer algo que não conseguia antes:

[CAPABILITY EVAL: feature-name]
Task: Description of what Claude should accomplish
Success Criteria:
  - [ ] Criterion 1
  - [ ] Criterion 2
  - [ ] Criterion 3
Expected Output: Description of expected result

Evals de Regressão

Garantem que as alterações não quebrem a funcionalidade existente:

[REGRESSION EVAL: feature-name]
Baseline: SHA or checkpoint name
Tests:
  - existing-test-1: PASS/FAIL
  - existing-test-2: PASS/FAIL
  - existing-test-3: PASS/FAIL
Result: X/Y passed (previously Y/Y)

Tipos de Grader

1. Grader Baseado em Código

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

# Check if file contains expected pattern
grep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"

# Check if tests pass
npm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"

# Check if build succeeds
npm run build && echo "PASS" || echo "FAIL"

2. Grader Baseado em Modelo

Usa o Claude para avaliar saídas em aberto:

[MODEL GRADER PROMPT]
Evaluate the following code change:
1. Does it solve the stated problem?
2. Is it well-structured?
3. Are edge cases handled?
4. Is error handling appropriate?

Score: 1-5 (1=poor, 5=excellent)
Reasoning: [explanation]

3. Grader Humano

Marca para revisão manual:

[HUMAN REVIEW REQUIRED]
Change: Description of what changed
Reason: Why human review is needed
Risk Level: LOW/MEDIUM/HIGH

Métricas

pass@k

"Pelo menos um sucesso em k tentativas"

• pass@1: Taxa de sucesso na primeira tentativa
• pass@3: Sucesso em até 3 tentativas
• Meta típica: pass@3 > 90%

pass^k

"Todos os k testes são bem-sucedidos"

• Barra mais alta para confiabilidade
• pass^3: 3 sucessos consecutivos
• Use para caminhos críticos

Fluxo de Trabalho de Eval

1. Definir (Antes de Codificar)

## EVAL DEFINITION: feature-xyz

### Capability Evals
1. Can create new user account
2. Can validate email format
3. Can hash password securely

### Regression Evals
1. Existing login still works
2. Session management unchanged
3. Logout flow intact

### Success Metrics
- pass@3 > 90% for capability evals
- pass^3 = 100% for regression evals

2. Implementar

Escreva código para passar nos evals definidos.

3. Avaliar

# Run capability evals
[Run each capability eval, record PASS/FAIL]

# Run regression evals
npm test -- --testPathPattern="existing"

# Generate report

4. Relatar

EVAL REPORT: feature-xyz
========================

Capability Evals:
  create-user:     PASS (pass@1)
  validate-email:  PASS (pass@2)
  hash-password:   PASS (pass@1)
  Overall:         3/3 passed

Regression Evals:
  login-flow:      PASS
  session-mgmt:    PASS
  logout-flow:     PASS
  Overall:         3/3 passed

Metrics:
  pass@1: 67% (2/3)
  pass@3: 100% (3/3)

Status: READY FOR REVIEW

Padrões de Integração

Pré-Implementação

/eval define feature-name

Cria o arquivo de definição de eval em .claude/evals/feature-name.md

Durante a Implementação

/eval check feature-name

Executa os evals atuais e relata o status

Pós-Implementação

/eval report feature-name

Gera o relatório completo de eval

Armazenamento de Evals

Armazene os evals no projeto:

.claude/
  evals/
    feature-xyz.md      # Eval definition
    feature-xyz.log     # Eval run history
    baseline.json       # Regression baselines

Melhores Práticas

1. Defina os evals ANTES de codificar - Força um pensamento claro sobre os critérios de sucesso
2. Execute os evals frequentemente - Capture regressões cedo
3. Monitore pass@k ao longo do tempo - Acompanhe as tendências de confiabilidade
4. Use graders de código sempre que possível - Determinístico > probabilístico
5. Revisão humana para segurança - Nunca automatize completamente as verificações de segurança

…