Saltar al contenido principal

CLAUDE.md y archivos de memoria

Principiante

Si haces una sola cosa para mejorar Claude Code, que sea esta. CLAUDE.md es un archivo de texto plano que Claude lee al inicio de cada sesión — el briefing permanente de tu proyecto.

What you'll learn
  • Por qué CLAUDE.md es el ajuste de Claude Code de mayor impacto
  • Cómo se carga la jerarquía de memoria, desde la política administrada hasta CLAUDE.local.md
  • En qué se diferencia la memoria automática del CLAUDE.md que escribes tú
  • Cómo generar un archivo inicial con /init y recortarlo
  • Qué pertenece a CLAUDE.md — y qué dejar fuera
  • Cómo los @imports te permiten referenciar documentos sin duplicarlos

Por qué es el ajuste de mayor impacto​

Sin él, vuelves a explicar tu proyecto en cada sesión ("usamos pnpm, los tests están en __tests__, no toques /generated…"). Con él, Claude ya lo sabe. Unas buenas instrucciones aquí mejoran cada interacción futura de golpe.

La jerarquía de memoria​

Claude Code carga la memoria desde varias ubicaciones y las combina en el orden de carga, primero el alcance más amplio — así que una instrucción de proyecto aterriza en el contexto después de una instrucción de usuario:

  • Política administrada — instrucciones a nivel de organización que despliega tu equipo de IT/DevOps. La ruta depende del sistema operativo: /Library/Application Support/ClaudeCode/CLAUDE.md en macOS, /etc/claude-code/CLAUDE.md en Linux y WSL, C:\Program Files\ClaudeCode\CLAUDE.md en Windows.
  • Instrucciones de usuario (~/.claude/CLAUDE.md) — tus preferencias personales en todos los proyectos.
  • Instrucciones de proyecto (./CLAUDE.md o ./.claude/CLAUDE.md, en el control de versiones) — cómo funciona este repo. Se comparten con tu equipo. Si tu repo usa AGENTS.md, ese puede cargarse en lugar de estos o junto a ellos.
  • Instrucciones locales (./CLAUDE.local.md) — notas específicas del proyecto solo para ti, como una URL de sandbox. Añádelo a tu .gitignore.

Los archivos del árbol de directorios por encima de tu directorio de trabajo se cargan al inicio; los archivos de las subcarpetas se cargan a demanda, cuando Claude toca algo en esa zona.

