CLAUDE.md: memoria de empresa vs. memoria del repositorio

Módulo 4 · Configuración y personalización · Lección 2 de 5

Al terminar esta lección sabrás usar CLAUDE.md como memoria persistente del proyecto, para dejar de volver a explicar las mismas cosas en cada sesión.

CLAUDE.md es la memoria persistente de tu proyecto.

La jerarquía de memoria

Cinco ámbitos, cargados del más amplio al más específico

Los archivos CLAUDE.md pueden estar en varias ubicaciones. No se sobrescriben entre sí: se concatenan. Claude los lee todos, desde el ámbito más amplio hasta el más específico, de modo que una instrucción del proyecto aparece en el contexto después de una política de toda la organización.

Ámbito	Descripción	Ubicación
Managed Policy · Toda la organización	Desplegada por TI mediante gestión de configuración. Se aplica a todas las sesiones de la máquina. Los desarrolladores no pueden excluirla. Siempre se carga.	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
User · Valores personales	Tus preferencias en todos los proyectos: estilo de código, enfoque para el manejo de errores, atajos personales. Te sigue a todas partes.	~/.claude/CLAUDE.md
Project · Instrucciones del equipo	Decisiones de arquitectura, estándares de código, comandos de compilación y flujos de trabajo habituales. Se confirma en el control de versiones y se comparte con el equipo. Es el más importante de acertar.	./CLAUDE.md o ./.claude/CLAUDE.md
Local · Notas personales del proyecto	Tus URLs de sandbox, datos de prueba personales o notas que no quieres confirmar. Añade CLAUDE.local.md a .gitignore.	./CLAUDE.local.md

En repositorios grandes, los archivos CLAUDE.md de los subdirectorios se cargan bajo demanda, cuando Claude lee archivos de esa carpeta, en lugar de al inicio de la sesión. En un monorepo, tus directorios frontend/, backend/ y test-cases/ pueden tener cada uno su propio CLAUDE.md con contexto relevante para ese módulo. Claude los carga solo cuando trabaja en esas carpetas, manteniendo ligero el contexto inicial.

flowchart TD
    A["Managed Policy (TI): siempre cargado"] --> B["User: ~/.claude/CLAUDE.md"]
    B --> C["Project: ./CLAUDE.md o ./.claude/CLAUDE.md"]
    C --> D["Local: ./CLAUDE.local.md"]
    D --> E["Contexto de la sesión (se concatenan)"]
    F["Claude lee archivos de un subdirectorio"] -.->|"carga bajo demanda"| G["CLAUDE.md del subdirectorio"]

Qué incluir

Escribe lo que volverías a explicar en cada sesión

La prueba para incluir algo es sencilla: si lo escribiste en el chat la sesión anterior, debe ir en CLAUDE.md. Si Claude lo hace bien sin la regla, elimínala.

Añade algo a CLAUDE.md cuando Claude cometa el mismo error dos veces, cuando una revisión de código detecte algo que Claude debería haber sabido sobre este código base, cuando repitas en el chat la misma corrección que escribiste la sesión anterior o cuando un nuevo miembro del equipo necesitaría el mismo contexto para ser productivo. Mantenlo en hechos que Claude debe conocer en todas las sesiones: comandos de compilación, convenciones de nombres, decisiones de arquitectura y reglas de tipo «haz siempre X». Si una entrada es un procedimiento de varios pasos o solo importa para una parte del código base, muévela a una skill o a una regla con alcance por ruta.

La regla de poda

Si Claude lo hace bien sin la instrucción, elimina la instrucción. Los archivos CLAUDE.md inflados degradan la adherencia: más corto es más efectivo.

Escribir de forma que funcione

Lo específico gana a lo general, siempre

Las instrucciones de CLAUDE.md se cargan como contexto, no como configuración aplicada. La forma en que las escribes determina con qué consistencia Claude las sigue.

Enfoque	Ejemplo	Resultado
Vago	Formatea bien el código	No funciona. Es demasiado abstracto para actuar. Claude podría interpretar «bien» de forma distinta en cada sesión. Nada de esta instrucción se puede verificar.
Específico	Usa indentación de 2 espacios. Ejecuta npm test antes de hacer commit.	Funciona. Es lo bastante concreto para verificarlo. Claude puede comprobar si cumplió la regla, y los revisores también.

Apunta a menos de 200 líneas por archivo CLAUDE.md. Los archivos más largos consumen más contexto y reducen la adherencia. Usa encabezados markdown para agrupar instrucciones relacionadas. Enlaza la documentación con la sintaxis @ruta/al/archivo en lugar de copiar su contenido: el archivo importado se carga al inicio de la sesión junto con el CLAUDE.md que lo referencia. Ejecuta /init en un proyecto nuevo para generar un CLAUDE.md automáticamente: Claude analiza tu código base y redacta comandos de compilación, convenciones y estructura del proyecto. Afínalo a partir de ahí.

En un monorepo, la jerarquía trabaja a tu favor

