CLAUDE.md, memoria y manejo del contexto

En el módulo 11 abriste la terminal, instalaste Claude Code y construiste algo. Si volviste al día siguiente, notaste algo incómodo: el agente no se acordaba de nada, ni de cómo se corre el proyecto ni de las reglas que le diste. No es un defecto de tu instalación: es el mismo principio del módulo 2, el empleado brillante que llega cada mañana sin memoria, ahora aplicado a un agente que edita archivos.

Este módulo lo resuelve en dos frentes: qué persiste entre sesiones y cómo escribir un archivo que le enseñe tu proyecto una sola vez, y cómo manejar la ventana de contexto en una sesión larga para que el agente no se pierda a mitad de la tarea. Al final tienes una plantilla, tres prompts y un ejercicio con el proyecto del módulo 11.

¿Por qué Claude Code empieza cada sesión desde cero?

La documentación de Claude Code lo dice en una línea: cada sesión empieza con una ventana de contexto vacía. Todo lo que el agente "sabe" en una sesión es lo que cargó al arrancar (sus instrucciones internas y los archivos de instrucciones que tú escribiste) más lo que va leyendo y haciendo. Cuando cierras la terminal, esa conversación queda guardada y puedes retomarla, pero una sesión nueva no hereda nada de ella.

A octubre de 2026, dos mecanismos llevan conocimiento de una sesión a la siguiente. El primero es el archivo CLAUDE.md: instrucciones que escribes tú y que Claude Code lee al inicio de cada sesión. El segundo es la memoria automática: notas que el propio agente escribe sobre tus correcciones y preferencias. El CLAUDE.md es la versión para constructores del documento de contexto del módulo 2: lo que le explicarías a un desarrollador nuevo en su primer día, escrito una sola vez.

¿Dónde vive el CLAUDE.md y cómo lo carga Claude Code?

Es un archivo de texto normal, en formato Markdown, y puede vivir en varios lugares con alcances distintos. Los tres que te interesan:

• Del proyecto: `CLAUDE.md` en la carpeta raíz del proyecto (o en `.claude/CLAUDE.md`). Es el que se comparte con el equipo a través del repositorio y el que escribes primero.
• Tuyo, para todos los proyectos: `~/.claude/CLAUDE.md`, en tu carpeta de usuario. Preferencias personales que aplican a todo lo que hagas: "respóndeme en español", "explica antes de borrar".
• Tuyo, solo para este proyecto: `CLAUDE.local.md`, junto al del proyecto. Notas privadas que no se suben al repositorio (hay que agregarlo a `.gitignore`, algo que vas a ver en el módulo 13).

Al arrancar, Claude Code carga el CLAUDE.md de la carpeta donde lo abriste y de las carpetas por encima; los de subcarpetas los carga solo cuando trabaja con un archivo de allí. Todos se concatenan, no se reemplazan: si tu archivo personal y el del proyecto se contradicen, el agente puede seguir cualquiera de los dos. Existen además una ubicación administrada para empresas y una carpeta `.claude/rules/` para repartir reglas largas en varios archivos; un proyecto pequeño no las necesita todavía.

Tres comandos que vas a usar desde hoy. `/init` analiza tu proyecto y escribe un primer borrador del CLAUDE.md; si ya existe uno, propone mejoras en vez de sobreescribirlo. `/memory` lista los archivos de memoria y te deja abrirlos en tu editor. `/context` muestra qué está ocupando la ventana de contexto; si tu CLAUDE.md no aparece ahí bajo "Memory files", el agente no lo está viendo.

¿Qué pongo en el CLAUDE.md y qué dejo por fuera?

La regla de Anthropic es brutalmente simple: por cada línea, pregúntate si quitarla haría que el agente cometiera errores. Si no, bórrala. Un CLAUDE.md largo no es más seguro: la documentación advierte que los archivos inflados hacen que Claude ignore las instrucciones que importan, y recomienda menos de 200 líneas. Lo que sí va:

• Cómo se corre, se construye y se prueba. Los comandos exactos, que el agente no puede adivinar leyendo el código.
• Convenciones que se apartan de lo normal. Estilo, idioma de los textos, cómo se nombran las cosas. Lo que cualquier programador haría por defecto no hace falta escribirlo.
• Qué no tocar. Archivos con claves, carpetas generadas, datos reales de clientes.
• Qué significa "terminado". Que las pruebas pasen, que se vea en los dos idiomas, que no haya rayas como puntuación: el criterio que tú aplicarías al revisar.
• Decisiones y trampas propias del proyecto. Por qué los precios viven en tal archivo, qué variable de entorno hace falta, el error que todos cometen la primera vez.

Lo que no va: documentación larga (enlaza a ella), lo que se deduce leyendo el código, descripciones archivo por archivo, consejos vacíos como "escribe código limpio" y lo que cambia cada semana. Una instrucción que solo aplica a una parte del proyecto, o un procedimiento de muchos pasos, va mejor en una skill, que se carga solo cuando hace falta (módulo 14).

