CLAUDE.md: memoria de proyecto

Qué es CLAUDE.md y para qué sirve

Cada vez que se abre una sesión de Claude Code, el agente arranca con una ventana de contexto vacía. No recuerda lo que ocurrió en sesiones anteriores ni conoce las particularidades del proyecto en el que trabaja. CLAUDE.md resuelve esta limitación: es un archivo de texto en formato markdown que Claude lee automáticamente al inicio de cada conversación, proporcionándole instrucciones persistentes sobre el proyecto.

El contenido de CLAUDE.md se carga en la ventana de contexto como si fuera parte del prompt del sistema. Claude lo trata como contexto orientativo, no como configuración estricta. Cuanto más específicas y concisas sean las instrucciones, con mayor consistencia las seguirá el agente.

CLAUDE.md funciona como la memoria del proyecto: convenciones de código, comandos de build, reglas del equipo y decisiones arquitectónicas que Claude necesita conocer en cada sesión. Sin este archivo, habría que repetir esas instrucciones manualmente cada vez.

Un CLAUDE.md típico incluye información que Claude no puede deducir leyendo el código fuente: comandos específicos de build o test, decisiones de arquitectura, convenciones del equipo y restricciones del entorno de desarrollo.

Ubicaciones y alcance

Los archivos CLAUDE.md se pueden colocar en distintas ubicaciones, cada una con un alcance diferente. Las ubicaciones más específicas tienen prioridad sobre las más generales.

| Alcance | Ubicación | Propósito | Compartido | |---|---|---|---| | Proyecto | ./CLAUDE.md o ./.claude/CLAUDE.md | Instrucciones del equipo para el proyecto | Con el equipo (via control de versiones) | | Usuario | ~/.claude/CLAUDE.md | Preferencias personales para todos los proyectos | Solo contigo | | Local | ./CLAUDE.local.md | Preferencias personales para un proyecto concreto | Solo contigo (no se sube a Git) | | Gestionado (managed) | Directorio del sistema operativo | Instrucciones de la organización, gestionadas por IT | Toda la organización |

flowchart TD
    A["Managed policy<br>(Organización)"] --> B["Usuario<br>(~/.claude/CLAUDE.md)"]
    B --> C["Proyecto<br>(./CLAUDE.md)"]
    C --> D["Local<br>(./CLAUDE.local.md)"]
    D --> E["Contexto final<br>de la sesión"]

Claude Code resuelve los archivos CLAUDE.md recorriendo el árbol de directorios hacia arriba desde el directorio de trabajo. Si se ejecuta Claude Code en foo/bar/, cargará tanto foo/bar/CLAUDE.md como foo/CLAUDE.md. Los archivos CLAUDE.md en subdirectorios del directorio de trabajo se cargan bajo demanda, cuando Claude accede a archivos en esas carpetas.

CLAUDE.md de proyecto

Es el archivo más habitual. Se coloca en la raíz del repositorio como ./CLAUDE.md o dentro de ./.claude/CLAUDE.md, y se comparte con el equipo a través del control de versiones. Debe contener instrucciones que apliquen a cualquier persona que trabaje en el proyecto.

Para generar un CLAUDE.md inicial de forma automática, se puede ejecutar el comando /init dentro de una sesión interactiva. Claude analiza el proyecto (sistema de build, framework de tests, patrones de código) y genera un archivo base con las convenciones que detecta. Si ya existe un CLAUDE.md, /init sugiere mejoras en lugar de sobrescribirlo.

CLAUDE.local.md

Cuando hay preferencias que solo aplican a tu máquina (URLs de sandbox, datos de prueba personales, atajos propios), se colocan en ./CLAUDE.local.md. Este archivo se carga automáticamente y Claude Code lo añade al .gitignore, de modo que no se sube al repositorio.

CLAUDE.md de usuario

El archivo ~/.claude/CLAUDE.md aplica a todos los proyectos en los que trabajes. Es el lugar adecuado para preferencias de estilo de código personales, atajos de herramientas o convenciones que usas de forma transversal.

