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: ```markdown [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: ```markdown [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: ```bash # 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: ```markdown [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: ```markdown [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) ```markdown ## 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 ```bash # 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 ```markdown 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