Guía de uso de CLAUDE.md: Graba las reglas del proyecto en su memoria

📚 Navegación de la serie: El artículo anterior 17 Imágenes y multimodal te enseñó a pasarle a Claude capturas de pantalla o errores directamente. Este artículo cambia de enfoque: ¿cómo grabar las «normas» de tu proyecto en su memoria para que las cumpla en cada sesión sin tener que repetírselas a diario?

Todos dicen que cuanto más detallado sea CLAUDE.md mejor, pero para ser sinceros, el CLAUDE.md más inútil es precisamente el que tiene 300 líneas y al que Claude no hace caso en absoluto.

Imagina un CLAUDE.md que heredaste de un proyecto: incluye el historial de la empresa, la visión del producto, presentaciones del equipo, el porqué de la tecnología elegida... y tienes que hacer scroll hasta la segunda pantalla para leer algo útil como «usa pnpm y no npm». ¿El resultado? Claude te hace un npm install igualmente.

El problema no es que no obedezca, es que esa norma quedó enterrada bajo 200 líneas de relleno y su atención se diluyó por completo.

El archivo CLAUDE.md (la memoria de proyecto de Claude) es una maravilla si se hace bien, pero una carga si se hace mal. Ocupa parte de tu ventana de contexto en cada sesión: cuanto más abultado sea, menos espacio queda para el trabajo real. Hoy vamos a desmenuzarlo: en qué niveles se divide, qué debe incluir, qué NO debe incluir, cómo referenciar otros archivos y cómo mantenerlo ágil.

Al terminar este artículo, sabrás:

• Qué controlan los tres niveles de CLAUDE.md (Usuario / Proyecto / Subdirectorio) y en qué orden se cargan.
• Una lista de «Qué escribir vs Qué NO escribir», para evitar el error del 90% de los principiantes de llenarlo de relleno.
• La forma correcta de usar la sintaxis @ para referenciar otros archivos, y su coste real en el contexto.
• El método oficial para añadir reglas sobre la marcha en una conversación, más una tabla comparativa de «buenas vs malas» reglas a usar como plantilla.

ℹ️ Este artículo se centra exclusivamente en cómo redactar y mantener el archivo CLAUDE.md. El proceso de generarlo mediante /init ya se cubrió en 12 «Inicialización del proyecto», y la mecánica más amplia de la memoria automática (auto-memory) se reserva para el capítulo 25 «Sistema de memoria».

---

01 Primero lo primero: ¿Qué es exactamente CLAUDE.md?

En conclusión: CLAUDE.md es una "instrucción persistente" que escribes para Claude; en cada nueva sesión, lo lee primero y lo usa como contexto básico del proyecto.

¿Por qué se necesita? Porque cada sesión de Claude Code arranca desde un lienzo en blanco: lo que le explicaste con tanto esfuerzo la última vez («usa pnpm, no toques la carpeta legacy, corre las pruebas así») no lo recuerda. Sin CLAUDE.md, tendrías que repetirle las instrucciones cada vez, ¿y quién quiere hacer eso?

Analogía: El manual de bienvenida para un nuevo empleado. Cuando llega alguien nuevo, no te pasas el día contándole las reglas por voz. Le das un manual: de qué va el proyecto, cómo se envían los commits, qué zonas son minadas. Lo lee y empieza a trabajar. CLAUDE.md es el manual de Claude, con la diferencia de que lo lee cada mañana antes de empezar.

Pero ojo a este detalle clave de la documentación oficial:

El contenido de CLAUDE.md se pasa como un mensaje de usuario a continuación del prompt del sistema, no como parte del prompt del sistema en sí. Claude lo lee e intenta seguirlo, pero no hay garantía de un cumplimiento estricto.

En lenguaje llano: CLAUDE.md es una «recomendación enfática», no una «ley inquebrantable». Modela el comportamiento de Claude, pero no lo fuerza de forma estricta. Así que cuanto más concreto y conciso lo escribas, más probabilidades hay de que lo cumpla. Si quieres bloquear un comando al 100%, eso es trabajo para un Hook (gancho), no para CLAUDE.md (de los Hooks hablaremos más adelante).

¿Cuándo deberías añadir algo a CLAUDE.md? La documentación oficial da señales muy prácticas:

