Qué es CLAUDE.md y cómo generarlo con /init

Hola, bienvenido. En la lección anterior cerramos la sección de configuración y permisos con el sandbox, y con esta lección empezamos la sección de memoria. Vamos a ver qué es CLAUDE.md, qué tipos de memoria tiene Claude Code y dónde vive cada uno, en qué momento se carga cada archivo, qué pasa cuando un repositorio trae un AGENTS.md y, para terminar, vamos a generar el primer CLAUDE.md de claude-tasks con /init y a comprobar con /context que Claude lo ha cargado.

¿Por qué ahora? Porque llevamos varias lecciones repitiendo lo mismo en cada prompt. En la lección del primer prompt le recordábamos a Claude que los comandos van con ./vendor/bin/sail, en la de prompts volvimos a escribirlo en las restricciones, y en la de ventana de contexto vimos que lo que le dices en la conversación se puede perder en una compactación. Además, en la lección de sesiones vimos que cada sesión nueva empieza con el contexto limpio. La documentación lo explica así: cada sesión de Claude Code empieza con una ventana de contexto nueva, y hay 2 mecanismos que llevan el conocimiento de una sesión a otra. El primero es CLAUDE.md, un archivo de instrucciones que escribes tú y que Claude lee al empezar cada sesión. El segundo es la auto memory, las notas que Claude escribe por su cuenta a partir de tus correcciones, que veremos al final de esta sección.

Antes de seguir, conviene tener clara una cosa desde el principio: Claude trata CLAUDE.md como contexto: lo lee e intenta seguirlo, y cuanto más concretas y breves son las instrucciones, con más constancia las sigue. Lo que no hace Claude Code es imponerlo, como sí impone las reglas de permisos. Por eso el deny del .env que pusimos en la sección anterior sigue haciendo falta aunque escribas en CLAUDE.md que no se lee, y por eso la documentación recomienda un hook PreToolUse cuando algo tiene que bloquearse decida lo que decida Claude.

CLAUDE.md es un archivo de markdown en texto plano, sin ningún formato obligatorio, y puede estar en varios sitios. Cada sitio tiene un ámbito distinto, igual que vimos con los archivos de configuración. Estos son, de más amplio a más concreto:

El de proyecto es el que vamos a escribir en claude-tasks, y va al repositorio como cualquier otro archivo. El local es para lo que no quieres compartir, como una URL de pruebas tuya, y la documentación te pide que lo añadas al .gitignore para que no acabe en un commit. En el curso no lo vamos a usar. Y el de usuario lo tienes siempre disponible para tus preferencias, como el idioma en que quieres las respuestas o tu forma de nombrar las ramas. Ninguno de ellos es sitio para secretos: son archivos de texto que se leen en cada sesión y que, en el caso del de proyecto, se comparten con todo el que clona el repositorio.

Claude Code carga al arrancar los CLAUDE.md y CLAUDE.local.md del directorio en el que lanzas claude y de todos los directorios por encima. Se concatenan en el contexto, desde la raíz del sistema de archivos hacia tu directorio de trabajo, y ninguno sustituye a otro, así que las instrucciones más cercanas a donde arrancaste se leen las últimas. Dentro de cada directorio, el CLAUDE.local.md va después del CLAUDE.md. Si 2 archivos se contradicen, la documentación avisa de que Claude puede elegir cualquiera de las 2 instrucciones, así que conviene revisarlos de vez en cuando y quitar lo que ya no aplica.

Los CLAUDE.md de subcarpetas funcionan distinto: se cargan cuando Claude lee con su herramienta Read un archivo de esa subcarpeta, así que al arrancar todavía no están y tampoco entran cuando Claude escribe o crea archivos ahí. Tenlo en cuenta porque es la misma idea sobre la que funcionan las rules por carpeta que veremos en la lección Rules en Claude Code: instrucciones por carpeta con .claude/rules.

Si juntamos las 2 formas de carga, el reparto entre lo que entra al arrancar y lo que entra bajo demanda queda así:

Un CLAUDE.md también puede importar otros archivos con la sintaxis @ruta. Los archivos importados se cargan al arrancar junto con el que los importa, las rutas relativas se resuelven desde el archivo que contiene el import y se admiten hasta 4 saltos de imports anidados. Si un CLAUDE.md de proyecto importa un archivo que está fuera del directorio de trabajo, la primera vez Claude Code te enseña un diálogo con los archivos para que los apruebes, porque ese import lo ha podido escribir cualquiera que tenga acceso al repositorio.