Por qué la IA ignora las reglas: revisa CLAUDE.md, Cursor Rules y AGENTS.md

Le preguntas a Claude Code si ha leído CLAUDE.md. Responde que sí, pero omite las pruebas que habías indicado. En estos casos, distingue entre instrucciones que no llegaron al modelo e instrucciones que llegaron pero no se siguieron. La respuesta «lo he leído» no permite determinar cuál de las dos situaciones ocurrió.

Con .cursor/rules de Cursor, .github/copilot-instructions.md de GitHub Copilot y AGENTS.md de Codex CLI ocurre lo mismo: desde dónde se cargan y cuándo se aplican varía según la herramienta. Que un archivo se cargue y que el modelo cumpla sus instrucciones son cuestiones distintas.

En resumen, el procedimiento tiene tres fases. Primero, comprueba si el archivo se carga. Si una regla se carga pero no se cumple, reescríbela como una frase cuyo cumplimiento se pueda comprobar después. Y lo que deba ejecutarse siempre, sin excepción, trasládalo a Hooks o CI. La propia documentación de Claude Code explica que CLAUDE.md es «contexto, no configuración que se imponga», y recomienda usar hooks si quieres bloquear una operación independientemente de lo que decida Claude.

Este artículo presenta, por este orden, cinco puntos que revisar (entre ellos la carga, la recuperación tras la compactación y los conflictos entre instrucciones), el procedimiento de diagnóstico y ejemplos de cómo reescribir las reglas.

1. Por qué la IA ignora las reglas: cinco puntos que revisar

1. Un archivo largo entierra las reglas

La documentación de Claude Code recomienda mantener cada archivo CLAUDE.md por debajo de 200 líneas y lo justifica así: «los archivos largos consumen más contexto y reducen el cumplimiento». Las 200 líneas no son un punto de corte de la carga: los CLAUDE.md de hasta 4 MiB se cargan completos (los que superan 4 MiB se omiten). Lo que ocurre con un archivo largo no es que se deje de leer a partir de cierto punto, sino que, aun leído entero, cada regla tiende a cumplirse peor.

2. Compactación automática en sesiones largas

El comando /compact de Claude Code comprime la conversación, pero el CLAUDE.md de la raíz del proyecto se vuelve a leer del disco y se reinserta en el contexto tras la compactación. En cambio, los CLAUDE.md de subdirectorios y las reglas específicas por ruta se recargan cuando se leen los archivos correspondientes. Según la documentación oficial, una instrucción que desaparece tras la compactación está en uno de estos tres casos: (1) solo se dio en la conversación; (2) está en un CLAUDE.md de un subdirectorio que aún no se ha recargado; (3) está en una regla específica por ruta cuyo archivo de destino aún no se ha tocado. Si quieres conservar lo decidido en la conversación, añádelo a CLAUDE.md.

3. Conflictos entre instrucciones y ámbito de aplicación

Si coexisten «ejecuta las pruebas antes del commit» y «esta vez omite las pruebas», decidir cuál se aplica queda en manos del modelo. La documentación de Claude Code explica que, si dos reglas se contradicen, Claude puede elegir una de forma arbitraria. Compara periódicamente las instrucciones generales del proyecto, las personales y las específicas de cada directorio para eliminar las contradicciones y, si admites excepciones, indica «quién puede pedirlas y cómo». Para bloquear la operación en sí, usa la configuración de permisos o Hooks, no CLAUDE.md.

4. Reglas vagas o contradictorias

Ante instrucciones subjetivas o abstractas como «escribe con cortesía» o «gestiona esto adecuadamente», la IA aporta su propia interpretación, que puede diferir de lo que esperas. Formula requisitos cuyo cumplimiento se pueda verificar, como «escribe un máximo de tres líneas» o «cuando uses la API de Slack, utiliza chat.postMessage» (ejemplos de reescritura en la sección 3).

5. Archivos de reglas excesivos o dispersos

Un enlace normal desde CLAUDE.md a SPEC.md no implica necesariamente que todo el archivo enlazado se cargue al iniciar. Claude Code expande las importaciones @path al inicio, pero su contenido también consume contexto. Dividir archivos para organizarlos no equivale a cargarlos solo cuando hacen falta. Si las reglas duplicadas difieren, define cuál es la fuente de referencia y su ámbito de aplicación.

Las especificaciones de Claude Code citadas hasta aquí proceden de la documentación oficial de memoria de Claude Code (a 21 de septiembre de 2026).

2. Cómo comprobar si se cumplen las reglas

Empieza por comprobar la situación actual. Haz estas preguntas a la IA y examina sus respuestas:

