¿Qué hace Autoevaluación del agente?
Tras completar una tarea compleja, el agente se detiene para valorar su propia salida según una rúbrica estructurada de 5 ejes. Esto NO es un filtro de aprobado/reprobado: es un paso de reflexión deliberado que detecta omisiones, señala exceso de confianza y revela áreas de mejora antes de que el usuario tenga que hacerlo.
Cuándo activarla
- Después de escribir código que abarque 3+ archivos o 50+ líneas
- Después de completar un flujo de trabajo de varios pasos (implementar → probar → revisar)
- Después de una sesión de depuración con 3+ intentos
- Después de producir un documento de diseño, una decisión de arquitectura o un análisis escrito
- Cuando el usuario pregunte «¿qué tan bueno fue eso?» o «evalúate a ti mismo»
- Al final de cualquier sesión, en el hook de Stop (si está configurado; véase
references/hook-integration.md)
Conceptos fundamentales
Los 5 ejes de evaluación
| Eje | Pregunta | Qué detecta |
|---|---|---|
| Precisión | ¿Son correctos los hechos, afirmaciones y salidas? | Alucinaciones, nombres de API incorrectos, sintaxis errónea, afirmaciones falsas |
| Completitud | ¿Cubrió todo lo que pidió el usuario? | Casos límite omitidos, rutas de error no manejadas, requisitos olvidados, subtareas saltadas |
| Claridad | ¿Es la explicación comprensible y bien estructurada? | Explicaciones confusas, jerga sin definición, contexto faltante, divagaciones |
| Capacidad de acción | ¿Puede el usuario actuar inmediatamente sobre la salida? | 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 detalles menores, sin carencias sustanciales
3 — Adecuado: cumple la solicitud pero tiene una debilidad notable en al menos un eje
2 — Débil: tiene una carencia clara que afecta la usabilidad o corrección
1 — Pobre: no cumple fundamentalmente la solicitud o contiene errores significativos
La regla de la evidencia
Cada puntuación inferior a 5 DEBE citar evidencia específica. Una puntuación de 3 no puede limitarse a decir «podría ser mejor»: debe decir exactamente qué falta o qué está mal. El mantra: «Muestra el vacío, no solo lo nombres».
Flujo de trabajo
Paso 1: Recopilar el material
Reúne lo que vas a evaluar:
- La solicitud original del usuario (léela de 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, «inténtalo de nuevo», «eso no está bien»)
Paso 2: Puntuar cada eje de forma independiente
Trabaja con los 5 ejes uno a uno. 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 es < 5, escribe una nota de mejora de una frase que cite el vacío
NO promedies primero las puntuaciones en tu cabeza 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
- Autoevaluació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 forma diferente
- Si la carencia se puede solucionar en menos de 30 segundos (enlace faltante, redacción poco clara), corrígela ahora
- Si la carencia 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: Buena evaluación (puntuación 4+)
Tarea: Añadir 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
retroceso exponencial. Sin métodos alucinados.
Completitud: 4 — Cubierto el camino feliz + 3 casos de error. Faltante:
manejo de timeout para conexiones colgadas.
Claridad: 5 — Los comentarios del código explican la fórmula de retroceso.
La descripción del PR enlaza con el incidente que motivó esto.
Capacidad de acción:5 — Fusión única. Sin tareas de seguimiento. Pruebas pasan.
Concisión: 4 — 47 líneas en total. El bucle de reintento podría extraerse
en un ayudante para reducir ~8 líneas.
Puntuación general: 4.6 — Una carencia (manejo de timeout). Corregir antes de fusionar.
Ejemplo: Evaluación débil (puntuación 2-3)
Tarea: Añadir 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. Biblioteca incorrecta.
Completitud: 3 — Funciona para GET. POST/PUT no manejados (el usuario
dijo «todas las solicitudes HTTP»).
Claridad: 4 — Código legible. Buenos nombres de variables.
Capacidad de acción:2 — Se mencionó «añadir pruebas» pero no se creó ningún archivo de prueba.
El usuario tiene que escribir las pruebas antes de fusionar.
Concisión: 3 — 120 líneas. La configuración de reintento está duplicada en
3 lugares en lugar de un objeto RetryConfig compartido.
Puntuación general: 2.8 — Biblioteca 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.
Anti-patrones
«Todo es un 5»
FALLO: Precisión: 5 — Todo bien.
Completitud: 5 — Todo cubierto.
Claridad: 5 — Claro.
Sin evidencia citada. Esto es autocomplacencia, no evaluación. Un 5 real requiere demostrar que no hay nada que mejorar.
Penalizar en exceso por aumento del alcance
FALLO: Completitud: 2 — No se manejaron 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 reabrir el debate
FALLO: «Como dije antes, este enfoque es incorrecto. Puntuación: 1»
La evaluación trata sobre la salida entregada, no sobre volver a discutir decisiones de diseño que ya se tomaron. Si el enfoque era incorrecto, debería haberse detectado antes de la entrega.
Mezclar preferencia personal con carencias 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, comprobabilidad o corrección, o deja la puntuación en 4+.
Mejores prácticas
- Evalúa la salida, no el proceso. Al usuario le importa lo que entregaste, no cuántas iteraciones te tomó.
- Una mejora por eje débil. No enumeres 5 cosas para un solo eje: elige la carencia de mayor impacto.
- Vincula las mejoras al impacto en el usuario. «Falta manejo de errores; la llamada a la API del usuario fallará silenciosamente» es mejor que «añadir 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 biblioteca».`
- Usa salidas de herramientas como evidencia. Si las pruebas pasaron, cítalas. Si el lint está limpio, cítalo. No adivines: busca la prueba.`
- Si no encuentras carencias, esfuérzate más. Una puntuación perfecta en los 5 ejes es rara. Pregúntate: «Si yo fuera el usuario, ¿qué me molestaría de esta salida?»`
Habilidades relacionadas
agent-eval— Comparación directa de diferentes agentes de código en tareas de referenciaverification-loop— Verificación sistemática de salidas contra resultados esperadossecurity-review— Lista de verificación de revisión de código centrada en seguridad