Memoria de Claude Code: /init, CLAUDE.md y el atajo #, ilustrado
Claude Code olvida cada sesión a menos que le des memoria. Este recorrido corre /init en un proyecto real de Next.js, lee la CLAUDE.md que genera, agrega una regla desde el chat con el atajo # y verifica que Claude de verdad la siga — cada paso chequeado con capturas.
TL;DR — la memoria de Claude Code en cuatro líneas
- Corre /init una vez por proyecto: Claude escanea el repo — estructura de carpetas, scripts, manejo de estado — y escribe una CLAUDE.md estructurada en la raíz.
- Ese archivo entra al contexto de cada sesión automáticamente, así que lo que escribas ahí moldea toda la generación de código futura.
- Escribe # más una regla en el chat para memorizarla al instante, y luego elige dónde vive: memoria de proyecto (commiteada), memoria local del proyecto o memoria de usuario (~/.claude/CLAUDE.md).
- Mantén el archivo al día cuando cambie tu estructura o stack — la memoria vieja desvía a Claude — y reabre cualquier archivo de memoria con /memory.
Claude Code Tutorial #2 - CLAUDE.md Files & /init
Canal:Net Ninja12:18
The CLAUDE.md file
Canal:Claude (official Anthropic channel)3:01
Claude Code's Memory System: The Full Guide
Canal:DIY Smart Code5:05
Manage Claude's memory — Claude Code documentation
Docs:code.claude.com
Los cuadros vienen de la lección de CLAUDE.md de Net Ninja (una grabación limpia de VS Code); el texto del recorrido se escribió de forma independiente y se contrastó con la documentación de memoria de Anthropic y el video oficial de CLAUDE.md.
Las capturas siguen siendo propiedad de sus creadores y se usan con atribución como documentación visual. Cada paso enlaza directo al momento exacto del video original.
De cero memoria a un proyecto que Claude conoce
1 · Genera CLAUDE.md con /init
- 1
Empieza con /init
Cuando metas Claude Code por primera vez a un proyecto, corre /init antes de pedir cualquier código. El tooltip dice exactamente qué hace: inicializar un archivo CLAUDE.md nuevo con documentación del codebase. Claude va a leer tu proyecto ahora para que las sesiones futuras no tengan que hacerlo.
/init — el único comando que corres antes que nada en un repo nuevo.Ver en 0:30 - 2
Mira a Claude explorar antes de escribir
En vez de adivinar, /init arma su propia lista de todos: explorar la estructura del repo, analizar package.json y el código fuente, revisar si hay documentación existente, y luego crear CLAUDE.md con los hallazgos. Ves cada ítem marcarse en tiempo real — el archivo es un resumen de lo que realmente se leyó, no una plantilla.
La lista de Update Todos durante la inicialización — explorar, analizar, luego escribir.Ver en 1:42 - 3
Lee el header de guías y los comandos que escribió
El archivo generado abre con un header de guías para Claude Code, seguido de Development Commands sacados directo de package.json — dev, build, lint, start. Esta es la sección que evita que Claude se invente su propio workflow: los scripts reales ya están en su contexto.
La apertura del archivo: guías para Claude Code más los scripts npm reales del proyecto.Ver en 2:56 - 4
Revisa las secciones de arquitectura y estructura
Más abajo el archivo documenta el overview de arquitectura (este proyecto: un blog en Next.js 15 con React 19 y Tailwind), un mapa de Project Structure que muestra dónde van los archivos nuevos, y notas de Data Persistence para la capa de Hygraph CMS. Las sesiones nuevas heredan todo eso sin releer tu repo.
Project Structure con rutas seleccionadas, más la nota de persistencia de datos de Hygraph.Ver en 2:30
2 · Agrega memorias y demuestra que pegan
- 5
Demuestra que la memoria cambia el comportamiento
La prueba: después de agregar “todos los hooks reutilizables van dentro de esta carpeta hooks” al archivo, el prompt pide un hook de preferencia de tema — y dice explícitamente que no lo use en ningún lado todavía. El todo de Claude muestra que lo crea en src/hooks/use-theme, y cierra con “el hook está listo para usarse pero no se ha integrado en ningún lado, como pediste”. Memoria entra, comportamiento sale.
El hook cae en la carpeta que nombró el archivo de memoria — y respeta el “no lo conectes aún”.Ver en 6:40 - 6
Memoriza una regla nueva con # desde el chat
No tienes que editar el archivo a mano. Empieza un mensaje con # — por ejemplo “# al crear componentes de página nuevos, agrega siempre un link a esa página en el header” — y Claude Code lo reconoce como memoria para guardar, y luego pregunta dónde va: memoria de proyecto, memoria local del proyecto o memoria de usuario.
El atajo # y el selector de tres destinos que abre.Ver en 7:30 - 7
Conoce los cuatro tipos de memoria
La tabla de documentación de Anthropic es el mapa: memoria de política empresarial para organizaciones, memoria de proyecto (./CLAUDE.md, commiteada y compartida con el equipo), memoria de usuario (~/.claude/CLAUDE.md, tus preferencias globales personales) y memoria local del proyecto (./CLAUDE.local.md, personal y sin trackear) — que la documentación marca como deprecada a favor de importar archivos sin trackear desde la memoria de proyecto, aunque la opción sigue apareciendo en el selector.
La tabla oficial de tipos de memoria: ubicación, propósito y quién comparte cada archivo.Ver en 10:50 - 8
Confirma que la regla quedó en el archivo
Elegir memoria de proyecto agrega la regla a la CLAUDE.md del proyecto, y ahí está al final del archivo: “al crear componentes de página nuevos, agrega siempre un link a esa página en el header”. Desde la siguiente sesión, esta línea viaja en el contexto automáticamente.
La regla nueva, guardada al final de la CLAUDE.md commiteada.Ver en 11:48
3 · Administra los archivos de memoria en el día a día
- 9
Verifica la memoria en una tarea fresca
Ahora pide una página About y mira el plan: “voy a crear una página About nueva y agregarle un link en el header según tu instrucción de memoria”, con “Add About page link to header navigation” como todo propio. La regla de # de dos pasos atrás está dirigiendo una tarea donde nunca se repitió. (Advertencia justa del video: Claude puede agregarte links a páginas que no mencionaste — scope creep que domas con una línea en el mismo archivo.)
“…según tu instrucción de memoria” — la lista de todos prueba que la regla está activa.Ver en 9:37 - 10
Reabre cualquier archivo de memoria con /memory
El comando /memory lista cada archivo de memoria con su ubicación: memoria de proyecto commiteada en ./.CLAUDE.md, memoria local en .gitignore en ./.CLAUDE.local.md, y tu archivo global de usuario en ~/.claude/CLAUDE.md. Elige uno y se abre en tu editor — 11 memorias contadas en el archivo de este proyecto.
Elige la memoria a editar — los tres scopes, un solo selector.Ver en 11:22 - 11
Edítala como cualquier otro archivo
Claude Code confirma “Opened project memory at ./.CLAUDE.md” y la abre en VS Code, con un tip: setea la variable de entorno $EDITOR o $VISUAL para elegir otro editor. De /init al mantenimiento diario, la memoria es solo un archivo markdown que mantienes honesto.
“Opened project memory at ./.CLAUDE.md” — edítala y mantenla al día.Ver en 12:06
Las capas de memoria y dónde vive cada archivo
Cuatro archivos, cuatro scopes — elige el correcto y la memoria de Claude Code deja de ser adivinanza:
- 1Memoria de proyecto — ./CLAUDE.md en la raíz del repo. Trackeada en git, compartida con cada dev del proyecto. Mantenla sobre el proyecto: estructura, convenciones, comandos, frameworks.
- 2Memoria local del proyecto — ./CLAUDE.local.md. Notas personales para este repo (tus herramientas, tus atajos) que quedan sin trackear. Deprecada según la documentación — el patrón recomendado es importar archivos sin trackear desde la memoria de proyecto — pero al momento de la grabación la opción seguía apareciendo en el selector de #.
- 3Memoria de usuario — ~/.claude/CLAUDE.md en tu home. Tus preferencias globales a través de todos los proyectos de la máquina: estilo de código, idioma de respuesta, workflows personales.
- 4Más allá de CLAUDE.md — builds recientes de Claude Code agregan un sistema de memoria automática (MEMORY.md y archivos de tema bajo ~/.claude/projects/) que Claude mantiene por su cuenta, separado del archivo de instrucciones, más @ imports para traer otros docs al contexto. Desactívalo con CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 si solo quieres archivos de instrucciones.
Sea cual sea la capa que uses, el hábito del video es el mismo: la memoria no es crear-y-olvidar. Cuando cambien tu estructura, paquetes o convenciones, actualiza el archivo — la memoria vieja es peor que ninguna, porque Claude la sigue con toda la confianza.