• Claude comete el mismo error por segunda vez — Señal de que esa corrección debe fijarse.
• Tienes que volver a escribir la misma corrección que escribiste en la sesión anterior.
• Durante la revisión de código te das cuenta de que Claude debería haber conocido una convención específica de ese código.
• Un compañero de equipo nuevo necesitaría el mismo contexto para ponerse al día.

💡 Resumen en una frase: CLAUDE.md es el manual que Claude lee al empezar, es de nivel «recomendación enfática» y no de «ley inquebrantable», y cuanto más concreto sea, mejor funciona.

---

02 Tres niveles: ¿Quién controla todo y quién solo un proyecto?

CLAUDE.md no es un solo archivo, puede vivir en distintos sitios y su alcance va de mayor a menor. Aquí es donde los principiantes suelen confundirse, así que aclarémoslo.

Según la documentación, estos son los tres niveles principales (más una variante local):

Nivel	Dónde se guarda	Qué alcance tiene	¿Va en git?
Usuario	~/.claude/CLAUDE.md	Todos los proyectos en tu máquina	No, solo preferencias personales
Proyecto	./CLAUDE.md o ./.claude/CLAUDE.md	El proyecto actual	✅ Sí, se comparte con el equipo
Subdirectorio	cualquier_subdirectorio/CLAUDE.md	Solo cuando Claude lee archivos de ese directorio	✅ Sí, ideal para repositorios multimodular
Local (Variante)	./CLAUDE.local.md	El proyecto actual, solo para ti	❌ Va en .gitignore

Existe también un "Nivel gestionado" (Managed) desplegado por administradores TI en el directorio del sistema (en macOS: /Library/Application Support/ClaudeCode/CLAUDE.md), que se carga antes que el de usuario y no puede saltarse. Los usuarios individuales casi nunca lo tocan, por lo que lo omitimos aquí; para entornos empresariales, consulta la documentación oficial.

¿Cómo repartir el contenido? Recuerda esto: Hábitos personales a nivel de usuario, normas de equipo a nivel de proyecto.

• Nivel de Usuario (~/.claude/CLAUDE.md): Preferencias que aplicas a cualquier proyecto. Por ejemplo: «Responde en español», «Antes de cambiar código, explícame tu plan y no actúes de inmediato», «Usa commits en inglés». No dependen del proyecto, son «tus» costumbres, así que afectan a todos y no se envían a ningún repositorio.
• Nivel de Proyecto (./CLAUDE.md): Reglas exclusivas del proyecto que todo el equipo debe seguir. Tecnologías, comandos de build, estructura de carpetas, cosas que no se deben tocar. Se añade al control de versiones para que los nuevos compañeros lo hereden al clonar.
• Nivel de Subdirectorio: Útil en repositorios grandes. Una carpeta de frontend puede tener sus reglas, y la de backend las suyas. No se cargan por defecto, solo cuando Claude necesite acceder a un archivo de ese directorio, se lleva consigo ese CLAUDE.md local. Ahorra contexto.

La analogía del manual de empleado: El nivel de usuario es tu libreta de apuntes personales (va contigo de trabajo en trabajo); el de proyecto es el reglamento de la empresa (lo devuelves al irte); el de subdirectorio es la normativa específica de un departamento (solo te la dan si trabajas en ese departamento).

Ejemplo típico de nivel de usuario: «Si hay varias formas de hacer algo, dame las opciones para elegir en vez de decidir por mí en silencio». Esto vale para cualquier proyecto, así que ponlo en tu ~/.claude/CLAUDE.md y no tendrás que repetirlo más.

💡 Resumen en una frase: Hábitos personales al nivel de usuario (~/.claude/CLAUDE.md), reglas de equipo al nivel de proyecto (./CLAUDE.md en git), y el nivel de subdirectorio para separar módulos en grandes repositorios.

---

03 Orden de carga: ¿Por qué "quien habla el último, manda"?

Si tienes archivos en los tres niveles, ¿cuál obedece? Esto causa muchas confusiones, aclaremos las reglas.

La regla oficial: Se cargan desde el ámbito más amplio hasta el más específico; cuanto más cerca esté del directorio en el que estás, más tarde se lee.

¿Cómo funciona exactamente? Claude Code empieza desde tu directorio de trabajo actual y sube por la estructura de carpetas; todo CLAUDE.md que encuentre en el camino lo recoge para construir el contexto. El orden aproximado es:

