← Volver al listado de tecnologías ← Índice de Claude Code

Cap 8: Memory y CLAUDE.md

2 de marzo de 2026 Por: Artiko

claude-codememoryclaude-mdconfiguración

Sistema de memoria

Claude Code tiene tres mecanismos de memoria complementarios:

CLAUDE.md — instrucciones explícitas escritas por el desarrollador
.claude/rules/*.md — reglas modulares, con carga opcional por globs de rutas
Auto Memory — conocimiento que Claude escribe y guarda automáticamente

CLAUDE.md en profundidad

Jerarquía de carga

La carga va de lo más amplio a lo más específico y todo se concatena, no se sobrescribe:

flowchart TD
    A["Política gestionada<br/>/Library/Application Support/ClaudeCode/CLAUDE.md<br/>/etc/claude-code/CLAUDE.md<br/>C:\Program Files\ClaudeCode\CLAUDE.md"] --> B["Usuario<br/>~/.claude/CLAUDE.md"]
    B --> C["Proyecto<br/>./CLAUDE.md o ./.claude/CLAUDE.md"]
    C --> D["Local<br/>./CLAUDE.local.md (gitignored)"]

No es un barrido de todos los directorios ancestros hasta el home: son estos cuatro niveles. Los CLAUDE.md de subdirectorios cargan bajo demanda, al leer archivos que estén ahí.

Verificar qué se cargó

/context lista los «Memory files» efectivamente cargados en la sesión.
/memory lista y abre los archivos de memoria.
El hook InstructionsLoaded registra qué se cargó y por qué.

Carga de archivos: Descendant loading

Cuando Claude accede a archivos en subdirectorios, carga los CLAUDE.md de esos directorios:

src/CLAUDE.md                ← Se carga cuando Claude lee archivos en src/
src/components/CLAUDE.md     ← Se carga cuando Claude trabaja en components/

Esto es útil para reglas específicas por módulo:

<!-- src/components/CLAUDE.md -->
# Reglas para componentes

- Usar functional components con hooks
- Props tipadas con interface, no type
- Exportar como named export, no default

Comportamiento tras /compact: el CLAUDE.md de la raíz sobrevive a la compactación (se relee de disco y se reinyecta). Los anidados no se reinyectan: solo vuelven a cargarse cuando Claude lee de nuevo un archivo de ese subdirectorio.

Archivos soportados

Archivo	Compartible	Uso
`CLAUDE.md` (o `.claude/CLAUDE.md`)	Sí (commiteable)	Reglas del equipo
`CLAUDE.local.md`	No (gitignored)	Reglas personales. Para worktrees se recomienda importar `@~/.claude/mi-archivo.md` desde el CLAUDE.md en vez de usar este archivo

AGENTS.md no se lee en runtime. Claude Code no lo carga directamente: la vía soportada es un CLAUDE.md que lo importe con @AGENTS.md, o un symlink.

Imports `@ruta`

Un CLAUDE.md puede importar otros archivos:

# CLAUDE.md
@AGENTS.md
@~/.claude/preferencias-personales.md
@docs/convenciones-api.md

Los imports se expanden en contexto al inicio, con un máximo de 4 niveles de anidamiento.
Por eso, dividir en imports organiza pero NO reduce el contexto: todo termina cargado igual.
Las rutas dentro de backticks (`@ruta`) no se importan.
Los imports fuera del directorio de trabajo piden aprobación en un diálogo la primera vez.

`.claude/rules/*.md`

Es la alternativa recomendada a un CLAUDE.md gigante: markdown modular en .claude/rules/ (proyecto) o ~/.claude/rules/ (usuario).

---
paths:
  - "src/api/**"
  - "**/*.sql"
---
# Reglas de acceso a datos

- Todas las queries pasan por el repositorio, nunca SQL inline en handlers
- Migraciones versionadas en migrations/

Con frontmatter paths: (globs), la regla solo carga al tocar archivos que matcheen.
Las reglas sin paths cargan al inicio, con la misma prioridad que .claude/CLAUDE.md.

Monorepo

En un monorepo, cada paquete puede tener su propio CLAUDE.md:

flowchart TD
    R["monorepo/<br/>CLAUDE.md — reglas globales"] --> P["packages/"]
    P --> A["api/<br/>CLAUDE.md — reglas del API"]
    P --> W["web/<br/>CLAUDE.md — reglas del frontend"]
    P --> S["shared/<br/>CLAUDE.md — reglas de la librería compartida"]

El de la raíz siempre está cargado; los de cada paquete entran bajo demanda cuando Claude lee archivos de ese paquete.

Auto Memory

Claude Code guarda automáticamente patrones y aprendizajes en un directorio de memoria persistente. Está activada por defecto y es un sistema distinto y complementario a CLAUDE.md: aquí escribe Claude, no el desarrollador.

flowchart TD
    D["~/.claude/projects/&lt;project&gt;/memory/"] --> M["MEMORY.md<br/>índice, carga por sesión"]
    M --> T1["debugging.md<br/>bajo demanda"]
    M --> T2["patterns.md<br/>bajo demanda"]

