Preludio

Considera un monorepo con catorce paquetes. Un frontend en React, una API en Node.js, una biblioteca compartida en TypeScript, una herramienta CLI, tres microservicios en Go, infraestructura como código en Terraform y un puñado de paquetes utilitarios que conectan todo entre sí.

Cada paquete tiene su propio sistema de compilación, sus propios patrones de testing, sus propias convenciones. El enfoque inicial suele ser un único archivo CLAUDE.md en el directorio raíz. Enorme. Más de cuatrocientas líneas de instrucciones que cubren cada paquete, cada comando de compilación, cada convención de código.

Funciona, técnicamente. Claude Code lo lee y sigue las instrucciones. Pero es lento de cargar, consume una parte significativa de la ventana de contexto y la mayor parte de la información es irrelevante para lo que sea que se esté trabajando en un momento dado.

Claude Code no lee solo un archivo CLAUDE.md. Recorre el árbol de directorios. Lee un archivo a nivel raíz para el contexto compartido y archivos en subdirectorios para el contexto específico de cada paquete. Soporta un directorio .claude/rules/ para reglas con alcance por patrones glob. Incluso tiene una variante local, CLAUDE.local.md, para preferencias personales que no deberían ser enviadas al control de versiones.

Una vez que se comprende esta jerarquía, toda la configuración de CLAUDE.md puede reestructurarse. El archivo raíz se reduce a sesenta líneas de convenciones compartidas. Cada paquete obtiene su propio archivo enfocado. Las reglas gestionan el comportamiento específico por tipo de archivo. El resultado son sesiones más rápidas, contexto más relevante y un Claude Code que se comporta adecuadamente sin importar en qué parte del monorepo se esté trabajando.

Esta guía es el manual completo para estructurar archivos CLAUDE.md en un monorepo. Si tienes más de unos pocos paquetes en un solo repositorio, esto te ahorrará semanas de prueba y error.

El Problema

Los monorepos son complicados. Contienen múltiples paquetes con diferentes lenguajes, diferentes herramientas de compilación, diferentes enfoques de testing y diferentes convenciones de código. Una biblioteca de componentes React tiene reglas distintas a las de un microservicio en Go. Un módulo de Terraform tiene expectativas diferentes a las de una API en Node.js.

Claude Code necesita entender estas diferencias. Cuando le pides que escriba un test en tu paquete React, debería saber usar Jest y React Testing Library. Cuando le pides que escriba un test en tu servicio Go, debería saber usar el paquete estándar de testing con tests basados en tablas. Cuando le pides que modifique tu configuración de Terraform, debería conocer tus convenciones de nomenclatura y la configuración del backend de estado.

Un único archivo CLAUDE.md no puede manejar esto bien. Si pones todo en un solo archivo, la mayor parte del contenido es ruido para cualquier tarea dada. Claude Code carga el archivo completo en su ventana de contexto al inicio de la sesión, lo que significa que cientos de líneas sobre tus microservicios en Go están consumiendo tokens de contexto mientras estás trabajando en tu frontend React. Peor aún, las instrucciones contradictorias de diferentes paquetes pueden confundir al modelo. "Usa siempre punto y coma" para tu JavaScript y "nunca uses punto y coma" para tus tests en Go son reglas válidas, pero entran en conflicto cuando aparecen en el mismo archivo sin un alcance claro.

El otro extremo, no tener ningún CLAUDE.md y depender de que Claude Code infiera las convenciones a partir del código, también falla. Claude Code es bueno leyendo código, pero no puede inferir las preferencias de tu equipo sobre patrones de manejo de errores, formatos de mensajes de commit o qué framework de testing usar cuando hay múltiples opciones disponibles. Algunas cosas necesitan declararse explícitamente.

La solución es una jerarquía estructurada de archivos CLAUDE.md que proporcione a Claude Code el contexto adecuado en el momento adecuado, sin desperdiciar tokens en información irrelevante.

El Camino

Comprendiendo el Orden de Carga