Y la aclaración más importante del módulo: Claude Code trata el CLAUDE.md como contexto, no como configuración que se hace cumplir. El agente lo lee y trata de seguirlo, pero no hay garantía, sobre todo con instrucciones vagas o contradictorias. Escribe cosas verificables ("usa dos espacios de sangría", "corre `npm test` antes de dar por terminado") y no deseos ("prueba bien tus cambios"). Cuando algo debe cumplirse siempre, sin excepción, el mecanismo es otro: los hooks, que vas a ver en el módulo 14.

Plantilla para un proyecto pequeño

Siete secciones, cada una de dos a cinco líneas. Si el archivo completo no cabe en una pantalla, sobra algo.

1. 1Qué es esto. Dos líneas: qué hace el proyecto, para quién y con qué está hecho (lenguaje y herramientas principales).
2. 2Cómo correrlo. Los comandos para instalar, correr, construir y probar, uno por línea.
3. 3Dónde está cada cosa. Las tres o cuatro carpetas que importan, no el árbol completo.
4. 4Reglas de estilo. Solo las que se apartan de lo normal: idioma, formato, lo prohibido.
5. 5No tocar. Archivos y carpetas que el agente no edita sin preguntar.
6. 6Qué significa terminado. Pruebas que deben pasar, cómo verificar a mano, qué revisar antes de entregar.
7. 7Flujo de trabajo. Cómo se nombran los commits o las ramas, y antes de qué acciones se pide confirmación. Esta sección crece en el módulo 13.

Si te intimida escribirlo de cero, deja que el agente te entreviste: es la técnica que la documentación de Anthropic recomienda para especificar funciones grandes, aplicada al archivo que las gobierna todas.

Quiero escribir el CLAUDE.md de este proyecto. Antes de escribir nada, explora la carpeta para entender qué es y con qué está hecho, y luego entrevístame, una pregunta a la vez, sobre lo que no puedas deducir del código:

- Para quién es el proyecto y qué hace en una frase.
- Cómo se corre, se construye y se prueba (confirma los comandos que encontraste).
- Convenciones que se apartan de lo normal: idioma, estilo, formato, palabras prohibidas.
- Qué archivos o carpetas no debes tocar sin preguntar.
- Qué significa "terminado" para mí: qué pruebas deben pasar y qué reviso a mano.
- Trampas o errores que ya pasaron y no quiero repetir.

No preguntes lo obvio ni lo que ya viste en el código. Cuando tengas suficiente, escribe el CLAUDE.md en la raíz del proyecto: máximo [NÚMERO, por ejemplo 60] líneas, secciones con títulos cortos, instrucciones concretas y verificables, sin explicaciones largas. Al final dime qué dejaste por fuera a propósito y por qué.

Revisa el archivo CLAUDE.md de este proyecto como si fueras un desarrollador nuevo que lo lee por primera vez, y compáralo con lo que ves en el código. Entrégame tres listas:

1. QUÉ SOBRA: líneas que podrías deducir leyendo el código, consejos genéricos, documentación que debería ser un enlace, y cualquier cosa que haya cambiado y ya no sea cierta. Para cada una, di si la borrarías o la moverías a una skill.
2. QUÉ FALTA: lo que tuviste que adivinar o preguntar en sesiones anteriores y debería estar escrito: comandos, convenciones, archivos que no se tocan, criterio de terminado.
3. QUÉ SE CONTRADICE: instrucciones que chocan entre sí, o que chocan con lo que el código hace de verdad. Incluye contradicciones con [OTROS ARCHIVOS DE INSTRUCCIONES, SI LOS HAY: ~/.claude/CLAUDE.md, .claude/rules/, agentes].

Luego propón la versión corregida completa, de máximo [NÚMERO] líneas. No apliques el cambio hasta que yo lo apruebe.

¿Claude Code tiene memoria propia?

Sí, y conviene entender qué hace para no confundirla con el CLAUDE.md. A octubre de 2026, la memoria automática viene activada por defecto en sesiones locales. Mientras trabajas, el agente decide si algo vale la pena recordar y lo anota: tu rol y tus preferencias, las correcciones que le hiciste, decisiones del proyecto que no se deducen del código. Se salta lo que ya dice tu CLAUDE.md. Cuando ves "Saved 2 memories" en la pantalla, es eso.

Esas notas viven en tu computador, en una carpeta por proyecto dentro de `~/.claude/`, con un índice llamado `MEMORY.md` del que se cargan las primeras 200 líneas al inicio de cada sesión. No se comparten con tu equipo ni con otras máquinas. Puedes leerlas, editarlas o borrarlas, y apagar la función desde `/memory`. La diferencia práctica: si le dices al agente "recuerda que usamos pnpm", lo guarda en su memoria automática, solo tuya; si le dices "agrega esto al CLAUDE.md", queda en el archivo que ve todo el equipo. Las reglas del proyecto van al archivo; la memoria automática es para lo que aprende de ti.

