Dónde deben ir las instrucciones de Claude Code: CLAUDE.md, reglas de ruta o hooks
Aprende por qué Claude Code trata a CLAUDE.md como contexto, cómo recortarlo, las reglas de alcance por ruta, cómo mover los pasos obligatorios a hooks y cómo verificar qué se cargó realmente.
Fuentes: 7 CLAUDE.md Patterns That Actually Change How Claude Writes Code
La mayoría de los equipos que utilizan Claude Code ahora mantienen un archivo CLAUDE.md, y pocos pueden decir si este realmente sirve para algo. Un patrón común es un archivo que ha llegado a tener varios cientos de líneas, donde el modelo sigue algunas instrucciones y ignora silenciosamente otras. La solución rara vez consiste en usar un plantilla mejor; se trata de comprender qué es realmente el archivo y dirigir cada instrucción al mecanismo adecuado para ejecutarla. Esta guía aborda siete patrones prácticos, desde reducir el tamaño del archivo hasta establecer reglas por ruta, pasar los requisitos obligatorios a hooks y verificar qué es lo que realmente carga Claude.
Si comienzas con un archivo en blanco, la guía práctica para escribir un CLAUDED.md efectivo aborda el contenido y la estructura. El enfoque aquí es diferente: qué instrucciones deben incluirse en CLAUDED.md y dónde debe ir el resto.
CLAUDED.md es contexto, no configuración
Todos los demás problemas se deben a este concepto erróneo. Claude Code inserta el archivo en la conversación como un mensaje; no se fusiona con el prompt del sistema, y nada en el entorno de ejecución lo hace obligatorio. El modelo lo lee e intenta cumplirlo. No hay ninguna garantía más allá de eso, y las posibilidades disminuyen aún más cuando la redacción es vaga o dos instrucciones apuntan en direcciones diferentes.
Un modelo mental útil es un memorando de transferencia para un compañero competente que lo revisa mientras toma su café por la mañana y luego se dedica al trabajo real. Lo que sobrevive a ese proceso es el material que era breve, específico y coherente. Por eso, la longitud, la precisión y la consistencia interna son las únicas herramientas reales de las que dispones, no cuestiones de estilo.
Mantén el archivo principal por debajo de 200 líneas
La guía actual es mantenerlo aproximadamente por debajo de 200 líneas. Más allá de ese número, el archivo ocupa más espacio en la ventana de contexto y la adherencia al contenido empeora en lugar de mejorar.
Esto es contraintuitivo: cuantas más instrucciones hay, menos se siguen. Cada línea compite por la misma atención limitada que todas las demás líneas y que la conversación en sí. Considere un equipo cuyo archivo llegó a tener 340 líneas. Al reducirlo a unas 120, Claude lo siguió de manera más fiable. Ninguna de las líneas eliminadas estaba equivocada; simplemente eran ruido añadido sobre las instrucciones que realmente importaban.
También existe un techo máximo, aunque no querrá diseñar su sistema teniéndolo en cuenta: según la documentación al momento de escribir esto, los archivos mayores a 4 MiB se ignoran por completo. La capacidad de seguir las instrucciones disminuye mucho antes de que un archivo se acerque siquiera a ese tamaño.
Elimine lo que Claude pueda descubrir en el repositorio
La regla de edición más efectiva es sencilla: eliminar todo aquello que Claude pueda deducir al leer el código. Esto coincide con los tipos de eliminaciones que sugiere la propia herramienta /doctor de Claude Code, la cual elimina la estructura de carpetas, las listas de dependencias y las descripciones de arquitectura a alto nivel, manteniendo sin embargo los problemas, la justificación y las convenciones que se desvían de los valores predeterminados de la herramienta. En otras palabras, invierte el contenido habitual de estos archivos.
Elementos a eliminar:
- La estructura de carpetas, ya que Claude puede listar los directorios por sí mismo.
- La lista de dependencias, que ya está registrada en
package.json. - Una descripción narrativa de la arquitectura, ya que el código la expresa con mayor precisión.
Elementos a conservar:
- Código que parece un error pero es intencional.
- La razón por la cual se rechazó el enfoque obvio.
Una buena prueba: si un ingeniero competente con el repositorio abierto podría aprenderlo en diez minutos, órgániceselo. Si solo lo descubriría al romper algo, escríbalo.
Deje notas para los humanos sin costo alguno
Los comentarios a nivel de bloque en HTML se eliminan antes de que el contenido del archivo llegue al contexto de Claude. Eso le permite anotar el archivo para quienes lo mantienen sin gastar nada del presupuesto del modelo, por ejemplo, para indicar por qué se movió una sección:
<!-- Deleted the API section — moved to .claude/rules/api.md, Sep 2026 -->
Sus compañeros de equipo ven el historial; el modelo nunca paga por ello.
@imports organiza el archivo pero no guarda contexto
Cuando un CLAUDE.md se vuelve largo, la reacción habitual es dividirlo en varios documentos e importarlos:
@docs/architecture.md
@docs/api-conventions.md
@docs/testing.md
Parece carga perezosa, pero no lo es. Los archivos importados se expanden y se cargan en el contexto al iniciar, junto con el CLAUDE.md que los hace referencia. Aunque se dividan 340 líneas en cuatro archivos separados, se siguen cargando las mismas 340 líneas.
Los importaciones sí tienen usos legítimos. Ayudan a la organización y permiten compartir un único conjunto canónico de instrucciones entre herramientas. Si un repositorio ya cuenta con un AGENTS.md, una sola línea @AGENTS.md en CLAUDE.md evita mantener dos copias diferentes. Simplemente no espere que reduzcan el uso de contexto. Para instrucciones que solo deben cargarse en ocasiones específicas, se necesitan reglas con alcance basado en rutas.
Aplique reglas condicionales con .claude/rules y rutas
Los archivos en .claude/rules/ pueden declarar un campo paths en su frontmatter. Esta es la característica que cumple con las expectativas de los usuarios respecto a las importaciones: una regla de ámbito global permanece fuera de contexto hasta que Claude lee o edita el archivo correspondiente. El frontmatter de un archivo de reglas de API podría verse así:
---
paths:
- "src/api/**/*.ts"
---
A continuación del frontmatter, el cuerpo de la regla contiene las convenciones que solo son aplicables a esa parte del árbol, como la validación de entrada, el formato común para los errores y los lugares donde se permite usar SQL:
# API rules- Every endpoint validates input before touching the database
- Errors use the standard envelope in `src/api/errors.ts`
- No direct SQL outside `src/api/repositories/`
El resultado es que el trabajo en la interfaz de usuario deja de incurrir en los costos por tokens relacionados con las convenciones de API, y el trabajo relacionado con la API deja de incurrir en costos por las convenciones de pruebas.
En la práctica, esta es la solución para un CLAUDE.md demasiado extenso. Divida el contenido por temas, asocie cada tema a los directorios que rigen y reserve el archivo raíz para las indicaciones universales del proyecto. Un archivo de reglas sin el campo paths se carga en cada sesión, así que considérelo una elección deliberada y no la opción predeterminada.
Los globos admiten la expansión con llaves, por lo que una sola regla puede cubrir varias extensiones y un patrón de prueba separado:
---
paths:
- "src/**/*.{ts,tsx}"
- "tests/**/*.test.ts"
---
Los pasos obligatorios deben ir en hooks
Líneas como “lint antes de cada commit”, “no subir directamente a main” o “formatear cada archivo después de editar” son comunes en CLAUDE.md. Se respetan en la mayoría de los casos, las excepciones se detectan y los equipos deciden que el modelo no es fiable.
Pero ese es el comportamiento documentado: CLAUDE.md influye en lo que hace Claude sin garantizarlo. Para una acción que debe realizarse en un momento específico del ciclo de vida de la sesión, un gancho ejecuta una orden de shell en ese instante, independientemente del juicio del modelo. Un gancho PreToolUse incluso puede vetar por completo una llamada a una herramienta, algo que el Markdown en negrita o con mayúsculas no puede lograr.
Una forma práctica de enrutar cada tipo de instrucción:
- Una convención que Claude debería seguir en general se incluye en CLAUDE.md.
- Una regla para un área específica del código se coloca en
.claude/rules/junto con lospaths. - Un requisito que no admite excepciones se convierte en un gancho.
- Un procedimiento repetible de múltiples pasos se convierte en una habilidad.
Mover un puñado de reglas “siempre” a hooks tiene una doble ventaja: ahora se aplican realmente los requisitos, y el archivo pierde líneas que nunca podrían funcionar, lo que permite dedicar más atención a las instrucciones que sí pueden hacerlo.
Verificar qué se cargó realmente
Ejecuta /context e inspecciona su sección de archivos de memoria, que refleja con exactitud lo que ha cargado la sesión en ejecución. /memory lo complementa al listar los archivos a nivel de usuario y de proyecto y permitiéndote abrirlos. Juntos convierten la pregunta “¿Está Claude ignorando esto?” de una conjetura en algo que se puede verificar. Es sorprendentemente fácil dedicar tiempo a pulir la redacción de un archivo que en realidad no se está cargando.
Contradicciones entre archivos concatenados
Nada se sobrescribe; todo se concatena. Partiendo del directorio de trabajo, Claude Code asciende hacia la raíz del sistema de archivos y recoge cada archivo CLAUDE.md en el camino, para luego ordenarlos desde la raíz hacia abajo. En cualquier nivel que también contenga un archivo CLAUDE.local.md, dicho archivo sigue al archivo CLAUDE.md que se encuentra en el mismo nivel. En un monorepo, dos archivos pueden ofrecer indicaciones opuestas fácilmente. Cuando esto ocurre, Claude puede simplemente elegir uno, y no habrá ninguna advertencia sobre el conflicto.
Archivos ancestrales que no solicitó
Si un archivo CLAUDE.md en un directorio padre se filtra en sus sesiones, la configuración claudeMdExcludes en sus ajustes locales permite excluir archivos mediante expresiones globales.
Qué sobrevive a la compactación
El archivo CLAUDE.md en la raíz del proyecto se vuelve a leer desde el disco e inserta nuevamente después de ejecutar /compact, por lo que sus instrucciones persisten. Todo lo que solo se dijo durante la conversación se pierde. Si sigue repitiendo la misma corrección después de cada compactación, eso es una señal clara de que pertenece al archivo.
Un plano inicial
Si tuviera que crear la configuración desde cero, un objetivo razonable sería el siguiente:
- Un archivo CLAUDE.md en la raíz con aproximadamente 120 líneas, que contenga únicamente lo que es válido en todas partes.
- Indicaciones condicionales ubicadas en
.claude/rules/, con patrones genéricos para los caminos. - Cada requisito “siempre” indispensable implementado como un gancho.
- Nada que alguien pueda aprender leyendo el repositorio en diez minutos.
- Una verificación rápida con
/contextdespués de cada cambio.
La referencia completa, incluyendo características como la memoria automática que merecen un tratamiento aparte, se encuentra en la documentación de memoria de Claude Code. El comportamiento y los límites evolucionan, así que revísela cuando algo no coincida con lo que esperas.
Puntos clave
- Escribe CLAUDE.md para un colega que lo leerá, no para una máquina que lo ejecutará: sea breve, específico y libre de contradicciones.
- Los archivos más cortos se siguen con mayor fiabilidad; elimina todo lo que la base de código ya le indique a Claude.
- Las importaciones reorganizan el contenido pero lo cargan completo; son las reglas de ámbito de ruta las que realmente posponen el carga.
- Cualquier acción que deba realizarse siempre necesita un gancho, ya que el contexto solo puede influir en el comportamiento.
- Trata
/contextcomo tu fuente de verdad antes de ajustar la redacción.
Lecturas relacionadas
- Un plan práctico para escribir un archivo CLAUDE.md efectivo — Aprenda 21 reglas concretas y verificables para reducir el tamaño de un archivo CLAUDE.md excesivo, de modo que Claude Code siga siendo fiable, predecible y digno de confianza durante sesiones prolongadas.
- Comparando los agentes de inteligencia artificial de Frontier: Astra, Flash, Fable y Mythos — Un análisis del rendimiento de las últimas versiones de los modelos GPT, Gemini y Claude en tareas reales de agencia como programación, navegación y uso de herramientas, más allá de simples pruebas de rendimiento.