Sistema de Memoria de Claude Code: Gestión Jerárquica de Contexto y Configuración

Acabas de empezar un nuevo proyecto con Claude Code. Le pides que implemente un endpoint. Claude usa tabs de 4 espacios. Tu equipo usa 2. Le corriges. Al día siguiente, vuelve a usar 4 espacios. Le corriges otra vez.

¿El problema? Claude no tiene memoria de tus preferencias. Cada sesión empieza desde cero.

O al menos, eso era cierto antes del sistema de memoria jerárquico de Claude Code.

Ahora puedes definir una vez que tu equipo usa 2 espacios, y Claude lo recordará en cada proyecto, en cada sesión, para siempre. Puedes establecer políticas de seguridad a nivel enterprise que nadie puede saltarse. Puedes compartir convenciones de arquitectura con tu equipo. Y puedes mantener tus preferencias personales sin contaminar el repositorio del equipo.

Todo esto mediante un sistema de 5 niveles de memoria que se cargan automáticamente y se priorizan en cascada.

Al final de este post, entenderás cómo funciona cada nivel, cómo configurarlos, y cómo aprovecharlos para evitar repetir las mismas instrucciones en cada sesión.

¿Qué es el Sistema de Memoria de Claude Code?

El sistema de memoria de Claude Code es una jerarquía de archivos CLAUDE.md que contienen instrucciones para Claude en diferentes niveles de alcance: desde políticas de toda tu organización hasta preferencias personales para un único proyecto.

Cómo funciona en 60 segundos:

Cuando Claude Code arranca, busca archivos de memoria en ubicaciones específicas
Los carga todos en orden jerárquico (de más general a más específico)
Los aplica en cada interacción que tienes con Claude
Si hay conflictos, el nivel más específico gana

Analogía: Imagina CSS en cascada, pero para instrucciones de IA:

/* Enterprise policy (nivel base) */
* { security: strict; }

/* User-level rules */
.my-projects { indentation: 2-spaces; }

/* Project memory */
#backend-api { language: python; testing: pytest; }

/* Project rules (modular) */
.api-routes { validation: required; openapi: true; }

/* Local overrides */
#backend-api.dev { debug: verbose; test-data: sandbox; }

El archivo más específico (CLAUDE.local.md) sobrescribe al más general (Enterprise Policy).

Los 5 Niveles de Memoria

Claude Code organiza la memoria en 5 niveles, cada uno con un propósito específico:

1. Enterprise Policy Memory

Ubicación:

macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux: /etc/claude-code/CLAUDE.md
Windows: C:\Program Files\ClaudeCode\CLAUDE.md

Propósito: Políticas obligatorias para toda la organización

Quién lo gestiona: IT/DevOps/Security Team

Alcance: Todos los usuarios de la organización

Casos de uso típicos:

Políticas de seguridad obligatorias (ej: "Nunca hardcodees secrets")
Estándares de compliance (ej: GDPR, SOC2)
Configuración de herramientas corporativas (ej: "Usa Artifactory para packages internos")
Restricciones de dependencias (ej: "No uses librerías GPL en proyectos comerciales")

Ejemplo de Enterprise Policy:

# Enterprise Security Policy

## Obligatorio para todos los proyectos

### Secrets Management
- NUNCA hardcodees API keys, contraseñas o tokens
- Usa AWS Secrets Manager para producción
- Usa variables de entorno en desarrollo
- Si detectas un secret hardcodeado, detén el trabajo y avisa a Security

### Dependency Management
- Solo usa packages del registry interno: https://artifactory.company.com
- Escanea vulnerabilidades con `npm audit` antes de cada commit
- Versiones permitidas de Node.js: 18.x, 20.x

### Logging
- Nunca loguees PII (nombres, emails, IPs)
- Usa el logger corporativo: @company/logger
- Nivel de log mínimo en producción: WARN

### Compliance
- Todo código debe incluir header de copyright
- Archivos de datos sensibles deben tener clasificación de seguridad

Deployment:

Usa sistemas de gestión de configuración para desplegar este archivo en todas las máquinas:

# Ansible
- name: Deploy Claude Enterprise Policy
  copy:
    src: files/CLAUDE.md
    dest: /etc/claude-code/CLAUDE.md
    mode: 0644

# Intune (Windows GPO)
Copy-Item -Path "CLAUDE.md" -Destination "C:\Program Files\ClaudeCode\"

