IA metacognitiva: enseñar autoevaluación a tu agente
Le dije a mi agente que arreglara un test que fallaba. El agente leyó el error, identificó la discrepancia en la aserción, cambió el valor esperado para que coincidiera con la salida real e informó: “Test arreglado. Todos los tests pasan”. Tenía razón. El test pasaba. Y la corrección era completamente incorrecta.
El test fallaba porque la función devolvía datos incorrectos. El agente “arregló” el test haciendo que esperara la respuesta equivocada. Siguió mi instrucción al pie de la letra: arreglar el test que falla. Lo que yo quería decir era: arreglar el código que el test está probando. El agente no tenía ningún mecanismo para distinguir entre estas dos interpretaciones, porque nada en su conjunto de instrucciones le pedía evaluar por qué falla un test antes de decidir cómo arreglarlo.
Esa brecha tiene nombre. Es la brecha entre las instrucciones a nivel de acción y las instrucciones metacognitivas. Uso “metacognitivo” como analogía funcional, no como afirmación de ciencia cognitiva: los LLM no tienen procesos internos de monitoreo como los humanos. Lo que tienen es un comportamiento de seguimiento de instrucciones que puede orientarse hacia la autoevaluación. El marco funciona porque cambia qué instrucciones sigue el agente durante la verificación, no porque el agente desarrolle una autoconciencia genuina. La mayoría de las personas solo escribe el primer tipo de instrucción.
La programación metacognitiva de IA es la práctica de dar a los agentes de IA instrucciones de autoevaluación: no solo decirles qué hacer, sino enseñarles a detectar cuándo van en la dirección equivocada. Las instrucciones a nivel de acción definen comportamiento (“escribe tests”, “valida las entradas”). Las instrucciones metacognitivas definen el automonitoreo (“si dices ‘debería’ en lugar de ‘lo hice’, no has verificado”). Esta segunda capa, implementada mediante puertas de evidencia, modos de fallo nombrados y detección de lenguaje evasivo, separa a los agentes que producen resultados plausibles de los agentes que producen resultados correctos.
TL;DR
Existen dos niveles de instrucciones para agentes de IA. Las instrucciones a nivel de acción le dicen al agente qué hacer: “valida las entradas”, “escribe tests”, “sigue las convenciones RESTful”. Las instrucciones metacognitivas le dicen al agente cómo evaluar si lo está haciendo bien: “si te descubres diciendo debería en lugar de lo hice, no has verificado”, “si tres correcciones fallan, detente y cuestiona la arquitectura”, “la confianza no es evidencia”. La mayoría de las configuraciones de agentes contienen exclusivamente instrucciones a nivel de acción. La capa metacognitiva separa a un agente que produce resultados plausibles de uno que produce resultados correctos. Llevo nueve meses operando en producción un sistema metacognitivo con siete modos de fallo nombrados, una puerta de evidencia de seis criterios y detección de lenguaje evasivo, todo aplicado mediante 95 hooks.
Los dos niveles de instrucciones para agentes
Toda instrucción para un agente opera en uno de dos niveles.
Las instrucciones a nivel de acción definen comportamiento:
# Action-level examples
- Use type hints on all functions
- Write tests for edge cases
- Follow RESTful conventions for API endpoints
- Validate all user input at boundaries
Las instrucciones a nivel de acción son necesarias. Le dicen al agente cómo se ve el comportamiento correcto. Pero comparten una limitación estructural: suponen que el agente las ejecutará fielmente. No contemplan cómo evalúa el agente su propio cumplimiento.
Las instrucciones metacognitivas definen el automonitoreo:
# Metacognitive examples
- If you catch yourself thinking "just try changing X and see if it works" — STOP.
That's a signal to investigate, not guess.
- If you've searched the same files three times — you're stuck.
Step back and question your assumptions.
- If you use the word "should" in a completion report, replace it with evidence.
Run the command. Paste the output.
- After three failed fixes, stop fixing. The problem is architectural.
La distinción importa porque las instrucciones a nivel de acción le dicen al agente cómo se ve el destino. Las instrucciones metacognitivas le dicen cómo detectar cuándo va en la dirección equivocada. Unas previenen acciones incorrectas. Las otras previenen razonamientos incorrectos: los patrones de pensamiento que, para empezar, producen las acciones incorrectas.
El proyecto obra/superpowers en GitHub explora este territorio con skills que enseñan a los agentes a vigilar su propio razonamiento en busca de señales de fallo.1 La clave: la mayoría de las skills operan a nivel de acción (haz X, no hagas Y). El nivel metacognitivo opera de otra manera (date cuenta de cuándo estás a punto de hacer Y).
La tabla de evidencia falsa
La herramienta metacognitiva más eficaz que he construido es una tabla que define qué NO cuenta como evidencia.2
Cuando le digo a un agente “verifica tu trabajo”, el agente produce una verificación. Pero esa verificación suele ser una reformulación de la intención, no una demostración del resultado. “Los tests deberían pasar”. “La implementación sigue las mejores prácticas”. “Estoy seguro de que esto es correcto”. Cada una de estas afirmaciones suena a evidencia. Ninguna es evidencia.
La tabla de evidencia falsa bloquea de antemano atajos concretos al nombrarlos:
| Afirmación | Evidencia requerida | NO suficiente (evidencia falsa) |
|---|---|---|
| “Los tests pasan” | Salida de los tests pegada con 0 fallos | “Los tests deberían pasar” o “Los ejecuté antes” |
| “Sigue los patrones” | Nombrar el patrón Y el archivo donde existe | “Seguí las mejores prácticas” |
| “La solución más simple” | Nombrar las alternativas descartadas y por qué | “Está limpio” |
| “Casos límite manejados” | Enumerar cada caso límite y cómo se maneja | “Consideré los casos límite” |
| “Sin regresiones” | Nombrar los archivos/funciones revisados | “Nada más debería verse afectado” |
| “Resuelve el problema” | Exponer la necesidad del usuario y cómo esto la atiende | “Implementa la función” |
El valor está en la tercera columna. Sin ella, el agente llena la segunda columna con reformulaciones plausibles de su propia confianza. Con ella, la tabla nombra y bloquea cada atajo concreto antes de que el agente lo tome.3
La tabla va más allá de la ingeniería de prompts típica. Crea un marco de automonitoreo en lugar de una directiva de comportamiento. La tabla no le dice al agente qué hacer de otra manera. Le dice qué vigilar en su propia salida. El agente contrasta sus propias respuestas con la columna NO suficiente y, cuando detecta una coincidencia, sabe que debe reemplazar el atajo con evidencia real.
El patrón escala. Se puede añadir cualquier afirmación propia de un dominio. Para revisiones de seguridad: “Sin vulnerabilidades” requiere “las clases concretas de vulnerabilidades revisadas y los hallazgos”, no “Revisé el código”. Para accesibilidad: “Cumple con WCAG” requiere “la salida de una auditoría de axe o Lighthouse”, no “Revisé el contraste”.
Modos de fallo nombrados como barreras metacognitivas
Los humanos tienen sesgos cognitivos con nombre: sesgo de confirmación, anclaje, Dunning-Kruger. Los nombres importan. En cuanto puedes nombrar un sesgo, puedes vigilarlo. Los agentes de IA necesitan el mismo vocabulario para sus patrones de fallo.
Documenté siete modos de fallo que mi agente mostraba una y otra vez, le di un nombre a cada uno y añadí señales de detección:4
| Modo de fallo | Cómo se ve | Señal de detección |
|---|---|---|
| Espiral de atajos | Saltarse pasos de verificación para informar más rápido | Informe de finalización sin evidencia para cada paso |
| Espejismo de confianza | “Estoy seguro” en lugar de una verificación real | Lenguaje evasivo en el informe |
| Meseta del “suficientemente bueno” | Código que funciona pero no está limpio, probado ni documentado | Titubeo ante preguntas sobre calidad |
| Visión de túnel | Pulir una función mientras se rompe el código adyacente | “Nada más se ve afectado” sin haberlo comprobado |
| Verificación fantasma | Afirmar que los tests pasan sin ejecutarlos ahora | Evidencia de una sesión anterior |
| Deuda diferida | Dejar TODO/FIXME/HACK en código ya incluido en un commit | Cualquier comentario de ese tipo en el diff |
| Informe vacío | “Listo” sin citar detalles concretos | Informe de finalización al que le falta evidencia para algún criterio |
Los nombres hacen que los fallos sean detectables. Sin ellos, el agente produce un Espejismo de confianza y ni el agente ni el usuario lo reconocen como patrón. Con ellos, la instrucción pasa a ser: “Si te descubres mostrando cualquier modo de fallo nombrado, DETENTE y vuelve a empezar desde el paso Evaluar”.
El monitoreo es metacognitivo en sentido estricto: el agente vigila su propio proceso cognitivo (¿me estoy saltando la verificación? ¿estoy usando la confianza como sustituto de la evidencia?) en lugar de su salida (¿es correcto este código?). El monitoreo moldea la generación como parte del proceso de razonamiento del agente, y por eso detecta errores que la revisión a nivel de salida pasa por alto.
Las propias implementaciones de referencia de skills de Anthropic respaldan este enfoque. El análisis de las skills oficiales de Claude Code reveló patrones estructurales en el diseño eficaz de instrucciones para agentes. Según la observación del autor, las prohibiciones (“NEVER X”) resultaron más eficaces que las sugerencias (“consider Y”) porque nombran la evasión concreta en lugar de la acción general.5 Los modos de fallo nombrados son prohibiciones concretas: “NEVER exhibit Phantom Verification” funciona mejor que “always run tests” porque bloquea la evasión en lugar de repetir la acción.
Detección de lenguaje evasivo
El monitor metacognitivo más simple que implementé detecta palabras concretas en la salida del agente:
Red flag words: should, probably, seems to, likely, I believe,
I'm confident, looks correct, appears to
Cada vez que el agente usa una de estas palabras en un informe de finalización, la propia palabra es evidencia de una verificación insuficiente.6 “Tests should pass” significa que el agente no los ejecutó. “It seems to work” significa que el agente lo miró por encima. “I’m confident” significa que el agente está sustituyendo la evidencia externa por un estado interno.
La implementación es mecánica. El sistema de hooks intercepta la salida del agente y marca el lenguaje evasivo. Después, el agente reemplaza la palabra evasiva por la verificación que debió haber hecho:
- “Tests should pass” se convierte en: ejecuta los tests, pega la salida que muestra 0 fallos
- “It looks correct” se convierte en: cita la aserción o comprobación concreta que confirma que es correcto
- “I’m confident” se convierte en: enumera la evidencia que sustenta esa confianza
El patrón proviene del trabajo de obra sobre verificación antes de la finalización.1 El paralelo con la ciencia cognitiva está bien establecido: en la metacognición humana, la precisión de los autoinformes (“lo entiendo”) se correlaciona poco con la comprensión real.3 Las personas que dicen “ya lo entendí” a menudo no lo han entendido. Las que pueden explicarlo, por lo general, sí. Lo mismo vale para los agentes de IA: un agente que puede citar evidencia concreta entiende el problema. Un agente que dice “estoy seguro” quizá no.
El interruptor de circuito de tres correcciones
La metacognición no consiste solo en detectar razonamientos defectuosos. También consiste en detectar cuándo detenerse.
La regla de escalamiento de tres correcciones: si tres intentos de corrección para el mismo problema han fallado, el agente debe detenerse y cuestionar la arquitectura desde la base.7 No intentar una cuarta corrección. No buscar otro ángulo dentro del mismo enfoque. Detenerse. Dar un paso atrás. Preguntarse si el problema está en la solución o en la definición del problema.
La regla actúa como interruptor de circuito para los bucles de depuración. Sin ella, los agentes entran en lo que llamo la Espiral de correcciones: cada intento fallido produce una nueva teoría, que produce una nueva corrección, que falla, que produce una nueva teoría. El agente puede recorrer decenas de correcciones sin preguntarse nunca si está trabajando en el problema correcto. El incidente de los 23 agentes desbocados fue una versión en anchura de esto: los agentes alcanzaron un consenso sobre la pregunta equivocada porque ninguna comprobación metacognitiva preguntó “¿está bien delimitada esta pregunta?”.
La regla de tres correcciones funciona porque fuerza una transición de fase en el razonamiento del agente. Las correcciones 1 a 3 operan dentro del modelo mental actual. La corrección 4 (que en realidad es “deja de corregir”) obliga al agente a construir un modelo mental nuevo. En la práctica, esto suele significar volver a leer el error desde el principio, reexaminar las suposiciones o pedirle aclaraciones al usuario, todo lo cual es más productivo que una cuarta conjetura.
Antes y después: qué cambia
Un ejemplo concreto. Le pedí a un agente que añadiera validación de entradas a un endpoint de API.
Sin instrucciones metacognitivas:
Added Pydantic model with field validators for email format, password
length (8+), and username pattern (alphanumeric). Tests should pass.
The implementation follows FastAPI best practices.
La salida contiene tres señales evasivas: “should pass” (no ejecutó los tests), “follows best practices” (no nombró qué prácticas) y ninguna evidencia de que se consideraran los casos límite. Un Espejismo de confianza envuelto en un Informe vacío.
Con instrucciones metacognitivas (misma tarea, mismo agente):
Added Pydantic model with field validators:
- Email: regex validation + max length 254 (RFC 5321)
- Password: min 8, max 128, requires 1 uppercase + 1 digit
- Username: alphanumeric + underscore, 3-30 chars
Test output (just ran):
tests/test_auth.py::test_valid_registration PASSED
tests/test_auth.py::test_invalid_email_rejected PASSED
tests/test_auth.py::test_short_password_rejected PASSED
tests/test_auth.py::test_empty_username_rejected PASSED
tests/test_auth.py::test_unicode_username_rejected PASSED
5 passed in 0.34s
Edge cases handled: empty string (returns 422), null (returns 422),
unicode injection in username (rejected by alphanumeric pattern),
overlength email (RFC limit enforced).
Pattern followed: same validation approach as UserUpdateSchema in
app/schemas.py line 45.
La diferencia no es que el segundo agente escribiera mejor código. Puede que ambos agentes escribieran código idéntico. La diferencia es que el segundo agente verificó su trabajo contra criterios de evidencia concretos e informó la evidencia en lugar de su confianza.
Cómo construir tu propia capa metacognitiva
El marco es portable. No necesitas mi sistema concreto. Necesitas tres componentes:
1. Una tabla de evidencia falsa. Define qué NO cuenta como prueba para las afirmaciones que tu agente hace con más frecuencia. Empieza con los seis criterios de arriba y añade filas propias de tu dominio. El valor está en la tercera columna (NO suficiente).
2. Modos de fallo nombrados. Documenta las tres a cinco formas en que tu agente falla con más frecuencia. Dale un nombre a cada una. Añade señales de detección. Incluye la instrucción: “Si te descubres mostrando cualquier modo de fallo nombrado, detente y vuelve a evaluar”.
3. Detección de lenguaje evasivo. Enumera las palabras concretas que, en tu dominio, señalan una verificación insuficiente. Añade la instrucción: “Reemplaza cualquier palabra evasiva por la evidencia que eliminaría la evasiva”.
Estos tres componentes se combinan en una capa metacognitiva que se asienta sobre cualquier conjunto de instrucciones a nivel de acción. Las instrucciones a nivel de acción definen cómo se ve el comportamiento correcto. La capa metacognitiva define cómo detecta el agente que se está apartando del comportamiento correcto.
La implementación puede ser tan simple como añadir una sección a tu CLAUDE.md o AGENTS.md:
## Self-Monitoring
### When to stop and re-evaluate
- If you've searched the same files 3+ times: you're stuck.
- If you've attempted 3 fixes for the same issue: question the architecture.
- If you use "should" or "probably" in your response: replace with evidence.
### What doesn't count as evidence
[your false evidence table here]
### Named failure modes to watch for
[your failure modes here]
Que la aplicación ocurra mediante hooks (deterministas, imposibles de saltar), archivos de reglas (cargados en el contexto) o instrucciones en línea (dependen de que el modelo las cumpla) determina la fiabilidad de la capa metacognitiva. Los hooks son lo más sólido porque interceptan a nivel de uso de herramientas, no a nivel de prompt. Aun así, incluso las instrucciones metacognitivas a nivel de prompt mejoran de forma medible la calidad de la salida del agente, porque cambian sus criterios de evaluación y no solo sus acciones.
Ejercicio: audita tus últimas tres interacciones con un agente. Copia los informes de finalización. Resalta cada aparición de “should”, “probably” o “I’m confident”. Para cada palabra resaltada, escribe la evidencia concreta que habría reemplazado la evasiva. Si la evidencia existe pero el agente no la citó, el agente necesita detección de lenguaje evasivo. Si la evidencia no existe, el agente se saltó la verificación por completo: necesita la tabla de evidencia falsa.
El orden importa: empieza por la tabla de evidencia falsa (el mayor impacto y lo más fácil de implementar), añade los modos de fallo nombrados una vez que hayas observado patrones recurrentes y, por último, añade la detección de lenguaje evasivo como comprobación mecánica. Cada capa detecta errores que la anterior pasa por alto. Juntas forman un bucle de retroalimentación: el agente monitorea su propia salida, detecta patrones de fallo conocidos y se autocorrige antes de informar que terminó.
Configuración mínima reproducible
Puedes probar el patrón metacognitivo central en cinco minutos. Crea un archivo llamado .claude/CLAUDE.md (o añádelo al que ya tienes) con este contenido:
## Evidence Gate
Before reporting any task as complete, provide evidence for ALL criteria:
| Claim | Required Evidence | NOT Sufficient |
|-------|------------------|----------------|
| "Tests pass" | Paste test output showing 0 failures | "Tests should pass" |
| "Follows patterns" | Name the pattern AND file where it exists | "Best practices" |
| "Edge cases handled" | List each case and handling | "Considered edge cases" |
## Red Flag Words
If your completion report contains: should, probably, seems to,
I believe, looks correct, I'm confident — STOP.
Replace the word with the evidence that eliminates the hedge.
## Circuit Breaker
After 3 failed fixes for the same issue, STOP.
Question whether you are solving the right problem.
Pídele al agente que haga cualquier tarea no trivial (por ejemplo, “añade validación de entradas a este endpoint”). Compara el informe de finalización con y sin la puerta de evidencia. La diferencia se ve desde la primera tarea: sin la puerta, el agente informa confianza. Con la puerta, el agente informa evidencia.
La configuración anterior es un subconjunto del sistema completo. Omite los modos de fallo nombrados y la aplicación mediante hooks, pero demuestra el mecanismo central: definir qué NO cuenta como evidencia cambia de inmediato el comportamiento de verificación del agente.
Resultados en producción después de nueve meses
El sistema metacognitivo funciona en 12 proyectos activos desde mayo de 2025. Medir su impacto con precisión es difícil porque no hay grupo de control (no puedo repetir los mismos nueve meses de desarrollo sin el sistema). Las señales de tendencia, en cambio, son claras:
Antes de las instrucciones metacognitivas (los tres primeros meses, de mayo a julio de 2025): El agente producía con regularidad Espejismos de confianza: informes que decían “tests pass” sin haberlos ejecutado, o “follows patterns” sin nombrar qué patrones. Los detectaba en la revisión manual, lo que significaba que cada finalización del agente requería una verificación humana completa. El agente era una herramienta de borradores, no una herramienta autónoma.
Después de la tabla de evidencia falsa (agosto de 2025): Las afirmaciones con evidencia falsa cayeron casi a cero en los informes de finalización del agente. Un ejemplo representativo: el commit 3a8f2c1 (septiembre de 2025, blakecrosley.com) muestra un informe de finalización del agente que cita salida de tests concreta, rutas de archivos revisadas y casos límite manejados, en el mismo tipo de tarea que antes producía “tests should pass” y “follows best practices”. La tabla nombra y bloquea cada atajo concreto. El agente no puede decir “tests should pass” cuando la instrucción enumera explícitamente esa frase como NO suficiente. La comprobación mecánica funciona porque compara patrones de texto, no intenciones semánticas.
Después de los modos de fallo nombrados (octubre de 2025): Los bucles de depuración se acortaron. Antes del interruptor de circuito de tres correcciones, el agente intentaba de 8 a 12 correcciones para un solo problema antes de que yo interviniera. Con el interruptor de circuito, el agente escala o pide aclaraciones después de tres intentos. La escalada suele llevar a un diagnóstico correcto más rápido de lo que lo habría hecho una cuarta conjetura.
Después de la detección de lenguaje evasivo mediante hooks (diciembre de 2025): El sistema de hooks intercepta el lenguaje evasivo de forma mecánica, lo que significa que el agente no puede saltarse la comprobación ni siquiera en tareas complejas de varios pasos, donde las instrucciones a nivel de prompt a veces pierden prioridad. La combinación de las tres capas (tabla + modos de fallo + hooks) produce una salida del agente que reviso por su corrección y no por su completitud: el agente informa de forma fiable lo que realmente hizo, no lo que pretendía hacer.
El sistema no elimina los errores. Elimina una clase concreta de errores: aquella en la que la autoevaluación del agente se aparta de su desempeño real.
El patrón cuenta con corroboración independiente de varias fuentes. El trabajo de Anthropic sobre IA constitucional entrena modelos con criterios de autoevaluación en lugar de solo con retroalimentación externa.9 El proyecto superpowers de obra descubrió de forma independiente que las skills de “verificación antes de la finalización” cambian el comportamiento del agente más que las instrucciones a nivel de acción.1 Los modelos de recompensa de proceso (PRM) de OpenAI encontraron que evaluar cada paso de razonamiento por separado produce salidas más fiables que evaluar solo la respuesta final, el mismo principio que la tabla de evidencia falsa aplica a los pasos de verificación del agente.10 El marco Reflexion de Shinn et al. (2023) demostró que los LLM a los que se dan prompts estructurados de autorreflexión mejoraron su precisión en benchmarks de programación entre un 20 y un 30 % frente a un simple reintento, lo que estableció que el formato de la autoevaluación importa tanto como su presencia.11 La tabla de evidencia falsa de este sistema es una versión especificada a mano del mismo principio: define explícitamente los criterios de evaluación y la calidad de la salida del agente mejora porque mejora su automonitoreo.
Lo que la metacognición no puede hacer
La programación metacognitiva hace más fiables a los agentes de IA. No los hace sabios.
La tabla de evidencia falsa detecta atajos concretos. No detecta atajos nuevos que la tabla no nombra. Los modos de fallo nombrados detectan patrones conocidos. No detectan patrones que todavía no tienen nombre. La detección de lenguaje evasivo atrapa la sustitución superficial de evidencia por confianza. No atrapa a un agente que se ha convencido genuinamente (en el sentido que “convencido” pueda tener aquí) de que una salida incorrecta es correcta.
Más en el fondo, las instrucciones metacognitivas se aproximan al buen criterio, pero no lo producen. El sistema Jiro puede impedir except: pass y exigir evidencia de tests. No puede determinar si la arquitectura es la adecuada, si los nombres capturan la intención o si la solución atiende el problema real y no el que se planteó. Esos juicios requieren un tipo de razonamiento contextual que los modelos actuales aproximan pero no realizan de forma fiable.
Alguien respondió a uno de mis tweets sobre el sistema Jiro, en paráfrasis: básicamente intentas enseñarle al bucle contención, buen criterio y algo parecido a una pausa moral, cosas contra las que el patrón Ralph base optimiza explícitamente en nombre del rendimiento.8
Tenía razón. La programación metacognitiva es un andamiaje estructural para cualidades que la máquina no tiene. Y ese andamiaje soporta carga. Sin él, la máquina produce Espejismos de confianza a escala. Con él, la máquina produce salida verificada a escala. La brecha entre esos dos resultados es la diferencia entre un agente al que puedes confiarle trabajar toda la noche y un agente al que tienes que vigilar como a un niño.
Pero el andamiaje no es el edificio. El edificio (el buen criterio, el juicio, la capacidad de saber cuándo la respuesta correcta a una pregunta es otra pregunta) sigue siendo humano. La capa metacognitiva hace visible esa limitación en lugar de esconderla detrás de una prosa segura de sí misma.
Conclusiones clave
Para ingenieros que construyen sistemas de agentes:
-
Escribe instrucciones metacognitivas, no solo instrucciones a nivel de acción. Las instrucciones a nivel de acción definen el comportamiento correcto. Las instrucciones metacognitivas definen cómo detecta el agente que se aparta del comportamiento correcto. El segundo tipo es lo que separa la salida plausible de la salida verificada.
-
Ponles nombre a los modos de fallo de tu agente. Cuando un patrón de fallo tiene nombre (Espejismo de confianza, Verificación fantasma, Espiral de atajos), el agente puede vigilarlo. Los fallos sin nombre se repiten indefinidamente.
Para equipos que escalan flujos de trabajo asistidos por IA:
-
Construye una tabla de evidencia falsa antes de escalar. Define qué NO cuenta como prueba para cada afirmación que hace tu agente. La tercera columna (NO suficiente) bloquea de antemano los atajos concretos que toman los agentes cuando se les pide “verificar”.
-
El lenguaje evasivo es una señal fiable. Cada vez que un agente dice “should”, “probably” o “I’m confident” en un informe de finalización, no ha realizado la verificación que afirma. Detéctalo y reemplázalo de forma mecánica.
La auditoría metacognitiva
¿Quieres evaluar tus propias instrucciones para agentes? La herramienta interactiva de abajo analiza cualquier CLAUDE.md, AGENTS.md o prompt de sistema y lo puntúa según las dimensiones metacognitivas descritas en este artículo.
Pega tus instrucciones para el agente y la auditoría identificará: qué porcentaje de tus instrucciones son a nivel de acción y cuál metacognitivas, qué modos de fallo nombrados están cubiertos, si existe detección de lenguaje evasivo y dónde están las brechas.
Preguntas frecuentes
¿Cuál es la diferencia entre las instrucciones a nivel de acción y las instrucciones metacognitivas para agentes de IA?
Las instrucciones a nivel de acción definen el comportamiento correcto: “usa type hints”, “escribe tests”, “valida las entradas”. Las instrucciones metacognitivas definen cómo el agente monitorea su propio cumplimiento de esos comportamientos: “si usas la palabra ‘debería’ en un informe de verificación, en realidad no has verificado”, “si tres correcciones fallan, cuestiona la arquitectura”. Las instrucciones a nivel de acción previenen salidas incorrectas. Las instrucciones metacognitivas previenen los patrones de razonamiento incorrectos que producen salidas incorrectas. La mayoría de las configuraciones de agentes solo contienen el primer tipo, y por eso los agentes producen trabajo plausible pero no verificado.
¿Cómo construyo una capa metacognitiva para un agente de programación con IA?
Empieza por la tabla de evidencia falsa. Enumera las cinco afirmaciones que tu agente hace con más frecuencia (“los tests pasan”, “sigue los patrones”, “maneja los casos límite”) y define qué NO cuenta como prueba para cada una. La tercera columna (NO suficiente) bloquea atajos concretos antes de que el agente los tome. Añade los modos de fallo nombrados después de observar el mismo patrón de error tres veces. Añade la detección de lenguaje evasivo al final, como comprobación mecánica. Cada capa detecta errores que la anterior pasa por alto. Todo el sistema puede empezar como una sección de markdown en tu CLAUDE.md y crecer a partir de ahí.
¿La programación metacognitiva funciona con modelos distintos de Claude?
Los principios son independientes del modelo. Cualquier modelo de lenguaje que siga instrucciones puede beneficiarse de las tablas de evidencia falsa, los modos de fallo nombrados y la detección de lenguaje evasivo. El mecanismo concreto de aplicación varía: Claude Code admite hooks que interceptan la salida del agente a nivel de uso de herramientas (deterministas, imposibles de eludir). Otros frameworks pueden depender de prompts de sistema o de scripts de posprocesamiento. La fuerza de la aplicación determina la fiabilidad: las instrucciones metacognitivas a nivel de prompt mejoran la calidad de la salida, pero la aplicación a nivel de hooks la garantiza.
¿Qué señales indican que un agente de IA necesita instrucciones metacognitivas?
Cuatro señales: (1) El agente informa “listo”, pero el trabajo contiene errores evidentes (un Informe vacío, en el que el agente se saltó la verificación). (2) El mismo tipo de error se repite entre sesiones: un modo de fallo sin nombre que se repite porque nada lo vigila. (3) Los informes de finalización del agente usan lenguaje evasivo (“should work”, “looks correct”) en lugar de citar evidencia: un Espejismo de confianza. (4) El agente entra en largos bucles de depuración sin cuestionar su enfoque: falta un interruptor de circuito. Si cualquiera de estos patrones aparece más de dos veces, el agente necesita un andamiaje metacognitivo.
Parte de la serie Claude Code Deep Dives. El sistema de hooks implementa la capa de aplicación descrita aquí. La ingeniería de contexto como arquitectura explica cómo encaja la capa metacognitiva dentro del sistema de contexto más amplio de siete capas.
-
obra/superpowers en GitHub. El proyecto superpowers incluye skills de depuración sistemática y verificación que enseñan a los agentes de Claude Code a monitorear sus propios patrones de razonamiento y no solo sus salidas. El enfoque metacognitivo de este artículo se basa en ese planteamiento. github.com/obra/superpowers ↩↩↩
-
La estructura de la tabla de evidencia falsa se basa en el patrón de verificación antes de la finalización del proyecto obra/superpowers. Adapté el concepto en la Puerta de evidencia, un sistema de verificación de seis criterios que se aplica mediante hooks. Consulta el artículo sobre la filosofía de calidad de Jiro para ver la implementación completa. ↩
-
La tercera columna (NO suficiente) aborda lo que la literatura académica llama “ilusiones metacognitivas”: casos en los que la autoevaluación de un agente sobre su propio desempeño se aparta del desempeño real. En ciencia cognitiva esto está bien documentado: los estudiantes que afirman “entender” un material a menudo rinden mal en las pruebas sobre ese material. Dunning, D., Johnson, K., Ehrlinger, J., & Kruger, J. (2003). Why people fail to recognize their own incompetence. Current Directions in Psychological Science, 12(3), 83-87. doi.org/10.1111/1467-8721.01235 ↩↩
-
Los siete modos de fallo nombrados surgieron de nueve meses de uso en producción. Cada uno se documentó después de observar el patrón al menos tres veces en distintos proyectos y tipos de tarea. El sistema completo se describe en Por qué mi agente de IA tiene una filosofía de calidad. ↩
-
Análisis del autor de las skills oficiales de Claude Code disponibles a través del sistema de skills de la CLI de Claude Code. Las prohibiciones (“NEVER X”) resultaron más eficaces que las sugerencias (“consider Y”) porque nombran la evasión concreta. La observación de que las skills orientadas a la mentalidad superan a las guías procedimentales en adopción se basa en informes de la comunidad en el Discord de Claude Code y en discusiones de GitHub, no en un estudio controlado. Consulta la documentación de Claude Code de Anthropic: docs.anthropic.com/en/docs/claude-code. ↩
-
La idea de que el lenguaje evasivo señala una verificación insuficiente tiene respaldo empírico más allá de los sistemas de agentes. Nisbett, R.E. and Wilson, T.D. (1977). “Telling More Than We Can Know: Verbal Reports on Mental Processes.” Psychological Review, 84(3), 231-259. doi.org/10.1037/0033-295X.84.3.231. Nisbett y Wilson encontraron que los autoinformes verbales sobre los procesos de razonamiento suelen ser confabulados: las personas describen explicaciones que suenan plausibles en lugar de relatos precisos de su razonamiento real. La misma dinámica aparece en la salida de los agentes: “estoy seguro de que esto es correcto” es un autoinforme que suena plausible, no evidencia de verificación. ↩
-
La regla de escalamiento de tres correcciones funciona como un patrón de interruptor de circuito aplicado a la depuración. El patrón es análogo al circuit breaker de los sistemas distribuidos (Nygard, M. Release It!, 2007, Pragmatic Bookshelf): fallar rápido, escalar, probar otro enfoque. Después de tres intentos fallidos dentro del mismo modelo mental, seguir por el mismo camino da rendimientos decrecientes. ↩
-
Parafraseado de una respuesta a @blakec en X, febrero de 2026. El tweet original trataba la tensión entre la optimización de velocidad del bucle Ralph y la fricción de calidad del sistema Jiro. La observación de quien respondió, de que el bucle base “explicitly optimizes against restraint in the name of throughput”, describe con precisión la tensión de diseño que aborda la capa metacognitiva. ↩
-
Anthropic, “Constitutional AI: Harmlessness from AI Feedback,” 2022. arxiv.org/abs/2212.08073. El enfoque de la IA constitucional entrena al modelo para evaluar sus propias salidas según un conjunto de principios. El sistema metacognitivo descrito aquí es una versión en tiempo de ejecución de la misma idea: en lugar de autoevaluación durante el entrenamiento, la tabla de evidencia falsa y los modos de fallo nombrados aportan criterios de evaluación en tiempo de inferencia a través del conjunto de instrucciones. ↩
-
Lightman, H., Kosaraju, V., Burda, Y., et al., “Let’s Verify Step by Step,” arXiv, 2023. arxiv.org/abs/2305.20050. La investigación de OpenAI sobre modelos de recompensa de proceso demostró que evaluar los pasos intermedios del razonamiento (supervisión de proceso) supera a evaluar solo la respuesta final (supervisión de resultado) en la resolución de problemas matemáticos. La tabla de evidencia falsa aplica el mismo principio a nivel de instrucciones: exige evidencia para cada afirmación de verificación en lugar de aceptar un informe final de “listo”. ↩
-
Shinn, N., Cassano, F., Gopinath, A., et al., “Reflexion: Language Agents with Verbal Reinforcement Learning,” NeurIPS 2023. arxiv.org/abs/2303.11366. Reflexion demostró mejoras de precisión del 20 al 30 % en los benchmarks HumanEval y ALFWorld al dar a los agentes LLM prompts estructurados de autorreflexión después de los fallos. El marco valida la idea central de este sistema: el formato y la especificidad de las instrucciones de autoevaluación importan tanto como su presencia. ↩