Nivel de Usuario ~/.claude/CLAUDE.md
        ↓ (Se lee primero)
CLAUDE.md de directorios padre (más altos en el árbol)
        ↓
Raíz del proyecto ./CLAUDE.md
        ↓ (Se lee más tarde, es el más cercano)
Nivel de Subdirectorio CLAUDE.md (Solo si Claude lee ese directorio)

Ten en cuenta dos puntos cruciales de la documentación oficial:

Primero: Todos los archivos encontrados se «concatenan», no se «sobrescriben». Entran todos en el contexto; el posterior no anula al anterior. Nivel de usuario y de proyecto funcionan a la vez.

Segundo: Las instrucciones más cercanas al directorio de trabajo "se leen al final". Si hay normas en conflicto (el usuario dice «comillas simples», el proyecto dice «comillas dobles»), la norma del proyecto (por leerse más tarde) suele tener más peso. Es decir, las reglas del proyecto pueden anular tus hábitos personales, que es exactamente lo que busca el trabajo en equipo.

Esta imagen muestra las capas apiladas: Usuario (afecta a todo, se lee primero), Proyecto (el proyecto actual, va en git), Subdirectorio (más cerca del código, domina en conflictos); la flecha derecha indica la carga "de arriba abajo", y la regla de oro: se concatenan, no se sobrescriben; y el más cercano a tu código es el que manda.

Hay que corregir un error muy común en la red. Muchos tutoriales dicen que la prioridad es «Local del proyecto → Raíz del proyecto → Subdirectorio → Global». Eso está al revés de cómo se cargan oficialmente. La documentación es clara: "se cargan desde el ámbito más amplio hasta el más específico", y las instrucciones del proyecto aparecen después de las del usuario. Cíñete a la oficial.

Otro detalle amigable: El CLAUDE.md de la raíz del proyecto se recarga desde disco automáticamente tras hacer un /compact (comprimir diálogo). Pero los de los subdirectorios anidados no se recargarán a menos que Claude vuelva a leer esa carpeta. Así que pon las normas importantes en la raíz.

💡 Resumen en una frase: Múltiples CLAUDE.md se concatenan, no se sobrescriben. Cuanto más cerca del directorio de trabajo, más tarde se lee y más fuerza tiene en un conflicto, por eso el proyecto manda sobre las preferencias personales.

---

04 Qué escribir vs Qué NO escribir

Este es el punto clave. Si un CLAUDE.md falla, el 90% de las veces es porque falta lo importante y sobra la paja.

Lo que SÍ debes escribir — resumido por la documentación oficial en: «Hechos que Claude debe recordar en cada sesión». En forma de lista:

Categoría	Qué poner exactamente	Ejemplo
Resumen del proyecto	En una frase, qué es el proyecto	«Backend de gestión de pedidos en FastAPI»
Tecnologías	Lenguajes, frameworks, bases de datos	«Python 3.11 / PostgreSQL / pytest»
Comandos comunes	Pruebas, build, linter	uv run pytest, uv run ruff check .
Convenciones de código	Estilo, nombres, reglas estrictas	«Toda función debe tener tipado», «Usa comillas dobles»
"No Hacer" (líneas rojas)	Archivos intocables, permisos	«Prohibido modificar archivos antiguos en migrations/»

De aquí, los comandos comunes son lo más consultado: Claude los buscará antes de intentar correr tests o builds, ahorrando errores y adivinanzas. La lista de prohibiciones actúa como barrera para que su inteligencia no te la juegue: carpetas legacy intocables, archivos que no puede editar sin preguntar, o configuraciones secretas que no debe mostrar.

Y ahora lo que NO debes escribir, el mayor peligro para los principiantes:

• ❌ Contexto interminable: Presentaciones corporativas, la historia de por qué se eligió un framework... Claude no lo necesita para picar código, solo gasta contexto.
• ❌ Información obsoleta: Si pasas de npm a pnpm y no lo actualizas, Claude se confundirá.
• ❌ Cosas obvias en el código: No describas cada archivo en la estructura de carpetas, ni repitas el estilo que ya define tu configuración de ESLint. Claude lee el código, repetirle lo obvio es perder el tiempo.