Antes de poder estructurar tus archivos CLAUDE.md de forma efectiva, necesitas entender cómo Claude Code los descubre y carga. El orden de carga determina qué instrucciones ve Claude y cuándo.

Claude Code lee los archivos CLAUDE.md desde múltiples ubicaciones, en este orden.

Primero, el archivo a nivel de usuario en ~/.claude/CLAUDE.md. Este contiene preferencias personales que se aplican a todos los proyectos. Cosas como "Prefiero el español castellano en los comentarios" o "siempre explica tu razonamiento antes de mostrar código." Este archivo no forma parte de tu repositorio y no se comparte con tu equipo.

Segundo, el CLAUDE.md raíz en el directorio de tu proyecto. Este es el archivo que está junto a tu package.json, go.mod o lo que defina la raíz de tu monorepo. Claude Code siempre lee este archivo, independientemente de en qué subdirectorio estés trabajando.

Tercero, archivos CLAUDE.md en directorios ancestros. Claude Code recorre el árbol de directorios desde tu directorio de trabajo actual hasta la raíz del proyecto, leyendo cualquier archivo CLAUDE.md que encuentre en el camino. Si inicias Claude Code en packages/api/, lee archivos CLAUDE.md de packages/api/, packages/ y la raíz del proyecto. Los archivos CLAUDE.md en subdirectorios por debajo de tu ubicación actual se cargan bajo demanda cuando Claude lee archivos en esos directorios, no de forma anticipada al inicio de la sesión.

Cuarto, archivos en .claude/rules/. Son archivos de reglas con alcance por patrones glob que se activan según las rutas de los archivos con los que Claude Code está trabajando. Más sobre estos en una sección posterior.

La clave es que todos estos archivos son aditivos. Claude Code los concatena en un único contexto. No reemplaza ni sobreescribe. Esto significa que tu archivo raíz y los archivos de subdirectorios deberían complementarse mutuamente, no repetirse.

El CLAUDE.md Raíz para Convenciones Compartidas

Tu archivo CLAUDE.md raíz es el que cada sesión de Claude Code lee, independientemente de dónde en el monorepo esté trabajando el desarrollador. Esto lo convierte en un espacio valioso. Cada línea en este archivo consume tokens de contexto en cada sesión. Mantenlo ligero y universal.

Esto es lo que debería contener un CLAUDE.md raíz para un monorepo.

# Monorepo de MiEmpresa

## Estructura del Repositorio
- `packages/web/` - Frontend React (TypeScript, Vite)
- `packages/api/` - API Node.js (TypeScript, Express)
- `packages/shared/` - Biblioteca compartida TypeScript
- `services/auth/` - Servicio de autenticación (Go)
- `services/billing/` - Servicio de facturación (Go)
- `infra/` - Infraestructura Terraform

## Convenciones Compartidas
- Nomenclatura de ramas: `feature/TICKET-123-descripcion-breve`
- Mensajes de commit: conventional commits (feat:, fix:, chore:, docs:)
- Todo el código debe pasar el CI antes de fusionar. Ejecuta `make check` para verificar localmente.
- Nunca hagas commit de secretos. Usa variables de entorno de `.env.local` (en gitignore).
- Castellano en toda la documentación y comentarios.

## Comandos del Monorepo
- `make build` - Compilar todos los paquetes
- `make test` - Ejecutar todos los tests
- `make lint` - Analizar todos los paquetes
- `make check` - Ejecutar compilación, tests y análisis

## Instrucciones Específicas por Paquete
Cada paquete tiene su propio CLAUDE.md con comandos de compilación y convenciones.
Consulta el CLAUDE.md en el directorio del paquete antes de hacer cambios.

Observa lo que NO está en este archivo. No hay comandos de compilación específicos por paquete, ni estándares de código por lenguaje, ni detalles de frameworks de testing. Eso pertenece a los archivos de subdirectorio. El archivo raíz proporciona el mapa. Los archivos de subdirectorio proporcionan el territorio.