¿Qué hago cuando la sesión se llena?

En el módulo 2 viste que las conversaciones largas se degradan. En Claude Code pasa más rápido, porque la ventana guarda cada archivo que el agente lee y cada salida de cada comando que corre: una sola sesión de depuración puede consumir decenas de miles de tokens. La guía de buenas prácticas de Anthropic lo pone como la restricción número uno: a medida que la ventana se llena, el agente empieza a "olvidar" instrucciones y a cometer más errores. Administrar ese espacio es ingeniería de contexto en su forma más concreta.

Las herramientas, con sus nombres exactos a octubre de 2026:

• `/context` muestra, como una cuadrícula de colores, qué está ocupando la ventana: instrucciones, archivos de memoria, herramientas, conversación.
• `/clear` empieza una conversación nueva con la ventana vacía. La anterior queda guardada y puedes volver a ella con `/resume`. Úsalo entre tareas que no tienen nada que ver.
• `/compact` reemplaza el historial por un resumen y libera espacio sin salir de la tarea. Puedes dirigirlo: `/compact concéntrate en los cambios de precios`. Claude Code lo hace solo cuando se acerca al límite, pero hacerlo tú antes de una tarea larga te deja escoger qué sobrevive.
• `/btw` hace una pregunta rápida sobre lo que está pasando sin que la pregunta ni la respuesta entren en el historial.
• `/rewind` (o Esc dos veces) vuelve a un punto anterior de la conversación o del código, o resume solo una parte.

Lo que sobrevive a una compactación, según la documentación: el CLAUDE.md y la memoria automática se recargan desde el disco, y el agente relee hasta cinco de los archivos que modificó más recientemente. Lo que el resumen no incluya, el agente ya no lo tiene. Por eso vale la pena poner en el CLAUDE.md una instrucción como "al compactar, conserva la lista de archivos modificados y los comandos de prueba".

Dos hábitos que la documentación recomienda. Uno: si corregiste al agente dos veces por lo mismo y sigue mal, haz `/clear` y escribe un prompt nuevo que incorpore lo que aprendiste; una sesión limpia con un buen prompt casi siempre le gana a una larga llena de intentos fallidos. Dos: no mezcles tareas en una sesión. Regla práctica: `/compact` cuando sigues en la misma tarea y solo necesitas espacio, `/clear` cuando cambias de tarea.

Para retomar lo que dejaste a medias no necesitas resúmenes: Claude Code guarda cada conversación en tu computador, ligada a la carpeta del proyecto. `claude --continue` reabre la más reciente de esa carpeta, `claude --resume` abre un selector y `/resume` cambia de conversación desde adentro; con `/rename` les pones nombre para encontrarlas después. El resumen escrito sigue siendo útil para pasar el trabajo a otra persona, a otra herramienta o a una sesión limpia sin arrastrar el ruido.

Esta sesión ya es larga y la voy a continuar en una nueva. Escribe un resumen para que otra sesión de Claude Code, sin ningún recuerdo de esta, pueda seguir exactamente donde vamos. En este orden:

1. OBJETIVO: qué estamos construyendo o arreglando, en dos líneas.
2. ARCHIVOS TOCADOS: cada archivo creado o modificado, con una línea sobre qué cambió y por qué.
3. DECISIONES: qué quedó definido, qué descartamos y por qué, para que no vuelva a proponerse.
4. ESTADO: qué funciona ya (y cómo lo verificamos), qué está a medias, qué falta.
5. COMANDOS: los comandos exactos que usamos para correr, probar y verificar.
6. SIGUIENTE PASO: lo primero que debería hacer la sesión nueva.
7. PARA EL CLAUDE.md: qué aprendimos en esta sesión que debería quedar permanente en el archivo, si algo.

Guárdalo en [NOMBRE, por ejemplo NOTAS-SESION.md] en la raíz del proyecto. No inventes nada que no esté en esta conversación; lo ambiguo márcalo como pendiente.

Y cuando responder una pregunta exige leer treinta archivos, hay una tercera vía: pedirle al agente que use un subagente, que investiga en su propia ventana de contexto y devuelve solo el resumen. Basta con decirlo: "usa un subagente para investigar cómo se calculan los precios". En el módulo 14 vas a definir los tuyos.

Para profundizar, el curso gratuito Claude Code in action de Anthropic Academy tiene una lección sobre escribir un CLAUDE.md que el agente de verdad siga y otra sobre dirigir sesiones largas. El siguiente módulo, "Planear, dar permisos y trabajar con Git", es donde el agente empieza a cambiar cosas reales con una red de seguridad debajo.