# MDM (macOS)
# Usa un perfil de configuración para desplegar el archivo

2. User Memory (Global)

Ubicación: ~/.claude/CLAUDE.md

Propósito: Preferencias personales que aplican a TODOS tus proyectos

Quién lo gestiona: Tú

Alcance: Solo tú (todos tus proyectos)

Casos de uso típicos:

Preferencias de estilo de código
Herramientas que usas habitualmente
Atajos personales
Convenciones que prefieres

Ejemplo de User Memory:

# Francisco París - Preferencias Personales

## Estilo de Código
- Indentación: 2 espacios (NUNCA tabs)
- Line length: 100 caracteres max
- Comillas: simples en JS/TS, dobles en Python
- Trailing commas: siempre en multiline
- Semicolons: no en JS/TS (usa ESLint + Prettier)

## Convenciones de Naming
- Variables: camelCase
- Constantes: UPPER_SNAKE_CASE
- Funciones: verbNoun (ej: getUserById, validateEmail)
- Archivos: kebab-case.ts

## Testing
- Framework preferido: Jest para frontend, pytest para backend
- Coverage mínimo: 80% para nuevo código
- Nombrado de tests: "should [expected behavior] when [scenario]"

## Git Workflow
- Commits: Conventional Commits format (feat:, fix:, docs:, etc.)
- Branch naming: tipo/descripcion-corta (ej: feat/user-authentication)
- Squash commits antes de merge a main

## Herramientas
- Package manager: npm (no yarn, no pnpm)
- Linter: ESLint con config de Airbnb
- Formatter: Prettier

Cómo crearlo:

# Crea el directorio si no existe
mkdir -p ~/.claude

# Edita tu archivo de memoria personal
nano ~/.claude/CLAUDE.md

3. Project Memory

Ubicación: ./CLAUDE.md o ./.claude/CLAUDE.md (en la raíz del proyecto)

Propósito: Instrucciones compartidas por todo el equipo para este proyecto específico

Quién lo gestiona: El equipo (vía Git)

Alcance: Todos los colaboradores del proyecto

Casos de uso típicos:

Arquitectura del proyecto
Convenciones específicas del proyecto
Workflows de desarrollo
Comandos comunes

Ejemplo de Project Memory:

# Backend API - Project Instructions

## Arquitectura

Este proyecto usa Clean Architecture con 4 capas:
- `domain/`: Entidades y lógica de negocio (sin dependencias)
- `application/`: Casos de uso (depende de domain)
- `infrastructure/`: DB, APIs externas, frameworks (depende de application)
- `presentation/`: Controllers, DTOs (depende de application)

## Stack Tecnológico
- Framework: NestJS
- Database: PostgreSQL 15 + TypeORM
- Auth: JWT con Passport
- Validación: class-validator + class-transformer
- Testing: Jest + Supertest

## Convenciones del Proyecto

### Estructura de Módulos
Cada feature tiene su propio módulo con esta estructura:

users/ domain/ user.entity.ts user.repository.interface.ts application/ create-user.use-case.ts get-user.use-case.ts infrastructure/ user.repository.ts user.module.ts presentation/ user.controller.ts dto/ create-user.dto.ts


### Testing
- Unitarios: Mock de dependencias, coverage > 90%
- Integración: Base de datos real en Docker
- E2E: Full app con seed data

### Commands
```bash
npm run dev          # Start en modo watch
npm run test:unit    # Tests unitarios
npm run test:e2e     # Tests end-to-end
npm run lint         # ESLint + Prettier check
npm run migration:generate -- MigrationName  # Crear migración

Reglas de Negocio Críticas

Autenticación

Todos los endpoints excepto /auth/** requieren JWT
Tokens expiran en 15 minutos
Refresh tokens en httpOnly cookies

Validación

SIEMPRE valida input con DTOs
NUNCA confíes en datos del cliente
Sanitiza HTML en campos de texto libre

Error Handling

Usa exception filters de NestJS
Nunca expongas stack traces en producción
Loguea errores con Winston


**Bootstrap con comando:**

```bash
# Claude Code incluye comando para generar CLAUDE.md inicial
cd tu-proyecto
claude init

# Esto crea .claude/CLAUDE.md con template básico

Imports de archivos:

CLAUDE.md puede importar otros archivos para mejor organización:

# Backend API - Instructions

