¿Por qué los agentes de IA ignoran los archivos de instrucciones que escribiste? (2026)

1. El archivo nunca se cargó

La causa más común, y la más vergonzosa, porque normalmente no hay ningún error.

Cursor documenta la versión más drástica: "Un archivo .md simple en .cursor/rules es ignorado por el sistema de reglas porque no tiene frontmatter para especificar description, globs y alwaysApply". El archivo está en el directorio correcto con un nombre sensato, y se omite silenciosamente. Esto afecta más justo después de migrar desde una herramienta cuyas reglas eran markdown simple: copias la carpeta, todo parece correcto y nada de eso se aplica.

Zed tiene una trampa diferente con el mismo resultado. Sus instrucciones de proyecto provienen de una lista de nombres de archivo — .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md — y la documentación dice: "Zed utiliza el primer archivo que coincida en esta lista". Primera coincidencia, no fusionado ni el más específico. Un archivo .cursorrules olvidado por un experimento de hace seis meses tiene prioridad sobre el AGENTS.md que escribiste ayer.

GitHub Copilot confunde a la gente con la ubicación. Su documentación admite archivos AGENTS.md en cualquier lugar del repositorio, teniendo prioridad el archivo más cercano en el árbol de directorios, pero enumera CLAUDE.md o GEMINI.md como alternativas en la raíz del repositorio. En un monorepo, esa distinción significa que tus archivos CLAUDE.md anidados son invisibles para Copilot, aunque el de la raíz funcione perfectamente.

La comprobación para los tres casos es la misma: antes de editar el contenido, confirma el nombre del archivo, su ubicación y, cuando la herramienta lo requiera, su frontmatter.

2. Se cargó, pero no está en contexto en este momento

Este es más engañoso, porque el archivo es válido y se está leyendo; simplemente no está presente en el momento que te interesa.

Las reglas con alcance solo se aplican al trabajo coincidente. Los cuatro modos de aplicación de Cursor deciden cuándo entra una regla en contexto: alwaysApply: true para siempre, una description para aplicación inteligente, globs para archivos específicos y reglas manuales que requieren una mención explícita con @. Una regla configurada como manual nunca se insertará por sí sola. El directorio .claude/rules/ de Claude Code se comporta de manera similar: las reglas con un campo de frontmatter paths: se aplican cuando Claude trabaja con archivos coincidentes, mientras que "Las reglas sin un campo paths se cargan incondicionalmente". Las reglas condicionales de Cline funcionan de la misma manera, activándose según los patrones glob del frontmatter evaluados frente a tu trabajo actual: archivos abiertos, pestañas visibles, rutas mencionadas, archivos que se están editando.

