affaan-m/eval-harness

Skill Eval Harness

Un framework formal de evaluación para sesiones de Claude Code, implementando principios de desarrollo orientado a evals (EDD).

Cuándo Activar

• Configurar desarrollo orientado a evals (EDD) para flujos de trabajo asistidos por IA
• Definir criterios de pass/fail para la completitud de tareas en Claude Code
• Medir confiabilidad del agente con métricas pass@k
• Crear suites de pruebas de regresión para cambios de prompts o agentes
• Comparar rendimiento del agente entre versiones de modelos

Filosofía

El Desarrollo Orientado a Evals trata los evals como las "pruebas unitarias del desarrollo de IA":

• Definir el comportamiento esperado ANTES de la implementación
• Ejecutar evals continuamente durante el desarrollo
• Rastrear regresiones con cada cambio
• Usar métricas pass@k para medición de confiabilidad

Tipos de Eval

Evals de Capacidad

Probar si Claude puede hacer algo que antes no podía:

[CAPABILITY EVAL: feature-name]
Task: Descripción de lo que Claude debe lograr
Success Criteria:
  - [ ] Criterio 1
  - [ ] Criterio 2
  - [ ] Criterio 3
Expected Output: Descripción del resultado esperado

Evals de Regresión

Asegurar que los cambios no rompan la funcionalidad existente:

[REGRESSION EVAL: feature-name]
Baseline: SHA o nombre del checkpoint
Tests:
  - existing-test-1: PASS/FAIL
  - existing-test-2: PASS/FAIL
  - existing-test-3: PASS/FAIL
Result: X/Y pasaron (anteriormente Y/Y)

Tipos de Evaluador

1. Evaluador Basado en Código

Verificaciones deterministas usando código:

# Verificar si el archivo contiene el patrón esperado
grep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"

# Verificar si las pruebas pasan
npm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"

# Verificar si el build tiene éxito
npm run build && echo "PASS" || echo "FAIL"

2. Evaluador Basado en Modelo

Usar Claude para evaluar salidas de forma abierta:

[MODEL GRADER PROMPT]
Evalúa el siguiente cambio de código:
1. ¿Resuelve el problema declarado?
2. ¿Está bien estructurado?
3. ¿Se manejan los casos límite?
4. ¿El manejo de errores es apropiado?

Puntuación: 1-5 (1=pobre, 5=excelente)
Razonamiento: [explicación]

3. Evaluador Humano

Marcar para revisión manual:

[HUMAN REVIEW REQUIRED]
Cambio: Descripción de qué cambió
Razón: Por qué se necesita revisión humana
Nivel de Riesgo: BAJO/MEDIO/ALTO

Métricas

pass@k

"Al menos un éxito en k intentos"

• pass@1: Tasa de éxito en el primer intento
• pass@3: Éxito dentro de 3 intentos
• Objetivo típico: pass@3 > 90%

pass^k

"Todos los k ensayos tienen éxito"

• Barra más alta para confiabilidad
• pass^3: 3 éxitos consecutivos
• Usar para rutas críticas

Flujo de Trabajo de Eval

1. Definir (Antes de Codificar)

## EVAL DEFINITION: feature-xyz

### Capability Evals
1. Puede crear nueva cuenta de usuario
2. Puede validar formato de email
3. Puede hashear contraseña de forma segura

### Regression Evals
1. El login existente sigue funcionando
2. La gestión de sesiones no cambió
3. El flujo de logout está intacto

### Success Metrics
- pass@3 > 90% para evals de capacidad
- pass^3 = 100% para evals de regresión

2. Implementar

Escribir código para pasar los evals definidos.

3. Evaluar

# Ejecutar evals de capacidad
[Ejecutar cada eval de capacidad, registrar PASS/FAIL]

# Ejecutar evals de regresión
npm test -- --testPathPattern="existing"

# Generar reporte

4. Reportar

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

Patrones de Integración

Pre-Implementación

/eval define feature-name

Crea el archivo de definición de eval en .claude/evals/feature-name.md

Durante la Implementación

/eval check feature-name

Ejecuta los evals actuales y reporta el estado

Post-Implementación

/eval report feature-name

Genera el reporte completo de eval

Almacenamiento de Evals

Almacenar evals en el proyecto:

.claude/
  evals/
    feature-xyz.md      # Definición de eval
    feature-xyz.log     # Historial de ejecuciones
    baseline.json       # Líneas base de regresión

Buenas Prácticas

1. Definir evals ANTES de codificar — Fuerza pensar claramente sobre los criterios de éxito
2. Ejecutar evals con frecuencia — Detectar regresiones temprano
3. Rastrear pass@k con el tiempo — Monitorear tendencias de confiabilidad
4. Usar evaluadores de código cuando sea posible — Determinístico > probabilístico
5. Revisión humana para seguridad — Nunca automatizar completamente las verificaciones de seguridad
6. Mantener los evals rápidos — Los evals lentos no se ejecutan
7. Versionar evals con el código — Los evals son artefactos de primera clase

Guía de pass@k

• pass@1: confiabilidad directa
• pass@3: confiabilidad práctica bajo reintentos controlados
• pass^3: prueba de estabilidad (las 3 ejecuciones deben pasar)

Umbrales recomendados:

• Evals de capacidad: pass@3 >= 0.90
• Evals de regresión: pass^3 = 1.00 para rutas críticas de release

Anti-Patrones de Eval

• Sobreajustar prompts a ejemplos de eval conocidos
• Medir solo salidas del camino feliz
• Ignorar deriva de costo y latencia mientras se persiguen tasas de pass
• Permitir evaluadores inestables en compuertas de release