Los asistentes de programación con inteligencia artificial han evolucionado de meros generadores de fragmentos de código a colaboradores capaces de razonar sobre arquitecturas, respetar convenciones y aplicar políticas internas. Esa evolución, sin embargo, depende casi por completo de un factor: el contexto persistente que el modelo recibe al arrancar cada sesión. En el caso de Claude Code, el asistente de programación de Anthropic, ese contexto se canaliza principalmente a través de un archivo Markdown llamado CLAUDE.md y de una estructura de directorios que cualquier administrador de sistemas o desarrollador con experiencia reconocerá como una capa de configuración seria.
A primera vista, CLAUDE.md parece un simple archivo de documentación. En la práctica, funciona como un contrato de comportamiento entre el repositorio y el modelo, leído de forma automática al inicio de cada conversación, versionable con Git y revisable como cualquier otro artefacto técnico del proyecto.
Jerarquía de carga, alcance y precedencia
Claude Code no se limita a leer un único archivo. El sistema soporta varias capas que se combinan en un orden de prioridad concreto, de menor a mayor especificidad. La capa más alta corresponde a la política gestionada, ubicada en rutas del tipo /etc/claude-code/CLAUDE.md y reservada a administradores que quieren imponer reglas a todos los usuarios de una máquina. Por encima del usuario, pero por debajo del proyecto, vive la configuración global personal en ~/.claude/CLAUDE.md, pensada para preferencias estables del desarrollador como el idioma de respuesta, el estilo de commits o la manera de proponer cambios.
A nivel de repositorio, el archivo CLAUDE.md en la raíz se comparte con el equipo y se versiona, mientras que CLAUDE.local.md cumple la función de overrides personales y debe añadirse al .gitignore. Por debajo, los CLAUDE.md ubicados en subdirectorios se cargan bajo demanda cuando el modelo lee archivos dentro de esa ruta, lo que resulta especialmente útil en monorepos. Las instrucciones más cercanas al directorio de trabajo se evalúan al final del contexto, lo que les otorga mayor peso efectivo en el razonamiento del modelo.
El comando /memory permite consultar en caliente todos los archivos cargados durante la sesión activa. El comando /init realiza un análisis del repositorio y genera un CLAUDE.md inicial que conviene revisar y corregir, ya que el escaneo automático puede pasar por alto convenciones internas o asignar patrones arquitectónicos erróneos. Tras un /compact, el CLAUDE.md de la raíz se reinyecta automáticamente; los anidados en subdirectorios solo se recargan cuando el asistente vuelve a abrir un archivo de esa zona.
Reglas modulares, memoria automática y límites técnicos
Para proyectos grandes, mantener todo en un único archivo se vuelve inviable. La solución oficial son las reglas modulares en .claude/rules/*.md, que se cargan automáticamente y admiten frontmatter con el campo paths, donde se definen patrones glob. De esa manera, una regla del tipo «todos los endpoints deben validar la entrada con un esquema» solo se inyecta cuando el modelo trabaja sobre src/api/**/*.ts, evitando saturar el contexto en zonas del repositorio donde esa norma no aplica.
A esto se suma la memoria automática, disponible desde Claude Code 2.1.59. Activada por defecto, permite al modelo guardar de forma autónoma comandos de build, observaciones de depuración, convenciones detectadas en el código y otros aprendizajes que considere útiles para sesiones futuras. La memoria automática se almacena en ~/.claude/projects/<proyecto>/memory/ con un archivo MEMORY.md como índice y archivos temáticos cargados bajo demanda. Puede desactivarse con la variable de entorno CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 o gestionarse mediante el ajuste autoMemoryEnabled en settings.json.
Los límites técnicos también importan. La documentación oficial sitúa el máximo recomendado de un archivo de memoria en 40.000 caracteres y advierte que pasar de 200 líneas reduce la adherencia del modelo a las instrucciones, además de aumentar el coste en tokens. Los comentarios HTML a nivel de bloque (<!-- ... -->) se eliminan antes de inyectar el contenido, lo que permite dejar notas para mantenedores humanos sin ocupar contexto. En monorepos, el ajuste claudeMdExcludes permite ignorar archivos de equipos vecinos para que sus convenciones no contaminen el razonamiento del modelo. La bandera --add-dir y la variable CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 extienden el alcance a directorios externos al de trabajo, algo habitual cuando se comparte configuración entre repositorios.
Conviene recordar que el contenido de CLAUDE.md no se inyecta como parte del prompt de sistema, sino como un mensaje de usuario al inicio de la conversación. Eso significa que no es un mecanismo blindado: el modelo lo lee y procura seguirlo, pero las instrucciones vagas, contradictorias o redundantes degradan su cumplimiento. Las reglas explícitas, expresadas en forma de imperativos concretos —«todas las funciones deben incluir anotaciones de tipo», «las llamadas externas requieren tiempo de espera», «el acceso a base de datos pasa siempre por una clase repositorio»— funcionan mucho mejor que las máximas genéricas sobre código limpio.
Buenas prácticas operativas para equipos técnicos
La experiencia consolidada apunta a un patrón claro. La raíz del proyecto debe contener un CLAUDE.md breve y estable, entre 20 y 80 líneas para repositorios pequeños y rara vez más de 200 en proyectos grandes. Ese archivo actúa como índice y resumen arquitectónico, y todo lo que sea profundo, específico de una ruta o relevante solo en parte de la base de código se mueve a .claude/rules/ con frontmatter de scoping.
Las normas que cambian semanalmente no pertenecen al archivo, ya que los planes de ejecución, las listas de tareas o los TODOs envejecen mal y generan contradicciones. Ese tipo de información debería vivir en sistemas de tracking, en commands personalizados o en skills reutilizables. Lo que sí debe estar es aquello que un desarrollador o un administrador necesita repetir cada vez que entra alguien nuevo en el proyecto: stack tecnológico, comandos de build y test, gestor de paquetes preferido, requisitos de despliegue, particularidades del entorno de desarrollo y restricciones de seguridad.
Esa transparencia es precisamente lo que diferencia a CLAUDE.md de otras estrategias. Frente a archivos de configuración propietaria como .cursor/config.json o las plantillas integradas en plugins de IDE, CLAUDE.md vive en el repositorio, pasa por revisiones de pull request y deja huella en el historial de Git, lo que encaja con flujos de cumplimiento normativo y auditorías técnicas. En cierto modo, es a la IA lo que .editorconfig o .eslintrc son al formato y al linter: un mecanismo declarativo y compartido que sustituye al conocimiento tácito.
El beneficio cultural es probablemente el más infravalorado. Redactar un CLAUDE.md serio obliga al equipo a articular sus normas de forma explícita; si una convención solo existe en la cabeza del responsable técnico, escribirla la convierte en patrimonio del proyecto. Equipos de operaciones y desarrollo que invierten ese tiempo consiguen algo más valioso que velocidad bruta de generación: previsibilidad. Y en infraestructuras críticas o en bases de código longevas, la previsibilidad es la diferencia entre una herramienta útil y una fuente continua de incidencias.
Preguntas frecuentes
¿Cuál es el orden exacto de precedencia de los archivos CLAUDE.md en Claude Code? La documentación oficial define cinco niveles, de menor a mayor prioridad: política gestionada por administradores en /etc/claude-code/CLAUDE.md, configuración global del usuario en ~/.claude/CLAUDE.md, archivo CLAUDE.md del proyecto compartido en Git, CLAUDE.local.md con overrides personales no versionados y, finalmente, los CLAUDE.md anidados en subdirectorios, que se cargan bajo demanda. Las instrucciones más cercanas al directorio de trabajo se evalúan al final del contexto, lo que les otorga mayor peso efectivo.
¿Cómo se evita que un CLAUDE.md crezca demasiado y degrade el rendimiento del modelo? El máximo técnico recomendado es de 40.000 caracteres por archivo, pero la pérdida de adherencia empieza a notarse a partir de las 200 líneas. La estrategia habitual consiste en dejar en la raíz un archivo conciso de entre 20 y 80 líneas que actúe como índice arquitectónico y mover todo lo específico a .claude/rules/*.md con frontmatter paths que limite su carga a determinadas zonas del repositorio mediante patrones glob.
¿Qué diferencia hay entre la memoria automática de Claude Code y un CLAUDE.md escrito a mano? La memoria automática, disponible desde la versión 2.1.59, permite al modelo registrar por su cuenta comandos de build, observaciones de depuración o convenciones detectadas durante la sesión. Se almacena en ~/.claude/projects/<proyecto>/memory/ y se carga al iniciar cada sesión. El CLAUDE.md, en cambio, contiene reglas explícitas redactadas por el equipo y versionadas con el código. Ambos sistemas son complementarios: la memoria automática funciona como cuaderno de bitácora interno, mientras que CLAUDE.md actúa como contrato formal del proyecto.
¿Es seguro confiar políticas críticas a CLAUDE.md o conviene reforzarlas con otros mecanismos? El contenido de CLAUDE.md se inyecta como mensaje de usuario, no como prompt de sistema, y por tanto el modelo intenta seguirlo pero no lo cumple de forma estricta. Para reglas críticas de seguridad o cumplimiento, conviene reforzarlas con claudeMdExcludes para evitar contaminación cruzada, hooks que validen los cambios antes de aplicarlos, herramientas de linting y CI/CD, y políticas gestionadas en /etc/claude-code/ que no puedan ser sobrescritas por configuraciones locales. CLAUDE.md guía el comportamiento, pero las defensas finales deben estar en el sistema, no en la capa de razonamiento del modelo.
