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 activar

• 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 confiabilidad del agente con métricas pass@k
• Crear suites de pruebas de regresión para cambios rápidos o de agente
• Comparar el rendimiento del agente entre versiones de modelo

Filosofía

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

• Defina el comportamiento esperado ANTES de la implementación
• Ejecute evaluaciones continuamente durante el desarrollo
• Rastree regresiones con cada cambio
• Use métricas pass@k para medir la confiabilidad

Tipos de Evaluación

Evaluaciones de Capacidad

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

[EVAL DE CAPACIDAD: nombre-característica]
Tarea: Descripción de lo que Claude debe lograr
Criterios de Éxito:
  - [ ] Criterio 1
  - [ ] Criterio 2
  - [ ] Criterio 3
Salida Esperada: Descripción del resultado esperado

Evaluaciones de Regresión

Asegúrese de que los cambios no rompan la funcionalidad existente:

[EVAL DE REGRESIÓN: nombre-característica]
Línea base: SHA o nombre de punto de control
Pruebas:
  - prueba-existente-1: APROBADO/RECHAZADO
  - prueba-existente-2: APROBADO/RECHAZADO
  - prueba-existente-3: APROBADO/RECHAZADO
Resultado: X/Y aprobados (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 "APROBADO" || echo "RECHAZADO"

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

# Verificar si la compilación es exitosa
npm run build && echo "APROBADO" || echo "RECHAZADO"

2. Evaluador Basado en Modelo

Use Claude para evaluar resultados abiertos:

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

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

3. Evaluador Humano

Marque 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 dentro de 3 intentos
• Objetivo típico: pass@3 > 90%

pass^k

"Los k intentos tienen éxito"

• Mayor estándar de confiabilidad
• pass^3: 3 éxitos consecutivos
• Use para rutas críticas

Flujo de Trabajo de Evaluación

1. Definir (Antes de Codificar)

## DEFINICIÓN DE EVALUACIÓN: característica-xyz

### Evaluaciones de Capacidad
1. Puede crear una nueva cuenta de usuario
2. Puede validar el formato del correo electrónico
3. Puede cifrar la 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

Escriba código para superar las evaluaciones definidas.

3. Evaluar

# Ejecutar evaluaciones de capacidad
[Ejecute cada evaluación de capacidad, registre APROBADO/RECHAZADO]

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

# Generar informe

4. Informar

INFORME DE EVALUACIÓN: característica-xyz
=========================================

Evaluaciones de Capacidad:
  crear-usuario:     APROBADO (pass@1)
  validar-correo:    APROBADO (pass@2)
  cifrar-contraseña: APROBADO (pass@1)
  General:           3/3 aprobados

Evaluaciones de Regresión:
  flujo-inicio-sesión:      APROBADO
  gestión-sesión:           APROBADO
  flujo-cierre-sesión:      APROBADO
  General:                  3/3 aprobados

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-característica

Crea archivo de definición de evaluación en .claude/evals/nombre-característica.md

Durante la Implementación

/eval check nombre-característica

Ejecuta las evaluaciones actuales e informa el estado

Post-Implementación

/eval report nombre-característica

Genera informe de evaluación completo

Almacenamiento de Evaluaciones

Almacene evaluaciones en el proyecto:

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

Mejores Prácticas

1. Defina evaluaciones ANTES de codificar - Obliga a pensar claramente sobre los criterios de éxito
2. Ejecute evaluaciones con frecuencia - Detecte regresiones temprano
3. Rastree pass@k a lo largo del tiempo - Monitoree tendencias de confiabilidad
4. Use evaluadores de código cuando sea posible - Determinista > Probabilístico
5. Revisión humana para seguridad - Nunca automatice completamente las comprobaciones de seguridad
6. Mantenga evaluaciones rápidas - Las evaluaciones lentas no se ejecutan
7. Versione evaluaciones con código - Las evaluaciones son artefactos de primera clase

Ejemplo: Agregar Autenticación

## EVALUACIÓN: agregar-autenticación

### Fase 1: Definir (10 min)
Evaluaciones de Capacidad:
- [ ] El usuario puede registrarse con correo electrónico/contraseña
- [ ] El usuario puede iniciar sesión con credenciales válidas
- [ ] Las credenciales inválidas se rechazan con el 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 API no han cambiado
- [ ] El esquema de base de datos es compatible

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

### Fase 3: Evaluar
Ejecutar: /eval check agregar-autenticación

### Fase 4: Informar
INFORME DE EVALUACIÓN: agregar-autenticación
============================================
Capacidad: 5/5 aprobados (pass@3: 100%)
Regresión: 3/3 aprobados (pass^3: 100%)
Estado: A PRODUCCIÓN

Utilidades Locales del Marco

Las utilidades mecánicas se envían en scripts/lib/eval-harness/:

node scripts/eval-harness.js ejemplo

• Cápsula: diario enlazado por hash 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 direccionados por contenido. Los accesorios faltantes fallan de forma cerrada; SE3 y superiores son rechazados en reproducción. El modo de grabación invoca la implementación registrada, así que solo registre 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 harness declarada. Las instantáneas repetidas cuentan una vez; las identidades en conflicto o las cápsulas inválidas rechazan todo el informe. Esto es conteo de registros de solo lectura, sin nuevos despliegues, puntuaciones o promociones. Use cápsulas pequeñas y en reposo. Las cargas útiles, los argumentos de directorio y los IDs de ejecución/cápsula en crudo se omiten, pero las etiquetas de familia/versión de tarea son textuales y las referencias de resumen se pueden enlazar; revíselas antes de compartir. La validación operativa sigue pendiente.

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

No presente 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 independientemente, un verificador protegido y canales de auditoría, y un rechazo fatal de línea base. Consulte docs/architecture/eval-harness-frameworks.md.

Evaluaciones de Producto (v1.8)

Use evaluaciones de producto cuando la calidad del comportamiento no se pueda capturar solo con 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 salidas ambiguas)

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:

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

Anti-Patrones de Evaluación

• Ajustar excesivamente los mensajes a ejemplos de evaluación conocidos
• Medir solo las salidas del camino feliz
• Ignorar la deriva de costo y latencia mientras se persiguen tasas de aprobación
• Permitir evaluadores inestables en las puertas de lanzamiento

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

• .claude/evals/<característica>.md definición
• .claude/evals/<característica>.log historial de ejecución
• docs/releases/<versión>/eval-summary.md instantánea de lanzamiento