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. La corrección tambié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 perfectamente: arreglar el test que falla. Lo que yo quería decir era: arreglar el código que el test está evaluando. 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 instrucciones a nivel de acción e instrucciones metacognitivas. La mayoría de las personas solo escriben el primer tipo.

TL;DR

Existen dos niveles de instrucciones para agentes de IA. Las instrucciones a nivel de acción le dicen al agente qué hacer: “valide las entradas,” “escriba tests,” “siga las convenciones RESTful.” Las instrucciones metacognitivas le dicen al agente cómo evaluar si lo está haciendo bien: “si se encuentra diciendo debería en lugar de lo hice, no ha verificado,” “si tres correcciones fallan, deténgase y cuestione 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. He operado un sistema metacognitivo en producción durante nueve meses con siete modos de fallo nombrados, una puerta de evidencia de seis criterios y detección de lenguaje evasivo aplicados a través de 95 hooks.

Los Dos Niveles de Instrucciones para Agentes

Cada 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: asumen que el agente las ejecutará fielmente. No contemplan cómo el agente evalúa 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 al agente cómo detectar cuándo se está dirigiendo en la dirección equivocada. Unas previenen acciones incorrectas. Las otras previenen razonamientos incorrectos: los patrones de pensamiento que producen acciones incorrectas en primer lugar.

El proyecto obra/superpowers en GitHub articuló esta distinción por primera vez, llamándola “enseñar a la IA a observar su propio razonamiento interno en busca de señales de fallo.”¹ La clave: la mayoría de las habilidades operan a nivel de acción (haga X, no haga Y). El nivel metacognitivo opera de manera diferente (note cuándo está a punto de hacer Y).

La Tabla de Evidencia Falsa

La herramienta metacognitiva individual más efectiva que he construido es una tabla que define qué NO cuenta como evidencia.²

Cuando le digo a un agente “verifique su trabajo,” el agente produce verificación. Pero la verificación frecuentemente es 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 como evidencia. Ninguna de ellas es evidencia.

La tabla de evidencia falsa bloquea preventivamente atajos específicos nombrándolos:

La tercera columna es donde reside el valor. Sin ella, el agente llena la segunda columna con reformulaciones plausibles de su propia confianza. Con ella, la tabla nombra y bloquea cada atajo específico antes de que el agente lo tome.³

La tabla no es ingeniería de prompts. Es arquitectura cognitiva. La tabla no le dice al agente qué hacer de manera diferente. Le dice al agente qué vigilar en su propia salida. El agente monitorea sus propias respuestas contra la columna de NO Suficiente y, cuando detecta una coincidencia, sabe que debe reemplazar el atajo con evidencia real.

El patrón es escalable. Cualquier afirmación específica de dominio puede añadirse. Para revisiones de seguridad: “Sin vulnerabilidades” requiere “clases específicas de vulnerabilidades verificadas y hallazgos,” no “Revisé el código.” Para accesibilidad: “Cumple con WCAG” requiere “salida de auditoría axe o Lighthouse,” no “Verifiqué el contraste.”

Modos de Fallo Nombrados como Barreras Metacognitivas

Los humanos tienen sesgos cognitivos nombrados: sesgo de confirmación, anclaje, Dunning-Kruger. Los nombres importan. Una vez que puede nombrar el sesgo, puede vigilarlo. Los agentes de IA necesitan el mismo vocabulario para sus patrones de fallo.

Documenté siete modos de fallo que mi agente exhibía repetidamente, le di un nombre a cada uno y añadí señales de detección:⁴

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 un patrón. Con ellos, la instrucción se convierte en: “Si se descubre exhibiendo cualquier modo de fallo nombrado, DETÉNGASE y reinicie desde el paso de Evaluación.”