Se navega con /memory. Se desactiva con autoMemoryEnabled: false en settings o con la variable de entorno CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

La auto memory del hilo principal no se pasa a los subagentes.

Qué guarda auto memory

Comandos de build/test del proyecto
Patrones de código confirmados
Preferencias del usuario detectadas
Soluciones a problemas recurrentes

Qué NO guarda

Contexto de sesión temporal
Información no verificada
Datos que duplican CLAUDE.md

MEMORY.md

MEMORY.md funciona como índice. De él se cargan las primeras 200 líneas o 25KB por sesión, lo que se alcance primero. Los archivos de tema se leen bajo demanda, así que las notas extensas van en archivos separados enlazados desde MEMORY.md.

Comandos de memoria

/init

/init            # Genera el CLAUDE.md inicial del proyecto

Genera el CLAUDE.md inicial y, si ya existe, propone mejoras en vez de sobrescribir. Además lee reglas de otras herramientas: Cursor (.cursor/rules, .cursorrules) y Copilot (.github/copilot-instructions.md).

Con CLAUDE_CODE_NEW_INIT=1 se activa un flujo interactivo multifase: explora el repo con un subagente, hace preguntas y propone CLAUDE.md + skills + hooks, leyendo también AGENTS.md, .devin/rules/, .windsurf/rules/ y .clinerules.

/memory

/memory          # Ver, listar y abrir los archivos de memoria

Permite navegar y editar los archivos de auto memory.

/context

/context         # Ver el uso de contexto y los "Memory files" cargados

Es la forma de confirmar qué archivos de memoria entraron realmente en la sesión.

Mejores prácticas

CLAUDE.md es advisory, no configuración forzada

CLAUDE.md se entrega como mensaje de usuario tras el system prompt: es una guía fuerte, no una restricción. Para garantías deterministas hay que usar hooks o permissions.deny.

Objetivo: menos de 200 líneas por archivo

El archivo se carga completo en el contexto de cada sesión. El criterio de poda oficial se aplica línea por línea: «Would removing this cause Claude to make mistakes?».

«Bloated CLAUDE.md files cause Claude to ignore your actual instructions!»

Diagnóstico oficial: «If Claude keeps doing something you don’t want despite having a rule against it, the file is probably too long and the rule is getting lost». Conviene tratar el CLAUDE.md como código: revisarlo, podarlo y verificar que el comportamiento efectivamente cambia.

Qué incluir y qué excluir

Incluir	Excluir
Comandos bash no adivinables	Lo deducible leyendo el código
Reglas de estilo que difieren del default	Convenciones estándar del lenguaje
Instrucciones de testing	Documentación de API detallada (enlazarla)
Etiqueta del repo (ramas, PRs)	Información que cambia seguido
Decisiones arquitectónicas	Descripciones archivo por archivo
Quirks del entorno y gotchas	Obviedades tipo «write clean code»

Ejemplo de CLAUDE.md acotado:

# CLAUDE.md — Proyecto Mi App

## Comandos
bun dev              # desarrollo
bun test             # tests
bun build            # producción

## Stack
- Astro 5 + React 19
- TypeScript strict
- Tailwind CSS
- Bun como runtime

## Convenciones
- Commits: feat: / fix: / refactor:
- Tests junto al código (__tests__/)
- Arquitectura hexagonal

## Reglas
- No modificar /vendor
- No commitear .env
- Ejecutar tests antes de commit

Separar por responsabilidad

En lugar de un CLAUDE.md gigante, usa la jerarquía:

Regla	Ubicación
Preferencias personales	`~/.claude/CLAUDE.md`
Reglas del proyecto	`./CLAUDE.md` o `./.claude/CLAUDE.md`
Config personal del proyecto	`./CLAUDE.local.md`
Reglas que solo aplican a ciertos archivos	`.claude/rules/*.md` con `paths:`
Reglas del módulo API	`src/api/CLAUDE.md`
Reglas de componentes	`src/components/CLAUDE.md`

Ten en cuenta que dividir con imports @ruta organiza el material pero no reduce el contexto; para reducirlo de verdad hay que usar paths: en .claude/rules/ o mover el conocimiento a skills.

Enrutar entre CLAUDE.md, skills y hooks

Mecanismo	Cuándo usarlo
CLAUDE.md	Solo para lo que aplica siempre
Skills	Conocimiento de dominio o flujos ocasionales; cargan bajo demanda «without bloating every conversation»
Hooks	Lo que debe ocurrir sin excepción (enforcement determinista)

Auto memory vs CLAUDE.md

Aspecto	CLAUDE.md	Auto Memory
Quién lo escribe	Desarrollador	Claude Code
Cuándo se carga	Siempre (raíz) / bajo demanda (anidados)	MEMORY.md por sesión; temas bajo demanda
Compartible	Sí	No (por usuario)
Contenido	Reglas explícitas	Aprendizajes
Objetivo de tamaño	< 200 líneas por archivo	200 líneas o 25KB de MEMORY.md por sesión
Subagentes	Se aplica	No se propaga

Siguiente: Orchestration Workflow