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.
//
Busca en todas las páginas de la documentación
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.
/init./init, escritura de reglas que realmente se siguen, herencia de alcance de CLAUDE.md anidado.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.
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:
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.
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.
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.
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 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.
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.
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.
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.
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.
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 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.
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.
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.
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.
Revisado por Chris St. John·Última actualización: 16 jul 2026