El monitoreo es metacognitivo en el sentido preciso: el agente vigila su propio proceso cognitivo (¿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 ocurre antes de que el agente produzca su salida, razón por la cual detecta errores que la revisión a nivel de salida no detecta.

Las propias implementaciones de referencia de habilidades de Anthropic respaldan este enfoque. El análisis de sus 16 habilidades oficiales de Claude Code reveló patrones estructurales en el diseño efectivo de instrucciones para agentes. Las prohibiciones (“NUNCA X”) resultaron significativamente más efectivas que las sugerencias (“considere Y”) porque nombran la evasión específica en lugar de la acción general.⁵ Los modos de fallo nombrados son prohibiciones específicas: “NUNCA exhiba Verificación Fantasma” supera a “siempre ejecute los tests” porque bloquea la evasión en lugar de reformular la acción.

Detección de Lenguaje Evasivo

El monitor metacognitivo más simple que implementé detecta palabras específicas 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 completitud, la palabra misma es evidencia de verificación insuficiente.⁶ “Los tests deberían pasar” significa que el agente no los ejecutó. “Parece funcionar” significa que el agente lo revisó superficialmente. “Estoy seguro” significa que el agente está sustituyendo estado interno por evidencia externa.

La implementación es mecánica. El sistema de hooks intercepta la salida del agente y señala el lenguaje evasivo. El agente entonces reemplaza la palabra evasiva con la verificación que debería haber realizado:

• “Los tests deberían pasar” se convierte en: ejecuta los tests, pega la salida mostrando 0 fallos
• “Parece correcto” se convierte en: cita la aserción o verificación específica que confirma la corrección
• “Estoy seguro” se convierte en: lista la evidencia que genera esa seguridad

El patrón proviene del trabajo de obra sobre verificación-antes-de-completitud: “Las propias elecciones de palabras de la IA señalan evidencia insuficiente.”¹ El paralelo con la ciencia cognitiva es real. En la metacognición humana, la precisión del autoinforme (“Entiendo esto”) se correlaciona pobremente con la comprensión real. Las personas que dicen “lo entiendo” frecuentemente no lo entienden. Las personas que pueden explicarlo generalmente sí. Lo mismo aplica a los agentes de IA: un agente que puede citar evidencia específica comprende el problema. Un agente que dice “estoy seguro” podría no comprenderlo.

El Interruptor de Circuito de Tres Correcciones

La metacognición no se trata solo de detectar razonamiento deficiente. También se trata de 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 fundamentalmente.⁷ No intentar una cuarta corrección. No buscar un ángulo diferente 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 un interruptor de circuito para bucles de depuración. Sin ella, los agentes entran en lo que llamo la Espiral de Corrección: 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 ciclar a través de docenas de correcciones sin jamás cuestionar si está trabajando en el problema correcto. El incidente de desbordamiento de 23 agentes fue una versión en amplitud de esto: los agentes alcanzaron consenso sobre la pregunta equivocada porque ninguna verificación metacognitiva preguntó “¿está correctamente delimitada esta pregunta?”

La regla de tres correcciones funciona porque fuerza una transición de fase en el razonamiento del agente. Las correcciones 1-3 operan dentro del modelo mental actual. La corrección 4 (que en realidad es “deje de corregir”) fuerza al agente a construir un nuevo modelo mental. En la práctica, esto generalmente significa releer el error desde el principio, reexaminar las suposiciones o pedir clarificación al usuario, todas las cuales son más productivas que una cuarta conjetura.

Antes y Después: Qué Cambia

Aquí hay un ejemplo concreto. Le pedí a un agente que añadiera validación de entrada 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ó cuáles prácticas) y ninguna evidencia de consideración de 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 escribió mejor código. Ambos agentes pueden haber escrito código idéntico. La diferencia es que el segundo agente verificó su trabajo contra criterios de evidencia específicos e informó la evidencia en lugar de su confianza.

Construyendo Su Propia Capa Metacognitiva

El marco es portable. No necesita mi sistema específico. Necesita tres componentes:

1. Una Tabla de Evidencia Falsa. Defina qué NO cuenta como prueba para las afirmaciones que su agente hace con más frecuencia. Comience con los seis criterios anteriores y añada filas específicas de su dominio. La tercera columna (NO Suficiente) es donde reside el valor.

2. Modos de Fallo Nombrados. Documente las tres a cinco maneras en que su agente falla con más frecuencia. Dé un nombre a cada una. Añada señales de detección. Incluya la instrucción: “Si se descubre exhibiendo cualquier modo de fallo nombrado, deténgase y reevalúe.”

3. Detección de Lenguaje Evasivo. Liste las palabras específicas que señalan verificación insuficiente en su dominio. Añada la instrucción: “Reemplace cualquier palabra evasiva con la evidencia que eliminaría la evasión.”

