La fiebre por los asistentes de programación ha inundado el mercado de promesas, pero existe una diferencia clave entre un chatbot que simple sugerencias de código y un agente que realmente ayuda: la capacidad de trabajar con un repositorio completo de manera coherente. En ese sentido, entra en juego Claude Code, la herramienta agéntica de Anthropic diseñada para leer bases de código, editar archivos y ejecutar comandos dentro del flujo habitual de desarrollo.
En este enfoque, un archivo Markdown aparentemente simple adquiere un papel central: CLAUDE.md. No es una plantilla decorativa ni un README alternativo. Es, en esencia, el documento que define cómo debe comportarse Claude Code en un proyecto, qué reglas seguir y qué significa “terminado”. Bien estructurado, ayuda a reducir malentendidos, acelerar iteraciones y evitar que el agente “improvise” decisiones inapropiadas.
Qué es CLAUDE.md y por qué es importante
Claude Code trabaja con un concepto clave: el contexto no puede depender únicamente de lo que se le dice en una conversación. Los proyectos reales tienen convenciones, comandos recurrentes, decisiones arquitectónicas y requisitos de validación que no conviene repetir en cada sesión. Por eso, Anthropic distingue dos tipos de memoria persistente:
- Auto memoria: notas que Claude guarda automáticamente acerca de patrones del proyecto, comandos clave o preferencias.
- CLAUDE.md: archivos Markdown que el usuario (o el equipo) escribe y mantiene con instrucciones, reglas y preferencias que el agente debe seguir.
Este reparto define la función de CLAUDE.md: lo normativo. Es decir, el “manual de operación” del repositorio: qué se hace, cómo se hace y qué no se modifica.
Ubicación y niveles de memoria
Uno de los aspectos más útiles del diseño es la jerarquía de memoria, que permite separar instrucciones según su alcance:
- Política gestionada (organización): reglas corporativas gestionadas por IT/DevOps (estándares, cumplimiento, seguridad).
- Memoria del proyecto:
./CLAUDE.mdo./.claude/CLAUDE.md(compartida en el repositorio). - Reglas modulares por tema:
./.claude/rules/*.md(ej, estilo, testing, seguridad, API). - Memoria personal del usuario:
~/.claude/CLAUDE.md(preferencias individuales para todos los proyectos). - Memoria privada del proyecto:
./CLAUDE.local.md(preferencias específicas y privadas de ese repositorio, no versionadas). - Auto memoria: directorio por proyecto en
~/.claude/projects/./memory/
La pieza que suele simplificar mucho la gestión en equipos es CLAUDE.local.md, porque por defecto se añade automáticamente a .gitignore. Esto facilita guardar, por ejemplo, URLs de sandboxes o datos de prueba locales sin “contaminar” el repositorio con información personal o sensible.
Cómo Claude Code “lee” estos archivos
Claude Code carga memorias de forma recursiva:
- Los CLAUDE.md en niveles superiores al directorio de trabajo se cargan completos al iniciar.
- Los CLAUDE.md en subdirectorios se cargan bajo demanda, cuando Claude accede a ellos en una determinada parte del árbol de archivos.
- En caso de conflicto, las instrucciones más específicas prevalecen sobre las más generales.
Este comportamiento resulta muy útil en repositorios grandes: puedes tener un CLAUDE.md general en la raíz y reglas específicas para frontend/, infra/ o src/api/, sin que todo se mezcle sin control.
Imports: reutilización de documentación sin duplicar información
Claude Code permite que CLAUDE.md importe otros archivos usando la sintaxis @path/to/import. La idea es sencilla pero potente: en lugar de copiar comandos o convenciones en múltiples sitios, se pueden importar fuentes existentes (como README, package.json, documentos internos, guías de Git, etc.).
Aspectos importantes a considerar:
- Pueden usarse rutas relativas y absolutas; las rutas relativas se resuelven respecto al archivo que realiza la importación.
- Si Claude detecta importaciones externas (fuera del proyecto), solicita un diálogo de aprobación la primera vez por motivos de seguridad.
- Las importaciones no se evalúan dentro de bloques Markdown para evitar posibles conflictos.
- Las importaciones pueden ser recursivas, con un límite en la profundidad.
Adicionalmente, el comando /memory permite visualizar qué memorias se están cargando y editar archivos de memoria directamente desde el entorno interactivo.
Auto memoria y MEMORY.md: la libreta de notas del agente
En contraposición a CLAUDE.md, auto memory representa “lo que Claude aprende” mientras trabaja. Se guarda en un directorio por proyecto (~/.claude/projects/) con un archivo principal llamado MEMORY.md y posibles archivos temáticos (como debugging.md o api-conventions.md).
Hay una regla clave: solo se cargan automáticamente las primeras 200 líneas de MEMORY.md en cada inicio de sesión. El resto no se carga automáticamente y Claude está configurado para mantener ese índice conciso, moviendo detalles adicionales a archivos temáticos que se cargarán bajo demanda.
La auto memoria puede activarse o desactivarse con /memory, o mediante configuración (~/.claude/settings.json o .claude/settings.json), o mediante variables de entorno para escenarios gestionados o integración continua.
.claude/rules: reglas modulares por temas y rutas según la necesidad del proyecto
Para equipos o repositorios complejos, Anthropic propone reglas modulares en .claude/rules/*.md. En vez de tener todo en un único CLAUDE.md, se pueden separar directrices por temas: estilos, testing, seguridad, APIs, etc.
Además, estas reglas pueden aplicarse condicionalmente por ruta, mediante el uso de frontmatter YAML con un campo paths. Esto permite, por ejemplo, exigir validación de entrada y documentación OpenAPI solo en src/api/, sin afectar otras partes del código.
Cómo perfeccionar un buen CLAUDE.md
Un CLAUDE.md efectivo casi nunca nace perfecto. Se construye como un manual vivo, con iteraciones basadas en el uso real. En Claude Code, el punto de partida suele ser el comando /init, que genera un borrador inicial a partir de la estructura del proyecto. Desde allí, la mejora sigue un patrón recurrente:
- Especificar comandos y flujos: build, test, lint, cómo levantar entorno, cómo reproducir fallos.
- Definir criterios verificables: qué pruebas deben pasar, qué endpoint responder, qué salida se considera correcta.
- Asegurar decisiones sensibles: qué no debe modificarse (estructura, dependencias prohibidas, patrones obligatorios).
- Modularizar cuando crece: trasladar reglas a
.claude/rules/y usar imports para no duplicar contenido. - Mantener apartadas las configuraciones privadas: todo lo local y personal en
CLAUDE.local.md, sin incluirlo en el repositorio.
El objetivo no es redactar un ensayo ni crear reglas excesivamente rígidas. Se trata de reducir ambigüedades. Un agente funciona mejor cuando no tiene que interpretar “qué quería decir” el humano, sino que recibe instrucciones claras y concisas.
Plantilla orientativa breve
# CLAUDE.md — Guía del proyecto ## Contexto - Qué es este repositorio y para qué sirve (2-3 líneas). ## Estructura - Carpeta A: … - Carpeta B: … - Archivos clave: … ## Comandos - Instalar: … - Desarrollo: … - Tests: … - Lint/Formato: … - Build/Release: … ## Convenciones - Naming, estilo, patrones. - Dependencias permitidas/prohibidas. - Qué NO se debe cambiar. ## Definición de “hecho” - Debe pasar: tests, lint, build. - Criterios funcionales verificables.
Preguntas frecuentes
¿Qué es exactamente CLAUDE.md en Claude Code?
Un archivo Markdown con instrucciones persistentes (reglas, convenciones y flujos) que Claude Code carga para trabajar de forma coherente en un proyecto.
¿En qué se diferencia de auto memory (MEMORY.md)?
CLAUDE.md lo escribe el usuario o el equipo (normativas). Auto memory lo genera Claude (notas aprendidas) y solo carga automáticamente las primeras 200 líneas de MEMORY.md.
¿Para qué sirven .claude/rules y las reglas por rutas?
Para dividir reglas por temas y aplicar directrices solo a partes específicas del repositorio mediante patrones de ruta.
¿Cuál es la forma más rápida de empezar?
Usar /init para crear un borrador y perfeccionarlo con comandos reales, criterios verificables y reglas que reduzcan ambigüedades.