Skill de Agent Eval
Una herramienta CLI ligera para comparar agentes de codificación cara a cara en tareas reproducibles. Cada comparación de "¿qué agente de codificación es mejor?" se basa en sensaciones — esta herramienta lo sistematiza.
Cuándo activarlo
- Comparar agentes de codificación (Claude Code, Aider, Codex, etc.) en tu propio código base
- Medir el rendimiento del agente antes de adoptar una nueva herramienta o modelo
- Realizar pruebas de regresión cuando un agente actualiza su modelo o herramientas
- Producir decisiones de selección de agentes respaldadas por datos para un equipo
Instalación
Nota: Instala agent-eval desde su repositorio después de revisar el código fuente.
Conceptos centrales
Definiciones de tareas en YAML
Define tareas de forma declarativa. Cada tarea especifica qué hacer, qué archivos tocar y cómo juzgar el éxito:
name: agregar-logica-de-reintento
description: Agregar reintento con retroceso exponencial al cliente HTTP
repo: ./mi-proyecto
files:
- src/cliente_http.py
prompt: |
Agrega lógica de reintento con retroceso exponencial a todas las solicitudes HTTP.
Máximo 3 reintentos. Demora inicial 1s, demora máxima 30s.
judge:
- type: pytest
command: pytest tests/test_cliente_http.py -v
- type: grep
pattern: "retroceso_exponencial|reintento"
files: src/cliente_http.py
commit: "abc1234" # fijar a un commit específico para reproducibilidad
Aislamiento con Git Worktree
Cada ejecución del agente obtiene su propio git worktree — no se necesita Docker. Esto proporciona aislamiento de reproducibilidad para que los agentes no interfieran entre sí ni corrompan el repositorio base.
Métricas recopiladas
| Métrica | Qué mide |
|---|---|
| Tasa de aprobación | ¿Produjo el agente código que pasa la evaluación? |
| Costo | Gasto de API por tarea (cuando está disponible) |
| Tiempo | Segundos de pared hasta la finalización |
| Consistencia | Tasa de aprobación en ejecuciones repetidas (ej., 3/3 = 100%) |
Flujo de trabajo
1. Definir tareas
Crea un directorio tasks/ con archivos YAML, uno por tarea:
mkdir tasks
# Escribe las definiciones de tareas (ver plantilla arriba)
2. Ejecutar agentes
Ejecuta agentes contra tus tareas:
agent-eval run --task tasks/agregar-logica-de-reintento.yaml --agent claude-code --agent aider --runs 3
Cada ejecución:
- Crea un git worktree fresco a partir del commit especificado
- Entrega el prompt al agente
- Ejecuta los criterios del juez
- Registra aprobado/falla, costo y tiempo
3. Comparar resultados
Genera un informe de comparación:
agent-eval report --format table
Tarea: agregar-logica-de-reintento (3 ejecuciones cada una)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ Agente │ Tasa Aprob.│ Costo │ Tiempo │ Consistencia│
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ claude-code │ 3/3 │ $0.12 │ 45s │ 100% │
│ aider │ 2/3 │ $0.08 │ 38s │ 67% │
└──────────────┴───────────┴────────┴────────┴─────────────┘
Tipos de jueces
Basados en código (deterministas)
judge:
- type: pytest
command: pytest tests/ -v
- type: command
command: npm run build
Basados en patrones
judge:
- type: grep
pattern: "class.*Retry"
files: src/**/*.py
Basados en modelos (LLM como juez)
judge:
- type: llm
prompt: |
¿Esta implementación maneja correctamente el retroceso exponencial?
Verificar: reintentos máximos, demoras crecientes, jitter.
Mejores prácticas
- Comienza con 3-5 tareas que representen tu carga de trabajo real, no ejemplos de juguete
- Ejecuta al menos 3 pruebas por agente para capturar la varianza — los agentes no son deterministas
- Fija el commit en tu YAML de tarea para que los resultados sean reproducibles a través de días/semanas
- Incluye al menos un juez determinista (pruebas, compilación) por tarea — los jueces LLM añaden ruido
- Rastrea el costo junto con la tasa de aprobación — un agente con 95% de aprobación a 10x el costo puede no ser la opción correcta
- Versiona tus definiciones de tareas — son fixtures de prueba, trátalos como código
Enlaces
- Repositorio: github.com/joaquinhuigomez/agent-eval