Estos tres componentes se componen en una capa metacognitiva que se sitúa sobre cualquier instrucción 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 el agente detecta su propia desviación del comportamiento correcto.

La implementación puede ser tan simple como añadir una sección a su 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]

El hecho de que la aplicación se realice a través de hooks (determinísticos, no se pueden saltar), archivos de reglas (cargados en el contexto) o instrucciones en línea (dependen del cumplimiento del modelo) determina la confiabilidad de la capa metacognitiva. Los hooks son los más fuertes porque interceptan a nivel de uso de herramientas, no a nivel de prompt. Pero incluso las instrucciones metacognitivas a nivel de prompt mejoran mediblemente la calidad de salida del agente porque cambian los criterios de evaluación del agente en lugar de solo sus acciones.

Lo Que la Metacognición No Puede Hacer

La programación metacognitiva hace que los agentes de IA sean más confiables. No los hace sabios.

La tabla de evidencia falsa detecta atajos específicos. No detecta atajos novedosos que la tabla no nombra. Los modos de fallo nombrados detectan patrones conocidos. No detectan patrones que aún no han sido nombrados. La detección de lenguaje evasivo detecta sustitución superficial de confianza. No detecta a un agente que se ha convencido genuinamente a sí mismo (en cualquier sentido en que “convencido” aplique) de que una salida incorrecta es correcta.

Más fundamentalmente, las instrucciones metacognitivas aproximan el criterio pero no lo producen. El sistema Jiro puede prevenir except: pass y forzar evidencia de tests. No puede determinar si la arquitectura es correcta, si los nombres capturan la intención, o si la solución aborda el problema real versus el declarado. Esos juicios requieren el tipo de razonamiento contextual que los modelos actuales aproximan pero no realizan de manera confiable.

Alguien respondió a uno de mis tweets sobre el sistema Jiro: “Básicamente estás tratando de enseñarle al bucle contención, criterio y algo que se aproxima a una pausa moral, cosas contra las que el patrón Ralph base optimiza explícitamente en nombre del rendimiento.”⁸

Tenían razón. La programación metacognitiva es andamiaje estructural para cualidades que la máquina no posee. El andamiaje es portante. Sin él, la máquina produce Espejismos de Confianza a escala. Con él, la máquina produce resultados verificados a escala. La brecha entre esos dos resultados es la diferencia entre un agente en el que puede confiar para que funcione durante la noche y un agente que necesita supervisión constante.

Pero el andamiaje no es el edificio. El edificio (criterio, juicio, la capacidad de saber cuándo la respuesta correcta a una pregunta es una pregunta diferente) sigue siendo humano. Por ahora.

Conclusiones Clave

Para ingenieros que construyen sistemas de agentes:

• Escriba 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 el agente detecta su propia desviación del comportamiento correcto. El segundo tipo es lo que separa la salida plausible de la salida verificada.

• Nombre los modos de fallo de su agente. Una vez que 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:

• Construya una tabla de evidencia falsa antes de escalar. Defina qué NO cuenta como prueba para cada afirmación que su agente hace. La tercera columna (NO Suficiente) bloquea preventivamente los atajos específicos que los agentes toman cuando se les pide “verificar.”

• El lenguaje evasivo es una señal confiable. Cada vez que un agente dice “debería,” “probablemente” o “estoy seguro” en un informe de completitud, el agente no ha realizado la verificación que afirma. Detecte y reemplace mecánicamente.

La Auditoría Metacognitiva

¿Desea evaluar sus propias instrucciones para agentes? La herramienta interactiva a continuación analiza cualquier CLAUDE.md, AGENTS.md o system prompt y lo puntúa a través de las dimensiones metacognitivas descritas en este artículo.

Pegue sus instrucciones para agentes, y la auditoría identificará: qué porcentaje de sus instrucciones son a nivel de acción versus metacognitivas, qué modos de fallo nombrados están cubiertos, si existe detección de lenguaje evasivo y dónde están las brechas.

Parte de la serie Claude Code Mastery, que documenta la infraestructura detrás del desarrollo autónomo con IA: desde hooks que aplican control determinístico hasta gestión de contexto como disciplina arquitectónica pasando por deliberación multi-agente que detecta puntos ciegos de agentes individuales. La filosofía de ingeniería compuesta que sustenta el sistema explica por qué cada componente acelera todo lo que se construye después.