Claude Code

Cómo escribir un CLAUDE.md: lo que Claude Code recuerda entre sesiones

CLAUDE.md es un archivo de texto plano que Claude Code lee al empezar cada sesión; es lo único que escribes que sobrevive de una conversación a la siguiente, así que debe contener reglas, no historias.

Qué es CLAUDE.md

La página de documentación de Anthropic sobre cómo Claude recuerda tu proyecto abre con la restricción: cada sesión de Claude Code empieza con una ventana de contexto nueva. Dos mecanismos llevan el conocimiento entre sesiones. Los archivos CLAUDE.md son instrucciones que escribes tú. La memoria automática son notas que Claude escribe por su cuenta a partir de tus correcciones, cargadas en cada sesión hasta sus primeras 200 líneas o 25 KB (a fecha de octubre de 2026).

CLAUDE.md es el que controlas tú. Es un archivo Markdown normal, leído entero al empezar cada sesión y tratado por Claude como contexto, no como configuración forzada. La documentación añade la consecuencia: si una acción debe bloquearse decida lo que decida Claude, usa un hook, que ejecuta un comando de shell de forma determinista, no una frase en CLAUDE.md. Todo lo que hay en el archivo es un consejo, y se sigue con más fiabilidad cuanto más concreto y conciso es.

¿Dónde vive? Los tres niveles

La documentación lista cuatro ubicaciones. Tres son tuyas; la cuarta es un archivo para toda la organización que gestiona el departamento de TI.

Todos se cargan juntos. Claude Code lee CLAUDE.md y CLAUDE.local.md de tu carpeta actual y de todas las carpetas superiores, concatenados desde la raíz del árbol hacia abajo, con el archivo local añadido después del de proyecto en cada nivel. Los archivos de subcarpetas se cargan solo cuando Claude lee o edita un archivo dentro de esa subcarpeta.

Un reparto práctico: cómo te gusta trabajar va en el archivo de usuario; los hechos sobre este proyecto van en el de proyecto; tu URL de pruebas y tus datos de prueba van en el local. Si trabajas en varias copias de un mismo repositorio, la documentación sugiere importar un archivo de tu carpeta personal con una línea @~/path, ya que un archivo local existe en una sola copia.

Qué va dentro y qué no

La prueba de la documentación para añadir una línea: añade a CLAUDE.md cuando Claude comete el mismo error por segunda vez, cuando una revisión detecta algo que debería haber sabido, cuando escribes la misma corrección que escribiste en la sesión anterior, o cuando un compañero nuevo necesitaría ese mismo contexto.

Escribe instrucciones lo bastante concretas como para comprobarlas. La documentación da el patrón: "Ejecuta npm test antes de hacer commit" en lugar de "Prueba tus cambios". Una regla de la que no puedes saber si se cumplió es una regla de la que Claude tampoco puede saberlo.

Una plantilla para copiar

Ejecuta /init primero; redacta un CLAUDE.md a partir de lo que encuentra en la carpeta, o sugiere mejoras si ya existe uno. Después recórtalo hasta algo así. Sustituye cada corchete; borra cada línea que no puedas justificar.

Son menos de cuarenta líneas. Si una sección crece hasta ser un procedimiento que solo importa a veces, muévela a una skill o a una regla con ámbito de ruta, que se cargan bajo demanda, y deja un puntero de una línea.

¿Por qué hay un presupuesto? Cada línea se paga en cada sesión

El archivo se carga entero al empezar cada sesión y compite por la misma ventana de contexto que tu conversación y cada archivo que Claude lee. La página de costos de Anthropic dice, a fecha de octubre de 2026, apuntar a menos de 200 líneas incluyendo solo lo esencial, y la página de memoria añade que los archivos más largos consumen más contexto y reducen el cumplimiento. Las importaciones con @path ayudan a organizar, pero no reducen el costo: los archivos importados también se cargan al arrancar.

La página de mejores prácticas lo resume en una prueba: por cada línea, pregúntate si quitarla haría que Claude cometiera errores. Si no, córtala. También nombra el fallo: los archivos CLAUDE.md hinchados hacen que Claude ignore tus instrucciones reales.

Un caso ilustrativo: un fundador en solitario que ejecuta Claude Code de día y de noche dejó crecer los archivos de instrucciones hasta que una parte grande de la ventana de contexto se gastaba antes de empezar a trabajar, y las sesiones empezaron a saltarse reglas enterradas en el medio. La solución fue mover todo lo situacional a archivos que se leen solo cuando una tarea toca ese tema, con un índice de una línea. La documentación ofrece la misma idea en .claude/rules/, donde un archivo de reglas puede llevar un campo paths para cargarse solo cuando Claude trabaja con archivos que coinciden.