Escribir instrucciones efectivas

La calidad de las instrucciones en CLAUDE.md afecta directamente a la consistencia con la que Claude las sigue. Tres principios guían la escritura de instrucciones efectivas: tamaño, estructura y especificidad.

Tamaño

El objetivo es mantener cada archivo por debajo de 200 líneas. Los archivos más largos consumen más contexto y reducen la adherencia del agente a las instrucciones. Si las instrucciones crecen demasiado, conviene dividirlas usando imports o archivos de reglas en .claude/rules/.

Estructura

Utilizar encabezados markdown y listas para agrupar instrucciones relacionadas. Claude procesa la estructura de forma similar a como lo hace un lector humano: secciones organizadas son más fáciles de seguir que párrafos densos.

Especificidad

Las instrucciones concretas y verificables funcionan mejor que las genéricas:

• Bien: "Los handlers de API van en src/api/handlers/"

• Mal: "Mantén los archivos organizados"

• Bien: "Ejecuta npm test antes de hacer commit"

• Mal: "Testea tus cambios"

• Bien: "Usa indentación de 2 espacios"

• Mal: "Formatea el código correctamente"

Las instrucciones de CLAUDE.md deben ser lo bastante concretas como para poder verificar si se están cumpliendo o no. Si una instrucción es demasiado vaga, Claude la interpretará a su criterio.

Ejemplo de CLAUDE.md

# Comandos de build y test
- Build: `npm run build`
- Tests: `npm test -- --watch`
- Lint: `npm run lint`
- Un solo test: `npm test -- path/al/test.spec.ts`

# Estilo de codigo
- Usar ES modules (import/export), no CommonJS (require)
- Desestructurar imports cuando sea posible
- Indentacion de 2 espacios
- Comillas simples para strings

# Flujo de trabajo
- Ejecutar typecheck despues de cada serie de cambios de codigo
- Preferir ejecutar tests individuales, no la suite completa
- Commits en ingles, formato conventional commits

# Arquitectura
- API REST en src/api/, cada recurso en su propia carpeta
- Base de datos PostgreSQL, migraciones en db/migrations/
- Variables de entorno en .env.example (nunca en .env)

Cada línea del archivo debe superar un filtro sencillo: "Si elimino esta instrucción, Claude cometería errores?" Si la respuesta es no, se puede eliminar.

Importar archivos adicionales

Los archivos CLAUDE.md pueden importar otros archivos usando la sintaxis @ruta/al/archivo. Los archivos importados se expanden y se cargan en el contexto junto al CLAUDE.md que los referencia.

Consulta @README.md para la descripcion del proyecto y @package.json para los comandos npm disponibles.

# Instrucciones adicionales
- Flujo de Git: @docs/git-instructions.md
- Preferencias personales: @~/.claude/my-project-instructions.md

Se admiten tanto rutas relativas como absolutas. Las rutas relativas se resuelven respecto al archivo que contiene el import, no respecto al directorio de trabajo. Los archivos importados pueden a su vez importar otros archivos, con un máximo de cinco niveles de profundidad.

La primera vez que Claude Code encuentra imports externos en un proyecto, muestra un cuadro de aprobación con la lista de archivos. Si se rechaza, los imports quedan desactivados.

Organizar reglas con .claude/rules/

Para proyectos grandes, las instrucciones se pueden organizar en archivos individuales dentro del directorio .claude/rules/. Cada archivo cubre un tema específico, con un nombre descriptivo como testing.md o api-design.md:

mi-proyecto/
  .claude/
    CLAUDE.md
    rules/
      code-style.md
      testing.md
      security.md

Los archivos .md dentro de rules/ se descubren de forma recursiva, lo que permite organizarlos en subdirectorios como frontend/ o backend/.

Reglas con alcance por ruta

Las reglas pueden restringirse a archivos específicos usando frontmatter YAML con el campo paths. Estas reglas condicionales solo se aplican cuando Claude trabaja con archivos que coinciden con los patrones indicados:

