Cuando la IA parece funcionar — Gustavo Teixeira Cuco

La mayoría de los fallos de IA son evidentes. El modelo alucina un hecho. Interpreta mal un prompt. Produce algo claramente erróneo. Lo detectas, lo corriges, sigues adelante.

El fallo que quiero describir es distinto. La IA entregó archivos. Llenó carpetas. Parecía productiva. Y estaba completamente equivocada — no porque mintiera, sino porque actuó antes de entender.

El contexto que todos asumen que está cargado

En enero de 2026, construí una plantilla de gobernanza para todos mis repositorios técnicos — un conjunto estructurado de instrucciones, normas base y borradores de documentación que todo repositorio nuevo debería heredar. La plantilla vive en su propio repositorio de GitHub. Cada archivo tiene un propósito. El SYSTEM_PROMPT.md explica la estructura completa. El CLAUDE.md define la política de carga de contexto: qué documentos leer, en qué orden, para qué tipo de tarea.

La semana pasada, le pedí a Claude Code que aplicara esa plantilla a un nuevo repositorio.

No leyó la plantilla. Fue directo a crear archivos.

El resultado parecía correcto — estructura de carpetas, archivos de documentación, convenciones de nomenclatura. Pero se había saltado cuatro documentos que el SYSTEM_PROMPT.md exigía explícitamente que existieran, aunque fuera como borradores. Había decidido, basándose en la memoria de sesión de un proyecto anterior, qué documentos "aplicaban" a este. Había sustituido la lectura de instrucciones por reconocimiento de patrones.

La sesión terminó. Seguí adelante. Solo descubrí el problema cuando volví y pregunté por un archivo específico que faltaba.

Qué falló realmente

El fallo tiene una anatomía precisa:

La IA no leyó las instrucciones antes de actuar. Cuando dije "aplica la plantilla", el primer paso correcto era abrir el SYSTEM_PROMPT.md y el CLAUDE.md del repositorio de la plantilla. Se saltó esto y actuó según lo que recordaba de sesiones anteriores.
Asumió que el conocimiento previo estaba actualizado. Las plantillas cambian. Las reglas evolucionan. Lo que el modelo recordaba de una sesión de hace tres semanas no era lo mismo que lo que decía el documento hoy. La memoria de un patrón no es lo mismo que la lectura de un estado.
Tomó decisiones de alcance sin preguntar. Concluyó que ciertos documentos no aplicaban a este repositorio. Fue una decisión que no tenía autoridad para tomar — las instrucciones decían explícitamente que todos los documentos debían existir, aunque estuvieran marcados como N/A.
El resultado era lo bastante plausible como para pasar una revisión rápida. Esta es la parte crítica. Un repositorio con archivos parece un repositorio configurado. La ausencia de cuatro documentos borrador es invisible hasta que se lee la especificación.

El patrón se generaliza

Esto no es un fallo específico de Claude. Es un modo de fallo integrado en la forma en que los asistentes de IA operan en flujos de trabajo agénticos.

Cuando le das a una IA una instrucción de alto nivel — "aplica esta plantilla", "configura esta integración", "migra esta configuración" — actuará según el contexto más disponible: lo que puede inferir del estado actual de los archivos, lo que recuerda de antes en la sesión, lo que la instrucción coincide por patrón procedente del entrenamiento. Leer la documentación de fuente de verdad es un acto deliberado y secuencial. No ocurre automáticamente a menos que se incorpore al flujo de trabajo.

La brecha entre "la IA entendió el espíritu de la tarea" y "la IA leyó la especificación autorizada" es donde viven los errores silenciosos.

En términos de producto: tu asistente de IA está optimizando para la finalización de la tarea, no para la corrección conforme a la especificación. No son lo mismo.

Qué cambié

Dos intervenciones, ambas estructurales:

Primera: Añadí una regla a la memoria persistente — antes de aplicar cualquier plantilla o patrón externo, leer primero los archivos de instrucciones de ese repositorio. Siempre. No como sugerencia, sino como primer paso obligatorio.

Segunda: Estoy construyendo una skill /read-context — una verificación previa que se ejecuta antes de cualquier tarea de aplicación de plantilla. Lee el SYSTEM_PROMPT.md, el CLAUDE.md y el documento de normas base, y luego resume lo que encontró antes de continuar. La IA no puede saltarse este paso porque es el primer paso.

La corrección más profunda es hacer que el comportamiento correcto sea el camino de menor resistencia. Si el flujo de trabajo exige leer antes de actuar, el modo de fallo exige esfuerzo para reproducirse.

Qué significa esto si estás construyendo con IA

La suposición de que "la IA sabe lo que quiero decir" es cómoda y normalmente inofensiva. Hasta que deja de serlo.

Los casos en los que falla son precisamente aquellos en los que el riesgo es mayor: incorporar un nuevo repositorio a una estructura de gobernanza, migrar una configuración crítica, aplicar una plantilla de cumplimiento normativo. Tareas en las que un resultado erróneo pero plausible es más peligroso que un error evidente.

La solución no es un mejor prompt en el momento. Es construir flujos de trabajo en los que la IA está obligada a leer la fuente autorizada antes de actuar — sin depender de la memoria, sin inferir a partir del contexto, sin hacer coincidencia de patrones de sesiones anteriores.

La corrección conforme a la especificación es una propiedad del flujo de trabajo, no del modelo.

¿Cuál es tu mecanismo forzador?

Si estás integrando IA en flujos de trabajo técnicos con riesgo real, ¿qué mecanismo la obliga a leer la especificación antes de actuar — en lugar de asumir que ya lo sabe?

Fuentes

Anthropic, Claude system prompts and persistent memory behaviour — claude.ai/docs, 2025
Andrew Ng, Agentic AI Design Patterns — deeplearning.ai, 2024
Personal incident log — gtc-portfolio governance template, March 2026