CLAUDE.md: qué es, cómo crearlo y configurarlo en Claude Code
CLAUDE.md es el archivo que permite proporcionar instrucciones persistentes a Claude Code. Puedes utilizarlo para explicar la arquitectura del proyecto, definir estándares de programación, indicar comandos, establecer convenciones y evitar repetir las mismas instrucciones en cada nueva sesión.
¿Qué es CLAUDE.md?
CLAUDE.md es un archivo Markdown
que Claude Code lee automáticamente
para obtener instrucciones persistentes.
Puede contener comandos de build y testing,
arquitectura, convenciones de código,
reglas del proyecto y workflows habituales.
Para un proyecto compartido puedes colocarlo
en ./CLAUDE.md
o ./.claude/CLAUDE.md.
También puedes ejecutar /init
para que Claude Code genere
una primera versión automáticamente.
Qué información conviene guardar en CLAUDE.md
La idea no es documentar absolutamente todo el proyecto, sino guardar aquello que Claude debería conocer en prácticamente cada sesión.
Arquitectura
Estructura, capas, responsabilidades y decisiones técnicas importantes.
Comandos
Cómo ejecutar desarrollo, tests, lint, build y despliegues.
Convenciones
Nombres, formato, estructura y patrones preferidos.
Reglas
Acciones que Claude debe realizar o evitar durante el trabajo.
Testing
Tests obligatorios, herramientas y condiciones de finalización.
Workflows
Pasos habituales que debe respetar antes de completar una tarea.
Claude lee las instrucciones al comenzar la sesión
CLAUDE.md forma parte del contexto que Claude Code utiliza para interpretar tus solicitudes.
Carga las reglas
Claude Code encuentra los archivos CLAUDE.md relevantes para el proyecto.
Obtiene contexto
Las instrucciones se incorporan al contexto de la conversación.
Trabaja según las reglas
Claude utiliza estas instrucciones mientras investiga, programa y verifica.
CLAUDE.md vs Auto Memory
Claude Code dispone actualmente de dos mecanismos complementarios para mantener información entre conversaciones.
| Aspecto | CLAUDE.md | Auto Memory |
|---|---|---|
| Quién escribe | Tú | Claude |
| Contenido | Instrucciones y reglas | Aprendizajes y patrones |
| Control | Explícito | Automático |
| Proyecto | Sí | Sí |
| Todos los proyectos | Sí, con archivo de usuario | No de la misma forma |
| Reglas del equipo | Ideal | No es su función principal |
Claude trata las instrucciones de CLAUDE.md como contexto. Si necesitas bloquear técnicamente una acción independientemente de la decisión del modelo, debes utilizar permisos, settings, sandbox o Hooks apropiados.
Dónde colocar CLAUDE.md
El lugar donde guardas el archivo determina su alcance.
| Ubicación | Alcance | Uso |
|---|---|---|
~/.claude/CLAUDE.md |
Usuario | Tus preferencias en todos los proyectos |
./CLAUDE.md |
Proyecto | Reglas compartidas del repositorio |
./.claude/CLAUDE.md |
Proyecto | Alternativa organizada dentro de .claude |
./CLAUDE.local.md |
Personal + proyecto | Preferencias privadas no compartidas |
Utiliza
./CLAUDE.md
o
./.claude/CLAUDE.md
y súbelo
al repositorio
para compartir
las reglas con el equipo.
Qué es CLAUDE.local.md
No todas las instrucciones deberían compartirse con el resto del equipo.
Preferencias privadas del proyecto
Puedes utilizarlo para URLs de sandbox, datos de prueba personales, preferencias locales o cualquier información que solo necesites tú.
# Preferencias locales
- Utiliza http://localhost:8080 para pruebas
- Mi base de datos local se llama proyecto_dev
- No modifiques archivos de fixtures personales
CLAUDE.local.md
está diseñado
para información personal,
por lo que normalmente
no debería entrar
al control de versiones.
Cómo crear CLAUDE.md automáticamente
Claude Code incluye un comando específico para generar un punto de partida.
Analizar el proyecto y generar instrucciones
/initClaude analiza el codebase y genera una base con comandos, instrucciones de testing y convenciones que puede descubrir en el proyecto.
Considera
/init
como un primer borrador.
Revisa,
simplifica
y añade aquello
que Claude
no podría deducir
simplemente leyendo
el código.
Qué pasa si CLAUDE.md ya existe
Ejecutar
/init
no debería reemplazar
ciegamente
tus instrucciones.
Claude propone cambios
Cuando ya existe
un CLAUDE.md,
/init
puede analizarlo
y sugerir mejoras
en lugar
de simplemente
sobrescribirlo.
Ejemplo de CLAUDE.md bien estructurado
Un archivo útil debería ser concreto, verificable y relativamente corto.
# Proyecto
Aplicación web para gestión de clientes.
## Stack
- PHP 8.3
- MySQL 8
- JavaScript
- Bootstrap 5
- PHPUnit
## Arquitectura
- `/src` contiene la lógica de negocio
- `/public` es el document root
- `/templates` contiene las vistas
- `/tests` contiene PHPUnit
- `/config` contiene configuración
## Base de datos
- Utiliza PDO
- Utiliza prepared statements
- Nunca concatenes datos del usuario en SQL
- Las migraciones están en `/database/migrations`
## Seguridad
- Sanitiza toda entrada del usuario
- Escapa contenido antes de imprimir HTML
- Valida permisos antes de operaciones sensibles
- No guardes secretos en el repositorio
## Testing
Antes de finalizar cambios:
1. ejecuta `composer test`
2. ejecuta `composer lint`
3. corrige cualquier fallo relacionado
## Git
- No hagas push automáticamente
- No modifiques main directamente
- Revisa el diff antes de crear commits
## Reglas
- Sigue los patrones existentes antes de crear abstracciones nuevas
- No cambies APIs públicas sin explicarlo primero
- Prefiere cambios pequeños y enfocados
- No realices refactors no relacionados con la tarea actualCLAUDE.md debe ser corto y específico
Más instrucciones no siempre producen mejores resultados.
Intenta mantenerlo por debajo de 200 líneas
Anthropic recomienda mantener cada CLAUDE.md relativamente conciso. Los archivos muy grandes consumen más contexto y pueden reducir la consistencia con que Claude sigue cada instrucción.
Documentación extensa, procedimientos largos y reglas que solo aplican a determinados archivos tienen mejores lugares dentro del ecosistema de Claude Code.
Escribe instrucciones que puedan verificarse
| Débil | Mejor |
|---|---|
| Formatea bien el código | Usa indentación de 2 espacios |
| Prueba tus cambios | Ejecuta npm test antes de finalizar |
| Mantén todo organizado | Los handlers API van en src/api/handlers/ |
| Escribe código seguro | Valida inputs con Zod antes de procesarlos |
| No rompas nada | Ejecuta test, lint y build después del cambio |
Importar otros archivos dentro de CLAUDE.md
No necesitas copiar información que ya existe en documentación mantenida por el proyecto.
Importar documentación
# Proyecto
Consulta @README.md para la arquitectura general.
## Git
Sigue @docs/git-workflow.md
## API
Consulta @docs/api-conventions.mdLas rutas relativas se resuelven respecto del archivo que realiza la importación.
Los archivos importados también pueden importar otros archivos, hasta una profundidad máxima de cuatro niveles.
Cómo escribir @ sin importar un archivo
Fuera de bloques
de código,
la sintaxis
@archivo
puede interpretarse
como importación.
Usa código inline
El alias `@app` apunta al directorio src/.Organizar reglas con .claude/rules/
Cuando CLAUDE.md comienza a crecer, puedes dividir las instrucciones por temas.
mi-proyecto/
├── CLAUDE.md
├── .claude/
│ └── rules/
│ ├── code-style.md
│ ├── testing.md
│ ├── security.md
│ ├── frontend/
│ │ └── react.md
│ └── backend/
│ └── api.md
├── src/
└── tests/
Archivos pequeños
como
testing.md,
security.md
o
api-design.md
son más fáciles
de mantener
que un CLAUDE.md
gigantesco.
Aplicar reglas solo a determinados archivos
No todas las instrucciones tienen que ocupar contexto durante todo el tiempo.
Reglas específicas para una ruta
---
paths:
- "src/api/**/*.ts"
---
# Reglas API
- Valida todos los inputs
- Utiliza el formato estándar de errores
- Documenta endpoints
- Añade tests para nuevos handlersClaude Code activa estas instrucciones cuando trabaja con archivos que coinciden con los patrones definidos.
Ejemplos de reglas por tipo de archivo
| Patrón | Aplica a |
|---|---|
**/*.php |
Todos los PHP |
**/*.ts |
Todos los TypeScript |
src/**/* |
Todo dentro de src |
src/components/*.tsx |
Componentes TSX directos |
tests/**/*.test.ts |
Tests TypeScript |
src/**/*.{ts,tsx} |
TypeScript y TSX dentro de src |
CLAUDE.md vs Rules vs Skills
Elegir el mecanismo correcto evita cargar instrucciones innecesarias en cada conversación.
| Mecanismo | Úsalo para | Carga |
|---|---|---|
| CLAUDE.md | Reglas generales del proyecto | Cada sesión |
| .claude/rules | Reglas modulares o por rutas | Global o contextual |
| Skills | Procedimientos y workflows especializados | Cuando son relevantes |
Si Claude debe recordarlo durante prácticamente todas las sesiones, utiliza CLAUDE.md. Si solo importa para ciertos archivos, usa Rules. Si describe un procedimiento reutilizable, considera un Skill.
Ver Claude Code Skills →Cómo carga Claude Code los archivos CLAUDE.md
Claude puede encontrar varios archivos al mismo tiempo.
Política administrada
Reglas distribuidas por una organización.
Usuario
~/.claude/CLAUDE.md
aplica tus preferencias
personales.
Proyecto
./CLAUDE.md
define reglas
del repositorio.
Local
CLAUDE.local.md
añade tus preferencias
personales
para ese proyecto.
Claude concatena las instrucciones relevantes dentro del contexto. Por eso debes evitar reglas contradictorias entre diferentes niveles.
CLAUDE.md también puede existir en subdirectorios
Esto resulta especialmente útil en monorepos y proyectos grandes.
monorepo/
├── CLAUDE.md
├── frontend/
│ ├── CLAUDE.md
│ └── src/
├── backend/
│ ├── CLAUDE.md
│ └── src/
└── mobile/
├── CLAUDE.md
└── src/Claude puede descubrir archivos CLAUDE.md de subdirectorios conforme lee archivos dentro de esas áreas.
Cómo comprobar que CLAUDE.md fue cargado
No necesitas adivinar si Claude Code encontró tu archivo.
Revisar Memory files
/contextAhí puedes confirmar qué archivos de instrucciones están formando parte del contexto actual.
Administrar memoria desde Claude Code
Claude Code también proporciona una interfaz para revisar los mecanismos de memoria.
Ver configuración de memoria
/memoryClaude también puede guardar aprendizajes automáticamente
Auto Memory complementa CLAUDE.md sin reemplazarlo.
Claude decide qué merece recordarse
Puede guardar correcciones, preferencias, decisiones del proyecto y referencias útiles cuando considera que serán relevantes en futuras sesiones.
Auto Memory intenta evitar información que Claude ya puede deducir directamente del código o que ya existe en CLAUDE.md.
CLAUDE.md y AGENTS.md
Algunos proyectos
utilizan
AGENTS.md
para configurar
diferentes agentes
de programación.
Reutilizar AGENTS.md
@AGENTS.md
# Claude Code
- Usa Plan Mode para cambios en src/billing/
- Ejecuta tests antes de modificar migracionesSi tu repositorio ya utiliza AGENTS.md, puedes importarlo desde CLAUDE.md para evitar duplicar instrucciones.
Ejemplo de CLAUDE.md para WordPress
Un proyecto WordPress puede beneficiarse mucho de reglas explícitas sobre seguridad, hooks y acceso a base de datos.
# WordPress Plugin
## Compatibilidad
- WordPress 6+
- PHP 8+
- WooCommerce cuando corresponda
## Seguridad
- Sanitiza inputs
- Escapa outputs
- Utiliza nonces en formularios y AJAX
- Comprueba capabilities antes de acciones sensibles
- Nunca confíes en datos enviados por el navegador
## Base de datos
- Utiliza $wpdb cuando corresponda
- Usa $wpdb->prepare() para valores dinámicos
- No concatenes inputs directamente en SQL
## WordPress
- No modifiques archivos del core
- Utiliza hooks y filtros existentes
- No inventes tablas nuevas si los metadatos son suficientes
- Sigue WordPress Coding Standards
## Frontend
- Encapsula CSS del plugin
- Evita contaminar estilos globales
- Mantén compatibilidad responsive
## Antes de finalizar
- Revisa errores PHP
- Revisa consola JavaScript
- Verifica nonces y permisos
- Resume los archivos modificadosEjemplo de reglas para un proyecto frontend
# Frontend
## Stack
- TypeScript
- React
- Vite
- Vitest
## Convenciones
- Usa TypeScript estricto
- Evita `any`
- Componentes en PascalCase
- Hooks personalizados comienzan con `use`
- No añadas dependencias sin explicar por qué
## Comandos
- Desarrollo: `npm run dev`
- Tests: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`
## Finalización
Antes de terminar:
1. ejecuta tests
2. ejecuta lint
3. ejecuta build
4. corrige los errores introducidos por el cambioCLAUDE.md no reemplaza permisos ni Hooks
Esta diferencia es importante cuando quieres impedir realmente determinadas acciones.
| Necesidad | Mecanismo |
|---|---|
| Estándares de código | CLAUDE.md |
| Convenciones del proyecto | CLAUDE.md |
| Bloquear un comando | Permissions / Hook |
| Bloquear acceso a una ruta | Permissions |
| Aislar comandos | Sandbox |
| Ejecutar validación automática | Hook |
Qué no deberías poner en CLAUDE.md
Documentación enorme: evita copiar toda la documentación técnica del proyecto.
Información obvia: no expliques cosas que Claude puede descubrir fácilmente leyendo el código.
Secretos: nunca guardes contraseñas, tokens ni API keys.
Reglas contradictorias: revisa periódicamente archivos raíz, locales y Rules.
Procedimientos enormes: considera convertirlos en Skills.
Reglas demasiado vagas: utiliza instrucciones concretas y comprobables.
Cuándo añadir una regla nueva a CLAUDE.md
Claude repite un error
Si tienes que corregir lo mismo más de una vez, probablemente merece una regla.
Code review detecta algo recurrente
Añade aquello que Claude debería haber sabido antes de programar.
Un nuevo desarrollador lo necesitaría
Si es contexto esencial para trabajar correctamente, suele ser un buen candidato.
Cómo crear un buen CLAUDE.md
Ejecuta
/init
como punto de partida.
Revisa qué información Claude ya puede deducir del código.
Añade comandos de test, lint y build.
Define convenciones técnicas concretas.
Añade decisiones arquitectónicas no evidentes.
Separa reglas
específicas
en
.claude/rules/.
Mantén el archivo corto y actualizado.
Comprueba
la carga
con
/context.
Documentación oficial de CLAUDE.md
Claude Code evoluciona rápidamente, por lo que conviene revisar periódicamente la documentación sobre memoria, configuración y Rules.
Memory
CLAUDE.md, Auto Memory, imports, Rules y jerarquía.
Ver documentación oficial →Settings
Configuración, scopes, permisos y settings de Claude Code.
Ver configuración →Guías relacionadas
Continúa con Plan Mode, Skills, subagentes y configuración avanzada.
FAQ sobre CLAUDE.md
Respuestas sobre creación, ubicación, /init, Rules, imports y memoria de Claude Code.
CLAUDE.md es un archivo Markdown utilizado por Claude Code para cargar instrucciones persistentes sobre un proyecto, usuario u organización.
Para un proyecto
puedes utilizar
./CLAUDE.md
o
./.claude/CLAUDE.md.
También existe
~/.claude/CLAUDE.md
para preferencias
personales globales.
Dentro de Claude Code
puedes ejecutar
/init.
Claude analiza el codebase
y genera una base
de CLAUDE.md
que después
puedes revisar
y mejorar.
Anthropic recomienda mantener cada archivo CLAUDE.md conciso, apuntando aproximadamente a menos de 200 líneas. Archivos demasiado grandes consumen más contexto y pueden reducir la adherencia a las instrucciones.
CLAUDE.local.md permite guardar instrucciones personales específicas de un proyecto. Normalmente debe añadirse a .gitignore para evitar compartirlo con el equipo.
Sí.
Puedes utilizar
la sintaxis
@ruta/archivo
para importar
otros documentos.
Los imports pueden ser
relativos o absolutos.
Es un directorio donde puedes dividir instrucciones en archivos Markdown independientes. Las reglas también pueden aplicarse únicamente a determinadas rutas mediante patrones.
No. CLAUDE.md contiene instrucciones escritas explícitamente por ti. Auto Memory contiene aprendizajes que Claude decide guardar automáticamente para futuras sesiones.
Claude Code utiliza
CLAUDE.md como
archivo de instrucciones.
Si un proyecto
ya dispone de AGENTS.md,
puedes importarlo
desde CLAUDE.md
mediante
@AGENTS.md.
Ejecuta
/context
dentro de Claude Code
y revisa
la sección
de archivos de memoria.
Ahí puedes comprobar
qué CLAUDE.md
están incluidos
en la sesión.
Aprende a utilizar Claude Code Plan Mode
Ya puedes definir reglas persistentes para que Claude Code entienda cada proyecto. El siguiente paso es aprender a separar investigación e implementación mediante Plan Mode, especialmente útil antes de cambios complejos.
Claude Code Plan Mode →