---
paths:
  - "src/api/**/*.ts"
---

# Reglas de desarrollo de API

- Todos los endpoints deben incluir validacion de entrada
- Usar el formato estandar de respuesta de error
- Incluir comentarios de documentacion OpenAPI

Las reglas sin campo paths se cargan incondicionalmente y aplican a todos los archivos. Las reglas con paths se activan cuando Claude lee archivos que coinciden con el patrón.

| Patrón | Coincide con | |---|---| | **/*.ts | Todos los archivos TypeScript en cualquier directorio | | src/**/* | Todos los archivos bajo src/ | | *.md | Archivos markdown en la raíz del proyecto | | src/components/*.tsx | Componentes React en un directorio concreto |

Memoria automática (auto memory)

Junto a los archivos CLAUDE.md que escribe el desarrollador, Claude Code cuenta con un segundo mecanismo de memoria: la memoria automática. Claude escribe notas para sí mismo conforme trabaja: comandos de build, patrones de depuración, notas de arquitectura, preferencias de estilo de código y hábitos de flujo de trabajo.

La memoria automática está activada por defecto. Se puede alternar desde /memory dentro de una sesión o mediante la configuración autoMemoryEnabled en los settings del proyecto.

Almacenamiento

Cada proyecto tiene su propio directorio de memoria en ~/.claude/projects/<proyecto>/memory/. El directorio contiene un archivo MEMORY.md como punto de entrada y archivos de temas opcionales:

~/.claude/projects/<proyecto>/memory/
  MEMORY.md
  debugging.md
  api-conventions.md

Las primeras 200 líneas de MEMORY.md se cargan al inicio de cada conversación. El contenido que supere ese límite no se carga automáticamente, aunque Claude puede acceder a él bajo demanda. Los archivos de temas como debugging.md tampoco se cargan al inicio: Claude los lee cuando necesita la información.

Gestionar la memoria

El comando /memory lista todos los archivos CLAUDE.md y reglas cargados en la sesión actual, permite alternar la memoria automática y ofrece un enlace para abrir la carpeta de memoria. Todos los archivos de memoria son markdown plano que se puede editar o eliminar en cualquier momento.

Cuando se pide a Claude que recuerde algo (por ejemplo, "usa siempre pnpm, no npm"), Claude lo guarda en la memoria automática. Para añadir instrucciones a CLAUDE.md en su lugar, hay que pedirlo explícitamente ("añade esto a CLAUDE.md") o editar el archivo manualmente desde /memory.

La diferencia clave entre CLAUDE.md y la memoria automática es quién escribe cada una. CLAUDE.md lo escribe el desarrollador con instrucciones para el agente. La memoria automática la escribe Claude con aprendizajes que acumula a partir de correcciones y patrones que descubre.

Resolución de problemas

Cuando Claude no sigue las instrucciones del CLAUDE.md, el problema suele estar en una de estas causas:

• Instrucciones contradictorias: si dos archivos dan indicaciones distintas para el mismo comportamiento, Claude puede elegir una de forma arbitraria. Revisar todos los CLAUDE.md, los archivos en subdirectorios y los .claude/rules/ para eliminar conflictos.

• Instrucciones vagas: "Usa indentación de 2 espacios" funciona mejor que "Formatea el código correctamente".

• Archivo no cargado: ejecutar /memory para verificar que el CLAUDE.md aparece en la lista de archivos cargados. Si no aparece, Claude no puede verlo.

• Archivo demasiado largo: por encima de 200 líneas, las instrucciones importantes se pierden entre el ruido. Mover contenido detallado a archivos separados referenciados con @imports o dividirlo en .claude/rules/.

• Instrucción perdida tras compactación: CLAUDE.md sobrevive intacto a la compactación. Tras /compact, Claude relee el CLAUDE.md del disco y lo reinyecta en la sesión. Si una instrucción desapareció tras compactar, es que se proporcionó solo en la conversación y no estaba escrita en CLAUDE.md.