Apunta a menos de cien líneas en el archivo raíz. Si lo estás superando, probablemente estás incluyendo detalles específicos de paquetes que deberían estar más cerca del código que describen.

Archivos CLAUDE.md a Nivel de Paquete

Cada paquete en tu monorepo debería tener su propio archivo CLAUDE.md con instrucciones específicas para ese paquete. Aquí es donde debes ser detallado y específico.

Aquí tienes un ejemplo para un paquete de frontend React.

# Frontend Web

## Compilación y Tests
- Servidor de desarrollo: `npm run dev` (desde este directorio)
- Compilar: `npm run build`
- Tests: `npm test`
- Test de un solo archivo: `npm test -- path/to/test.ts`
- Lint: `npm run lint`
- Verificación de tipos: `npx tsc --noEmit`

## Stack Tecnológico
- React 19 con TypeScript
- Vite para empaquetado
- Tailwind CSS para estilos
- React Query para estado del servidor
- Zustand para estado del cliente
- Jest + React Testing Library para tests

## Estándares de Código
- Solo componentes funcionales. Sin componentes de clase.
- Usar exports con nombre. Sin exports por defecto.
- Co-ubicar tests con archivos fuente: `Button.tsx` y `Button.test.tsx` en el mismo directorio.
- Usar `interface` para props de componentes, no `type`.
- Todos los componentes deben tener un archivo de test correspondiente.
- Preferir composición sobre props complejas. Dividir componentes grandes en más pequeños.

## Estructura de Directorios
- `src/components/` - Componentes UI reutilizables
- `src/pages/` - Componentes a nivel de página (uno por ruta)
- `src/hooks/` - Hooks personalizados de React
- `src/api/` - Cliente API y definiciones de consultas
- `src/store/` - Definiciones de stores Zustand
- `src/types/` - Tipos TypeScript compartidos

Y aquí tienes un ejemplo para un microservicio en Go.

# Servicio de Autenticación

## Compilación y Tests
- Compilar: `go build ./...`
- Tests: `go test ./...`
- Tests con cobertura: `go test -coverprofile=coverage.out ./...`
- Ejecutar localmente: `go run cmd/auth/main.go`
- Lint: `golangci-lint run`

## Estándares de Código
- Estructura estándar de proyecto Go. cmd/ para puntos de entrada, internal/ para paquetes privados.
- Tests basados en tablas para todas las funciones con múltiples combinaciones de entrada/salida.
- Envolver errores con `fmt.Errorf("contexto: %w", err)`.
- Sin estado global. Pasar dependencias a través de parámetros de función o campos de struct.
- Propagación de contexto a través de todas las cadenas de funciones. El primer parámetro es siempre `ctx context.Context`.
- Usar `slog` para logging estructurado. Sin `fmt.Println` en código de producción.

## Base de Datos
- PostgreSQL con driver `pgx`.
- Migraciones en el directorio `migrations/`, numeradas secuencialmente.
- Nunca modificar migraciones existentes. Siempre crear nuevas.

## API
- gRPC con Protocol Buffers. Archivos proto en el directorio `proto/`.
- Ejecutar `buf generate` después de modificar archivos proto.
- Todos los métodos RPC deben tener validación de solicitud.

Cada archivo de paquete es autónomo. Un desarrollador trabajando en el servicio de autenticación en Go no necesita saber sobre React Testing Library, y viceversa. Claude Code carga solo los archivos relevantes según dónde esté trabajando el desarrollador.

El Directorio .claude/rules/ para Reglas con Alcance por Patrón Glob

A veces necesitas reglas que se apliquen a tipos de archivo específicos en lugar de directorios específicos. Para eso existe .claude/rules/. Este directorio se ubica en la raíz de tu proyecto, y cada archivo en él contiene un patrón glob en su frontmatter que determina a qué archivos se aplican las reglas.

Aquí tienes un ejemplo. Crea un archivo en .claude/rules/typescript-tests.md.

