≡En resumen
- CLAUDE.md es contexto, no configuración obligatoria: Claude lo lee y procura seguirlo, pero no hay garantía absoluta de cumplimiento.
- Los archivos se suman, no se sustituyen: se cargan desde el más general (empresa, usuario) hasta el más específico (proyecto, carpeta).
- Conviene mantenerlo corto y concreto; lo que solo afecta a una parte del código va mejor en reglas por ruta o en skills.
- Admite imports con @ruta para reutilizar otros archivos, como el README o un AGENTS.md compartido con otros agentes.
- Para obligar a algo de verdad, combina CLAUDE.md con hooks y reglas de permisos.
01 ¿Qué es CLAUDE.md?
Cada sesión de Claude Code empieza con una ventana de contexto vacía. Sin ayuda, Claude tendría que redescubrir en cada conversación cómo se lanzan los tests, qué estilo de código usa el equipo o dónde vive cada cosa. CLAUDE.md resuelve eso: es un archivo de texto en Markdown que Claude Code carga automáticamente al inicio y que funciona como la guía de bienvenida de un compañero nuevo.
Es una de las dos piezas de memoria persistente de Claude Code. La otra es la memoria automática, que son notas que Claude escribe por su cuenta; la diferencia es quién escribe: CLAUDE.md lo redactas tú, con las reglas que quieres que se cumplan.
02 Dónde se coloca CLAUDE.md y qué alcance tiene
| Alcance | Ubicación | Para qué | Quién lo ve |
|---|---|---|---|
| Política gestionada | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md; Linux: /etc/claude-code/CLAUDE.md | Normas de la empresa, seguridad y cumplimiento | Toda la organización |
| Usuario | ~/.claude/CLAUDE.md | Tus preferencias personales en todos los proyectos | Solo tú |
| Proyecto | ./CLAUDE.md o ./.claude/CLAUDE.md | Arquitectura, convenciones y comandos del repositorio | Todo el equipo, vía git |
| Local | ./CLAUDE.local.md | Preferencias tuyas en un proyecto (añádelo a .gitignore) | Solo tú en ese proyecto |
Claude Code carga los CLAUDE.md del directorio donde lo lanzas y de todos los directorios superiores, y los concatena en orden: primero lo más general y al final lo más cercano a tu carpeta de trabajo. Los CLAUDE.md de subcarpetas no se cargan al arrancar, sino cuando Claude lee o edita archivos dentro de ellas. Para comprobar qué se ha cargado, ejecuta /context y mira la lista de archivos de memoria.
03 Qué poner (y qué no) en tu CLAUDE.md
- ✓Comandos para instalar, compilar, lanzar tests y pasar el linter.
- ✓Convenciones verificables: "indentación de 2 espacios", no "formatea bien el código".
- ✓Estructura del proyecto: dónde están los controladores, servicios, tests y configuración.
- ✓Decisiones de arquitectura que no se deducen leyendo el código.
- ✓Normas de flujo de trabajo: formato de commits, ramas, qué no tocar nunca.
- ✓Errores que Claude ha cometido más de una vez y cómo evitarlos.
No: procedimientos largos
Un proceso de despliegue en diez pasos ocupa contexto en cada sesión. Mejor como skill, que solo se carga cuando se usa.
No: reglas de una sola carpeta
Lo que afecta solo al frontend o a la API va en una regla con paths, que se carga al trabajar con esos archivos.
No: secretos
Claves, contraseñas o tokens nunca van en CLAUDE.md, y menos en uno que se sube al repositorio.
No: instrucciones vagas
"Escribe buen código" no cambia nada. Cuanto más concreta y comprobable sea una instrucción, más se cumple.
04 Cómo crear y mantener CLAUDE.md
-
1
Genera un borrador con /init
Claude analiza el repositorio y escribe un CLAUDE.md con comandos, tests y convenciones. Si ya existe, propone mejoras en vez de sobrescribirlo.
-
2
Recórtalo
Quita lo obvio y lo que Claude deduce leyendo el código. La documentación oficial recomienda quedarse por debajo de 200 líneas por archivo.
-
3
Añade lo que falta
Cada vez que corrijas a Claude dos veces por lo mismo, o que una revisión detecte algo que debía saber, añádelo.
-
4
Edítalo con /memory
El comando /memory lista tus archivos de instrucciones y los abre en tu editor; también puedes pedirle a Claude que lo actualice.
-
5
Audita de vez en cuando
/doctor prompt-audit busca instrucciones obsoletas, contradicciones o referencias a archivos que ya no existen y propone cambios.
05 Imports, reglas por ruta y proyectos grandes
Un CLAUDE.md puede importar otros archivos con la sintaxis @ruta/al/archivo. Las rutas relativas se resuelven desde el archivo que importa y los imports pueden anidarse hasta cuatro saltos. Ten en cuenta que importar no ahorra contexto: el archivo importado también se carga al arrancar.
Para repositorios grandes, la carpeta .claude/rules/ permite dividir las instrucciones en archivos por tema (testing.md, api.md…). Si una regla lleva en su frontmatter un campo paths con patrones como src/api/**/*.ts, solo se carga cuando Claude trabaja con archivos que coinciden.
Comandos: composer setup para instalar, composer quality para Pint, PHPStan y tests.
Arquitectura: Controller → Action → Service → Repository; nada de Eloquent fuera de los repositorios.
Reglas: declare(strict_types=1); en todos los archivos PHP; textos en lang/es/; env() solo dentro de config/.
Más contexto: decisiones en @docs/architecture/adr/README.md.
Son pocas líneas, todas verificables y todas útiles en cualquier tarea del proyecto. Es la forma de trabajar que aplicamos en el desarrollo de aplicaciones web a medida.
06 CLAUDE.md y AGENTS.md
AGENTS.md es un archivo equivalente que usan otros agentes de programación. Las versiones recientes de Claude Code lo leen directamente cuando el repositorio no tiene CLAUDE.md, así que un proyecto ya preparado para otras herramientas funciona sin tocar nada.
| Tu repositorio tiene | Claude lee |
|---|---|
| Solo AGENTS.md | AGENTS.md |
| AGENTS.md y CLAUDE.md (o CLAUDE.local.md) | Solo los CLAUDE.md |
| Un CLAUDE.md que importa @AGENTS.md | CLAUDE.md, con AGENTS.md incluido mediante el import |
07 Límites de CLAUDE.md y cómo complementarlo
CLAUDE.md llega al modelo como un mensaje después del prompt de sistema, no como una regla técnica. Si dos instrucciones se contradicen, Claude puede elegir cualquiera, y en sesiones muy largas las instrucciones pueden perder peso. Por eso no basta para lo crítico: si algo no debe pasar nunca, como editar un .env o hacer un push forzado, protégelo con reglas de permisos o con hooks de Claude Code, que se ejecutan siempre.
| Necesidad | Mejor opción |
|---|---|
| Contexto que Claude debe tener siempre | CLAUDE.md |
| Instrucciones de una carpeta o tipo de archivo | .claude/rules/ con paths |
| Procedimientos que se usan de vez en cuando | Skills |
| Preferencias y correcciones que Claude aprende | Memoria automática |
| Prohibiciones que deben cumplirse sí o sí | Permisos y hooks |
Para saber más sobre la memoria que Claude escribe por su cuenta, consulta la ficha de la memoria de Claude; para los procedimientos bajo demanda, la de Claude Skills. Y si estás lanzando un producto y quieres un equipo que ya trabaja con agentes bien configurados, mira nuestro servicio de desarrollo de SaaS o explora la guía de herramientas y recursos para Claude.
Preguntas frecuentes sobre CLAUDE.md
Es un archivo Markdown con instrucciones que Claude Code carga al inicio de cada sesión: comandos, convenciones, estructura del proyecto y normas del equipo. Evita repetir el mismo contexto en cada conversación.
Para un proyecto, en la raíz del repositorio (./CLAUDE.md) o en ./.claude/CLAUDE.md. Para tus preferencias en todos los proyectos, en ~/.claude/CLAUDE.md. Las preferencias personales de un solo proyecto van en CLAUDE.local.md, fuera de git.
Ejecuta /init en Claude Code. Analiza el repositorio y genera un borrador con comandos, tests y convenciones; si el archivo ya existe, sugiere mejoras en lugar de sobrescribirlo.
La documentación oficial recomienda menos de 200 líneas por archivo. Los archivos largos consumen más contexto y reducen el cumplimiento, así que lo que solo afecta a una parte del código conviene moverlo a reglas por ruta o skills.
Sí, las versiones recientes lo leen cuando no hay CLAUDE.md en la carpeta de trabajo ni en las superiores. Si tienes ambos, puedes importar AGENTS.md desde CLAUDE.md con la línea @AGENTS.md.
Suele deberse a instrucciones vagas, contradictorias o a un archivo demasiado largo. Comprueba con /context que se ha cargado, hazlas concretas y verificables, y usa hooks o permisos para lo que deba cumplirse siempre.
Fuentes consultadas
Sobre el autor
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil y artículos → Ver perfil en LinkedIn ↗