Por qué los agentes de IA ignoran tus reglas .md — y cómo hacer que CLAUDE.md, Cursor Rules y AGENTS.md realmente se cumplan

Le preguntas a Claude Code: "¿Leíste CLAUDE.md?". Te responde con entusiasmo: "Sí, lo leí". Unos turnos después, ninguna de las reglas de ese archivo se está aplicando: tus comandos específicos del proyecto, tus convenciones de mensajes de commit, tus pasos de despliegue. Todo se ha evaporado en silencio.

Este no es un problema exclusivo de Claude Code. La misma deriva aparece en .cursor/rules de Cursor, en .github/copilot-instructions.md de GitHub Copilot y en AGENTS.md de Codex CLI cuando los usas el tiempo suficiente.

Este artículo expone las cinco causas raíz por las que los agentes de IA ignoran tus archivos de reglas .md, y luego recorre técnicas rápidas de reescritura y sistematización a largo plazo con Hooks y sub-agents, todo con ejemplos concretos.

1. Por qué la IA ignora tus reglas: 5 causas raíz

1. Límites estructurales de la ventana de contexto

Un LLM no presta la misma atención a cada token de su entrada. Las instrucciones enterradas en medio de un documento largo se pierden: el bien documentado efecto "lost in the middle". Una vez que tu CLAUDE.md supera unas 200 líneas, todo lo del medio prácticamente desaparece.

2. Auto-compact en sesiones largas

Claude Code tiene una función /compact que comprime el historial de la conversación. Cuando se dispara automáticamente, las instrucciones a nivel de system prompt sobreviven, pero los detalles operativos de CLAUDE.md se resumen o se descartan por completo. Por eso las violaciones de reglas se concentran en la segunda mitad de las sesiones largas.

3. Las instrucciones directas del usuario tienen prioridad

Para una IA, "lo que el usuario acaba de decir" pesa más que "una regla que leyó hace 300 turnos". En el momento en que un usuario dice "hazlo y ya" o "adelante, haz el commit", tu regla "siempre confirma antes de hacer commit" en CLAUDE.md queda atropellada.

4. Reglas vagas o contradictorias

Directrices subjetivas como "escribe las cosas con cortesía" o "maneja esto adecuadamente" dejan que la IA interprete por su cuenta, lo que rara vez coincide con lo que querías. Reescríbelas como restricciones verificables: "mantén las respuestas bajo 3 líneas", "usa chat.postMessage para la API de Slack", y así.

5. Archivos de reglas inflados y dispersos

CLAUDE.md más SPEC.md más README.md más un montón de otros archivos .md: una vez que están dispersos y son individualmente largos, la IA no los lee con el mismo peso. Cuando la misma regla aparece en varios archivos con diferencias sutiles, la IA tiende a elegir la versión que parece más segura.

2. Cómo diagnosticar si tus reglas se están aplicando de verdad

Empieza por revisar el estado actual. Lánzale a la IA las siguientes preguntas y observa la respuesta:

Que la IA diga "lo leí" o "entendido" no te dice nada. Si realmente aplica las reglas es una pregunta aparte: júzgala por el comportamiento posterior a la ejecución, no por lo que afirma.

3. Soluciones rápidas que puedes desplegar en 5 minutos

1. Comprime tu archivo de reglas a menos de 150 líneas

En la práctica, Claude Code sigue de forma fiable un CLAUDE.md de aproximadamente 100 a 150 líneas. Más allá de eso, divídelo:

• Reglas innegociables (10 a 20 líneas): al inicio de CLAUDE.md
• Especificaciones por servicio: extrae a SPEC-xxx.md
• Historial y contexto: muévelo a un directorio docs/

Mantén CLAUDE.md acotado a "cosas que son catastróficas si se olvidan". El detalle puede vivir en archivos enlazados.

2. Añade marcadores explícitos de prioridad

Usa palabras clave de prioridad ruidosas para forzar la atención de la IA:

• CRITICAL: violarlo provoca un incidente en producción
• MUST: siempre se sigue
• SHOULD: se sigue por defecto
• NICE TO HAVE: solo si hay margen

Una línea como "CRITICAL: las queries destructivas contra la BD de producción requieren aprobación explícita" es mucho más difícil de pasar por alto, incluso enterrada en un archivo largo.

3. Vuelve a enfatizar dentro del propio chat

Al inicio de una sesión, suelta una línea como "Antes de empezar, declara las tres reglas más importantes de CLAUDE.md." Eso trae esas reglas al contexto reciente y hace que se queden durante el resto de la sesión.

4. Registra operaciones peligrosas en TodoWrite

Usa la herramienta TodoWrite de un agente de IA (o el equivalente de seguimiento de tareas en tu herramienta) para incluir "verificación de reglas" como un paso explícito. La visibilidad hace que el "se me olvidó" sea mucho menos frecuente.

4. Sistematización a largo plazo: Hooks, sub-agents y slash commands

Las reglas basadas en prosa solo dan para tanto. Pasar de "pedirle a la IA que siga las reglas" a "hacer que el entorno las imponga" es mucho más fiable.