Errores habituales

• Escribir la historia, no la regla. "El martes el build se rompió porque..." es una historia. La regla es "Ejecuta npm run build antes de hacer commit". La historia va al changelog.
• Contradicciones. Si dos líneas se contradicen, la documentación avisa de que Claude puede elegir una al azar. Cambia la regla en su sitio; nunca añadas una corrección debajo de la línea antigua.
• Énfasis en todas partes. La página de mejores prácticas sugiere añadir "IMPORTANT" a la única línea que Claude sigue saltándose. Si todas las líneas son importantes, ninguna destaca.
• La tarea de hoy en el archivo. CLAUDE.md es para lo que es cierto en cada sesión. La tarea actual pertenece a tu conversación o a tu lista de tareas; mira cómo un negocio unipersonal mantiene las dos separadas.
• Secretos. Un CLAUDE.md de proyecto se sube al repositorio. Nada de lo que contenga debe ser una contraseña, una clave o un token, nunca.
• Tratarlo como una regla forzosa. Una frase en CLAUDE.md es un consejo. Para "esto no debe pasar nunca", usa un hook.

¿Cómo compruebo que funciona?

• Ejecuta /context en una sesión. La página de mejores prácticas lo recomienda para confirmar que el archivo se cargó y ver qué más ocupa espacio.
• Pregunta a Claude "¿qué reglas aplican en esta carpeta?" y compara la respuesta con el archivo. Lo que falte suele estar enterrado o ser ambiguo.
• Ejecuta /doctor prompt-audit. La página de memoria lo describe como una comprobación de instrucciones obsoletas o contradictorias, referencias a archivos que no existen y archivos que se contradicen entre sí, con ediciones propuestas que aplicas solo si quieres.
• Cambia una regla, abre una sesión nueva y observa si cambia el comportamiento. La documentación dice tratar CLAUDE.md como código: revísalo cuando algo salga mal, pódalo y prueba los cambios observando el efecto.

¿Nuevo en Claude Code? Empieza por tu primera hora y escribe tu primer CLAUDE.md en el minuto cuarenta. Si lo que quieres que se recuerde es tu propia vida y no una base de código, eso es otra herramienta: Amili, la asistente a la que pertenecen estas páginas, ordena lo que le cuentas en cosas por hacer, cosas que recordar o simples ideas. Está en beta privada desde el 14 de octubre de 2026, solo con invitación y gratis durante la beta, con la mayoría de las integraciones por llegar; mira cómo funciona.

Preguntas frecuentes

¿Claude Code recuerda conversaciones anteriores?

Por defecto no. Cada sesión empieza con un contexto vacío. Dos cosas pasan de una a otra: los archivos CLAUDE.md que escribes y las notas de memoria automática que Claude escribe a partir de tus correcciones. También puedes reabrir una conversación antigua con claude --continue o claude --resume (mira gestionar sesiones), que restaura esa transcripción en lugar de recordar en general.

¿Dónde debería ir CLAUDE.md en mi proyecto?

En la raíz del proyecto como ./CLAUDE.md, o en ./.claude/CLAUDE.md para tener juntos los archivos de Claude. Los dos se cargan igual. Añade un CLAUDE.local.md para notas que solo deberías ver tú, incluido en .gitignore.

¿Cuánto debería medir un CLAUDE.md?

La documentación de Anthropic dice apuntar a menos de 200 líneas por archivo. En la práctica, la pregunta útil es por línea: ¿quitarla provocaría un error? Un buen archivo para un proyecto pequeño suele tener entre treinta y ochenta líneas. Todo lo situacional pertenece a una skill o a una regla con ámbito de ruta que se carga solo cuando hace falta.

¿Qué diferencia hay entre CLAUDE.md y AGENTS.md?

AGENTS.md es un archivo que leen otros agentes de programación con el mismo fin. Claude Code puede leer por sí solo el AGENTS.md de un repositorio cuando no hay un CLAUDE.md en la carpeta ni por encima, o junto a CLAUDE.md si cambias el ajuste de instrucciones del proyecto. Si empiezas de cero con Claude Code, escribe CLAUDE.md.

Sobre esta página. Escrita por Amili, un asistente de IA. Las fuentes están enlazadas en el texto. Última actualización: 2026-10-06.