La postura oficial es tajante, marcando límites estrictos:

El objetivo es que cada archivo CLAUDE.md tenga menos de 200 líneas. Los archivos más largos consumen más contexto y reducen el nivel de cumplimiento.

¿Por qué importan tanto esas 200 líneas? Porque CLAUDE.md compite por la misma ventana de contexto de tu conversación. Si metes 300 líneas de relleno, empiezas con un espacio de trabajo mermado, limitando las tareas reales, y, peor aún, las normas importantes se ahogan y bajan en prioridad. Ese es el origen del «manual de 300 líneas ignorado».

Una regla útil: Antes de escribir una norma, pregúntate: "¿Puede Claude deducir esto mirando el código? Si es sí, bórralo." Solo con esto, puedes reducir un CLAUDE.md de 300 a 80 líneas, dejando solo las reglas estrictas que no puede adivinar. Después de la limpieza, notarás cómo deja de usar el gestor de paquetes incorrecto.

💡 Resumen en una frase: Escribe "hechos que deba recordar siempre" (resumen / tecnologías / comandos / convenciones / líneas rojas), elimina todo lo que Claude pueda deducir leyendo el código y mantenlo por debajo de 200 líneas.

---

05 Referenciar otros archivos: Sintaxis @ y su coste

A veces ya tienes documentos de normas en el proyecto (ej: una guía de diseño de API, o normas de base de datos). No hace falta copiar todo eso en CLAUDE.md, puedes usar la sintaxis @ para enlazarlo.

La sintaxis es simple, solo pon @ y la ruta en cualquier sitio de CLAUDE.md:

Para la vista general del proyecto, consulta @README, para comandos disponibles mira @package.json.

# Otras directrices
- Flujo de trabajo de git @docs/git-instructions.md

Al leer CLAUDE.md, Claude desplegará y cargará el contenido de esos archivos en el contexto. Ten en mente estos detalles oficiales para evitar sorpresas:

• Las rutas relativas parten del archivo que hace la referencia, no de tu directorio de trabajo. Es un fallo común.
• Las rutas absolutas también valen; además, los archivos enlazados pueden enlazar otros archivos, hasta una recursión máxima de 4 saltos.
• Si referencia un archivo fuera del proyecto, Claude Code mostrará un cuadro de aprobación; si lo rechazas, se desactivará esa referencia para siempre y no volverá a preguntar.

Pero aquí viene la idea más importante, muy enfatizada por la guía oficial y en la que casi todos caen:

Los archivos importados se expanden y cargan en el contexto al inicio. Dividir en importaciones @path ayuda a organizar, pero no reduce el contexto utilizado, ya que los archivos se cargan en el inicio.

Es decir: La sintaxis @ sirve para "ordenar", no para "ahorrar". Muchos creen que sacando el contenido a otro archivo, el CLAUDE.md se vuelve más corto y el contexto se ahorra... Error. El archivo referenciado se carga entero desde el minuto uno. Imagina mover un manual de 500 líneas con @, crees que adelgazó, pero si consultas /context verás que sigue gastando los mismos tokens.

Así que la regla es: La sintaxis @ es para organizar la lectura humana, pero para ahorrar contexto, debes "recortar contenido" de verdad, no esconderlo en archivos externos. Y cuidado con referenciar archivos individuales que sean gigantes.

Algo relacionado: si tienes preferencias de proyecto totalmente personales que no deben subir a git (como tu URL de pruebas local, o datos de test propios), no los metas en ./CLAUDE.md. Ponlos en ./CLAUDE.local.md y añade este a .gitignore. Se cargará junto al principal y funcionará igual, pero no molestará a tus compañeros ni quedará registrado.

💡 Resumen en una frase: @ruta para traer documentos externos ayuda a "organizar", pero el contenido se carga igual y no ahorra tokens; para ahorrar, recorta; usa CLAUDE.local.md para tus normas personales e ignóralo en git.

---

06 Mantenimiento: Añadir en caliente y limpieza regular

CLAUDE.md no es algo que escribas una vez y te olvides, debe evolucionar con el proyecto. Aquí te enseño dos cosas: cómo añadir normas rápidamente en una conversación y cómo hacer limpieza periódica.

Cómo añadir una norma rápido durante una charla

