Los cuatro tipos de fallo agéntico (y por qué tres son culpa tuya)

Cuando la IA rompe el sistema, no es magia negra

Conectas un agente a tu design system, le pides una pantalla y devuelve algo que casi funciona pero está mal: un color que no tocaba, un componente anidado donde no debe, una variante inventada. El reflejo es culpar al modelo. Casi siempre es el reflejo equivocado.

Cuando un agente rompe un sistema, la causa es una de cuatro, y solo una nace de verdad en el modelo. Las otras tres nacen en cómo escribiste el sistema. Diagnosticar cuál es lo que separa “la IA no funciona” de “ya sé qué arreglar”.

Fallo 1 · Token: el sistema no dice para qué sirve

El agente elige #E5342B para un botón de guardar. Técnicamente existe en tu paleta. El problema es que tu capa de tokens guarda el valor del rojo pero no su intención: que está reservado para errores y estados destructivos.

Un humano lo sabe por contexto. Un agente solo lee lo que está escrito. Si el token no declara su propósito, el modelo trata #E5342B como una cadena cualquiera y la usa donde “queda bien”.

El fix es estructural, no de prompt. Los tokens necesitan semántica suficiente para que el modelo no adivine: nombres por intención (color.bg.danger, no red.500), reglas de uso en los datos (no solo en la documentación) y, si tu formato lo permite, metadata que diga con qué combinan y qué contraste garantizan. Un token que se auto-explica no se usa mal. El procedimiento para construir esa capa está en la auditoría AI-readiness.

Fallo 2 · Composición: la regla que nadie escribió

El agente mete un modal dentro de otro modal, o un botón interactivo dentro de un elemento de lista que ya es clicable. Cada pieza es válida por separado; la combinación no.

La composición es donde más fallan los agentes, porque es donde más reglas viven sin escribir. “Eso no se hace” es folclore del equipo: una norma que todos respetan y nadie documentó. Un agente no asiste a las reuniones donde se acordó.

El fix: codificar las reglas de composición como datos verificables, no como costumbre. Qué hijos admite un componente, cuáles prohíbe, qué padre exige. Una taxonomía explícita (permitido / desaconsejado / prohibido, con la razón estructural) que tu sistema pueda consultar y rechazar antes de que la combinación inválida llegue al código.

Fallo 3 · Contexto: el cable incompleto

El agente genera bien, pero contra una versión vieja de tu sistema, o sin enterarse de la mitad de los componentes. No es que decida mal: es que decidió a ciegas.

Esto pasa cuando el cable entre tu sistema y el agente está incompleto. Le pasaste unas capturas, o un fragmento de la documentación, o nada estructurado, y el agente rellenó los huecos improvisando.

El fix: dar acceso a la fuente, no a un resumen. Un llms.txt que enumere tokens, principios y APIs en crudo; mejor aún, un MCP server que el agente consulte en vivo: qué componentes hay, cuál es su API, qué tokens existen. El contexto deja de ser una foto fija que envejece y pasa a ser una consulta siempre actual.

Fallo 4 · Interpretación: la instrucción ambigua

Le dijiste “hazlo limpio” o “que se vea profesional”. El agente interpretó algo razonable que no es lo que tenías en la cabeza. Este es el único de los cuatro que no se arregla tocando el sistema: se arregla tocando lo que pides.

Y es, casi siempre, culpa del autor de la instrucción. “Limpio” no es un criterio: es una sensación. Un agente no comparte tu sensación; aplica lo que puede medir.

El fix: convertir el criterio en regla evaluable. “El cuerpo de texto no baja de 16px y el contraste no baja de 7:1” es una instrucción que un agente puede cumplir y verificar; “que respire” no. El procedimiento para reescribir criterios vagos como reglas está en cómo escribir principios que un agente pueda aplicar.

Tres de cada cuatro veces, el problema eres tú

Mira la lista otra vez. Token, composición y contexto son fallos del sistema: cosas que tu design system sabía pero no había escrito de forma que una máquina pudiera leer. Solo interpretación vive del lado de la instrucción, y aun así suele ser una instrucción mal formulada.

Esa es la buena noticia. Si el problema fuera el modelo, no podrías hacer nada salvo esperar al siguiente. Como el problema casi siempre es el sistema, está en tu mano: documentar la intención, escribir las reglas de composición, completar el cable. No se trata de pedirle mejor las cosas al agente. Se trata de que tu sistema esté tan bien definido que el agente no tenga que adivinar.

Diseñar para que eso ocurra, y no después de que el agente ya rompió algo, es el oficio. Lo trabajamos a fondo, sobre tu propio sistema, en el Programa Anual.