Qué Hace Realmente CLAUDE.md: Explicación de la Memoria Persistente del Proyecto
Cada vez que inicias una nueva conversación con Claude Code, este no sabe nada sobre tu proyecto, excepto lo que puede ver en los propios archivos.
No recuerda que ayer le pediste que usara siempre una biblioteca de pruebas particular, o que tu equipo nunca hace commits directamente a main.
CLAUDE.md existe para cerrar esa brecha.
Es un archivo markdown plano, incluido en tu repositorio, que Claude Code lee automáticamente para que las convenciones, la estructura y las reglas de tu proyecto persistan entre sesiones en lugar de evaporarse en el momento en que termina una conversación.
Resumen
- Idea Central: CLAUDE.md es un archivo de memoria del proyecto que proporciona a Claude Code conocimiento persistente de las convenciones, la estructura y las reglas de tu proyecto entre sesiones.
- Por Qué Importa: Sin él, cada sesión comienza desde cero y terminas repitiendo las mismas instrucciones en cada prompt.
- Conceptos Clave: memoria del proyecto, persistencia de sesión, convenciones vs. instrucciones, alcance anidado, el arranque
/init. - Cuándo Usar: Cualquier proyecto al que regreses más de una vez, cualquier repositorio de equipo con convenciones compartidas y cualquier base de código con reglas que un agente de codificación genérico no adivinaría por sí solo.
- Limitaciones / Compensaciones: CLAUDE.md es tan útil como lo que pongas en él: la guía vaga se pasa por alto, y un archivo obsoleto puede desorientar activamente a Claude Code si se desvía del código real.
- Temas Relacionados: arranque con
/init, escritura de reglas que realmente se siguen, herencia de alcance de CLAUDE.md anidado.
Fundamentos
En su forma más simple, CLAUDE.md es solo un archivo markdown llamado CLAUDE.md en la raíz de tu proyecto.
Claude Code lo busca automáticamente y carga su contenido como contexto antes de comenzar a trabajar en tu solicitud.
Piénsalo como el documento de incorporación del proyecto, excepto que el lector es un agente de codificación de IA en lugar de un nuevo empleado.
Una analogía útil es la primera semana de un nuevo ingeniero.
Un buen documento de incorporación le dice qué gestor de paquetes usar, dónde viven las pruebas y en qué patrones se ha estandarizado el equipo, para que no tenga que adivinar o preguntar en cada tarea.
CLAUDE.md desempeña el mismo papel para Claude Code, excepto que se vuelve a leer al inicio de cada sesión en lugar de leerse una vez y olvidarse a medias.
El archivo suele cubrir cosas como la pila tecnológica del proyecto, la estructura de carpetas, las convenciones de codificación, el enfoque de pruebas y cualquier regla estricta ("nunca edites archivos generados directamente", "siempre ejecuta el linter antes de terminar").
Un ejemplo mínimo podría verse así:
# Proyecto: Order Service
- Lenguaje: TypeScript, modo estricto.
- Las pruebas viven en `__tests__/`, reflejando la estructura de carpetas de origen.
- Nunca modifiques archivos bajo `generated/` - se reconstruyen con `npm run codegen`.
- Usa la utilidad `logger` existente en lugar de `console.log`.Nada de esto es exótico. Es la misma información que pondrías en un README para un humano, solo que dirigida a un agente que lo lee fresco cada vez.
Mecánica e Interacciones
La mecánica que hace que CLAUDE.md sea diferente de un prompt único es cuándo se lee.
Un prompt solo existe para la conversación en la que se escribió. CLAUDE.md se carga automáticamente al inicio de una nueva sesión, antes de que hayas escrito nada, que es lo que lo hace "persistente" en lugar de "recordado".
Claude Code no está reteniendo memoria entre sesiones de la manera en que lo haría un humano.
Cada nueva conversación sigue siendo una pizarra en blanco en términos de historial de chat anterior.
Lo que cambia es que la pizarra en blanco ahora incluye el contenido de CLAUDE.md como parte de su contexto inicial, por lo que el agente se comporta como si ya conociera las convenciones del proyecto.
Esto tiene algunas consecuencias prácticas que vale la pena interiorizar:
- El contenido de CLAUDE.md compite por espacio en la ventana de contexto junto con tus prompts, lecturas de archivos y salida de herramientas, por lo que no es gratis: un archivo inflado tiene un costo real.
- Dado que es un archivo normal en tu repositorio, se versiona, se puede comparar (diffable) y revisar a través del mismo proceso de pull-request que cualquier otro cambio.
- Se puede estructurar en capas: un CLAUDE.md raíz establece reglas generales para todo el proyecto, y los archivos CLAUDE.md anidados en subcarpetas agregan reglas más específicas que se aplican solo dentro de ese alcance.
- Es descriptivo, no aplicado: Claude Code lo sigue porque las instrucciones están en su contexto, no por alguna barrera técnica estricta que impida la desviación.
Ese último punto es importante. CLAUDE.md es una guía que el agente lee y razona, no un sistema de permisos.
Si una regla realmente nunca debe violarse, respáldala con algo aplicado fuera del modelo, como una verificación de CI o un hook de pre-commit, además de declararla en CLAUDE.md.
Consideraciones y Aplicaciones Avanzadas
A medida que un proyecto crece, CLAUDE.md tiende a crecer con él, y ese crecimiento necesita gestión activa en lugar de acumulación pasiva.
Un archivo que comienza como diez líneas enfocadas puede convertirse silenciosamente en doscientas líneas de historial parcialmente relevante si nadie lo poda.
Dado que CLAUDE.md consume presupuesto de contexto en cada sesión, un archivo excesivamente grande o mal organizado tiene un costo real: puede ocupar espacio para los archivos y la conversación reales que el agente necesita para razonar sobre tu tarea actual.
Es por eso que las reglas concretas y actuales superan a las exhaustivas: un archivo más corto con guía precisa y específica supera a un archivo largo relleno de generalidades o notas obsoletas.
Los equipos que trabajan en múltiples partes de una base de código grande a menudo pasan de un único CLAUDE.md raíz a una estructura anidada, donde una carpeta de backend y una carpeta de frontend llevan cada una su propio CLAUDE.md con reglas específicas para esa área, superpuestas al archivo raíz compartido.
Esto mantiene cada archivo enfocado y relevante para el trabajo que realmente se está realizando en ese subárbol, en lugar de obligar a cada sesión a cargar reglas para partes de la base de código que no está tocando.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| CLAUDE.md raíz único | Simple, un lugar donde buscar, fácil de mantener sincronizado | Puede volverse difícil de manejar en bases de código grandes y multidominio | Proyectos pequeños a medianos, repositorios de un solo equipo |
| Archivos CLAUDE.md anidados | Las reglas permanecen con alcance y relevantes para el subárbol que se está trabajando | Más archivos para mantener consistentes, requiere comprender la herencia de alcance | Monorepos grandes, proyectos multi-paquete |
| Sin CLAUDE.md | Cero mantenimiento | Cada sesión reexplica las convenciones desde cero, resultados inconsistentes | Scripts desechables, experimentos únicos |
CLAUDE.md también interactúa con la forma en que evoluciona una sesión con el tiempo. A medida que una conversación se alarga y su ventana de contexto se llena, herramientas como /compact y /clear entran en juego para gestionar ese presupuesto, pero CLAUDE.md se recarga fresco al inicio de cada nueva sesión independientemente, que es exactamente lo que lo convierte en un ancla duradera en lugar de algo que decae a medida que progresa una conversación.
Conceptos Erróneos Comunes
- "CLAUDE.md significa que Claude recuerda nuestras conversaciones pasadas." - No lo hace. Cada sesión sigue siendo independiente; CLAUDE.md solo asegura que la misma información de fondo esté presente cada vez, lo que produce un comportamiento similar a la memoria sin una recuperación real entre sesiones.
- "Más largo siempre es mejor." - Un CLAUDE.md inflado cuesta presupuesto de contexto en cada sesión y entierra las reglas importantes. Conciso y específico supera a lo exhaustivo.
- "Se aplica como un sistema de permisos." - CLAUDE.md es contexto que el agente lee y razona, no una barrera técnica estricta. Las reglas críticas aún necesitan aplicación fuera del modelo, como verificaciones de CI.
- "Un CLAUDE.md tiene que cubrir todo el código por igual." - Los archivos CLAUDE.md anidados permiten que diferentes partes de un proyecto grande lleven sus propias reglas con alcance superpuestas al archivo raíz.
- "Es documentación opcional, así que la precisión no importa mucho." - Un CLAUDE.md obsoleto o inexacto desorienta activamente al agente, ya que se confía en él como contexto actual del proyecto por defecto.
Preguntas Frecuentes
¿Qué nombre de archivo y ubicación busca realmente Claude Code?
Un archivo llamado CLAUDE.md, típicamente en la raíz del proyecto. Las versiones anidadas del mismo nombre de archivo también pueden vivir en subcarpetas para añadir reglas adicionales y más específicas.
¿CLAUDE.md reemplaza la escritura de buenos prompts?
No. Elimina la necesidad de repetir el contexto estable del proyecto (convenciones, estructura, reglas) en cada prompt, pero las instrucciones específicas de la tarea para lo que quieres que se haga ahora mismo todavía pertenecen al prompt en sí.
¿Se lee CLAUDE.md una vez por proyecto, o una vez por sesión?
Se carga al inicio de cada nueva sesión. No hay memoria de chat persistente entre sesiones; CLAUDE.md es lo que hace que el efecto se sienta persistente.
¿Qué tipo de contenido pertenece a CLAUDE.md?
- Pila tecnológica y dependencias clave
- Estructura de carpetas y dónde viven las cosas
- Convenciones de codificación y patrones de nomenclatura
- Enfoque de pruebas y cómo ejecutar pruebas
- Reglas estrictas ("nunca hagas X", "siempre haz Y antes de terminar")
¿Puede CLAUDE.md hacer que Claude Code haga algo objetivamente incorrecto si el archivo está desactualizado?
Sí. Dado que el agente trata CLAUDE.md como contexto confiable del proyecto, una regla obsoleta (que hace referencia a una biblioteca que eliminaste, una carpeta que se movió) puede dirigirlo hacia un comportamiento desactualizado o incorrecto. Trátalo como documentación viva que necesita mantenimiento.
¿Un archivo CLAUDE.md grande ralentiza a Claude Code?
Consume parte de la ventana de contexto en cada sesión, lo que deja menos espacio para lecturas de archivos y conversación antes de que la ventana se llene. No es "lento" en un sentido literal, pero es un costo de presupuesto real que vale la pena minimizar.
¿En qué se diferencia CLAUDE.md de un README regular?
Un README está escrito para contribuyentes humanos que navegan por el repositorio. CLAUDE.md está escrito para ser cargado automáticamente como contexto del agente en cada sesión; puede y a menudo se solapa con el contenido del README, pero su audiencia y mecanismo de entrega son diferentes.
¿Tengo que escribir CLAUDE.md a mano?
No. El comando de barra /init inicia un CLAUDE.md de inicio inspeccionando un repositorio nuevo, que luego editas y refinas para las necesidades reales de tu proyecto.
¿Qué sucede si un proyecto no tiene CLAUDE.md en absoluto?
Claude Code todavía funciona, pero cada sesión comienza desde lo que puede inferir de los archivos que lee; no hay memoria de proyecto permanente, por lo que las convenciones y reglas deben reiterarse o redescubrirse cada vez.
¿Puede CLAUDE.md entrar en conflicto con lo que pido en un prompt?
Puede hacerlo, en el sentido de que ambos son solo contexto que compite por la atención del agente. Una instrucción de prompt específica y explícita para la tarea actual generalmente tiene prioridad sobre las reglas generales del proyecto, pero la guía genuinamente contradictoria debe resolverse arreglando el archivo, no confiando en que el modelo adivine correctamente cada vez.
¿Es CLAUDE.md específico de un lenguaje de programación?
No. Es un archivo markdown plano que describe las convenciones del proyecto, por lo que se aplica por igual a cualquier lenguaje o pila; el contenido es lo que tu proyecto realmente necesita documentar.
¿Debería incluirse CLAUDE.md en el control de versiones?
Sí. Dado que reside en el repositorio como cualquier otro archivo, incluirlo significa que todo el equipo comparte la misma memoria del proyecto, y los cambios en él pasan por el mismo proceso de revisión que los cambios de código.
Relacionados
- Bootstrapping de un Nuevo Proyecto con /init - la forma más rápida de generar un CLAUDE.md inicial automáticamente.
- Escribir un Archivo CLAUDE.md Que Realmente Se Siga - cómo estructurar reglas para que Claude Code las obedezca realmente.
- Archivos CLAUDE.md Anidados y Cómo Funciona la Herencia de Alcance - superposición de memoria del proyecto en subcarpetas.
- Conceptos Básicos de Gestión de Contexto - el punto de partida para toda esta sección.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.