---
paths: ["*.test.ts", "*.test.tsx", "*.spec.ts", "*.spec.tsx"]
---

Al escribir o modificar tests en TypeScript, sigue estas reglas.

- Usa bloques `describe` e `it`, no bloques `test`.
- Cada bloque `describe` debe corresponder a una función o componente que se está probando.
- Usa `beforeEach` para configuración compartida. Evita `beforeAll` a menos que la configuración sea genuinamente costosa.
- Simula dependencias externas. Nunca hagas llamadas reales a APIs ni consultas a bases de datos en los tests.
- Usa `jest.fn()` para simulaciones de funciones y `jest.spyOn()` para simulaciones de métodos.
- Aserta valores específicos, no solo veracidad. Usa `toEqual` en lugar de `toBeTruthy`.
- Incluye al menos un test para el camino feliz, uno para manejo de errores y uno para casos límite.

Y otro para archivos Terraform en .claude/rules/terraform.md.

---
paths: ["*.tf", "*.tfvars"]
---

Al trabajar con archivos Terraform, sigue estas reglas.

- Usa el estilo de `terraform fmt`. Indentación de dos espacios.
- Todos los recursos deben tener un bloque `tags` con al menos las etiquetas `Environment` y `ManagedBy`.
- Usa data sources para referenciar recursos existentes. Nunca escribas ARNs ni IDs directamente en el código.
- Las variables deben tener campos `description` y `type`. Incluye `default` solo si la variable es opcional.
- Los outputs deben tener campos `description`.
- Usa módulos para patrones repetidos. Nunca copies y pegues bloques de recursos.

