eval-harness

Habilidad de Eval Harness

Un marco de evaluación formal para sesiones de Claude Code, que implementa los principios de desarrollo impulsado por evaluaciones (EDD).

Cuándo activarlo

• Configurar desarrollo impulsado por evaluaciones (EDD) para flujos de trabajo asistidos por IA
• Definir criterios de aprobación/rechazo para la finalización de tareas de Claude Code
• Medir la fiabilidad del agente con métricas pass@k
• Crear suites de pruebas de regresión para cambios en prompts o agentes
• Evaluar el rendimiento del agente entre versiones del modelo

Filosofía

El Desarrollo Impulsado por Evaluaciones trata las evaluaciones como "pruebas unitarias del desarrollo de IA":

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

Tipos de Evaluaciones

Evaluaciones de Capacidad

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

[EVAL DE CAPACIDAD: nombre-funcionalidad]
Tarea: Descripción de lo que Claude debe lograr
Criterios de Éxito:
  - [ ] Criterio 1
  - [ ] Criterio 2
  - [ ] Criterio 3
Resultado Esperado: Descripción del resultado esperado

Evaluaciones de Regresión

Aseguran que los cambios no rompan la funcionalidad existente:

[EVAL DE REGRESIÓN: nombre-funcionalidad]
Línea Base: SHA o nombre del checkpoint
Pruebas:
  - prueba-existente-1: PASS/FAIL
  - prueba-existente-2: PASS/FAIL
  - prueba-existente-3: PASS/FAIL
Resultado: X/Y pasadas (anteriormente Y/Y)

Tipos de Evaluadores

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 la compilación tiene éxito
npm run build && echo "PASS" || echo "FAIL"

2. Evaluador Basado en Modelo

Usa Claude para evaluar resultados abiertos:

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

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

3. Evaluador Humano

Marcar para revisión manual:

[REVISIÓN HUMANA REQUERIDA]
Cambio: Descripción de lo que 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 en 3 intentos
• Objetivo típico: pass@3 > 90%

pass^k

"Todos los k intentos tienen éxito"

• Mayor exigencia de fiabilidad
• pass^3: 3 éxitos consecutivos
• Usar para rutas críticas

Flujo de Trabajo de Evaluación

1. Definir (Antes de Programar)

## DEFINICIÓN DE EVAL: funcionalidad-xyz

### Evaluaciones de Capacidad
1. Puede crear una nueva cuenta de usuario
2. Puede validar formato de correo electrónico
3. Puede cifrar contraseña de forma segura

### Evaluaciones de Regresión
1. El inicio de sesión existente sigue funcionando
2. La gestión de sesiones no ha cambiado
3. El flujo de cierre de sesión está intacto

### Métricas de Éxito
- pass@3 > 90% para evaluaciones de capacidad
- pass^3 = 100% para evaluaciones de regresión

2. Implementar

Escribir código para superar las evaluaciones definidas.

3. Evaluar

# Ejecutar evaluaciones de capacidad
[Ejecutar cada evaluación de capacidad, registrar PASS/FAIL]

# Ejecutar evaluaciones de regresión
npm test -- --testPathPattern="existente"

# Generar informe

4. Reportar

INFORME DE EVAL: funcionalidad-xyz
========================

Evaluaciones de Capacidad:
  crear-usuario:     PASS (pass@1)
  validar-email:     PASS (pass@2)
  cifrar-contraseña: PASS (pass@1)
  Total:             3/3 pasadas

Evaluaciones de Regresión:
  flujo-inicio-sesión:      PASS
  gestión-sesiones:         PASS
  flujo-cierre-sesión:      PASS
  Total:                    3/3 pasadas

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

Estado: LISTO PARA REVISIÓN

Patrones de Integración

Pre-Implementación

/eval define nombre-funcionalidad

Crea archivo de definición de evaluación en .claude/evals/nombre-funcionalidad.md

Durante la Implementación

/eval check nombre-funcionalidad

Ejecuta evaluaciones actuales e informa el estado

Post-Implementación

/eval report nombre-funcionalidad

Genera informe completo de evaluación

Almacenamiento de Evaluaciones

Almacenar evaluaciones en el proyecto:

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

Mejores Prácticas

1. Define evaluaciones ANTES de programar - Obliga a pensar claramente sobre los criterios de éxito
2. Ejecuta evaluaciones con frecuencia - Detecta regresiones temprano
3. Rastrea pass@k a lo largo del tiempo - Monitorea tendencias de fiabilidad
4. Usa evaluadores de código cuando sea posible - Determinista > probabilístico
5. Revisión humana para seguridad - Nunca automatices completamente los controles de seguridad
6. Mantén las evaluaciones rápidas - Las evaluaciones lentas no se ejecutan
7. Versiona las evaluaciones con el código - Las evaluaciones son artefactos de primera clase