1. Imposición mecánica con los Hooks de Claude Code

La funcionalidad de Hooks en Claude Code te permite ejecutar scripts arbitrarios antes o después de llamadas a herramientas específicas. Puedes montar un esquema en el que el sistema detiene a la IA incluso cuando la propia IA olvida la regla.

Por ejemplo, con un hook PreToolUse:

• Detectar comandos peligrosos (rm -rf, git push --force) antes de que se ejecute Bash y bloquearlos
• Verificar permisos de archivo o estado de bloqueo antes de que Edit toque un archivo objetivo
• Ejecutar tests específicos del proyecto antes del commit y abortar si fallan

Pedir amablemente en prosa no es competencia para la imposición mecánica vía Hooks.

2. Separa responsabilidades con sub-agents

Usa las capacidades de sub-agent en el Claude Agent SDK o en Cursor para construir un "agente auditor de reglas" dedicado. Un flujo en dos etapas, donde el agente principal escribe el código y el agente auditor lo revisa, atrapa violaciones de reglas incluso cuando el agente principal las olvida.

El sub-agent solo necesita un prompt corto enfocado en auditoría, así que su tasa de reconocimiento de reglas se mantiene alta. Esa es la clave.

3. Codifica rutinas como slash commands personalizados

Flujos repetidos como "ejecuta estas 3 verificaciones antes de cada commit" encajan perfecto en un slash command (/precommit, etc.). Cuando el usuario escribe /precommit, la IA ejecuta una secuencia fija. No hace falta releer el archivo de reglas cada vez.

4. Detecta violaciones con scripts automatizados

Ejecuta detección basada en grep para patrones prohibidos en CI o como pre-commit hook. Ejemplos:

• console.log sueltos en código de producción
• API keys hardcodeadas
• Cabeceras de copyright faltantes

No te apoyes en la IA: deja que las máquinas lo encuentren. Esta es tu última línea de defensa.

5. Buenas prácticas por herramienta

La regla universal es "corto, específico, priorizado". Los nombres de archivo y las ubicaciones varían según la herramienta, pero los principios de redacción son los mismos.

6. Tres antipatrones de diseño de reglas

1. "Por favor sigue las best practices."

¿Las best practices de quién? La IA cae por defecto en el promedio de sus datos de entrenamiento, lo que significa que obtienes el mínimo común denominador. Las particularidades específicas del proyecto nunca entran. Escribe do's y don'ts concretos en su lugar.

2. La misma regla duplicada en varios archivos

Si tus "convenciones de commit" viven en CLAUDE.md y SPEC.md y README.md, las tres copias se irán desincronizando sutilmente y confundirán a la IA. Elige una única fuente de verdad y enlázala desde el resto.

3. Estampar "ABSOLUTAMENTE OBLIGATORIO" en todo

Si todo es "absoluto", la IA pierde la capacidad de priorizar. Reserva "CRITICAL" para lo genuinamente catastrófico; deja que el resto descanse en prosa normal. El énfasis sufre inflación: úsalo con escasez.

Resumen

Cuando los agentes de IA ignoran tus reglas .md, casi siempre se debe a restricciones estructurales y problemas de diseño de las reglas, no a pereza por parte de la IA. La mayoría de los casos se resuelven con soluciones rápidas: comprime a menos de 150 líneas, añade marcadores de prioridad, vuelve a enfatizar en el chat. Para las reglas verdaderamente críticas que queden, pasa a la imposición mecánica: Hooks, sub-agents, slash commands y scripts de detección automatizados.

"Si las reglas no se siguen, construye un sistema que las fuerce": el nuevo sentido común al operar agentes de IA.

FAQ

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

En la práctica, 100 a 150 líneas. Pasadas las 200, divide en SPEC-xxx.md o similar. Poner un resumen de "top 5 reglas críticas" en lo más alto es un buen seguro contra el olvido.

Q2. ¿Debería usar .cursorrules o .cursor/rules/*.mdc en Cursor?

Para configuraciones nuevas, .cursor/rules/*.mdc. Una regla por archivo, con patrones glob para acotar dónde aplica cada regla. El legado .cursorrules de archivo único tiende a inflarse con el tiempo.

Q3. ¿Reglas más largas hacen que la IA sea más estricta?

Lo contrario. Cuanto más largo el archivo, más se diluye el medio. Las reglas cortas y esenciales colocadas de forma prominente (al inicio) se siguen con mayor frecuencia.

Q4. ¿Qué pasa si uso varias herramientas de IA (Claude Code + Cursor) en el mismo proyecto?

La respuesta pragmática es poner el mismo resumen en el archivo de configuración de cada herramienta y centralizar los detalles en un SPEC.md compartido. Aún no hay una solución totalmente unificada (a mayo de 2026).

Q5. Cuando la IA dice "lo leí", ¿realmente no lo está leyendo?

La afirmación "lo leí" y el comportamiento real en tiempo de ejecución son cosas distintas. Usa los métodos de diagnóstico de la sección 2 para verificar el reconocimiento a nivel de ejecución.