Las respuestas «lo he leído» o «lo entiendo» no demuestran ni la carga ni la aplicación. Lo que sirve como prueba es la indicación de carga y los archivos resultantes de la ejecución.

Cuatro pasos para aislar la causa

1. Revisa el punto de entrada. En Claude Code, comprueba si el CLAUDE.md y las reglas correspondientes aparecen en Memory files de /context. Si no aparecen, revisa la ubicación del archivo y la configuración de exclusiones (claudeMdExcludes). Si Claude Code lee AGENTS.md directamente, ese AGENTS.md no aparece en esta lista. Con la configuración predeterminada, comprueba si al iniciar se muestra la línea no CLAUDE.md found; AGENTS.md loaded: … (un AGENTS.md importado desde CLAUDE.md sí aparece en la lista).
2. Activa las condiciones de la regla. Para las reglas específicas por ruta, pide al agente que lea un archivo coincidente. Si aún no lo ha leído desde la compactación, esa regla no se ha recargado. Si quieres dejar constancia de qué se cargó y cuándo, el hook InstructionsLoaded permite registrar la carga de CLAUDE.md y de las reglas (no se activa con un AGENTS.md leído directamente).
3. Prueba con una tarea pequeña e inocua. Pide al agente que modifique una muestra desechable siguiendo reglas como «indica el archivo de destino antes de cambiarlo» e «informa después del comando de pruebas y su código de salida». No uses como prueba la eliminación de datos de producción ni la publicación. Si pruebas con una frase secreta, escríbela solo en el archivo de instrucciones y no la incluyas en la pregunta.
4. Verifica el resultado de forma independiente. Busca cambios inesperados en el diff, confirma que las pruebas comunicadas se ejecutaron y comprueba si se revisaron suficientes elementos. Anota la configuración, la versión de la herramienta y los archivos con los que probaste, y vuelve a probar si cambia cualquiera de ellos.

Por ejemplo, si la instrucción «ejecuta las pruebas antes del commit» se cargó pero las pruebas no se ejecutaron, mover el archivo no lo resolverá. Lo que hay que corregir es la redacción de la regla (ejemplos de reescritura en la siguiente sección) y el mecanismo de comprobación. Exigir comprobaciones de CI antes de fusionar aporta pruebas independientes del propio informe de la IA.

Si el CLAUDE.md correspondiente no aparece entre los archivos cargados, corrige la ubicación de inicio y la configuración antes de añadir más énfasis al texto. Si las infracciones persisten después de confirmar la carga, revisa la precisión de las instrucciones y el proceso de comprobación. Esta secuencia evita atribuir todos los fallos a que «la IA lo olvidó».

3. Soluciones rápidas para probar en cinco minutos

1. Separa las reglas permanentes de los detalles que se leen cuando hacen falta

Usa como referencia la recomendación oficial de Claude Code de menos de 200 líneas, pero reduce duplicaciones y explicaciones innecesarias en vez de perseguir una cifra. Por ejemplo:

• Reglas esenciales (10–20 líneas) → al principio de CLAUDE.md
• Especificaciones detalladas de los servicios → archivos SPEC-xxx.md separados
• Historial y contexto → directorio docs/

Tras mover los detalles a otro archivo, indica en el archivo de entrada qué debe leerse antes de cada tipo de tarea. Si importas todo lo necesario para cada sesión, dividir los archivos no reduce el contexto inicial. Usa reglas específicas por ruta o skills cuando quieras cargar instrucciones condicionales solo cuando hagan falta.

2. Reescribe las reglas como frases cuyo cumplimiento se pueda comprobar

Ante una regla que se carga pero no se cumple, mira primero si indica qué hay que hacer para cumplirla. La documentación de Claude Code también recomienda escribir instrucciones lo bastante concretas para poder verificarlas, y pone como ejemplo «ejecuta npm test antes de hacer commit» en lugar de «prueba tus cambios». Si das un paso más e indicas también qué hacer si falla y cuándo se admite una excepción, queda así:

Con la versión reescrita, el cumplimiento se puede comprobar con el diff, el historial de comandos y los códigos de salida. Y si la regla ya es comprobable, sirve tal cual como condición de verificación cuando más adelante la traslades a Hooks o CI (sección 4).

3. Añade indicadores de prioridad

Las etiquetas de importancia ayudan a personas e IA a entender la intención. Las etiquetas no obligan por sí mismas a ejecutar nada. Por ejemplo, defínelas así:

• CRITICAL: infringirla podría causar un incidente en producción
• MUST: siempre obligatoria
• SHOULD: lo esperado normalmente
• NICE TO HAVE: opcional si hay tiempo

