En el universo de asistentes de programación, hay una diferencia enorme entre “un chatbot que sugiere código” y un agente capaz de entrar en un repositorio, entenderlo, ejecutar comandos, corregir fallos y verificar resultados con cierta autonomía. Anthropic ha intentado resolver esa diferencia con Claude Code, y una de sus piezas más importantes —y menos comentadas fuera de círculos técnicos— es un simple archivo Markdown: CLAUDE.md.
Lejos de ser un adorno, CLAUDE.md actúa como un manual persistente: un conjunto de instrucciones, reglas y preferencias que se cargan al inicio de cada sesión para que Claude no tenga que “adivinar” cómo se trabaja en ese proyecto. Bien usado, es el documento que reduce iteraciones, evita malentendidos y hace que el agente se comporte de forma consistente a lo largo del tiempo, incluso cuando el contexto de la conversación se comprime o se pierde.
Qué es CLAUDE.md y por qué existe
Según la documentación oficial, Claude Code cuenta con dos tipos de memoria que persisten entre sesiones:
- Memoria automática (auto memory): notas que Claude escribe para sí mismo mientras trabaja (patrones del proyecto, comandos clave, preferencias).
- Archivos CLAUDE.md: documentos que escribe y mantiene el usuario (o el equipo) con instrucciones, reglas y contexto que Claude debe seguir.
La razón de ser de CLAUDE.md es muy práctica: Claude Code opera en un bucle “agéntico” de recopilar contexto → actuar → verificar, repitiendo el ciclo hasta completar la tarea. Si ese agente no dispone de un marco estable (convenciones, estructura, criterios de éxito), tenderá a improvisar, y la improvisación en software suele pagarse en tiempo y errores.
En otras palabras: CLAUDE.md es la forma “oficial” de enseñar al agente cómo se trabaja aquí.
Para qué se usa en el mundo real
En un proyecto normal, CLAUDE.md suele cubrir cuatro bloques que marcan la diferencia:
- Contexto del proyecto: qué es el repositorio, qué problema resuelve, cómo se organiza el código.
- Convenciones y decisiones: estilo, naming, estructura de carpetas, patrones arquitectónicos, librerías aprobadas.
- Flujos de trabajo repetibles: comandos de build, test, lint, cómo levantar el entorno local, cómo generar releases.
- Criterios verificables: qué significa “hecho”, qué pruebas deben pasar, qué salida esperada se considera correcta.
Esto último es clave. La propia guía de buenas prácticas de Claude Code insiste en que el mayor multiplicador de calidad es darle una forma de verificar su trabajo: tests, outputs esperados, capturas de pantalla en UI, checks automáticos. Cuando el agente puede comprobarse a sí mismo, reduce dependencias del usuario como “único bucle de feedback”.
Dónde se coloca y qué niveles existen
Anthropic define una jerarquía de memoria con alcances distintos. En lo esencial, se puede entender así:
- Política gestionada (organización): instrucciones corporativas administradas por IT/DevOps para todos los usuarios.
- Memoria de proyecto:
./CLAUDE.mdo./.claude/CLAUDE.md(lo que el equipo comparte en el repositorio). - Reglas modulares:
./.claude/rules/*.md(dividir por temas: estilo, testing, seguridad, API…). - Memoria de usuario:
~/.claude/CLAUDE.md(preferencias personales que aplican a todos los proyectos). - Memoria local del proyecto:
./CLAUDE.local.md(preferencias privadas para ese repo, diseñada para no versionarse).
El matiz importante: CLAUDE.local.md se añade automáticamente al .gitignore, de forma que es ideal para datos que no deben viajar con el repositorio (URLs de entorno local, rutas internas, preferencias personales). Esto también sugiere una regla de oro: lo compartido va en CLAUDE.md; lo privado, en CLAUDE.local.md; lo sensible, en ninguno.
Cómo funciona por dentro: carga, prioridad e imports
Claude Code aplica reglas muy concretas de carga:
- Los CLAUDE.md situados por encima del directorio de trabajo se cargan completos al inicio.
- Los CLAUDE.md dentro de subdirectorios se cargan “bajo demanda” cuando Claude accede a archivos en esos subárboles.
- La memoria se lee de forma recursiva: desde el directorio actual hacia arriba (hasta antes de la raíz del sistema), incorporando los archivos encontrados.
- En caso de conflicto, las instrucciones más específicas tienen prioridad sobre las más generales.
Además, CLAUDE.md puede importar otros archivos usando sintaxis @ruta/al/archivo. Se permiten rutas absolutas o relativas (resueltas respecto al archivo que hace la importación). Por seguridad, las importaciones externas muestran un diálogo de aprobación la primera vez, las importaciones no se evalúan dentro de bloques de código, y existe una profundidad máxima de importaciones encadenadas.
Este sistema de imports suele ser muy útil para evitar duplicidades: en lugar de copiar comandos de package.json o explicaciones del README, se importa el archivo y se mantiene una sola fuente de verdad.
¿Y la memoria automática? Cómo encaja con CLAUDE.md
Auto memory vive en un directorio por proyecto y tiene un punto de entrada MEMORY.md. Un detalle importante que marca estilo: solo se cargan automáticamente las primeras 200 líneas de MEMORY.md al iniciar sesión. El resto no entra por defecto, y Claude está instruido para mantener ese índice conciso y mover detalles a archivos temáticos (por ejemplo, debugging.md, api-conventions.md, etc.).
Esto convierte CLAUDE.md en el lugar natural para lo normativo (reglas) y auto memory en el lugar para lo aprendido (notas). En proyectos reales, el equilibrio suele ser:
- CLAUDE.md: lo que no debería cambiar cada semana.
- Auto memory: lo que se descubre mientras se trabaja y conviene recordar.
Cómo se refina CLAUDE.md: de borrador a herramienta de precisión
Un CLAUDE.md eficaz rara vez nace perfecto. Se construye por iteración, igual que un buen runbook de operaciones. Un enfoque que encaja con la propia filosofía de Claude Code es convertirlo en un documento vivo que se ajusta tras el uso real.
1) Arrancar con /init y recortar lo que sobra
Claude Code permite iniciar un CLAUDE.md con el comando /init. La recomendación práctica es tratar ese primer resultado como borrador y recortarlo hasta dejar solo lo estable: comandos, estructura, convenciones y criterios de éxito.
2) Convertirlo en “verificable”
Si el documento dice “haz que funcione”, el agente puede interpretar muchas cosas. Si dice “debe pasar npm test, el endpoint /health debe devolver 200 y el build no puede aumentar el tiempo más de X”, el margen de error baja.
3) Modularizar con .claude/rules/
Cuando el archivo crece, la documentación recomienda mover instrucciones a reglas modulares en .claude/rules/. Mantener reglas por tema (testing, seguridad, estilo) facilita que el equipo las revise y evita un único documento inmanejable.
4) Usar imports para no duplicar verdad
Si el repo ya tiene documentación viva (README, docs internas, convenciones), importarla reduce inconsistencias. Menos “copiar-pegar”, más referencia única.
5) Ajustarlo a la realidad del contexto (compaction)
Claude Code advierte de un límite operativo: la ventana de contexto se llena y, cuando se llena, el rendimiento puede degradar y parte de la conversación se compacta o se resume. Por eso, las reglas persistentes deben vivir en CLAUDE.md y no depender de “lo que se dijo al principio del chat”. También se puede añadir una sección de “Compact Instructions” para guiar qué debe preservarse cuando el sistema compacte contexto.
6) Cierre de tarea: mejorar el documento con lo aprendido
Anthropic describe prácticas internas donde, al final de una sesión, se pide a Claude que resuma lo hecho y sugiera mejoras para el propio CLAUDE.md, creando un ciclo de mejora continua de documentación y flujo de trabajo.
Plantilla práctica de CLAUDE.md (orientativa)
# CLAUDE.md — Guía del proyecto## Qué es este proyecto
- Propósito en 2–3 líneas.
- Usuarios objetivo / entorno (web, API, CLI).## Estructura del repositorio
- Carpeta X: ...
- Carpeta Y: ...
- Archivos clave: ...## Flujo de trabajo (comandos)
- Instalar: ...
- Desarrollo: ...
- Tests: ...
- Lint / formato: ...
- Build / release: ...## Convenciones
- Estilo (naming, imports, tipos).
- Patrones (arquitectura, módulos, APIs).
- Qué NO hacer (dependencias prohibidas, anti-patrones).## Definición de “hecho”
- Debe pasar: tests, lint, build.
- Output esperado / criterios funcionales.## Compact Instructions
- Si se compacta contexto, preservar: reglas de seguridad + definición de hecho + comandos.
Errores comunes que convierten CLAUDE.md en un lastre
- Escribir un ensayo en lugar de reglas: demasiada prosa, poca instrucción accionable.
- Mezclar preferencias personales con reglas del equipo: lo personal en
~/.claude/oCLAUDE.local.md. - Guardar secretos o datos sensibles: ni en CLAUDE.md ni en imports.
- No incluir verificación: sin tests, outputs o checks, el usuario se convierte en QA manual.
- Dejarlo obsoleto: un CLAUDE.md desactualizado es peor que ninguno, porque induce al agente a errores consistentes.
Preguntas frecuentes (FAQ)
¿CLAUDE.md es obligatorio para usar Claude Code?
No, pero mejora mucho la consistencia cuando el proyecto tiene reglas, estructura y flujos repetibles.
¿Qué diferencia hay entre CLAUDE.md y la memoria automática?
CLAUDE.md lo escribe el usuario (normas e instrucciones); la memoria automática la escribe Claude (notas y aprendizajes del proyecto).
¿Se puede tener más de un CLAUDE.md en el mismo repositorio?
Sí. Claude Code carga memorias de forma recursiva y puede incorporar CLAUDE.md por subárboles cuando accede a esos directorios.
¿Cuál es la mejor forma de refinar CLAUDE.md sin que se haga enorme?
Mantenerlo conciso, modularizar reglas en .claude/rules/ y usar imports para referenciar documentación existente en vez de duplicarla.
