Al usar Claude Code en un proyecto, suelen surgir dos necesidades: «Esta regla debe cumplirse siempre» y «Recuerda lo que descubrimos la última vez».
La primera la gestiona el archivo de reglas CLAUDE.md y la segunda, la función de memoria. Ambas son «instrucciones que permanecen después de terminar una sesión», por lo que se confunden fácilmente, pero difieren en quién las gestiona y en su naturaleza.
Este artículo resume la jerarquía de CLAUDE.md, el funcionamiento de la memoria y los criterios para decidir qué contenido debe ir en cada lugar.
Empecemos por el resumen clave.
- CLAUDE.md es un archivo de reglas que se carga automáticamente en cada sesión y se organiza por ámbitos globales y de proyecto.
- La memoria permite que Claude registre y recupere por sí mismo hechos aprendidos durante el trabajo en carpetas específicas de cada proyecto.
- Las reglas definidas por las personas van en CLAUDE.md; la experiencia acumulada por el agente, en la memoria.
- Ambos consumen contexto, así que deben mantenerse ligeros según si la información es «siempre necesaria».
CLAUDE.md: la ubicación define el ámbito de aplicación
CLAUDE.md es un archivo Markdown que se carga completo en el prompt al iniciar la sesión. Contiene reglas que «siempre deben cumplirse», como convenciones de código, prohibiciones y contexto del proyecto.
Incluso los archivos con el mismo nombre tienen un ámbito distinto según su ubicación.
| Ubicación | Ámbito | Compartición |
|---|---|---|
| ~/.claude/CLAUDE.md | Todos los proyectos | Solo personal |
| project/CLAUDE.md | Ese proyecto | Compartido con el equipo mediante Git |
| subfolder/CLAUDE.md | Al trabajar en esa carpeta | Compartido con el equipo mediante Git |
En el archivo global se colocan preferencias personales ajenas al proyecto, como el estilo de commits o el idioma de respuesta; en el archivo del proyecto, las reglas propias del repositorio. Si los ámbitos entran en conflicto, lo más seguro suele ser indicar que prevalece el más específico: la regla del proyecto.
Si el archivo se alarga, puedes dividirlo importando otros documentos con el formato @경로/파일.md. Sin embargo, esos documentos también entran en el contexto, así que es una función para facilitar la gestión, no para ahorrar contenido.
Memoria: notas que escribe el agente
Si CLAUDE.md son reglas descendentes escritas por personas, la memoria funciona en la dirección opuesta. Claude registra como archivos los hechos que descubre durante el trabajo en una carpeta de memoria específica del proyecto y los recupera en sesiones posteriores.
La estructura es sencilla: cada memoria es un archivo y en el índice MEMORY.md se acumula un resumen de una línea. Al iniciar la sesión solo entra el índice en el contexto; el contenido de cada memoria se lee cuando se realiza una tarea relacionada.
La naturaleza de lo que se registra también difiere de la de las reglas. Son hechos que solo se conocen al experimentarlos, como «esta DB necesita comprobación de tipos después del procesamiento por lotes» o «hay que iniciar el servidor dev en este worktree para que se reflejen los cambios». Es conocimiento basado en la experiencia que se acumula antes de formalizarlo como regla.
Durante una conversación también puedes enviar un mensaje que empiece por # y decir directamente: «Recuerda esto». En ese caso, Claude puede preguntar en qué archivo guardarlo o clasificarlo automáticamente.
Criterios para decidir dónde colocarlo
Cuando las funciones parecen solaparse, decide con tres preguntas.
Primero, ¿quién lo decidió? Si es una regla establecida por el equipo o por ti, va en CLAUDE.md; si es un hecho descubierto durante el trabajo, va en la memoria.
Segundo, ¿causa problemas si se incumple? Las reglas cuya infracción provoca directamente un incidente, como prohibir commits de claves secretas o definir el procedimiento de despliegue, deben estar en CLAUDE.md. La memoria se parece más a una nota de referencia que a un mecanismo obligatorio que garantice la recuperación.
Tercero, ¿ya puede saberse leyendo el código o la documentación? Por regla general, no pongas en ninguno de los dos sitios información que puede obtenerse leyendo el repositorio. Solo desperdicia contexto y se vuelve falsa cuando cambia el código.
Dos prácticas que mantener en la operación
Primero, limpiarlos con regularidad. CLAUDE.md tiende a acumular reglas sin eliminarlas. Borra en cuanto las detectes las reglas que ya no son válidas y las instrucciones de un solo uso para evitar desperdiciar contexto en cada sesión. Lo mismo vale para la memoria: es mejor borrar las entradas invalidadas por cambios en el código que conservarlas.
Segundo, formula las reglas de forma breve y categórica. Las frases cortas como «hacer X» o «prohibido X» se cumplen mejor que «si es posible, conviene hacer X». Añadir un ejemplo de una línea mejora notablemente el cumplimiento.
Resumen
CLAUDE.md es la constitución y la memoria es el diario de trabajo. Las reglas inmutables decididas por las personas bajan desde arriba, mientras la experiencia obtenida en el trabajo se acumula desde abajo.
Cuando empiezas a gestionarlos por separado, reduces tanto la repetición de las mismas explicaciones en cada sesión como la necesidad de volver a sufrir los problemas de la sesión anterior.
Seguir leyendo
- Diseño de memoria para agentes de IA: técnicas para mantenerla fuera del contexto (archivos de planificación, memoria y RAG)
- ¿Por qué CLAUDE.md debe ser corto? Diseño del contexto cargado permanentemente para agentes de IA
- [MCP·Skill n.º 2] Guía completa de Skill para agentes de IA, desde comandos de barra hasta activadores automáticos