«CRITICAL: las consultas destructivas sobre la base de datos de producción requieren aprobación previa» especifica la operación y la condición de autorización. Para bloquear de verdad operaciones no autorizadas también hacen falta permisos configurados o comprobaciones previas a la ejecución.

4. Reitera las reglas en el chat

Al empezar una sesión, añade «Indica las tres reglas más importantes antes de comenzar.» La declaración recuerda las reglas al agente; si se cumplieron se ve en los resultados al terminar.

5. Incluye condiciones de finalización en el plan

Incluye «comprobar las reglas» en el seguimiento de tareas de tu agente de IA y muestra las condiciones para completar cada paso. Pide el comando, el código de salida y el alcance no verificado, en lugar de un simple «probado». Si un paso tiene la marca de completado pero el campo de pruebas está vacío, no lo des por completado.

4. Medidas duraderas: Hooks, revisiones y skills

Convierte en scripts las condiciones que se pueden evaluar y controla los permisos de operación mediante la configuración. Hooks, CI, revisión con IA y skills tienen funciones distintas. Llamar a todo «cumplimiento automático» oculta las áreas que no comprueban.

1. Impón comprobaciones con Hooks de Claude Code

La función Hooks de Claude Code puede ejecutar scripts antes o después de determinadas llamadas a herramientas. Permite crear un mecanismo en el que el sistema detenga una operación aunque la IA olvide la regla.

Por ejemplo, un hook de PreToolUse puede:

• Detectar comandos peligrosos (rm -rf, git push --force) antes de ejecutar la herramienta Bash y denegarlos
• Comprobar los permisos o el estado de bloqueo del archivo de destino antes de ejecutar la herramienta Edit
• Ejecutar las pruebas específicas del proyecto antes de un commit y bloquearlo si fallan

Cuando un hook de PreToolUse deba bloquear una operación, haz que devuelva el código de salida 2 o el JSON de denegación correspondiente. Si una prueba fallida devuelve 1 únicamente con una salida de texto normal, se trata de un error no bloqueante y la operación continúa. PostToolUse se ejecuta después, por lo que no sirve para deshacer una operación ya completada.

Un hook solo puede bloquear lo que su script evalúe en el evento configurado. Vigilar únicamente Edit no cubre las escrituras realizadas mediante una shell. La simple coincidencia de cadenas peligrosas tampoco es exhaustiva. Combina hooks con permisos, un entorno aislado y CI, y prueba tanto entradas que deban aceptarse como entradas que deban rechazarse.

2. Separa responsabilidades con subagentes

Usa las capacidades de subagentes del Claude Agent SDK o de Cursor para crear un agente dedicado a auditar las reglas. Que otro agente revise el código del agente principal puede revelar omisiones desde otra perspectiva. Aun así, ambos pueden cometer el mismo error o pasar por alto el mismo problema.

Entrega al revisor las reglas que debe revisar, el diff y las pruebas que esperas recibir (nombres de pruebas o códigos de salida). Contrasta cada hallazgo con los archivos reales o los resultados de las pruebas y trata como no verificadas las áreas ajenas a su encargo.

3. Invoca procedimientos repetibles mediante skills

En Claude Code puedes guardar un procedimiento repetible en .claude/skills/precommit/SKILL.md e invocarlo con tu propio /precommit. Es un ejemplo que debes crear, no un comando integrado. Los archivos del antiguo directorio .claude/commands/ siguen funcionando, pero la documentación actual los integra en las skills. Invocar un procedimiento no equivale a superar todas las comprobaciones, así que examina los resultados al terminar.

Las ubicaciones de los archivos y cómo invocarlos se explican en la documentación oficial de skills. Incluye en la skill el procedimiento y las condiciones para superarlo, y pide pruebas de que los pasos se ejecutaron.

4. Detecta infracciones con scripts automáticos

Usa grep en CI o en un hook previo al commit para detectar patrones prohibidos. Por ejemplo:

• console.log olvidado en código de producción
• Claves de API incrustadas en el código
• Ausencia de comentarios de copyright al principio de los archivos

Los scripts no pueden comprobar reglas que no implementan ni archivos fuera de su alcance. Prueba ejemplos válidos, infracciones y fallos de lectura, y muestra cuántos elementos se comprobaron o se omitieron. Por ejemplo, si no se pueden leer dos de diez archivos, que los otros ocho superen la revisión no significa que «todos los archivos pasaron».

5. Buenas prácticas por herramienta

Consulta la documentación de reglas de Cursor, las instrucciones personalizadas de GitHub Copilot y la guía de AGENTS.md de OpenAI para comprobar las condiciones de cada herramienta. Las instrucciones por ruta de Copilot usan *.instructions.md, y qué funciones las leen varía de una función a otra. Los 32 KiB de Codex son el límite combinado de bytes predeterminado, no una cantidad de caracteres ni de líneas.

