Cap 9: CLAUDE.md: Jerarquía y Organización

Jerarquía de CLAUDE.md

Claude Code lee instrucciones de múltiples niveles, cada uno con diferente alcance y visibilidad:

1. User-level: ~/.claude/CLAUDE.md

• Alcance: solo para el usuario que lo configuró
• Compartido: NO — no se versiona ni se comparte con el equipo
• Uso: preferencias personales, atajos, estilos de coding propios

<!-- ~/.claude/CLAUDE.md -->
# Mis preferencias
- Escribe en español todas tus respuestas
- Usa tabs en lugar de espacios
- Commits en formato conventional commits

2. Project-level: CLAUDE.md o .claude/CLAUDE.md

• Alcance: todos los que trabajen en el proyecto
• Compartido: SÍ — versionado con git
• Uso: estándares del proyecto, arquitectura, convenciones del equipo

<!-- CLAUDE.md (raíz del proyecto) -->
# Proyecto API
- Framework: Express + TypeScript
- Testing: Vitest con coverage > 80%
- Base de datos: PostgreSQL con Drizzle ORM

Ambas ubicaciones (CLAUDE.md en raíz o .claude/CLAUDE.md) son válidas. La convención es usar la raíz para proyectos simples y .claude/ cuando hay más archivos de configuración.

3. Directory-level: CLAUDE.md en subdirectorios

• Alcance: se aplica cuando Claude trabaja en archivos de ese directorio
• Compartido: SÍ — versionado con git
• Uso: reglas específicas de un módulo o subsistema

<!-- src/api/CLAUDE.md -->
# API Module
- Todos los endpoints deben validar input con Zod
- Respuestas en formato { data, error, meta }
- Rate limiting obligatorio en endpoints públicos

Orden de precedencia

Las instrucciones se cargan en orden y se acumulan:

user-level → project-level → directory-level

Si hay conflicto, el nivel más específico (directory) prevalece sobre el más general (user).

@import para modularización

Cuando CLAUDE.md crece demasiado, usa @import para referenciar archivos externos:

<!-- CLAUDE.md -->
# Proyecto Principal

@architecture.md
@api-conventions.md
@testing-standards.md

Cada archivo importado se carga como si su contenido estuviera inline en CLAUDE.md. Esto mantiene el archivo principal como un índice legible.

Rutas de import

• Rutas relativas al archivo que contiene el @import
• Pueden apuntar a cualquier archivo .md del proyecto
• Ejemplo: @docs/conventions.md carga docs/conventions.md relativo al CLAUDE.md

.claude/rules/ como alternativa

En lugar de un CLAUDE.md monolítico, puedes usar archivos individuales en .claude/rules/:

.claude/
├── CLAUDE.md          # Mínimo: solo lo esencial
└── rules/
    ├── testing.md     # Estándares de testing
    ├── api-conventions.md  # Convenciones de API
    ├── deployment.md  # Procedimientos de deploy
    └── security.md    # Políticas de seguridad

Ventajas de rules/

• Topic-specific: cada archivo cubre un tema
• Fácil de mantener: cambios aislados, PRs más claros
• Carga selectiva: Claude carga las rules relevantes al contexto
• Onboarding: nuevos miembros pueden leer rules individuales

Cuándo usar cada approach

Proyecto	Recomendación
Pequeño (< 50 líneas de config)	Un solo CLAUDE.md
Mediano (50-200 líneas)	CLAUDE.md + @imports
Grande (200+ líneas, múltiples equipos)	.claude/rules/ con archivos por tema

Diagnosticando problemas de jerarquía

Escenario: nuevo miembro no recibe instrucciones

Síntoma: un nuevo desarrollador reporta que Claude no sigue las convenciones del equipo.

Diagnóstico paso a paso:

1. ¿Las instrucciones están en ~/.claude/CLAUDE.md (user-level)?

   • Si sí → ese es el problema. User-level es personal, no compartido
   • Mover a CLAUDE.md del proyecto o .claude/rules/

2. ¿El archivo está en .gitignore?

   • Verificar que CLAUDE.md no esté ignorado por git

3. ¿Hay conflicto entre niveles?

   • El user-level del nuevo miembro puede sobreescribir project-level

Escenario: instrucciones que se “pierden”

Síntoma: Claude a veces sigue reglas y a veces no.

Diagnóstico:

1. ¿Las reglas están en un directory-level CLAUDE.md?
   • Solo aplican cuando Claude trabaja en ese directorio
2. ¿El CLAUDE.md es muy largo?
   • Archivos muy extensos pueden hacer que instrucciones al final tengan menos peso
   • Dividir en archivos más cortos

Estrategia de splitting

Para un proyecto grande, esta estructura es efectiva:

CLAUDE.md                    # Overview del proyecto, 20-30 líneas
.claude/
├── rules/
│   ├── testing.md          # Framework, patterns, coverage
│   ├── api-conventions.md  # Endpoints, validation, responses
│   ├── deployment.md       # CI/CD, environments, rollback
│   ├── database.md         # Migrations, naming, queries
│   └── security.md         # Auth, sanitization, secrets
└── commands/
    └── ...

El CLAUDE.md raíz se mantiene como un overview conciso:

# Mi Proyecto

Stack: TypeScript + Express + PostgreSQL + Vitest

## Reglas críticas
- Nunca hacer push directo a main
- Coverage mínimo: 80%
- Todos los endpoints validados con Zod

## Detalles
Ver .claude/rules/ para convenciones específicas por tema.

Verificar memory files cargados

Usa /memory en Claude Code para verificar qué memory files están cargados en la sesión actual. Esto ayuda a diagnosticar si las instrucciones esperadas están activas.

---

← Cap 8: Errores y tool_choice · Índice · Cap 10: Commands y Skills →