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 lograrSuccess Criteria:  - [ ] Criterio 1  - [ ] Criterio 2  - [ ] Criterio 3Expected 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 checkpointTests:  - existing-test-1: PASS/FAIL  - existing-test-2: PASS/FAIL  - existing-test-3: PASS/FAILResult: 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 esperadogrep -q "export function handleAuth" src/auth.ts && echo "PASS" || echo "FAIL"
# Verificar si las pruebas pasannpm test -- --testPathPattern="auth" && echo "PASS" || echo "FAIL"
# Verificar si el build tiene éxitonpm 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 humanaNivel 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 Evals1. Puede crear nueva cuenta de usuario2. Puede validar formato de email3. Puede hashear contraseña de forma segura
### Regression Evals1. El login existente sigue funcionando2. 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ónnpm 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