El principio común es «breve, concreto y con prioridades claras». Los nombres y las ubicaciones de los archivos varían según la herramienta, pero los principios de redacción son los mismos.

6. Tres errores de diseño de reglas

1. «Sigue las buenas prácticas»

Esa petición por sí sola no define qué son «buenas prácticas». Especifica los métodos que utiliza tu proyecto y cómo verificarlos. En vez de «haz las pruebas adecuadas», indica los comandos necesarios y el paso del flujo de trabajo que debe detenerse si fallan (ejemplos de reescritura en la sección 3).

2. Duplicar una misma regla en varios archivos

Si las mismas convenciones de commit aparecen en CLAUDE.md, SPEC.md y README.md, las actualizaciones pueden dejar las tres copias en desacuerdo. Elige una única fuente de referencia y enlázala desde los demás archivos.

3. Escribir «obligatorio sin excepción» en todas partes

Dar el mismo énfasis a todas las condiciones dificulta comunicar las prioridades. Reserva «CRITICAL» para condiciones con consecuencias realmente graves y usa un lenguaje normal para las demás. Recuerda que el énfasis pierde valor cuando se abusa de él.

Resumen

Cuando no se cumplan las reglas, investiga en este orden: condiciones de carga → ámbito de aplicación → instrucciones contradictorias → resultados de ejecución. El CLAUDE.md raíz se reinserta tras la compactación, así que una instrucción que desaparece tras compactar o solo se dio en la conversación, o está en un CLAUDE.md anidado o en una regla específica por ruta que aún no se ha recargado.

• No se carga: corrige la ubicación, las exclusiones o las condiciones de carga de AGENTS.md
• Se carga pero no se cumple: reescribe la regla como una frase cuyo cumplimiento se pueda comprobar después
• Debe ejecutarse siempre: compruébalo con Hooks o CI y define las operaciones permitidas en la configuración de permisos

Las pruebas de finalización son los resultados de la ejecución y los archivos generados, no la respuesta «lo he leído».

Preguntas frecuentes

P1. ¿Cuál es la longitud ideal de CLAUDE.md?

La recomendación oficial es menos de 200 líneas por archivo; la documentación explica que los archivos largos consumen más contexto y reducen el cumplimiento. Superar las 200 líneas no corta la carga a mitad del archivo (hasta 4 MiB se carga completo). Deja solo las reglas necesarias en cada sesión y traslada a reglas específicas por ruta las que solo se usan con ciertos archivos. Los archivos separados mediante importaciones @path también se cargan al iniciar, así que no reducen el contexto.

P2. ¿Debo usar .cursorrules o .cursor/rules/*.mdc en Cursor?

Para una configuración nueva, usa .cursor/rules/*.mdc. Mantén una regla por archivo y especifica su ámbito con patrones glob. El antiguo .cursorrules es un único archivo que puede volverse difícil de manejar.

P3. ¿Las reglas más largas se aplican con más rigor?

La longitud por sí sola no hace más estrictas las reglas. La documentación oficial también indica que los archivos largos reducen el cumplimiento. Si añades algo, que sean condiciones verificables y ejemplos concretos, y elimina duplicaciones y contradicciones.

P4. ¿Qué hago si uso varias herramientas de IA, como Claude Code y Cursor, en un mismo proyecto?

Reúne las reglas compartidas en AGENTS.md como fuente única y deja la configuración propia de cada herramienta en su punto de entrada. Codex y Cursor admiten AGENTS.md. Claude Code, desde la v2.1.277, lee AGENTS.md directamente si no hay ningún CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo ni en sus directorios superiores. Si existe alguno, por defecto solo se lee ese, y basta con añadir un CLAUDE.local.md personal para que AGENTS.md deje de leerse. En proyectos que también usan CLAUDE.md, escribe en él la línea @AGENTS.md para importarlo (otra opción es poner Project instructions de /config en claude-md-and-agents-md para que lea ambos). La lectura directa no funciona en sesiones a través de proveedores externos como Amazon Bedrock o con la telemetría desactivada, en la primera sesión tras instalar o actualizar, ni en entornos con los hooks desactivados (por ejemplo, con disableAllHooks); en esos casos, usa la importación. Puedes distinguir por qué vía se lee con el paso 1 de la sección 2.

P5. Si la IA dice «lo he leído», ¿podría no haberlo leído?

La respuesta no demuestra ni que lo haya leído ni que no. Sigue los pasos de diagnóstico de la sección 2 para comprobar la indicación de carga y contrástala con los diffs, los resultados de las pruebas y el historial de ejecución.