Ejemplo: Añadir Autenticación

## EVAL: añadir-autenticación

### Fase 1: Definir (10 min)
Evaluaciones de Capacidad:
- [ ] El usuario puede registrarse con correo/contraseña
- [ ] El usuario puede iniciar sesión con credenciales válidas
- [ ] Las credenciales inválidas son rechazadas con error adecuado
- [ ] Las sesiones persisten al recargar la página
- [ ] El cierre de sesión limpia la sesión

Evaluaciones de Regresión:
- [ ] Las rutas públicas siguen siendo accesibles
- [ ] Las respuestas de la API no cambian
- [ ] El esquema de base de datos es compatible

### Fase 2: Implementar (varía)
[Escribir código]

### Fase 3: Evaluar
Ejecutar: /eval check añadir-autenticación

### Fase 4: Reportar
INFORME DE EVAL: añadir-autenticación
==============================
Capacidad: 5/5 pasadas (pass@3: 100%)
Regresión: 3/3 pasadas (pass^3: 100%)
Estado: A PRODUCCIÓN

Utilidades Locales del Marco

Las utilidades mecánicas se distribuyen en scripts/lib/eval-harness/:

node scripts/eval-harness.js example

• Cápsula: diario con hash encadenado con cinco linajes y comprobaciones de integridad local.
• Inspección: resúmenes de fuente, rutas de variante validadas y advertencias sintácticas.
• Reproducción: herramientas declaradas y accesorios con direccionamiento por contenido. Los accesorios faltantes fallan de forma cerrada; SE3 y superiores se rechazan en reproducción. El modo de grabación invoca la implementación registrada, por lo que solo se deben registrar funciones de confianza.
• Recibo: verificación fuera de línea de cápsula y bytes de artefacto, con comprobaciones nombradas.
• Preparación retrospectiva: node scripts/eval-harness.js capsule group <dir> [<dir> ...] agrupa de 1 a 100 instantáneas de cápsula local explícitamente seleccionadas y verificadas de una familia de tareas por versión de arnés declarada. Las instantáneas repetidas cuentan una vez; las identidades conflictivas o las cápsulas inválidas rechazan todo el informe. Esto es solo recuento de registros de solo lectura, sin nuevos despliegues, puntuaciones o promociones. Usa cápsulas pequeñas y estáticas. Las cargas útiles, los argumentos de directorio y los IDs de ejecución/cápsula en bruto se omiten, pero las etiquetas de familia de tareas/versión son literales y las referencias de resumen se pueden enlazar; revísalos antes de compartir. La validación operativa sigue pendiente.

La ejecución de candidatos está deshabilitada en todos los sistemas operativos porque no se ha implementado un backend de contención de SO verificado. gate run, runGate, runVariant, el lanzamiento directo de hijos, y la precarga de efectos retirada se niegan con gate.isolation_required. Ninguna marca de confianza o ejecutor proporcionado por la persona que llama puede eludir la negativa. El ejemplo registra esa negativa e inspecciona la fuente sin ejecutarla ni puntuarla.

No presentes advertencias estáticas, un recibo de cápsula o pruebas de utilidad exitosas como evidencia de contención o promoción de candidatos. Una puerta futura requiere un límite de SO revisado de forma independiente, canales de verificación y auditoría protegidos, y rechazo fatal de línea base. Consulta docs/architecture/eval-harness-frameworks.md.

Evaluaciones de Producto (v1.8)

Usa evaluaciones de producto cuando la calidad del comportamiento no pueda ser capturada solo por pruebas unitarias.

Tipos de Evaluadores

1. Evaluador de código (afirmaciones deterministas)
2. Evaluador de reglas (restricciones de regex/esquema)
3. Evaluador de modelo (rúbrica LLM-como-juez)
4. Evaluador humano (adjudicación manual para resultados ambiguos)

Guía de pass@k

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

Umbrales recomendados:

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

Antipatrones de Evaluación

• Sobreajustar prompts a ejemplos de evaluación conocidos
• Medir solo resultados del camino feliz
• Ignorar la deriva de coste y latencia mientras se persiguen tasas de aprobación
• Permitir evaluadores inestables en puertas de lanzamiento

Diseño Mínimo de Artefacto de Evaluación

• .claude/evals/<funcionalidad>.md definición
• .claude/evals/<funcionalidad>.log historial de ejecuciones
• docs/releases/<version>/eval-summary.md instantánea de lanzamiento