La fiebre de los asistentes de programación ha llenado el mercado de promesas, pero hay una diferencia práctica que separa a un chatbot “que sugiere código” de un agente que realmente ayuda: la capacidad de trabajar con un repositorio completo de forma consistente. Ahí es donde entra Claude Code, la herramienta agéntica de Anthropic diseñada para leer una base de código, editar archivos y ejecutar comandos dentro del flujo habitual de desarrollo.

En ese enfoque, un archivo Markdown aparentemente banal se vuelve 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 debe seguir y qué significa “terminado”. Bien planteado, reduce malentendidos, acelera iteraciones y evita que el agente “improvise” decisiones que no debería tomar.

Qué es CLAUDE.md y por qué importa

Claude Code trabaja con una idea clave: el contexto no puede depender solo de lo que se le diga 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 formas de memoria persistente:

• Auto memory: notas que Claude guarda automáticamente sobre patrones del proyecto, comandos clave o preferencias.
• CLAUDE.md: archivos Markdown que escribe y mantiene el usuario (o el equipo) con instrucciones, reglas y preferencias que el agente debe seguir.

Ese reparto define el papel de CLAUDE.md: lo normativo. Es decir, el “manual de operación” del repo: qué se hace, cómo se hace y qué no se toca.

Dónde se coloca y qué niveles de memoria existen

Uno de los puntos 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 administradas por IT/DevOps (estándares, compliance, seguridad).
• Memoria de proyecto: ./CLAUDE.md o ./.claude/CLAUDE.md (compartida en el repositorio).
• Reglas modulares de proyecto: ./.claude/rules/*.md (por temas: estilo, testing, seguridad, API…).
• Memoria de usuario: ~/.claude/CLAUDE.md (preferencias personales para todos los proyectos).
• Memoria local del proyecto: ./CLAUDE.local.md (preferencias privadas de ese repo, pensada para no versionarse).
• Auto memory: directorio por proyecto en ~/.claude/projects/<project>/memory/.

La pieza que suele ahorrar más dolores de cabeza en equipos es CLAUDE.local.md, porque se añade automáticamente a .gitignore. Eso permite guardar, por ejemplo, URLs de sandbox o datos de prueba locales sin “contaminar” el repositorio con información personal o no compartible.

Cómo “lee” Claude Code esos archivos

Claude Code carga memorias de forma recursiva:

• Los CLAUDE.md por encima del directorio de trabajo se cargan completos al iniciar.
• Los CLAUDE.md en subdirectorios se cargan bajo demanda, cuando Claude entra a trabajar en esos árboles.
• Si hay conflicto, las instrucciones más específicas tienen prioridad sobre las más generales.

Este comportamiento es muy útil en repositorios grandes: se puede tener un CLAUDE.md general en la raíz y, además, reglas específicas para frontend/, infra/ o src/api/ sin que todo se mezcle indiscriminadamente.

Imports: reutilizar documentación sin duplicar “verdad”

Claude Code permite que CLAUDE.md importe otros archivos usando sintaxis @path/to/import. La idea es obvia, pero potente: en lugar de copiar comandos o convenciones en varios sitios, se pueden importar fuentes ya existentes (README, package.json, documentos internos, guías de Git, etc.).

Hay matices importantes:

• Se permiten rutas relativas y absolutas; las rutas relativas se resuelven respecto al archivo que contiene la importación.
• Si Claude Code detecta importaciones externas (fuera del proyecto), muestra un diálogo de aprobación la primera vez por seguridad.
• Las importaciones no se evalúan dentro de bloques de código Markdown para evitar colisiones.
• Los imports pueden ser recursivos, con un límite de profundidad.

Además, el comando /memory permite ver qué memorias se están cargando y editar archivos de memoria desde el propio entorno interactivo.

Auto memory y MEMORY.md: el cuaderno de notas del agente

A diferencia de CLAUDE.md, auto memory es “lo que Claude aprende” mientras trabaja. Se guarda en un directorio por proyecto (~/.claude/projects/<project>/memory/) con un archivo de entrada llamado MEMORY.md y posibles ficheros temáticos (por ejemplo, debugging.md o api-conventions.md).

Aquí hay una regla de funcionamiento crítica: solo se cargan automáticamente las primeras 200 líneas de MEMORY.md al inicio de cada sesión. El resto no entra por defecto, y Claude está instruido para mantener ese índice conciso y mover detalles a ficheros temáticos que leerá bajo demanda.

Auto memory se puede activar o desactivar desde /memory, y también mediante configuración (~/.claude/settings.json o .claude/settings.json) o una variable de entorno pensada para escenarios gestionados o CI.

.claude/rules: cuando el proyecto necesita reglas por temas (y por rutas)

Para equipos o repositorios complejos, Anthropic propone reglas modulares en .claude/rules/*.md. En vez de meterlo todo en un solo CLAUDE.md, se pueden separar directrices por tema: estilo, testing, seguridad, APIs, etc.

Además, estas reglas pueden ser condicionales por ruta, usando frontmatter YAML con un campo paths. Eso permite, por ejemplo, exigir validación de entrada y documentación OpenAPI solo para src/api/**, sin imponerlo a todo el repositorio.

Cómo se refina un buen CLAUDE.md

Un CLAUDE.md efectivo rara vez nace perfecto. Se construye como un buen runbook: con iteraciones basadas en uso real. En Claude Code, el punto de arranque suele ser el comando /init, que genera un primer borrador a partir de la estructura del proyecto. A partir de ahí, la mejora suele seguir un patrón bastante estable:

1. Concretar comandos y flujos: build, test, lint, cómo levantar entorno, cómo reproducir bugs.
2. Definir criterios verificables: qué tests deben pasar, qué endpoint debe responder, qué salida se considera correcta.
3. Bloquear decisiones sensibles: lo que no se debe tocar (estructura, dependencias prohibidas, patrones obligatorios).
4. Modularizar cuando crece: mover reglas a .claude/rules/ y usar imports para no duplicar documentación.
5. Separar lo privado: todo lo local y personal a CLAUDE.local.md, nunca al repositorio.

El objetivo no es escribir un ensayo. Es reducir ambigüedad. Un agente rinde más cuando no tiene que interpretar “qué quería decir” el humano.

Plantilla breve (orientativa)

# 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 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 consistente en un proyecto.

¿En qué se diferencia de auto memory (MEMORY.md)?
CLAUDE.md lo escribe el usuario/equipo (normas). Auto memory lo escribe 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 directrices por temas y aplicar reglas solo a partes concretas del repositorio mediante patrones de ruta.

¿Cuál es la forma más rápida de empezar?
Usar /init para generar un borrador y refinarlo con comandos reales, criterios verificables y reglas que eviten ambigüedad.

Referencia: Volver a programar y ¿Qué es Claude.md?