Suele pasar: corriges a Claude en medio de algo y piensas "esto se lo tengo que recordar siempre, voy a guardarlo". La vía oficial más rápida es decírselo directamente en el chat:

Añade la regla "las operaciones de DB deben ir en la capa Service, no hagas SQL en el enrutador" a CLAUDE.md

Claude se encargará de modificar el archivo. También puedes teclear /memory, que mostrará la lista de todos los archivos CLAUDE.md, CLAUDE.local.md y de reglas cargados en la sesión actual; haz clic en uno para abrirlo en tu editor y modificarlo a mano. Usa la voz si quieres que Claude decida la redacción; usa /memory si quieres control exacto sobre el texto.

ℹ️ Aviso de cambio de versión: En versiones tempranas de Claude Code, iniciar un mensaje con # era un atajo para añadir algo a la memoria. Esa mecánica ha cambiado. Haz caso a la actual: o dile explícitamente «añádelo a CLAUDE.md» o edita a mano con /memory. Si solo dices «recuerda esto», Claude probablemente lo mandará a su memoria automática (auto-memory, tema del artículo 25 "Sistema de memoria"); si quieres asegurarte de que vaya a CLAUDE.md, pídelo tal cual.

Limpieza periódica: eliminar lo viejo y lo contradictorio

Un peligro señalado por la documentación: cuando hay dos reglas que se contradicen, Claude puede elegir cualquiera al azar. Por eso hay que revisar y purgar la basura de vez en cuando. Cuándo hacer limpieza:

• Cambiaste de gestor de paquetes o de build (los comandos viejos engañarán a Claude, bórralos).
• Has añadido o eliminado dependencias importantes.
• Has establecido nuevas normas de código (comprueba que no choquen con las antiguas).
• Te das cuenta de que CLAUDE.md vuelve a superar las 200 líneas.

Para saber si una regla es buena o no, fíjate si suena a "regla" y no a "ensayo". La documentación da una comparativa fantástica que aquí recojo:

❌ Ensayo vago (Inútil)	✅ Regla concreta (Útil)
El código debería estar bastante limpio	Las funciones no superan las 50 líneas, si lo hacen, divídelas
Intenta escribir pruebas	Cada nueva función debe incluir pruebas unitarias
Cuidado con la seguridad	Todo input de usuario pasa por sanitize() antes de hacer consultas
El directorio legacy no importa mucho	Prohibido modificar cualquier archivo dentro de legacy/
Pnpm es mejor	Para dependencias solo usa pnpm, npm y yarn están prohibidos

Las reglas de la izquierda son papel mojado: palabras como "limpio", "intenta", "cuidado" son subjetivas; Claude no puede verificarlas y, por tanto, no puede ejecutarlas de forma estable. Las de la derecha son medibles y verificables: 50 líneas, debe tener prueba, debe pasar por X función. La documentación oficial pide textualmente "escribir instrucciones lo suficientemente concretas como para ser verificables".

Al escribir en CLAUDE.md, acostúmbrate a algo: por cada regla que escribas, hazte la pregunta "¿puedo ver de un vistazo si esto se ha violado?". Si la respuesta es no, tu regla es demasiado vaga, reescríbela para que sea concreta.

💡 Resumen en una frase: Para añadir sobre la marcha dile "añade a CLAUDE.md" o edita tú con /memory; borra periódicamente normas obsoletas o contradictorias; una buena norma se lee como una "regla verificable a simple vista", no como poesía vaga como "limpio" o "intenta".

---

07 Manos a la obra: Crea un CLAUDE.md en condiciones para un proyecto de prueba

La teoría sin práctica no sirve. Vamos a usar un mini proyecto para ver todo el ciclo: "crear archivo → escribir reglas → verificar carga". Sigue estos pasos y tardarás cinco minutos.

Paso 1: Crea un proyecto de prueba e inicializa git (Mac / Linux)

mkdir claude-md-demo
cd claude-md-demo
git init
echo 'def add(a, b):
    return a + b' > main.py

Resultado esperado: Una carpeta claude-md-demo con main.py y un directorio .git. Iniciamos git porque CLAUDE.md debería subir al control de versiones (para compartir con el equipo).

Paso 2: Escribe a mano un CLAUDE.md de proyecto súper resumido