Los patrones glob soportan la sintaxis estándar. *.rs coincide con todos los archivos Rust. packages/web/**/*.tsx coincide con todos los archivos TSX en el paquete web. **/migrations/*.sql coincide con archivos de migración SQL en cualquier parte del repositorio.

Los archivos de reglas son poderosos porque se activan automáticamente según el contexto. Cuando Claude Code edita un archivo de test, obtiene las reglas de testing. Cuando edita un archivo Terraform, obtiene las reglas de infraestructura. No se requiere cambio manual.

Normalmente recomendamos crear archivos de reglas para entre tres y cinco tipos de archivo que tengan convenciones distintas en la base de código. Más que eso y corres el riesgo de sobrecargar el contexto. El objetivo es capturar las reglas que los desarrolladores olvidan con frecuencia o que Claude Code no acierta sin orientación explícita.

CLAUDE.local.md para Preferencias Personales

Cada desarrollador tiene preferencias que son personales, no organizacionales. Quizá un desarrollador prefiere explicaciones detalladas mientras que otro prefiere respuestas concisas. Quizá un desarrollador quiere que Claude Code siempre sugiera tests mientras que otro solo quiere tests cuando se los pide.

CLAUDE.local.md es la respuesta. Este archivo se ubica en la raíz del proyecto junto a CLAUDE.md, pero está en el gitignore. Cada desarrollador puede crear su propia versión con preferencias personales que no afectan al equipo.

# Mis Preferencias

- Al explicar código, sé conciso. Omite el preámbulo.
- Prefiero ver el archivo completo después de las ediciones, no solo el diff.
- Cuando pido un refactoreo, sugiere tests para el código refactorizado.
- Uso atajos de vim, así que no sugieras atajos de VS Code.

Añade CLAUDE.local.md a tu archivo .gitignore en la raíz del monorepo. Esto asegura que las preferencias personales permanezcan personales. La guía de system prompts vs CLAUDE.md explica la distinción más amplia entre configuración compartida y preferencias personales con más detalle.

La Directriz de Longitud de Líneas

Claude Code carga los archivos CLAUDE.md completos independientemente de su longitud. No hay truncamiento. Sin embargo, los archivos más cortos producen mejor adherencia porque mantienen las instrucciones más importantes prominentes en la ventana de contexto.

La recomendación actual es apuntar a menos de quinientas líneas por archivo CLAUDE.md. Esta es una directriz de buenas prácticas, no un límite técnico. Si no puedes encajar las instrucciones de tu paquete en ese rango, probablemente estás incluyendo detalles que no necesitan estar en el CLAUDE.md en absoluto.

Aquí te mostramos cómo priorizar el contenido cuando te acercas al límite.

Primera prioridad: comandos de compilación y tests. Estas son las instrucciones que Claude Code usa con más frecuencia. Cada CLAUDE.md debería empezar con cómo compilar, testear y analizar el código.

Segunda prioridad: estándares de código que Claude frecuentemente no acierta. Si Claude Code usa consistentemente el estilo de importación incorrecto o el patrón de manejo de errores equivocado, añade una regla para ello. Si ya sigue la convención correctamente al leer tu código, no necesitas una regla.

Tercera prioridad: estructura del proyecto. Una breve descripción de dónde están las cosas ayuda a Claude Code a navegar paquetes grandes sin leer cada directorio.

Prioridad más baja: texto explicativo. Claude Code no necesita párrafos explicando por qué elegiste un framework en particular. Necesita instrucciones concisas sobre cómo usarlo.

Si genuinamente necesitas más contexto para un área en particular, usa la sintaxis @path/to/file para referenciar archivos externos.

Usando Imports para Referenciar Otros Archivos

A veces necesitas que Claude Code entienda especificaciones detalladas, esquemas de API o decisiones arquitectónicas que no encajan bien en un solo CLAUDE.md. La sintaxis @path/to/file te permite referenciar otros archivos que Claude Code cargará cuando sea necesario.

# Mi Paquete

## Compilación
- `npm run build`
- `npm test`

## Esquema de API
@docs/api-schema.md

## Decisiones de Arquitectura
@docs/architecture-decisions.md

La sintaxis @path indica a Claude Code que lea el archivo referenciado e incluya su contenido en el contexto. Esto es más flexible que meter todo en un solo archivo porque los archivos importados pueden ser más largos, pueden compartirse entre múltiples archivos CLAUDE.md y pueden mantenerse independientemente.

Los imports funcionan bien para tres tipos de contenido. Documentación de API que Claude Code necesita para generar llamadas de cliente correctas. Registros de decisiones arquitectónicas que explican por qué se usan ciertos patrones. Y documentos de estándares de código que son mantenidos por el equipo y se duplicarían si se copiaran en cada archivo CLAUDE.md.

Sé selectivo con los imports. Cada archivo importado se suma al tamaño de la ventana de contexto. Si importas cinco archivos grandes, estarás consumiendo el contexto disponible para tu conversación real con Claude Code.

Un Ejemplo Real de Monorepo

Aquí tienes la estructura completa de CLAUDE.md de un monorepo real. El repositorio tiene esta distribución.

miproyecto/
  CLAUDE.md                    # Raíz, convenciones compartidas
  CLAUDE.local.md              # Preferencias personales (en gitignore)
  .claude/
    rules/
      typescript-tests.md      # Reglas para archivos *.test.ts
      go-tests.md              # Reglas para archivos *_test.go
      terraform.md             # Reglas para archivos *.tf
  packages/
    web/
      CLAUDE.md                # Instrucciones del frontend React
    api/
      CLAUDE.md                # Instrucciones de la API Node.js
    shared/
      CLAUDE.md                # Instrucciones de la biblioteca compartida
  services/
    auth/
      CLAUDE.md                # Instrucciones del servicio de auth en Go
    billing/
      CLAUDE.md                # Instrucciones del servicio de facturación en Go
  infra/
    CLAUDE.md                  # Instrucciones de Terraform

Cuando un desarrollador abre Claude Code en packages/web/, carga cuatro fuentes. El ~/.claude/CLAUDE.md a nivel de usuario (personal, global), el CLAUDE.md raíz (convenciones compartidas), el packages/web/CLAUDE.md (instrucciones específicas de React) y cualquier archivo en .claude/rules/ que coincida con los tipos de archivo que se están editando.

Cuando el mismo desarrollador cambia a services/auth/, el contexto cargado cambia. El archivo raíz permanece igual, pero packages/web/CLAUDE.md se descarga y services/auth/CLAUDE.md se carga en su lugar. Si está editando un archivo _test.go, el archivo de reglas go-tests.md también se activa.

Este es el beneficio clave de la jerarquía. El contexto se adapta automáticamente a dónde está trabajando el desarrollador. Sin cambio manual, sin necesidad de recordar actualizar configuraciones, sin tokens desperdiciados en instrucciones irrelevantes.

Anti-patrones a Evitar

Los equipos cometen los mismos errores repetidamente al configurar CLAUDE.md para monorepos. Aquí están los patrones a evitar.

Duplicar información entre archivos. Si tu CLAUDE.md raíz dice "usa conventional commits" y cada archivo de paquete también dice "usa conventional commits", estás desperdiciando tokens de contexto en repetición. Pon las reglas compartidas en el archivo raíz. Pon las reglas específicas de paquete en los archivos de paquete. Nunca te repitas.

Poner todo en el archivo raíz. Este es el error más común. El archivo raíz debería ser un mapa, no una enciclopedia. Si contiene comandos de compilación para cada paquete, estándares de código para cada lenguaje y patrones de testing para cada framework, está haciendo demasiado. Mueve el contenido específico de paquete a los archivos a nivel de paquete.

Ignorar los archivos de subdirectorio por completo. Algunos equipos crean un único CLAUDE.md raíz y nunca añaden archivos a nivel de paquete. Esto fuerza al archivo raíz a crecer indefinidamente y significa que Claude Code obtiene el mismo contexto independientemente de dónde esté trabajando el desarrollador. Aprovecha la jerarquía.

Instrucciones contradictorias entre niveles. Si el archivo raíz dice "siempre añade comentarios JSDoc" y un archivo de paquete dice "sin comentarios, el código debería ser auto-documentado", Claude Code recibirá instrucciones contradictorias. Resuelve los conflictos siendo específico. El archivo raíz debería establecer valores por defecto. Los archivos de paquete deberían sobrescribir solo cuando sea necesario, con lenguaje claro como "En este paquete, a diferencia de la convención general..."

Usar CLAUDE.md para documentación. CLAUDE.md es para instrucciones, no para documentación. No expliques la historia de tus decisiones arquitectónicas, la justificación detrás de tu stack tecnológico ni los objetivos de tu producto. Claude Code no necesita este contexto para escribir buen código. Mantenlo enfocado en instrucciones accionables.

Skills vs CLAUDE.md

Claude Code soporta slash commands y skills que proporcionan contexto bajo demanda en lugar de contexto persistente. Comprender cuándo usar cada uno es importante para mantener tus archivos CLAUDE.md ligeros.

CLAUDE.md es para instrucciones que deberían estar siempre activas. Estándares de código, comandos de compilación, estructura del proyecto. Estas son cosas que Claude Code necesita saber en cada interacción dentro de un alcance dado.

Los skills y slash commands son para instrucciones que se necesitan ocasionalmente. Un proceso de despliegue complejo, un flujo de trabajo de migración de base de datos, un procedimiento de perfilado de rendimiento. Son instrucciones detalladas que desperdiciarían contexto si se cargaran en cada sesión pero son invaluables cuando se necesitan.

En un monorepo, usa CLAUDE.md para el contexto del día a día y skills para flujos de trabajo especializados. Un packages/web/CLAUDE.md le dice a Claude Code cómo compilar y testear el frontend. Un skill /deploy-web le dice cómo desplegar el frontend, incluyendo el proceso de doce pasos con verificaciones de entorno, verificación de compilación, invalidación de CDN y pruebas de humo.

La regla general es simple. Si Claude Code necesita esta información en más de la mitad de las sesiones donde está trabajando en un alcance particular, ponla en CLAUDE.md. Si la necesita con menos frecuencia, conviértela en un skill o documéntala en un archivo que se pueda importar bajo demanda.

Autoguardado de Memoria y Memoria Específica del Proyecto

Claude Code tiene una función de memoria que guarda automáticamente el contexto en ~/.claude/projects/{ruta-del-proyecto}/memory/. Esto es separado de CLAUDE.md y sirve para un propósito diferente.

La memoria captura cosas que Claude Code aprende durante las sesiones. Si le dices "en este proyecto usamos pnpm, no npm" durante una conversación, puede guardar eso en la memoria para recordarlo en sesiones futuras. Esto es útil para capturar preferencias ad-hoc que no justifican una actualización del CLAUDE.md.

En el contexto de un monorepo, la memoria es a nivel de proyecto, no a nivel de paquete. Esto significa que una corrección que hagas mientras trabajas en packages/web/ se recuerda cuando estés trabajando en services/auth/. Para la mayoría de correcciones, esto está bien. Pero si haces una corrección específica de paquete que no debería aplicarse en otro lugar, añádela al CLAUDE.md a nivel de paquete en lugar de depender de la memoria.

Revisar periódicamente los archivos de memoria del proyecto y promover las entradas útiles al archivo CLAUDE.md apropiado es una buena práctica. Esto mantiene las instrucciones importantes en el control de versiones donde todo el equipo se beneficia de ellas, en lugar de estar encerradas en un almacén de memoria personal.

La Lección

La lección más valiosa de estructurar archivos CLAUDE.md en un monorepo es que la gestión del contexto es un problema de diseño, no un problema de documentación. No estás escribiendo documentación para que Claude Code la lea. Estás diseñando un sistema de contexto que entrega la información correcta en el momento correcto con el mínimo desperdicio.

La jerarquía, con archivos raíz para convenciones compartidas, archivos de paquete para instrucciones específicas, reglas para comportamientos por tipo de archivo y archivos locales para preferencias personales, te da un marco para pensar dónde pertenece cada pieza de contexto. Cuando añades una nueva instrucción, hazte tres preguntas. ¿Necesita esto cada sesión? ¿Lo necesita solo este paquete? ¿Lo necesita solo este tipo de archivo?

La respuesta te dice dónde va. Mantén los archivos cortos. Sé específico. No te repitas. Deja que la jerarquía haga el trabajo de acotar el contexto a las sesiones correctas. Revisa tus archivos CLAUDE.md regularmente, porque tus convenciones evolucionan y tu contexto debería evolucionar con ellas.

Conclusión

Estructurar CLAUDE.md para un monorepo es sencillo una vez que comprendes la jerarquía de carga. Pon las convenciones compartidas en el archivo raíz. Pon las instrucciones específicas de paquete en archivos de subdirectorio. Usa .claude/rules/ para reglas de tipo de archivo con alcance por ruta. Mantén las preferencias personales en CLAUDE.local.md.

Apunta a menos de quinientas líneas por archivo y usa imports @path/to/file para contenido que no quepa. La recompensa es significativa. Claude Code se comporta de forma consistente en todo tu monorepo, cargando solo el contexto relevante para la tarea actual. Los desarrolladores no necesitan cambiar de modo manualmente ni recordarle a Claude Code en qué paquete están trabajando.

Para una comprensión más profunda de la relación entre CLAUDE.md y los system prompts, lee la guía de system prompts vs CLAUDE.md. Y para consejos prácticos sobre integrar Claude Code en tu rutina diaria de desarrollo en cualquier estructura de proyecto, la guía de flujos de trabajo diarios con Claude Code cubre los flujos y hábitos que marcan la mayor diferencia.

El monorepo añade complejidad, pero con la estructura de CLAUDE.md adecuada, Claude Code maneja esa complejidad con elegancia. Configura la jerarquía una vez, mantenla mientras tu base de código evoluciona y deja que Claude Code se enfoque en lo que mejor sabe hacer: escribir buen código en el contexto adecuado.