01 Por qué basta con carpetas y texto
Cada sesión de Claude Code empieza con la memoria en blanco. La tentación es montar un sistema sofisticado (embeddings, una base vectorial, un gestor de notas conectado por MCP) para que «recuerde». Para un proyecto de código, la documentación de un cliente o la carpeta de trabajo de un departamento, eso suele ser excesivo: Claude Code ya sabe recorrer el árbol de carpetas, buscar texto y abrir archivos por su nombre.
Lo que le falta no es un buscador, es orientación: saber qué es el proyecto, dónde está cada cosa y qué reglas aplicar. Eso se resuelve con archivos de texto plano llamados CLAUDE.md, que Claude lee como contexto, que puedes versionar con git y que cualquier persona del equipo entiende.
02 Dónde van los CLAUDE.md y cuándo se leen
| Archivo | Ámbito | ¿Se sube a git? |
|---|---|---|
| ~/.claude/CLAUDE.md | Tus preferencias en todos los proyectos | No, vive en tu ordenador |
| ./CLAUDE.md o ./.claude/CLAUDE.md | Instrucciones del proyecto para todo el equipo | Sí |
| ./CLAUDE.local.md | Tus notas personales de este proyecto | No, añádelo a .gitignore |
| subcarpeta/CLAUDE.md | Reglas de esa carpeta concreta | Sí |
Los archivos de la carpeta donde arrancas Claude Code y de las carpetas superiores se cargan al inicio. Los de las subcarpetas se cargan bajo demanda: solo cuando Claude lee o edita un archivo dentro de ellas. Si trabajas en facturas/, las reglas de clientes/ no ocupan contexto. Por eso es mejor repartir las instrucciones por carpetas que acumularlas en un único archivo enorme.
Todos los archivos se concatenan, no se sustituyen: lo más cercano a donde trabajas se lee al final. Si dos reglas se contradicen, Claude puede elegir cualquiera, así que revisa que no choquen.
03 Una estructura por niveles que funciona
empresa/
├── CLAUDE.md ← mapa: qué hay aquí y reglas generales
├── clientes/
│ ├── CLAUDE.md ← cómo se nombran fichas y propuestas
│ └── acme/
├── facturacion/
│ └── CLAUDE.md ← formato de importes, IVA, qué no tocar
├── marketing/
│ └── CLAUDE.md ← tono de marca, longitud de posts
└── plantillas/
└── CLAUDE.md ← qué plantilla usar en cada casoEl CLAUDE.md raíz es un mapa
Qué es el proyecto, para quién, cómo se ejecuta o se revisa, qué contiene cada carpeta y tres o cuatro reglas que siempre aplican.
Cada carpeta, su nota
Solo lo que es propio de esa carpeta: nombres de archivo, convenciones y lo que no se debe modificar. Nada que ya diga la raíz.
Nombres que se explican solos
facturacion/ es mejor que docs2/. Claude busca por nombre antes de abrir nada.
Poca profundidad
Dos o tres niveles. Las jerarquías muy anidadas confunden a las personas y al agente por igual.
04 Primer CLAUDE.md en dos minutos con /init
/init/init analiza la carpeta y genera un CLAUDE.md inicial con los comandos de compilación y pruebas, las convenciones que detecta y un resumen de la estructura. Si ya existe uno, no lo sobrescribe: propone mejoras. Léelo, borra lo obvio y añade lo que Claude no puede deducir por sí mismo, como decisiones de negocio o archivos que nunca debe tocar.
05 Prompts para montar la estructura
Revisa el contenido de esta carpeta y propón una organización en carpetas temáticas, con nombres claros en minúsculas y como máximo tres niveles de profundidad. Para cada carpeta indica en una línea qué contendrá y qué archivos actuales moverías allí. No muevas, crees ni borres nada hasta que yo apruebe la propuesta.Crea un CLAUDE.md dentro de [carpeta] con un máximo de 30 líneas. Incluye: qué hay en la carpeta, cómo se nombran los archivos, qué convenciones aplican solo aquí y qué no se debe modificar nunca. No repitas nada que ya esté en el CLAUDE.md de la raíz. Enséñame el texto antes de guardarlo.Antes de terminar, repasa esta sesión y dime qué decisiones, convenciones o errores evitados merecen quedar como regla. Para cada uno propone una línea concreta y el CLAUDE.md donde iría (raíz o carpeta). Señala también reglas actuales que hayan quedado obsoletas o que se contradigan. Aplica los cambios solo cuando yo confirme.06 Imports, /memory y mantenimiento
Cuando un CLAUDE.md crece, puedes partirlo e incluir otros archivos con la sintaxis @ruta/al/archivo.md. Las rutas relativas se resuelven desde el archivo que hace la importación y se admiten hasta cuatro niveles de anidación. Ojo: importar ordena, pero no ahorra contexto, porque lo importado se carga entero al arrancar. Si una regla solo afecta a ciertos archivos, es mejor una regla con ruta en .claude/rules/, que solo se carga cuando Claude trabaja con esos archivos.
El comando /memory lista los archivos de instrucciones y te permite abrirlos para editarlos; también activa o desactiva la memoria automática, en la que Claude guarda por su cuenta aprendizajes en ~/.claude/projects/. Para ver qué archivos se cargaron realmente al iniciar la sesión, usa /context.
- ✓Revisa los CLAUDE.md una vez al mes o al cerrar cada fase del proyecto.
- ✓Borra reglas que ya no se aplican: una regla muerta confunde más que su ausencia.
- ✓Si Claude ignora una instrucción, comprueba con /context que el archivo se cargó.
- ✓Lo que debe cumplirse sí o sí (no borrar, no publicar) va en un hook, no en un CLAUDE.md.
Preguntas frecuentes
Para tus notas personales del proyecto que no quieres compartir: URLs de tu entorno de pruebas, datos de prueba preferidos o atajos propios. Se carga junto al CLAUDE.md y debe estar en .gitignore.
Sí. La estructura sirve igual para documentación de clientes, procesos internos o material de marketing. Claude Code trabaja con cualquier carpeta de archivos.
Las versiones recientes de Claude Code leen AGENTS.md cuando no hay ningún CLAUDE.md. Si tienes ambos, lo más limpio es importar AGENTS.md desde el CLAUDE.md con @AGENTS.md para mantener una sola fuente.
No, se complementan. Los CLAUDE.md son reglas que escribes y controlas tú; la memoria automática son notas que Claude toma por su cuenta. Ambas se cargan en cada sesión.
No. Claude las trata como contexto, no como configuración obligatoria. Cuanto más concretas y breves, mejor las sigue; para prohibiciones estrictas usa hooks o permisos.
Sobre el autor
Equipo editorial de appyweb
Marketing, SEO y desarrollo con IA
Especialistas de appyweb en SEO, publicidad, desarrollo web y automatización con IA.