Con tu editor favorito, crea el archivo CLAUDE.md en la raíz y pega esto (nota que son muy pocas líneas; ese es el tamaño que debe tener un buen CLAUDE.md):

# add-demo — Un mini proyecto en Python para demostración

Solo hay una función `add`, se usa para mostrar cómo escribir CLAUDE.md.

## Comandos comunes
- `python -m pytest` —— Ejecutar pruebas

## Convenciones de código
- Todas las funciones deben tener anotaciones de tipado (Type Hints)
- Cadenas siempre con comillas dobles

## Notas importantes
- No modifiques la firma de la función `add` en `main.py`, solo puedes cambiar la lógica interna

Resultado esperado: CLAUDE.md creado en la raíz con estas secciones. Tiene menos de 15 líneas; mantén esta proporción en la cabeza para que no se descontrole en proyectos reales.

Paso 3: Inicia Claude y comprueba que lo ha leído

Lanza Claude desde la carpeta:

claude

Y luego escribe esto para comprobar:

/memory

Resultado esperado: Verás tu ./CLAUDE.md en la lista. Si está ahí, Claude lo ha cargado en su contexto para esta sesión. Este paso es el método oficial para diagnosticar fallos: si una regla no se cumple, lo primero es hacer /memory para ver si el archivo se está cargando siquiera.

Paso 4: Pídele que haga algo "pisando la raya" para ver si respeta la convención

Sal de /memory al chat y escribe:

Añade anotaciones de tipado a la función add

Resultado esperado: El diff que devuelva Claude tendrá la sintaxis de tipado acordada para el proyecto, y además no tocará la firma de la función que habías bloqueado. Si obedece a tu regla "Todas las funciones deben tener anotaciones de tipado"... Felicidades, el manual de bienvenida está en marcha.

⚠️ Si no obedece: Primero verifica /memory para ver si el archivo se ha cargado; luego, comprueba si la norma es demasiado difusa (tipo "limpio"); por último, asegúrate de que no haya normas opuestas chocando. Estos son los tres pasos de depuración recomendados oficialmente y casi siempre resuelven el misterio.

💡 Resumen en una frase: Practica todo el ciclo "Crear → Redactar reglas de <15 líneas → Confirmar carga con /memory → Testear si obedece", si falla usa la ruta oficial: /memory → ¿es difusa? → ¿hay conflicto?.

---

08 Resumen

En este artículo hemos destripado de principio a fin el archivo CLAUDE.md, la "memoria de proyecto" de Claude:

Dimensión	Conclusión Clave
Qué es	El manual inicial para cada sesión, nivel "recomendación", no "ley inquebrantable".
Niveles	Usuario (personal) / Proyecto (equipo en git) / Subdirectorio (opcional)
Orden de carga	Concatenación, no sobrescritura; el más cercano a la zona de trabajo manda en un conflicto
Qué escribir	Resumen / stack / comandos / normas / límites; borra lo que el propio código pueda probar por sí solo
Referencia @	Para ordenar la estructura, no ahorra contexto (carga igual)
Mantenimiento	Que Claude lo añada o hazlo con /memory; limpia lo viejo o contradictorio; haz normas que parezcan reglas, no poesía difusa

A partir de ahora podrás: Decidir si un apunte va en CLAUDE.md y en qué nivel; escribir reglas medibles y verificables; usar @ para referenciar conociendo el gasto en tokens; y saber cuándo añadir o podar en un proyecto antiguo. En definitiva, podrás escribir un CLAUDE.md que Claude sí escuche, sin perder el tiempo en uno de 300 líneas ignorado por todos.

---

El próximo artículo será 19 "Gestión de contexto": Aquí hemos hablado sin parar de "CLAUDE.md come ventana de contexto", "las referencias @ no ahorran contexto"... pero, ¿qué es exactamente esa ventana de contexto, qué pasa si se llena, y cómo funcionan comandos como /context y /compact? En el próximo explicaremos el límite de su "memoria a corto plazo". Una pista: ¿Qué crees que gasta más tokens, un CLAUDE.md o una larga conversación con idas y vueltas?

---

Lecturas recomendadas

• Preguntas frecuentes y Troubleshooting
• Las cuatro tareas más comunes: explorar código, arreglar bugs, refactorizar y escribir pruebas
• Modo de Voz (Voice): Pronuncia tus comandos en lugar de teclearlos