Ver @README.md para arquitectura general.
Ver @package.json para comandos disponibles.

## Git Workflow
@docs/git-workflow.md

## Deployment
@docs/deployment-guide.md

## Preferencias de desarrollo individual
@~/.claude/backend-preferences.md

4. Project Rules (Modular)

Ubicación: ./.claude/rules/*.md

Propósito: Instrucciones modulares específicas por topic o tipo de archivo

Quién lo gestiona: El equipo (vía Git)

Alcance: Todos los colaboradores (con condicionales opcionales)

Ventajas sobre CLAUDE.md:

Organización por topics (testing, API, database, etc.)
Reglas condicionales por path con frontmatter YAML
Fácil de compartir entre proyectos (symlinks)
No necesitas editar un archivo gigante

Ejemplo 1: Reglas generales de API

.claude/rules/api-standards.md:

# API Development Standards

## Todos los endpoints públicos

### Validación
- Usa DTOs con class-validator
- Valida tipos, rangos, formatos
- Retorna errores 400 con detalles específicos

### Documentación
- Todos los endpoints deben tener decorador @ApiOperation
- Incluye @ApiResponse para cada status code posible
- Usa @ApiProperty en DTOs

### Rate Limiting
- Endpoints públicos: 100 req/min por IP
- Endpoints de auth: 5 req/min por IP
- Usa @Throttle decorator

Ejemplo 2: Reglas condicionales por path

.claude/rules/api-routes.md:

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

# API Routes - Reglas Específicas

ESTAS REGLAS SOLO APLICAN A ARCHIVOS EN src/api/

## Validación Obligatoria
- TODOS los endpoints deben validar input con DTOs
- Usa ValidationPipe global configurado en main.ts
- NO uses validación manual con if/else

## OpenAPI Documentation
- Cada controller debe tener @ApiTags
- Cada endpoint debe tener @ApiOperation con summary y description
- Documenta todos los status codes: @ApiResponse({status: 200, ...})

## Error Handling
- Usa HttpException y sus subclases (BadRequestException, etc.)
- NUNCA uses throw new Error() directamente
- Mensajes de error deben ser user-friendly

## Testing
- Cada ruta debe tener test E2E en tests/e2e/
- Casos a testear: success, validación, auth, rate limit

Ejemplo 3: Reglas para tests

.claude/rules/testing.md:

---
paths:
  - "**/*.spec.ts"
  - "**/*.test.ts"
---

# Testing Standards

## Estructura de Tests

Usa patrón AAA (Arrange-Act-Assert):

```typescript
describe('UserService', () => {
  describe('createUser', () => {
    it('should create user when valid data provided', async () => {
      // Arrange
      const userData = { email: 'test@example.com', name: 'Test' };
      const mockRepository = { save: jest.fn().mockResolvedValue(userData) };

      // Act
      const result = await service.createUser(userData);

      // Assert
      expect(result).toEqual(userData);
      expect(mockRepository.save).toHaveBeenCalledWith(userData);
    });
  });
});

Coverage

Unitarios: > 90% para nuevo código
Integración: Casos críticos (auth, payments, etc.)
E2E: Happy paths principales

Mocking

Mock dependencias externas (APIs, DB)
NO mockees la clase bajo test
Usa jest.mock() para módulos completos


**Organización con subdirectorios:**

.claude/rules/ api/ validation.md authentication.md rate-limiting.md testing/ unit-tests.md e2e-tests.md database/ migrations.md queries.md docs/ openapi.md


Claude Code descubre recursivamente todos los archivos `.md` en `.claude/rules/`.

**Symlinks para compartir reglas entre proyectos:**

```bash
# Crea reglas compartidas en un repo central
~/shared-claude-rules/
  typescript-standards.md
  testing-best-practices.md

# Linkea desde cada proyecto
ln -s ~/shared-claude-rules/typescript-standards.md .claude/rules/
ln -s ~/shared-claude-rules/testing-best-practices.md .claude/rules/

5. Project Memory (Local)

Ubicación: ./CLAUDE.local.md

Propósito: Preferencias personales SOLO para este proyecto

Quién lo gestiona: Tú (archivo gitignored automáticamente)

Alcance: Solo tú (este proyecto)

Casos de uso típicos:

URLs de tu entorno de desarrollo local
Datos de test personales
Configuración de debugging
Shortcuts temporales

