¿Qué hace Auto-Evaluación del Agente?
Después de completar una tarea compleja, el agente se detiene para calificar su propio resultado frente a una rúbrica estructurada de 5 ejes. Esto NO es una puerta de aprobación/rechazo, sino un paso deliberado de reflexión que detecta omisiones, señala exceso de confianza y revela áreas de mejora antes de que el usuario tenga que hacerlo.
Cuándo activarlo
- Después de escribir código que abarca 3+ archivos o 50+ líneas
- Después de completar un flujo de trabajo de múltiples pasos (implementar → probar → revisar)
- Después de una sesión de depuración que implicó 3+ intentos
- Después de producir un documento de diseño, decisión de arquitectura o análisis escrito
- Cuando el usuario pregunta "¿qué tan bueno fue eso?" o "califícate"
- Al final de cualquier gancho de sesión Stop (si está configurado — ver
references/hook-integration.md)
Conceptos fundamentales
Los 5 ejes de evaluación
| Eje | Pregunta | Qué detecta |
|---|---|---|
| Precisión | ¿Los hechos, afirmaciones y resultados son correctos? | Alucinaciones, nombres de API incorrectos, sintaxis errónea, afirmaciones falsas |
| Integridad | ¿Cubrió todo lo que el usuario pidió? | Casos extremos omitidos, rutas de error no manejadas, requisitos olvidados, subtareas saltadas |
| Claridad | ¿La explicación es comprensible y está bien estructurada? | Explicaciones confusas, jerga sin definición, contexto faltante, divagaciones |
| Viabilidad | ¿Puede el usuario actuar sobre el resultado de inmediato? | Sugerencias vagas, pasos faltantes, "deberías hacer X" sin mostrar cómo, sin ruta de verificación |
| Concisión | ¿Usó las palabras/tokens mínimos necesarios? | Redundancia, sobre-explicación, repetir la pregunta del usuario textualmente, contenido de relleno |
Escala de puntuación
5 — Excepcional: no es posible una mejora razonable
4 — Bueno: solo pequeños detalles sin brechas sustanciales
3 — Adecuado: cumple con la solicitud pero tiene una debilidad notable en al menos un eje
2 — Débil: tiene una brecha clara que afecta la usabilidad o corrección
1 — Pobre: no cumple fundamentalmente con la solicitud o contiene errores significativos
La regla de la evidencia
Cada puntuación por debajo de 5 DEBE citar evidencia específica. Una puntuación de 3 no puede simplemente decir "podría ser mejor" — debe decir exactamente qué falta o está mal. El mantra: "Muestra la brecha, no solo la nombres."
Flujo de trabajo
Paso 1: Recopilar el material bruto
Reúne lo que vas a evaluar:
- La solicitud original del usuario (leída desde la conversación)
- Tu respuesta/salida final (el entregable)
- Cualquier salida de herramientas que verifique la corrección (resultados de pruebas, códigos de salida, salida de lint)
- Cualquier comentario del usuario recibido durante la tarea (correcciones, "intenta de nuevo", "eso no está bien")
Paso 2: Puntuar cada eje de forma independiente
Trabaja a través de los 5 ejes uno a la vez. Para cada uno:
- Lee la pregunta del eje
- Encuentra evidencia (o falta de ella) en la salida
- Asigna una puntuación del 1 al 5
- Si la puntuación < 5, escribe una nota de mejora de una oración citando la brecha
NO promedies las puntuaciones en tu cabeza primero y luego trabajes hacia atrás. Puntúa cada eje desde cero.
Paso 3: Producir el informe de evaluación
Usa la plantilla de templates/evaluation-report.md. El informe debe incluir:
- Resumen de una línea
- Tarjeta de puntuación de 5 ejes (puntuación + evidencia por eje)
- Puntuación general (promedio simple, redondeado a 1 decimal)
- 1-3 mejoras específicas ordenadas por impacto
- Autoverificación: "¿Estaría el usuario de acuerdo con esta evaluación?"
Paso 4: Aplicar la mejora
Si algún eje obtuvo 3 o menos:
- Indica qué harías de manera diferente
- Si la brecha se puede solucionar en menos de 30 segundos (enlace faltante, redacción poco clara), corrígela ahora
- Si la brecha requiere retrabajo, márcala explícitamente: "Este eje obtuvo [razón] porque [evidencia]. Volver a ejecutar con [solución específica] probablemente lo elevaría a [puntuación]."
Ejemplos de código
Ejemplo: Evaluación buena (Puntuación 4+)
Tarea: Agregar lógica de reintento al cliente HTTP
Tarjeta de puntuación:
Precisión: 5 — Todas las llamadas a la API correctas. Verificado:
los reintentos usan backoff exponencial. No hay
métodos alucinados.
Integridad: 4 — Cubrió el camino feliz + 3 casos de error.
Falta: manejo de tiempo de espera para conexiones
colgadas.
Claridad: 5 — Los comentarios del código explican la fórmula
de backoff. La descripción del PR enlaza al incidente
que motivó esto.
Viabilidad: 5 — Un solo merge. Sin tareas de seguimiento.
Las pruebas pasan.
Concisión: 4 — 47 líneas en total. El bucle de reintento
podría extraerse a un helper para reducir ~8 líneas.
General: 4.6 — Una brecha (manejo de tiempo de espera).
Corregir antes de hacer merge.
Ejemplo: Evaluación débil (Puntuación 2-3)
Tarea: Agregar lógica de reintento al cliente HTTP
Tarjeta de puntuación:
Precisión: 2 — Se usó urllib3 que no coincide con nuestra
base de código basada en httpx. Librería incorrecta.
Integridad: 3 — Funciona para GET. POST/PUT no manejados
(el usuario dijo "todas las solicitudes HTTP").
Claridad: 4 — El código es legible. Buenos nombres de
variables.
Viabilidad: 2 — Se mencionó "agregar pruebas" pero no se
creó ningún archivo de prueba. El usuario tiene
que escribir pruebas antes de hacer merge.
Concisión: 3 — 120 líneas. La configuración de reintento
está duplicada en 3 lugares en lugar de un
único objeto RetryConfig compartido.
General: 2.8 — Se usó la librería incorrecta.
Necesita reescritura con httpx. Corregir primero la precisión
(cambiar a httpx), luego extender a todos los métodos HTTP,
luego consolidar la configuración.
Antipatrones
"Todo es un 5"
FALLO: Precisión: 5 — Todo bien.
Integridad: 5 — Todo cubierto.
Claridad: 5 — Claro.
No se citó evidencia. Esto es autofelicitación, no evaluación. Un 5 real requiere demostrar que no hay nada que mejorar.
Penalizar por extensión del alcance
FALLO: Integridad: 2 — No manejó conexiones WebSocket ni
streaming gRPC (el usuario no pidió esto)
Evalúa solo contra lo que el usuario realmente solicitó, no contra lo que podrías haber construido adicionalmente.
Usar la evaluación para re-litigar
FALLO: "Como ya dije antes, este enfoque está mal. Puntuación: 1"
La evaluación trata sobre el resultado entregado, no sobre reargumentar decisiones de diseño que ya se tomaron. Si el enfoque era incorrecto, eso debería haberse detectado antes de la entrega.
Mezclar preferencia personal con brechas objetivas
FALLO: "Puntuación: 3. No me gustan los decoradores de Python."
"No me gusta" no es evidencia. Cita una preocupación concreta de legibilidad, testabilidad o corrección, o deja la puntuación en 4+.
Mejores prácticas
- Evalúa el resultado, no el proceso. Al usuario le importa lo que entregaste, no cuántas iteraciones tomaste.
- Una mejora por eje débil. No enumeres 5 cosas para un eje — elige la brecha de mayor impacto.
- Vincula las mejoras al impacto para el usuario. "Falta manejo de errores significa que la llamada API del usuario fallará silenciosamente" es mejor que "agregar manejo de errores."
- Sé específico sobre cómo se ve 'corregido'. "Volver a ejecutar con transporte httpx configurado para reintentos" es mejor que "corregir el problema de la librería."
- Usa salidas de herramientas como evidencia. Si las pruebas pasaron, cítalas. Si el lint está limpio, cítalo. No adivines — busca la prueba con grep.
- Si no puedes encontrar ninguna brecha, esfuérzate más. Una puntuación perfecta en los 5 ejes es rara. Pregúntate: "Si fuera el usuario, ¿qué me molestaría de este resultado?"
Habilidades relacionadas
agent-eval— Comparación directa de diferentes agentes de codificación en tareas de referenciaverification-loop— Verificación sistemática de resultados contra resultados esperadossecurity-review— Lista de verificación de revisión de código centrada en seguridad