Nada de eso es un error. Es el mecanismo que mantiene el contexto pequeño. Pero significa que "la regla existe" y "la regla está frente al modelo" son estados diferentes, y una regla con alcance para src/api/** realmente no está cargada mientras el agente edita un componente.

El conocimiento bajo demanda se queda en el estante hasta que se solicita. Las Skills de Zed son carpetas que el agente carga cuando son relevantes o cuando las invocas, lo cual es eficiente y también significa que una Skill que asumías que era ambiental puede que simplemente nunca se haya cargado. Lo mismo ocurre con las habilidades en general, por lo que no son un sustituto de la memoria; la distinción se explica en por qué las habilidades de los agentes no son memoria.

La compactación descarta parte de lo que se cargó. El elemento menos valorado de esta lista. La documentación de Claude Code establece que el archivo CLAUDE.md de la raíz del proyecto sobrevive a la compactación (se vuelve a leer del disco y se reinyecta), pero "Los archivos CLAUDE.md anidados en subdirectorios y las reglas con frontmatter paths: no se reinyectan automáticamente; se vuelven a cargar la próxima vez que Claude lea un archivo en ese subdirectorio o un archivo que coincida con los patrones de la regla".

Compara esto con una sesión real. Trabajas durante una hora, el contexto se compacta y, a partir de ese momento, el agente opera con tus instrucciones de la raíz pero sin las reglas por directorio que tenía antes, hasta que casualmente vuelve a tocar un archivo coincidente. El comportamiento cambia a mitad de la sesión, no hay errores y el archivo de reglas que vuelves a inspeccionar parece perfecto.

3. Se cargó, pero algo más lo contradijo

Cada uno de estos sistemas superpone múltiples fuentes, y cada uno resuelve los conflictos de manera diferente.

Cline combina en lugar de reemplazar: "Cline procesa todos los archivos .md y .txt dentro de .clinerules/, combinándolos en un conjunto unificado de reglas", y entre ámbitos, "Cuando existen tanto reglas de espacio de trabajo como globales, Cline las combina. Las reglas del espacio de trabajo tienen prioridad cuando entran en conflicto con las reglas globales". También señala que "Las reglas sin frontmatter siempre están activas", por lo que un archivo antiguo siempre activo seguirá compitiendo con el nuevo para siempre.

Claude Code concatena hacia arriba en el árbol de directorios, ordenado desde la raíz del sistema de archivos hasta tu directorio de trabajo, y su documentación advierte directamente sobre las consecuencias: "si dos reglas se contradicen entre sí, Claude puede elegir una de forma arbitraria", recomendando una revisión periódica de CLAUDE.md, archivos anidados y .claude/rules/.

Copilot proporciona varias capas a la vez con una clasificación establecida: "Las instrucciones personales tienen la prioridad más alta. Las instrucciones del repositorio van a continuación, y luego las instrucciones de la organización se priorizan en último lugar. Sin embargo, todos los conjuntos de instrucciones relevantes se proporcionan a Copilot". Esa última frase es la importante: menor prioridad no significa exclusión. Si tu organización tiene instrucciones configuradas, están ahí, posiblemente escritas por alguien a quien nunca has conocido, moldeando silenciosamente un resultado que tú no configuraste.

Zed lo resuelve al revés para los archivos del repositorio: "Las instrucciones del proyecto anulan el archivo personal AGENTS.md cuando entran en conflicto".

Cuando el comportamiento de un agente parece arbitrario (siguiendo una regla el lunes y no el martes), una contradicción entre capas es una mejor primera hipótesis que la variabilidad del modelo.

4. Se cargó, no era ambiguo y el modelo no lo cumplió

Este es real, y es el único sobre el que la propia documentación de los proveedores te advierte de antemano.

La documentación de Claude Code explica el mecanismo: "El contenido de CLAUDE.md se entrega como un mensaje de usuario después del prompt del sistema, no como parte del prompt del sistema en sí. Claude lo lee e intenta seguirlo, pero no hay garantía de cumplimiento estricto, especialmente para instrucciones vagas o contradictorias". En otra parte, la misma documentación describe las instrucciones como "contexto, no configuración obligatoria". Cursor expresa la misma idea de forma positiva: "Los modelos de lenguaje grandes no retienen la memoria entre completados. Las reglas proporcionan un contexto persistente y reutilizable a nivel de prompt".

Contexto a nivel de prompt. No es configuración, ni política, ni una garantía. Lo que nos lleva a la única respuesta correcta para las reglas que realmente no se pueden romper: no las expreses como instrucciones en absoluto. Ambos ecosistemas apuntan a la misma alternativa: un hook que se ejecuta como un comando en un evento de ciclo de vida fijo, o una comprobación en CI. A una regla de linter no hace falta persuadirla.

Hacer que la regla sea más llamativa. Mayúsculas, "IMPORTANTE:", "DEBES". Ocasionalmente ayuda un poco, pero no hace nada por los tres primeros modos de fallo y añade ruido que hace que el archivo sea más difícil de mantener.

Hacer el archivo más largo. El reflejo cuando se pasa por alto una regla es explicarla más a fondo, lo que hace que el archivo sea más grande, lo que a su vez empeora el cumplimiento. Los proveedores coinciden aquí: Cursor aconseja mantener las reglas por debajo de las 500 líneas y dividir las grandes en piezas combinables; Claude Code recomienda apuntar a menos de 200 líneas por archivo y señala que "Los archivos más largos consumen más contexto y reducen el cumplimiento".

Configurar todo para que se aplique siempre. Resuelve el modo de fallo 2 por fuerza bruta y crea el modo de fallo 3 a gran escala: ahora todas las reglas están en contexto todo el tiempo, incluidas las contradictorias, en cada tarea.

Duplicar el archivo para cada herramienta. Un .cursorrules, un CLAUDE.md, un copilot-instructions.md, todos con el mismo contenido. Funciona durante una semana. Luego uno se actualiza y tienes una contradicción que no puedes ver, además de —en Zed— una gran probabilidad de que el obsoleto gane por ser el primero de la lista.

Culpar al modelo y cambiar de herramienta. La versión costosa. La nueva herramienta tiene sus propias reglas de carga, y los mismos cuatro modos de fallo vuelven a aparecer con una forma diferente.

Si das un paso atrás, verás que la mayoría de los archivos de instrucciones sobrecargados intentan hacer dos tareas no relacionadas. Un pequeño número de cosas realmente debe estar frente al modelo cada vez: las convenciones, las prohibiciones, los comandos. Todo lo demás es conocimiento: decisiones de arquitectura, por qué existe una restricción, qué se intentó y se rechazó, cómo se comporta un subsistema. Ese material no necesita estar residente de forma permanente. Necesita ser localizable cuando sea relevante.

Separarlos soluciona estructuralmente los tres primeros modos de fallo. Un archivo corto siempre activo es fácil de verificar que se ha cargado, difícil de contradecir y lo suficientemente económico como para mantenerlo en contexto. Y el conocimiento se traslada a un lugar donde la recuperación de información pueda alcanzarlo, en lugar de competir por el espacio en un archivo que la herramienta puede leer o no.

MemoryLake es esa segunda capa: un almacén de memoria del que leen tus agentes, independiente de las convenciones de nombres de archivo y las reglas de precedencia de cada herramienta. La configuración consta de tres pasos.

Paso 1: Crea una clave API

Inicia sesión en MemoryLake y crea una clave API. Una sola credencial para cada agente que conectes, lo cual es importante aquí precisamente porque cada herramienta difiere sobre dónde residen los archivos.

Paso 2: Sube tus primeras memorias

Saca el material de referencia de tus archivos de reglas: las decisiones de arquitectura y su razonamiento, las restricciones que parecen arbitrarias sin contexto, los enfoques que intentaste y abandonaste, el comportamiento de los subsistemas que la gente sigue explicando una y otra vez. Mantén las entradas cortas y de un solo tema. Lo que quede en el archivo de reglas debe ser la lista corta que defenderías en una revisión de código.

Paso 3: Conecta tu IA y tus agentes

Conecta tus herramientas. Se puede acceder a MemoryLake a través de MCP y de una API, por lo que los agentes nativos de MCP (entre ellos Claude Code, Codex y OpenClaw) se conectan apuntando al servidor MCP, y otras herramientas leen la misma memoria a través de la API. Cada herramienta mantiene su propio archivo pequeño de instrucciones para el conjunto que siempre debe aplicarse, y todas se nutren del mismo cuerpo de conocimiento en lugar de tener cinco copias desincronizadas.

Dos límites honestos, ambos relevantes para el tema de este artículo. Una capa de memoria no soluciona el modo de fallo 4: sigue siendo contexto, no obligatoriedad, y cualquier cosa que deba cumplirse independientemente de lo que decida el modelo pertenece a un hook o a la CI. Y tampoco hace que tus archivos se carguen; si .cursor/rules está lleno de archivos .md simples, eso sigue siendo un problema de frontmatter que debes solucionar.

El diagnóstico se vuelve rápido. Con un archivo corto siempre activo, la pregunta "¿se cargó?" se responde de un vistazo en lugar de estar enterrada bajo 400 líneas de contenido mixto.

Las contradicciones se vuelven más raras. La mayoría de las contradicciones provienen de archivos largos editados por diferentes personas en diferentes momentos. Los archivos cortos con una sola tarea no las acumulan al mismo ritmo.

El cumplimiento aumenta sin cambiar de modelo. Esta es la parte contraintuitiva: eliminar texto del archivo de instrucciones generalmente mejora el cumplimiento, porque las reglas restantes no compiten con el material de referencia por la atención.

Las migraciones de herramientas dejan de reiniciar tu configuración. Cuando el conocimiento no está en archivos específicos de la herramienta, cambiar de editor significa escribir un único archivo corto de reglas en el formato de la nueva herramienta, no volver a deducirlo todo. Esa es la diferencia visible en migrar CLAUDE.md a GitHub Copilot.

El comportamiento a mitad de la sesión se estabiliza. Una vez que el conocimiento duradero es recuperable en lugar de depender de qué archivos resultan estar residentes después de la compactación, el agente deja de estar silenciosamente menos informado a medida que avanza la sesión.

Confirma que el archivo se carga. Claude Code expone los archivos de memoria cargados en la sesión a través de /context, y ofrece un hook InstructionsLoaded para registrar exactamente qué archivos de instrucciones se cargan, cuándo y por qué. Utiliza cualquier equivalente que proporcione tu herramienta antes de asumir que el modelo tiene la culpa.

Comprueba si hay frontmatter donde sea necesario. En .cursor/rules, se ignora un archivo .md simple. Esta es una auditoría de cinco minutos con una alta tasa de acierto.

Haz una lista de los nombres de archivo que compiten. Especialmente en Zed, revisa la lista de nueve nombres y elimina o consolida los sobrantes. La primera coincidencia gana, silenciosamente.

Comprueba si la regla tiene un alcance definido. Un patrón paths:, globs: o applyTo significa que la regla está ausente a menos que los archivos coincidentes estén en juego. Las reglas en modo manual nunca se cargan por sí solas.

Comprueba si la sesión se compactó. Si el comportamiento cambió a mitad de una sesión larga, es posible que los archivos anidados y las reglas con alcance de ruta no se hayan reinyectado. Iniciar una nueva sesión es una forma rápida de confirmarlo.

Mira una capa más arriba. Las instrucciones personales, de repositorio y de organización se proporcionan todas en Copilot; las reglas globales y del espacio de trabajo se combinan en Cline; todo el árbol de directorios se concatena en Claude Code. La regla que se está contradiciendo puede vivir en un archivo que tú no escribiste.

Entonces, y solo entonces, reescribe para buscar especificidad. Lo concreto supera a lo abstracto: "Usa sangría de 2 espacios" en lugar de "da formato al código correctamente". Esa es la solución para el modo de fallo 4, y solo funciona una vez que hayas descartado los otros tres.

"El agente ignora mis reglas" son cuatro problemas diferentes que llevan la misma camiseta. Tres de ellos son de configuración y tienen respuestas exactas: comprueba el nombre del archivo y el frontmatter, comprueba si la regla tiene un alcance definido o si se descartó al compactar, comprueba qué más se ha cargado que la contradiga. El cuarto es una limitación real que todos los proveedores documentan de antemano (las instrucciones son contexto, no obligatoriedad) y la respuesta en ese caso es un hook o una comprobación de CI, no un adjetivo más fuerte.

La razón por la que esto sigue ocurriendo es que los archivos de instrucciones se utilizan como bases de conocimiento, lo que los hace largos, lo que a su vez empeora los cuatro modos de fallo simultáneamente. Mantén el conjunto siempre activo lo suficientemente corto como para verificarlo, traslada el conocimiento de referencia a un lugar recuperable y coloca lo no negociable donde se obligue a cumplir en lugar de sugerirse. Si estás lidiando con esto en una herramienta específica, las versiones a nivel de herramienta están cubiertas para Cursor, Claude Code, Copilot, Cline, Windsurf y Zed.