Pro tip
  • ¿Se te ha quedado pequeño un solo archivo? Divide las instrucciones en .claude/rules/*.md — un tema por archivo, descubiertos de forma recursiva. Las reglas sin frontmatter paths se cargan al inicio con la misma prioridad que .claude/CLAUDE.md; añade el frontmatter paths para cargar una regla solo cuando Claude trabaje en archivos coincidentes, lo que ahorra contexto.
Conoce tus capas de memoria
Pulsa Intro o Espacio para girar la tarjeta. Usa las flechas izquierda y derecha para moverte entre las tarjetas.Término mostrado.
1 / 6

La otra mitad: la memoria automática​

CLAUDE.md es la mitad de la memoria que escribes tú. Claude Code también mantiene una memoria automática — notas que Claude escribe por sí mismo a partir de tus correcciones y preferencias, almacenadas por repositorio y cargadas en cada sesión junto a tus archivos CLAUDE.md.

Archivos CLAUDE.mdMemoria automática
Quién la escribeTúClaude
Qué contieneInstrucciones y reglasAprendizajes y patrones
AlcanceProyecto, usuario u organizaciónPor repositorio, compartida entre worktrees

Ambas son contexto, no imposición: Claude las trata como orientación que puede ponderar, no como configuración que debe obedecer. Para bloquear de forma dura una acción al margen de lo que Claude decida, usa un hook PreToolUse en su lugar.

Watch out
  • La memoria automática carga solo sus primeras 200 líneas o 25 KB — un MEMORY.md inflado se trunca en silencio. Consulta Auditoría del presupuesto de contexto para el desglose completo del coste de arranque.

Genera un punto de partida​

Guided walkthrough1 of 3
  1. Claude inspecciona el código y redacta un CLAUDE.md por ti automáticamente.

Genera un borrador de CLAUDE.md

/init

Toma una plantilla lista para usar en Plantillas de CLAUDE.md.

Qué poner en él​

  • Qué es el proyecto, en dos frases.
  • El stack tecnológico y cómo ejecutar / testear / hacer lint.
  • Convenciones que Claude no puede inferir (nomenclatura, estructura, estilo de commits).
  • Salvaguardas: "ejecuta los tests antes de declarar que está hecho", "nunca edites /vendor", "nunca hagas commit de secretos".

Qué NO poner en él​

Watch out
  • Claude sigue CLAUDE.md al pie de la letra — las instrucciones obsoletas, vagas o aspiracionales perjudican activamente.
  • Describe cómo funciona el proyecto realmente hoy; breve y veraz gana a largo y aspiracional.
  • Evita documentos enormes pegados (usa @imports en su lugar), secretos y reglas que en realidad no sigues.
  • Revísalo periódicamente para que se mantenga preciso a medida que el proyecto evoluciona.

Importaciones​

Trae documentos existentes en lugar de duplicarlos — p. ej. referencia tu guía de estilo con una importación @path/to/file para que haya una única fuente de verdad. Funcionan tanto las rutas relativas como las absolutas; las rutas relativas se resuelven respecto al archivo que contiene la importación, no respecto a tu directorio de trabajo. Los archivos importados pueden importar otros, hasta una profundidad máxima de cuatro saltos.

Dos trampas de sintaxis que conviene conocer antes de que te muerdan:

  • Los espacios necesitan barras invertidas. @Design\ Docs/api-conventions.md funciona; sin la barra invertida la ruta se corta en el primer espacio. Envolverla entre comillas no importa el archivo en absoluto.
  • Las comillas invertidas te dejan fuera. El análisis de importaciones se salta los fragmentos de código y los bloques delimitados, así que `@README` se queda como texto literal mientras que @README por sí solo importa el archivo. Así es como mencionas una ruta sin cargarla.

Consulta la documentación oficial de memoria para la referencia completa.

Pro tip
  • Una única fuente de verdad: referencia un archivo con @imports en lugar de pegar su contenido en CLAUDE.md.
  • Si un documento ya existe, enlázalo — no lo copies. Las copias se quedan obsoletas.

Compruébate​

Compruébate

0/6
  1. ¿Qué archivo lee Claude Code al inicio de cada sesión como el briefing permanente de tu proyecto?
  2. ¿Qué hace ejecutar /init en un proyecto?
  3. ¿Cuál es la forma recomendada de incluir un documento grande existente, como una guía de estilo?
  4. ¿Dónde van las notas personales específicas de un proyecto, las que no quieres incluir en el control de versiones?
  5. ¿Quién escribe la memoria automática?
  6. ¿Cuándo se carga un CLAUDE.md que está en una subcarpeta?
Key takeaways
  • CLAUDE.md es el ajuste de mayor impacto: mejora cada sesión futura de golpe.
  • La memoria se carga primero por el alcance más amplio: política administrada, luego usuario (~/.claude/CLAUDE.md), proyecto (./CLAUDE.md o ./.claude/CLAUDE.md) y después local (./CLAUDE.local.md). Los archivos de las subcarpetas se cargan a demanda.
  • La memoria automática es la otra mitad — las notas propias de Claude, por repositorio, cargadas en cada sesión. Ambas son contexto, no imposición: usa un hook para bloquear algo de forma dura.
  • ¿Se te ha quedado pequeño un solo archivo? Divídelo en .claude/rules/*.md y delimita las reglas con el frontmatter paths.
  • Empieza con /init, luego recorta el borrador a lo que es realmente cierto.
  • Mantenlo breve y veraz — usa @imports (máximo cuatro saltos) para documentos grandes y nunca hagas commit de secretos.

Siguiente​