CLAUDE.md: la memoria de tu proyecto en Claude Code
CLAUDE.md es el archivo de memoria persistente de tu proyecto: Claude Code lo lee al iniciar cada sesión. Ahí pones las reglas y convenciones que no quieres repetir cada vez (estilo de código, comandos de build, qué no tocar). Bien usado, hace que el modelo entienda tu proyecto de entrada. Mal usado (inflado), consigue lo contrario: que ignore la mitad.
Regla de oro: mantén
CLAUDE.mdpor debajo de 200 líneas, con las reglas críticas en las primeras 20. Un archivo inflado hace que el modelo descarte parte. Poda lo que ya hace bien o conviértelo en un hook.
Los comandos de memoria de un vistazo
| Comando / archivo | Qué hace |
|---|---|
/init |
Genera el CLAUDE.md inicial del proyecto. |
CLAUDE.md |
Memoria del proyecto; se lee al iniciar la sesión. |
~/.claude/CLAUDE.md |
Reglas globales del usuario (todos tus proyectos). |
/claude-md-revise |
Revisa y optimiza tu CLAUDE.md. |
Cómo empezar
- Genera el archivo: corre
/initen tu proyecto. Claude Code analiza el código y crea unCLAUDE.mdcon lo básico (estructura, comandos, convenciones detectadas). - Pódalo: revisa lo generado y deja solo lo que de verdad importa. Lo crítico, arriba.
- Añade lo que el modelo no puede adivinar: restricciones no obvias ("no tocar esta tabla", "usar este formato de commit"), comandos de build y test, decisiones de arquitectura.
- Optimízalo con el tiempo:
/claude-md-revisete ayuda a recortar y mejorar el archivo cuando crece.
Proyecto vs usuario: dos niveles de memoria
CLAUDE.mddel proyecto (en la raíz del repo): reglas de ese proyecto. Se commitea para que todo el equipo las comparta.~/.claude/CLAUDE.md(global del usuario): tus preferencias personales, válidas en cualquier proyecto.
El error más común
Meter demasiado. Claude Code inyecta tu CLAUDE.md con la advertencia interna de que "puede o no ser relevante", así que cada regla queda sujeta al criterio del modelo. Cuanto más largo y ruidoso el archivo, más probabilidad de que ignore reglas importantes. Si una regla es crítica y no admite fallo, no la dejes en CLAUDE.md: súbela a un hook, que se cumple siempre.
Preguntas frecuentes
¿Qué es el archivo CLAUDE.md?
CLAUDE.md es la memoria persistente de un proyecto en Claude Code: un archivo que el agente lee al iniciar cada sesión. Contiene las convenciones, comandos y reglas del proyecto que no quieres repetir en cada prompt. Se genera con el comando /init.
¿Cómo se crea un CLAUDE.md?
Con el comando /init dentro del proyecto: Claude Code analiza el código y genera un CLAUDE.md inicial. Después conviene podarlo y dejar solo lo esencial, con las reglas críticas en las primeras líneas.
¿Dónde va el archivo CLAUDE.md?
El CLAUDE.md del proyecto va en la raíz del repositorio (y se commitea para compartirlo con el equipo). Las reglas globales tuyas, válidas en todos tus proyectos, van en ~/.claude/CLAUDE.md.
¿Por qué el modelo ignora mi CLAUDE.md?
Suele ser porque está inflado. Claude Code lo trata como contexto que puede o no ser relevante, así que un archivo largo y ruidoso hace que descarte parte. La regla es mantenerlo por debajo de 200 líneas con lo crítico arriba; lo que no admite fallo, llevarlo a un hook.
Recursos relacionados
- Cómo dominar Claude Code: la guía completa.
- Skills, hooks y MCP: cuándo una regla debe ser un hook en vez de una línea en CLAUDE.md.
- Ingeniería de contexto: por qué un CLAUDE.md curado mejora cada sesión.
Tu siguiente paso
El comando /init, la regla de las 200 líneas y decenas de comandos más están en la Cheat Sheet de Claude Code: una hoja imprimible, en español.
Descargar la Cheat Sheet gratis
Es el resumen de Ship with Claude Code, la guía de Takren (14 módulos, 190 capítulos, actualizaciones gratuitas).