Los repositorios de clientes empresariales rara vez son un único código base. La jerarquía de CLAUDE.md está diseñada para ello. Cada módulo lleva su propio contexto y Claude lo carga solo cuando es relevante.

Un monorepo empresarial bien estructurado puede tener archivos CLAUDE.md en la raíz del monorepo (visión general del sistema, estructura de equipos, estrategia de modernización), en cada frontera de servicio (diseño de API, modelos de datos y arquitectura de servicios para el backend; patrones de UI y librería de componentes para el frontend) y en el directorio de casos de prueba (requisitos de cobertura, estrategia de automatización). El CLAUDE.md de la raíz se carga en cada sesión. Los archivos de subdirectorios se cargan bajo demanda, cuando Claude toca archivos de esa área. Si los archivos CLAUDE.md de otro equipo se cargan y generan ruido, usa claudeMdExcludes en tu configuración local para omitirlos. Esto funciona desde cualquier ámbito excepto la política gestionada.

Comprueba tu comprensión

Cuatro afirmaciones sobre CLAUDE.md. ¿Verdadero o falso?

Estos son los malentendidos que más aparecen cuando los equipos configuran Claude Code por primera vez en un engagement. Indica si cada afirmación es verdadera o falsa y revisa la respuesta.

1. «Las instrucciones de CLAUDE.md se aplican de forma obligatoria. Claude debe seguirlas pase lo que pase en la sesión.»

Ver respuesta

Falso. El contenido de CLAUDE.md se carga como contexto, no como configuración obligatoria. Claude lo lee e intenta seguirlo, pero no hay garantía de cumplimiento estricto, sobre todo con instrucciones vagas o contradictorias. Para una aplicación estricta en un evento del ciclo de vida, escribe un hook en su lugar.

2. «El CLAUDE.md del proyecto es el lugar adecuado para guardar URLs de sandbox personales y datos de prueba.»

Ver respuesta

Falso. El CLAUDE.md del proyecto se confirma en el control de versiones y se comparte con el equipo. Las notas personales y las específicas de tu máquina van en CLAUDE.local.md, que debe añadirse a .gitignore para que nunca salga de tu máquina.

3. «Ejecutar /init en un proyecto que ya tiene CLAUDE.md sobrescribirá el archivo existente.»

Ver respuesta

Falso. Si ya existe un CLAUDE.md, /init sugiere mejoras en lugar de sobrescribirlo. Es seguro ejecutarlo en cualquier momento del engagement como forma de detectar lo que Claude ha inferido sobre el proyecto y que todavía no has escrito.

4. «Los desarrolladores pueden excluir un CLAUDE.md gestionado de toda la organización usando claudeMdExcludes en su configuración local.»

Ver respuesta

Falso. claudeMdExcludes funciona con los archivos CLAUDE.md de usuario, de proyecto y locales, pero los archivos de política gestionada no pueden excluirse. Es por diseño: si TI desplegó un CLAUDE.md para toda la organización, se aplica a cada sesión de la máquina y los desarrolladores no pueden optar por no usarlo.

La distinción clave: CLAUDE.md da forma al comportamiento de Claude. No es una capa de restricciones. Para un comportamiento que debas imponer sin excepciones, usa hooks (que se ejecutan como comandos de shell en eventos fijos del ciclo de vida) o managed settings (que se aplican antes de que Claude se ejecute). CLAUDE.md es potente para la gran mayoría de las indicaciones de equipo y de proyecto; solo escribe instrucciones específicas, concisas y verificables, y poda las que ya no hagan falta.

Simulación: El engagement Whitmore

Estás en tu cuarto día de un nuevo engagement en Whitmore Group, configurando cómo Claude recuerda este código base.

Decisión 1 de 3 · El registro de arquitectura

El equipo de plataforma de Whitmore tiene un registro de decisiones de arquitectura de 60 páginas. Quieren que Claude conozca todo. ¿Cómo lo tratas en CLAUDE.md?

• A. Pegar el registro completo: pegar las 60 páginas en CLAUDE.md.
• B. Resumir y referenciar con @: escribir un resumen de arquitectura de 3 párrafos y referenciar el documento completo con @docs/architecture.md.
• C. Solo comandos de compilación: omitir la arquitectura y añadir solo los comandos de compilación y los ejecutores de pruebas.

Ver respuesta

• A · 0 puntos. Incorrecta. Esto satura el contexto de Claude y entierra las instrucciones que cambian el comportamiento. CLAUDE.md no es un volcado de documentación: es una capa de señal seleccionada.
• B · 2 puntos (mejor opción). Correcta. El patrón de referencia con @ permite a Claude traer el detalle completo cuando es relevante, sin cargarlo en cada sesión. Señal sobre volumen.
• C · 1 punto (parcial). Demasiado mínimo. Los comandos de compilación son esenciales, pero omitir el contexto de arquitectura significa que Claude tomará decisiones de diseño sin entender las restricciones de la plataforma.

Decisión 2 de 3 · Un error recurrente

Dos semanas después, Claude sigue sugiriendo un patrón ORM obsoleto que el equipo abandonó hace 6 meses. ¿Qué haces?