Ejemplo de CLAUDE.local.md:

# Configuración Local de Francisco

## Entorno de Desarrollo
- API local: http://localhost:3000
- Database: postgresql://localhost:5432/backend_dev_francisco
- Redis: localhost:6379

## Datos de Test
- Email de test: francisco.test@example.com
- User ID de test: 550e8400-e29b-41d4-a716-446655440000

## Debugging
- Usa console.log libremente en local (elimina antes de commit)
- Breakpoints preferidos: user.service.ts:45, auth.middleware.ts:23

## Preferencias Temporales
- Por ahora, salta los tests E2E (están fallando en mi máquina)
- Usa puerto 3001 en vez de 3000 (conflicto con otro proyecto)

Auto-gitignore:

Claude Code añade automáticamente CLAUDE.local.md a .gitignore cuando lo detecta.

Jerarquía y Precedencia

Cuando hay conflictos entre niveles, el más específico gana.

Orden de carga (de base a override):

Enterprise Policy (base foundation)
User-level rules (~/.claude/rules/)
Project memory (./CLAUDE.md o ./.claude/CLAUDE.md)
Project rules (./.claude/rules/*.md)
Project local (./CLAUDE.local.md) (máxima prioridad)

Ejemplo de cascada:

# 1. Enterprise Policy (/etc/claude-code/CLAUDE.md)
- Indentación: 4 espacios (política corporativa)
- Nunca uses console.log

# 2. User Memory (~/.claude/CLAUDE.md)
- Indentación: 2 espacios (mi preferencia gana)
- Usa Jest para testing

# 3. Project Memory (.claude/CLAUDE.md)
- Testing: usa Vitest en vez de Jest (preferencia del equipo gana)

# 4. Project Rules (.claude/rules/frontend.md)
- En archivos .tsx: usa console.log solo para debugging (override de Enterprise)

# 5. Project Local (./CLAUDE.local.md)
- En mi máquina: usa console.log libremente (debugging local)

Resultado final:
→ Indentación: 2 espacios
→ Testing: Vitest
→ console.log: permitido en local, eliminado antes de commit

Comportamiento de carga:

Claude Code carga memories recursivamente desde el directorio actual hasta la raíz
Memories de subdirectorios se cargan lazy cuando Claude lee archivos de ese subdirectorio
Todos los archivos se cargan automáticamente al inicio de la sesión

Ejemplo de carga en subdirectorios:

proyecto/
  .claude/CLAUDE.md           # Se carga siempre
  .claude/rules/api.md        # Se carga siempre

  frontend/
    .claude/CLAUDE.md         # Se carga solo si trabajas en frontend/

  backend/
    .claude/CLAUDE.md         # Se carga solo si trabajas en backend/
    api/
      .claude/rules/auth.md   # Se carga solo si trabajas en backend/api/

Comandos de Gestión

/init - Bootstrap de CLAUDE.md

Crea un archivo CLAUDE.md inicial con template básico.

# Desde terminal
cd tu-proyecto
claude init

# O desde chat de Claude Code
/init

Output:

# [Nombre del Proyecto]

## Project Overview
[Claude analiza tu proyecto y genera descripción]

## Technology Stack
[Detecta frameworks, librerías, herramientas]

## Common Commands
[Lista comandos de package.json, Makefile, etc.]

## Development Workflow
[Template básico para completar]

/memory - Ver y Editar Memories

Abre cualquier archivo de memoria en tu editor preferido.

# Desde chat de Claude Code
/memory                    # Lista todas las memories cargadas
/memory enterprise         # Abre enterprise policy
/memory user              # Abre user memory
/memory project           # Abre project memory
/memory local             # Abre project local memory

Output de /memory (sin argumentos):

Loaded memories:

1. Enterprise Policy
   /etc/claude-code/CLAUDE.md

2. User Memory
   ~/.claude/CLAUDE.md

3. User Rules (2 files)
   ~/.claude/rules/python.md
   ~/.claude/rules/git.md

4. Project Memory
   ./.claude/CLAUDE.md

5. Project Rules (5 files)
   ./.claude/rules/api-standards.md
   ./.claude/rules/testing.md
   ./.claude/rules/database.md
   ./.claude/rules/frontend.md
   ./.claude/rules/deployment.md

6. Project Local
   ./CLAUDE.local.md

Total: 10 memory files loaded

Casos de Uso Prácticos

Caso 1: Empresa con Políticas de Seguridad Estrictas

Escenario:

Tu empresa maneja datos financieros. Security requiere que NADIE hardcodee secrets, use librerías sin aprobar, o exponga PII en logs.

Solución:

IT despliega Enterprise Policy en todas las máquinas:

/etc/claude-code/CLAUDE.md:

# Financial Corp - Security Policy

## CRÍTICO: Secrets Management
- NUNCA hardcodees API keys, tokens, passwords
- Usa HashiCorp Vault para secrets (endpoint: https://vault.company.com)
- Si detectas un secret hardcodeado, DETÉN el trabajo y notifica a security@company.com

## Approved Libraries Only
- Solo usa packages del allowlist corporativo
- Verifica allowlist en: https://security.company.com/approved-packages
- Si necesitas una librería nueva, abre ticket en Security Portal

## PII Protection
- NUNCA loguees: nombres, emails, teléfonos, SSN, tarjetas de crédito
- Usa PrivacyLogger para logs con PII (hashea automáticamente)
- Antes de cada PR, ejecuta: npm run scan-pii

## Compliance (SOC2, GDPR)
- Todo código debe incluir copyright header
- Archivos con datos sensibles requieren header de clasificación
- Implementa data retention según política: https://compliance.company.com/retention

Resultado:

Todos los desarrolladores, en todos los proyectos, tienen estas restricciones. Claude Code las aplica automáticamente.

Caso 2: Developer con Múltiples Proyectos

Escenario:

Trabajas en 5 proyectos diferentes (frontend React, backend Node, CLI en Python, etc.). Quieres que Claude respete tus preferencias personales en todos ellos.

Solución:

Crea ~/.claude/CLAUDE.md con tus preferencias globales:

# Mis Preferencias Globales

## Estilo de Código
- Indentación: 2 espacios SIEMPRE
- Comillas: simples en JS/TS, dobles en Python
- Semicolons: no (usa Prettier)

## Git Workflow
- Commits: Conventional Commits (feat, fix, docs, etc.)
- Branch naming: tipo/descripcion
- Squash antes de merge

## Testing
- Coverage mínimo: 80%
- Preferencia: Jest (JS/TS), pytest (Python)

## Comunicación
- Explica cambios complejos en comentarios
- Si hay trade-offs, documenta el por qué de la decisión

Resultado:

En TODOS tus proyectos, Claude usa tus preferencias automáticamente. No necesitas repetirlas.

Caso 3: Equipo con Convenciones de Arquitectura

Escenario:

Tu equipo usa Clean Architecture con reglas estrictas: domain sin dependencias, use cases en application, infraestructura aislada.

Solución:

Crea .claude/CLAUDE.md en el repo (compartido vía Git):

# Backend - Clean Architecture

## Estructura de Capas (OBLIGATORIO)

src/ domain/ # Entidades, Value Objects, Interfaces entities/ repositories/ # Interfaces (sin implementación)

application/ # Casos de uso, DTOs use-cases/ dtos/

infrastructure/ # Implementaciones concretas database/ external-apis/

presentation/ # Controllers, Middleware controllers/


## Reglas de Dependencia

1. **domain/** NO puede importar de otras capas (cero dependencias)
2. **application/** solo puede importar de domain
3. **infrastructure/** puede importar de application y domain
4. **presentation/** puede importar de application

## Inyección de Dependencias

- Usa interfaces en domain/repositories
- Implementa en infrastructure
- Inyecta con NestJS DI

Ejemplo correcto:
```typescript
// domain/repositories/user.repository.interface.ts
export interface IUserRepository {
  findById(id: string): Promise<User>;
}

// infrastructure/database/user.repository.ts
@Injectable()
export class UserRepository implements IUserRepository {
  findById(id: string): Promise<User> { ... }
}

// application/use-cases/get-user.use-case.ts
export class GetUserUseCase {
  constructor(
    @Inject('IUserRepository')
    private userRepo: IUserRepository
  ) {}
}

Claude, RECHAZA código que no respete estas capas.


**Resultado:**

Todos los miembros del equipo tienen las mismas reglas. Claude rechaza PRs que violen la arquitectura.

### Caso 4: Reglas Condicionales por Tipo de Archivo

**Escenario:**

Tienes reglas diferentes para archivos de API vs archivos de frontend vs archivos de database.

**Solución:**

Usa Project Rules con frontmatter YAML condicional:

`.claude/rules/api-validation.md`:

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

# API Validation Rules

ESTAS REGLAS SOLO APLICAN A src/api/

- Todos los endpoints deben validar input con DTOs
- Usa class-validator decorators
- Retorna 400 con errores específicos

.claude/rules/frontend-components.md:

---
paths:
  - "src/components/**/*.tsx"
---

# React Component Rules

ESTAS REGLAS SOLO APLICAN A src/components/

- Todos los componentes deben tener PropTypes o TypeScript types
- Usa hooks en vez de class components
- Componentes < 200 líneas (split si es necesario)

.claude/rules/database-migrations.md:

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

# Database Migration Rules

ESTAS REGLAS SOLO APLICAN A src/migrations/

- NUNCA modifiques una migración ya aplicada en producción
- Incluye DOWN migration para rollback
- Testea migración en staging antes de producción

Resultado:

Claude aplica reglas diferentes según qué archivo estés editando. Contexto automático sin necesidad de especificar manualmente.

Mejores Prácticas

1. Sé Específico

❌ Mal (vago):

- Escribe código limpio
- Usa buenas prácticas
- Documenta tu código

✅ Bien (específico):

- Funciones: max 20 líneas (split si es más largo)
- Complejidad ciclomática: max 10
- Documenta funciones públicas con JSDoc:
  - @param con tipo y descripción
  - @returns con tipo
  - @example con uso real

2. Usa Estructura y Headings

❌ Mal (bloque de texto):

Usa 2 espacios para indentación. Siempre valida input. Los errores deben ser descriptivos. Usa async/await en vez de callbacks. Prefiere const sobre let.

✅ Bien (organizado):

## Estilo de Código

### Indentación
- 2 espacios (no tabs)

### Variables
- Usa const por defecto
- Usa let solo si reasignas
- Evita var

## Validación

### Input Validation
- Valida TODOS los inputs del usuario
- Usa Joi o Zod para schemas
- Retorna 400 con mensaje específico

## Async Code

### Promises
- Usa async/await (no callbacks)
- Siempre maneja errores con try/catch

3. Revisa y Actualiza Periódicamente

Las convenciones evolucionan. Tu memoria también debe evolucionar.

Calendario sugerido:

Enterprise Policy: Review trimestral (Q1, Q2, Q3, Q4)
Project Memory: Review al inicio de cada sprint
User Memory: Review mensual

Checklist de review:

¿Hay reglas obsoletas? (ej: "Usa Webpack" → ya migraste a Vite)
¿Hay nuevas convenciones del equipo?
¿Hay conflictos entre niveles?
¿Hay duplicación entre archivos?

4. Mantén Project Rules Enfocados

Cada archivo de rules debe cubrir UN topic específico.

❌ Mal (archivo gigante):

.claude/rules/everything.md  (2000 líneas)

✅ Bien (archivos modulares):

.claude/rules/
  api/
    validation.md         (100 líneas)
    authentication.md     (80 líneas)
    rate-limiting.md      (50 líneas)
  testing/
    unit-tests.md         (120 líneas)
    e2e-tests.md          (90 líneas)

5. Usa Ejemplos Concretos

Claude aprende mejor con ejemplos que con descripciones abstractas.

❌ Mal (abstracto):

Usa buena gestión de errores en las API

✅ Bien (ejemplo concreto):

## Error Handling en API

Ejemplo correcto:

```typescript
@Post('/users')
async createUser(@Body() dto: CreateUserDto) {
  try {
    const user = await this.userService.create(dto);
    return { success: true, data: user };
  } catch (error) {
    if (error instanceof ValidationError) {
      throw new BadRequestException({
        message: 'Validación fallida',
        errors: error.details
      });
    }

    if (error instanceof ConflictError) {
      throw new ConflictException('Email ya existe');
    }

    // Errores inesperados
    this.logger.error('Error creando usuario', error);
    throw new InternalServerErrorException('Error interno');
  }
}

Ejemplo INCORRECTO (no hacer):

@Post('/users')
async createUser(@Body() dto: CreateUserDto) {
  const user = await this.userService.create(dto);  // No maneja errores
  return user;
}


### 6. Documenta el "Por Qué", No Solo el "Qué"

**❌ Mal (solo dice qué):**

```markdown
- Usa Redis para caché
- Timeout de sesión: 15 minutos

✅ Bien (explica por qué):

- Usa Redis para caché
  - Por qué: PostgreSQL no escala para miles de requests/seg en queries frecuentes
  - Alternativa considerada: Memcached (descartada por falta de persistencia)

- Timeout de sesión: 15 minutos
  - Por qué: Balance entre seguridad y UX (security requiere < 30min, UX prefiere > 10min)
  - Contexto: Financial app con datos sensibles

7. Usa Condicionales con Moderación

Las reglas condicionales (con paths: frontmatter) son potentes, pero pueden hacer el sistema difícil de debuggear.

Guía de uso:

Usa condicionales cuando: Reglas aplican a tipo de archivo específico (ej: API, tests, components)
Evita condicionales cuando: Reglas son generales para todo el proyecto

Ejemplo de buen uso:

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

# Estas reglas SOLO para archivos de API

Ejemplo de mal uso:

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

# Estas reglas para TODO el proyecto
# (No necesitas condicional, pon en CLAUDE.md)

Limitaciones y Consideraciones

1. Límite de Tokens

Todos los archivos de memoria se cargan en el contexto de Claude. Si tienes demasiadas memories muy largas, consumes tokens rápidamente.

Síntomas:

Sesiones lentas
Respuestas truncadas
Error: "Context limit exceeded"

Solución:

Mantén memories concisas (< 500 líneas por archivo)
Usa imports para dividir archivos grandes
Elimina reglas obsoletas

2. Límite de Recursión en Imports

Los imports de archivos tienen un límite de 5 niveles de profundidad.

Esto funciona:

# CLAUDE.md
@docs/architecture.md

# docs/architecture.md
@docs/api/design.md

# docs/api/design.md
@docs/api/authentication.md

Esto NO funciona (6 niveles):

# CLAUDE.md → import 1
# → import 2
# → import 3
# → import 4
# → import 5
# → import 6 (RECHAZADO)

3. Conflicts Entre Niveles

Si hay instrucciones contradictorias, el nivel más específico gana. Pero esto puede causar confusión.

Ejemplo problemático:

# Enterprise Policy
- Nunca uses console.log

# Project Memory
- Usa console.log para debugging (conflicto!)

Resultado: Project Memory gana, pero puede violar políticas corporativas.

Solución:

Sé explícito sobre overrides:

# Project Memory
- En desarrollo local: console.log permitido para debugging
- Antes de commit: elimina TODOS los console.log (Enterprise Policy aplica)

4. Sensibilidad a Prompts

Claude interpreta las memories como instrucciones, pero no son comandos absolutos. Puedes pedir explícitamente que ignore una regla si es necesario.

Ejemplo:

# User Memory
- Nunca uses var en JavaScript

Conversación:

Tú: Convierte este código legacy a ES6 pero mantén var por compatibilidad con IE11

Claude: Entendido. Aunque mi configuración prefiere const/let, en este caso
mantendré var por los requisitos de compatibilidad con IE11.

Solución de Problemas

Mis Memories No Se Están Cargando

Síntomas:

Claude no respeta las reglas que definiste en CLAUDE.md.

Checklist:

¿El archivo está en la ubicación correcta?

# Verifica ubicaciones
ls ~/.claude/CLAUDE.md              # User memory
ls .claude/CLAUDE.md                # Project memory
ls /etc/claude-code/CLAUDE.md       # Enterprise (Linux)

¿El archivo tiene el nombre correcto?
- Debe ser exactamente CLAUDE.md (mayúsculas)
- No claude.md, Claude.md, CLAUDE.txt

¿Estás en el directorio correcto?

pwd  # Verifica que estás en la raíz del proyecto

¿Reiniciaste Claude Code después de crear el archivo?

Las memories se cargan al inicio. Si creaste un archivo nuevo, reinicia.
Usa /memory para verificar:
```
/memory
```
Esto lista TODOS los archivos de memoria cargados. Si no aparece tu archivo, hay un problema.

Conflicts Entre Reglas

Síntomas:

Claude está haciendo algo que contradice tus reglas.

Debugging:

Identifica qué nivel está ganando:

Tú: ¿Qué reglas tienes cargadas sobre indentación?

Claude: Tengo estas reglas sobre indentación:
1. Enterprise Policy: 4 espacios
2. User Memory: 2 espacios
3. Project Memory: tabs

La regla más específica (Project Memory) gana: tabs

Verifica el orden de precedencia:

Project Local > Project Rules > Project Memory > User Rules > Enterprise
Elimina o ajusta el conflicto:

Decide qué nivel debe ganar y elimina/ajusta los otros.

Rules Condicionales No Aplican

Síntomas:

Definiste reglas con paths: frontmatter pero Claude no las respeta en esos archivos.

Checklist:

¿El frontmatter está bien formateado?
```
---
paths:
  - "src/api/**/*.ts"
---
```
Debe tener:
- --- antes y después
- paths: exactamente (no path:)
- Array con - delante de cada pattern

¿El pattern coincide con la ruta del archivo?

# Tu archivo
src/api/users/controller.ts

# Tu pattern
src/api/**/*.ts  ✅ Coincide

# Pattern incorrecto
api/**/*.ts      ❌ No coincide (falta src/)

¿Estás trabajando en ese archivo?

Las reglas condicionales solo se cargan cuando Claude lee archivos en esos paths.

Enterprise Policy No Se Aplica

Síntomas:

Configuraste Enterprise Policy pero los usuarios la están bypassing.

Posibles causas:

Users tienen overrides en niveles más específicos

Solución: Haz que Enterprise Policy sea MÁS específica y clara:

# Enterprise Policy

## OBLIGATORIO - NO PUEDE SER OVERRIDDEN POR OTRAS MEMORIES

### Secrets Management
NUNCA hardcodees secrets. Esta regla NO puede ser ignorada en ningún
nivel de memoria (User, Project, Local). Si Claude detecta un secret
hardcodeado, debe RECHAZAR el cambio y notificar a security@company.com.

Enterprise Policy no está desplegado en todas las máquinas

Verifica con Ansible/MDM que el archivo llegó:
```
# En cada máquina
cat /etc/claude-code/CLAUDE.md
```
Usuarios están usando Claude Code web sin Enterprise Policy

Enterprise Policy solo funciona en CLI local. Si usan claude.ai/code, necesitas gestionar policies vía APIs de Anthropic (contacta Enterprise Support).

Conclusión

El sistema de memoria de Claude Code transforma la experiencia de desarrollo de "repetir instrucciones en cada sesión" a "configurar una vez, aplicar siempre".

Qué hemos cubierto:

Los 5 niveles de memoria y sus propósitos específicos
Jerarquía y precedencia (de Enterprise a Local)
Project Rules modulares con condicionales por path
Comandos /init y /memory para gestión
Casos de uso prácticos (enterprise, multi-proyecto, equipos)
Mejores prácticas (especificidad, estructura, ejemplos)
Troubleshooting de problemas comunes

¿Qué hacer ahora?

Setup Inicial (15 minutos)

Crea tu User Memory personal:
```
mkdir -p ~/.claude
nano ~/.claude/CLAUDE.md
```
Incluye tus preferencias de estilo, naming, herramientas.

Bootstrap Project Memory en tu proyecto actual:

cd tu-proyecto
claude init
# o manualmente:
mkdir -p .claude
nano .claude/CLAUDE.md

Verifica que se cargaron:
```
/memory
```

Optimización Continua

Semana 1: Observa qué instrucciones repites a Claude
Semana 2: Añade esas instrucciones a CLAUDE.md
Semana 3: Organiza en Project Rules modulares si crece mucho
Mes 1: Review completo, elimina reglas obsoletas

Para Equipos

Si lideras un equipo de desarrollo:

Define convenciones en .claude/CLAUDE.md (commit a Git)
Organiza reglas modulares en .claude/rules/ por topic
Documenta el "por qué" de cada regla (onboarding de nuevos miembros)
Haz review trimestral para mantener memories actualizadas

Para Organizaciones

Si gestionas políticas enterprise:

Define políticas de seguridad/compliance en Enterprise Policy
Despliega vía MDM/Ansible a todas las máquinas
Monitorea compliance con auditorías periódicas
Actualiza políticas cuando cambien regulaciones

El sistema de memoria de Claude Code no es solo configuración técnica. Es documentación ejecutable que tu equipo mantiene viva, evoluciona con el proyecto, y se aplica automáticamente en cada sesión.

Si ya usas Claude Code en tu día a día (revisa mi guía de setup), configurar el sistema de memoria multiplica tu productividad al eliminar repeticiones y establecer un estándar consistente en todo tu equipo.