• A. Escalar a Anthropic: es un problema de comportamiento del modelo.
• B. Añadir una entrada «Qué NO hacer»: incluir en CLAUDE.md una entrada que señale explícitamente el patrón obsoleto.
• C. Corregirlo en cada sesión: repetir la corrección en la conversación.

Ver respuesta

• A · 0 puntos. Incorrecta. Esto no es un problema del modelo. Claude no puede saber de una migración hecha hace 6 meses a menos que alguien se lo diga. La solución está en CLAUDE.md.
• B · 2 puntos (mejor opción). Correcta. La sección «Qué NO hacer» existe exactamente para esto. Las prohibiciones explícitas son más fiables que esperar a que Claude infiera algo del código base.
• C · 1 punto (parcial). Funciona en parte. Esto lo arregla sesión a sesión, pero se reinicia cada vez. Estás haciendo el mismo trabajo repetidamente en lugar de codificar la decisión una sola vez.

Decisión 3 de 3 · Escalar el archivo

Un ingeniero de Whitmore pregunta: «Nuestro CLAUDE.md se está haciendo largo. ¿Deberíamos separar las preferencias personales?» ¿Qué le aconsejas?

• A. Mover al archivo de nivel User: las preferencias personales van en el CLAUDE.md de usuario (~/.claude/CLAUDE.md), no en el del repositorio.
• B. Mantener un solo archivo: dejar todo en un único CLAUDE.md por simplicidad.
• C. Eliminarlas: las preferencias personales no tienen cabida en Claude.

Ver respuesta

• A · 2 puntos (mejor opción). Correcta. El CLAUDE.md del repositorio es para el proyecto. Las preferencias personales te siguen entre proyectos a través del archivo de nivel User. Mezclarlas contamina el contexto compartido con preferencias individuales.
• B · 1 punto (parcial). Simple ahora, frágil después. El archivo acumulará preferencias personales con el tiempo. Cuando cambie el equipo, los futuros desarrolladores se confundirán con instrucciones pensadas para el flujo de trabajo de una sola persona.
• C · 0 puntos. Incorrecta. Las preferencias personales son exactamente para lo que sirve el CLAUDE.md de nivel User. Eliminarlas pierde el beneficio de un flujo de trabajo personal coherente en todos los proyectos.

Ver cierre de la simulación

• 5–6 puntos · Instrumento de precisión. Bien informado. Tratas CLAUDE.md como un instrumento de precisión: señal seleccionada, no almacenamiento de documentación. Lleva este criterio al artefacto.
• 3–4 puntos · Estructura sólida. Buen instinto para la estructura. La brecha suele estar en saber qué nivel contiene qué: personal, de proyecto o de equipo. Vuelve a leer las consecuencias de los pasos en los que perdiste puntos.
• 0–2 puntos · Vuelve a ejecutar la configuración. CLAUDE.md es la configuración con mayor apalancamiento de este curso. Vale la pena crear uno desde cero en un repositorio real antes del engagement y después repetir el escenario.

Artefacto del curso

Contribución de la lección 2: CLAUDE.md + catálogo de slash commands

Al terminar este curso tendrás un CLAUDE.md configurado y un comando slash personalizado listo para desplegar en un engagement con un cliente. Esta lección aporta el CLAUDE.md a nivel de repositorio para tu proyecto de ejemplo.

1. Crea un CLAUDE.md en la raíz de tu repositorio de ejemplo. Empieza con una sección ## Build & Test que contenga los comandos exactos necesarios para compilar y ejecutar las pruebas. Son las instrucciones que Claude necesita en cada sesión.
2. Añade una sección ## Architecture. Escribe de 2 a 3 frases sobre la estructura del proyecto y sobre cualquier decisión de arquitectura no obvia. Usa @ruta/al/documento para referenciar la documentación existente en lugar de duplicarla.
3. Añade una sección ## Code Style con de 2 a 3 reglas específicas y verificables. Aplica la prueba de lo vago a lo específico: cada regla debe poder comprobarse. Si tuvieras que hacer un juicio para verificarla, es demasiado vaga.

Ideas clave

Ya puedes enseñarle a Claude tu repositorio. En cada sesión.

La jerarquía de CLAUDE.md te permite superponer instrucciones desde la política de toda la organización hasta las notas personales del proyecto. Escribe reglas específicas, concisas y verificables, y poda las que ya no hagan falta. Esa es toda la disciplina.

• CLAUDE.md se concatena desde la política gestionada hasta las notas locales, de lo más amplio a lo más específico. Los archivos de subdirectorios se cargan bajo demanda.
• Incluye lo que Claude necesitaría volver a explicar en cada sesión, y elimina las instrucciones que Claude ya cumple sin ellas.
• Escribe instrucciones específicas y verificables, y mantén cada archivo por debajo de 200 líneas.
• CLAUDE.md orienta el comportamiento; no es una restricción. Para imponer algo sin excepciones, usa hooks o managed settings.
• El CLAUDE.md del proyecto se comparte con el equipo; las notas personales van en CLAUDE.local.md.

Siguiente: settings.json vs. settings.local.json