Gestión de Contexto en Claude Code: Patrones de Diseño para CLAUDE.md

La gestión de contexto en Claude Code se resume en un principio: mantén CLAUDE.md corto y específico, divide las reglas por directorio y gestiona activamente lo que entra en la ventana de contexto. Los cinco patrones de diseño de CLAUDE.md en este artículo — Mínimo, Seccionalizado, Enfocado en Tareas, Jerárquico e Índice de Contexto — combinados con Auto Memory, Hooks y división de sesiones, harán que Claude realmente siga tus reglas.

Escribiste un CLAUDE.md detallado, solo para ver cómo Claude Code lo ignoraba por completo. "Ni siquiera lo leíste, ¿verdad?" — es una de las quejas más comunes en GitHub Discussions. El problema normalmente no es Claude. Es cómo está escrito el CLAUDE.md.

Este artículo cubre los patrones prácticos de gestión de contexto que surgen del uso real de Claude Code. Combinando los patrones de diseño correctos para CLAUDE.md con .claudeignore y Plan mode, puedes lograr un aumento significativo en productividad — aquí te explico exactamente cómo.

¿Por Qué la Ventana de Contexto se Llena Tan Rápido?

Desde marzo de 2026, Claude Code soporta hasta 1 millón de tokens de contexto con Opus 4.6 y Sonnet 4.6 — un salto masivo desde el límite anterior de 200K. Pero incluso con 1M de tokens, la gestión de contexto sigue siendo importante. Más contexto no significa mejor output — significa más ruido que Claude tiene que filtrar.

Toma un proyecto Next.js donde le pides a Claude que refactorice cada página. Solo leer los archivos fuente consume decenas de miles de tokens. Añade el historial de conversación, el contenido de CLAUDE.md, definiciones de herramientas, servidores MCP y el código generado, y el contexto se llena más rápido de lo esperado.

¿Qué pasa cuando el contexto se infla? La atención de Claude se diluye. Las reglas importantes compiten con miles de líneas de código irrelevante. En la práctica, una sesión enfocada de 200K a menudo supera a una sesión dispersa de 1M porque la densidad de señal es mayor.

Estimaciones aproximadas de tokens (por experiencia):

• Un CLAUDE.md típico: 2,000–5,000 tokens
• System prompt + herramientas: ~40,000 tokens
• Un archivo fuente (500 líneas): ~5,000 tokens
• Una sesión de conversación larga: 50,000–200,000 tokens

Usa el comando /context para ver exactamente cómo se está distribuyendo tu presupuesto de tokens. Claude Code también muestra un indicador de uso de contexto en la parte inferior de la pantalla.

La gestión de contexto es fundamentalmente un problema de diseño: decidir qué entra en la ventana y qué se queda fuera — sin importar el tamaño de la ventana.

¿Por Qué Claude Code Ignora Tu CLAUDE.md?

Por experiencia, los fallos de CLAUDE.md casi siempre se reducen a tres causas raíz.

Error 1: Demasiadas reglas

Cuando metes convenciones de código, estructuras de directorios, patrones prohibidos y políticas de testing todo a la vez, Claude tiene que procesar todo antes de hacer cualquier otra cosa. La atención se dispersa y las reglas importantes dejan de cumplirse.

Error 2: Instrucciones vagas

"Escribe código limpio" y "hazlo fácil de entender" no funcionan. Escribe reglas que se puedan evaluar mecánicamente: "Las funciones tienen una sola responsabilidad" o "Los comentarios se escriben en inglés."

Error 3: Un solo archivo para todo el proyecto

Un único CLAUDE.md en la raíz tiende a crecer descontroladamente y solo puede expresar reglas genéricas a nivel de proyecto. Cuando diferentes módulos tienen diferentes requisitos, colocar archivos CLAUDE.md separados en subdirectorios funciona mucho mejor.

¿Qué Patrones de Diseño de CLAUDE.md Realmente Funcionan en la Práctica?

Estos son los cinco patrones en los que me he asentado después de extenso ensayo y error.

Patrón 1: Mínimo (para proyectos pequeños)

# Project Rules
- Language: TypeScript strict mode
- Test: Vitest. Run `pnpm test` before committing
- Style: No inline styles. Tailwind only

Escribe solo lo esencial. Apunta a menos de diez líneas. No le temas al espacio en blanco.

Patrón 2: Seccionalizado (para proyectos medianos)

# CLAUDE.md

## Critical Rules (non-negotiable)
- No direct writes to production DB
- Never console.log secrets

## Code Style
- Prefer pure functions
- Isolate side effects in useEffect / event handlers

## Project Context
- Next.js 15 App Router
- Supabase (RLS enabled)
- Deploy target: Vercel

Separar las "reglas catastróficas si se rompen" de las "guías de estilo" deja claro dónde Claude debería enfocar su atención.

Patrón 3: Enfocado en Tareas (para sesiones de trabajo específicas)

Convierte el patrón Enfocado en Tareas en una plantilla reutilizable. Mantén una versión en blanco con tres secciones — "Tarea de hoy," "Archivos a tocar," y "Restricciones" — y rellénala al inicio de la sesión. Este solo hábito mejora drásticamente qué tan bien Claude se mantiene en el camino correcto.

# Current Task Context
Today's task: Refactor the auth module
Files to touch: src/auth/ only
Files NOT to touch: src/api/, src/components/

## Constraints
- Do not modify Supabase Auth
- Existing tests must pass (adding new tests is fine)

Efectivo cuando quieres que Claude se enfoque exclusivamente en el trabajo de hoy en un proyecto de larga duración. Reescríbelo al inicio de cada sesión.

Patrón 4: Jerárquico (para proyectos grandes)

root/CLAUDE.md              # Project-wide rules (keep minimal)
src/api/CLAUDE.md           # API layer rules
src/components/CLAUDE.md    # UI layer rules
src/lib/CLAUDE.md           # Utility layer rules

Claude Code busca hacia arriba desde el directorio actual y lee todos los archivos CLAUDE.md que encuentra. Separar por capa te permite aplicar las reglas correctas al contexto correcto.

Patrón 5: Índice de Contexto (para referenciar documentación externa)

## Architecture Decision Records
See: docs/adr/ (key design decisions live here)

## API Specification
See: docs/api-spec.md (full endpoint list)

## Known Issues
- #234: Session persists after logout in some edge cases (in progress)

En lugar de copiar toda tu documentación en CLAUDE.md, úsalo como un índice — "qué leer para saber qué." Esto mantiene el archivo ligero mientras orienta a Claude eficazmente.

¿Cómo Usas .claudeignore para Reducir el Consumo de Tokens?

.claudeignore usa la misma sintaxis que .gitignore y especifica archivos que Claude Code debería omitir al indexar el proyecto.

# .claudeignore

# Build artifacts (always exclude)
.next/
dist/
out/
node_modules/

# Large files Claude never needs to read
*.lock
pnpm-lock.yaml
package-lock.json

# Test snapshots (huge token consumers)
**/__snapshots__/
**/*.snap

# Secrets
.env*
*.pem
*.key

# Images and binaries
*.png
*.jpg
*.svg
*.woff2

# Logs
*.log
logs/

Las exclusiones de mayor valor son node_modules/ y .next/. Excluir solo estos reduce dramáticamente el consumo de tokens.

Los archivos de bloqueo como pnpm-lock.yaml también merecen atención — pueden tener miles de líneas, y cargar uno accidentalmente en el contexto desperdicia una porción significativa de tu presupuesto de tokens.

¿Cuándo Deberías Usar Plan Mode en Claude Code?

Plan mode hace que Claude piense en qué va a hacer antes de escribir una sola línea de código. Presiona Shift+Tab dos veces para activar Plan mode, o escribe /plan directamente en el prompt (disponible desde v2.1.0).

Cuándo usarlo:

• Refactorizaciones de amplio alcance que afectan más de 10 archivos
• Cambios en el esquema de la base de datos
• Cambios en flujos de autenticación o pagos
• Cuando genuinamente no sabes por dónde empezar

Cuándo puedes saltártelo:

• Corrección de bugs con causa raíz clara
• Añadir un nuevo componente
• Añadir o actualizar tests
• Renombramientos simples o movimientos de archivos

La mayor ventaja de Plan mode es detectar problemas de alineación antes de que empiece la implementación. Cuando Claude dice "Voy a implementar A → B → C," puedes decir "en realidad, haz C antes que B" — en lugar de descubrir la discrepancia después de que se han escrito cientos de líneas.

# Presiona Shift+Tab dos veces (o escribe /plan), luego da tu instrucción
> I want to migrate user auth from JWT to Supabase Auth. Plan only, don't implement yet.

Revisa el plan que Claude produce. Si se ve bien, sal de Plan mode con Shift+Tab y dile a Claude que proceda con la implementación.

¿Cómo Elegir Entre /compact y /clear?

A medida que las sesiones se alargan, la acumulación de contexto degrada la calidad de las respuestas. Dos comandos abordan esto.

/compact — Comprimir contexto

Resume el historial de conversación, conservando solo las decisiones importantes. Úsalo cuando quieras continuar la misma sesión pero empiece a sentirse pesada.

> /compact

/clear — Resetear contexto

Borra todo el historial de conversación para un inicio limpio. Úsalo cuando una tarea está completa o estás cambiando a un trabajo completamente diferente. CLAUDE.md se releerá.

Verificar uso de contexto — Usa /context para ver exactamente cómo se distribuyen los tokens entre system prompt, herramientas, servidores MCP, memoria y conversación. Es la herramienta de diagnóstico más útil cuando Claude empieza a comportarse de forma extraña.

En la práctica, el simple hábito de ejecutar /clear al final de cada tarea completada previene la mayoría de la contaminación de contexto.

Para estrategias específicas de sesiones largas, consulta Claude Code Memory Management: Cómo Mantener Sesiones Largas Productivas.

Auto Memory — Claude Ahora Toma Sus Propias Notas

Agregado a finales de febrero de 2026, Auto Memory permite a Claude Code registrar automáticamente información importante durante las conversaciones. Los archivos se guardan en ~/.claude/projects/<project>/memory/, con MEMORY.md como archivo índice.

Cómo se dividen las responsabilidades entre CLAUDE.md y Auto Memory:

Ejemplos prácticos:

• Dile a Claude "no uses mocks en los tests" y Auto Memory lo registra como feedback. Persiste entre sesiones
• Contexto del proyecto que no aparece en el código (plazos, requisitos de stakeholders) se registra automáticamente
• "Este usuario es un desarrollador senior de TypeScript" — Claude ajusta la profundidad de las explicaciones

Lo que sigue perteneciendo a CLAUDE.md no ha cambiado: reglas, restricciones, stack tecnológico. Pero "feedback para Claude" y "estado del proyecto" deberían vivir en Auto Memory. Mezclarlos infla CLAUDE.md.

# Gestionar Auto Memory
> /memory          # Ver entradas de memoria

Solo las primeras 200 líneas de MEMORY.md se inyectan en el contexto, así que necesitarás limpiar entradas antiguas a medida que la memoria crezca.

Hooks — Convierte "Solicitudes" en "Obligaciones"

Las reglas en CLAUDE.md son en última instancia solicitudes. Claude podría olvidarlas bajo presión de contexto. Los Hooks te permiten ejecutar scripts de shell automáticamente en respuesta a eventos específicos — elevando las reglas de "por favor haz esto" a "esto va a suceder."

Estructura básica de Hook (settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/check-script.sh"
          }
        ]
      }
    ]
  }
}

Tres eventos de Hook que más importan en la práctica:

1. PreToolUse — Verificar antes de que se ejecute una herramienta

Ejecutar un linter antes de cualquier escritura de archivo, bloquear escrituras a directorios específicos, etc.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/hooks/pre-write-check.sh $FILE_PATH"
          }
        ]
      }
    ]
  }
}

2. PostToolUse — Procesar después de que se ejecute una herramienta

Ejecutar tests automáticamente después de un commit, ejecutar un formateador después de cambios en archivos, etc.

3. PreCompact — Guardar información crítica antes de la compresión de contexto

Cuando la auto-compactación comprime el contexto, las decisiones críticas pueden resumirse y perderse. PreCompact te permite escribir el estado clave en un archivo antes de que eso suceda — una solución de raíz para "Claude olvidó los requisitos a mitad de sesión."

Claude Code actualmente soporta más de 20 eventos de hook — incluyendo SessionStart, WorktreeCreate, InstructionsLoaded y más. No necesitas todos. Los tres anteriores cubren la mayoría de los casos de uso del mundo real.

Custom Commands — Atajos de Un Comando para Instrucciones Repetidas

Si te encuentras escribiendo las mismas instrucciones cada vez, Custom Commands resuelve esto. Coloca un archivo Markdown en .claude/commands/ y se vuelve invocable con /. Custom Commands se ha integrado en "Skills" (.claude/skills/<name>/SKILL.md), pero .claude/commands/ sigue funcionando.

Ejemplo: Comando de revisión de código

<!-- .claude/commands/review.md -->
Revisa el siguiente archivo para:
- Problemas de seguridad de tipos
- Manejo de errores faltante
- Brechas en la cobertura de tests

Objetivo: $ARGUMENTS

Uso:

> /review src/auth/login.ts

Ejemplo: Verificación pre-commit

<!-- .claude/commands/pre-commit.md -->
Ejecuta lo siguiente en orden:
1. `pnpm typecheck` para verificación de tipos
2. `pnpm test` para ejecución de tests
3. Si hay problemas, corrígelos. Si está limpio, ejecuta `git add` y `git commit`

Cuándo usar cuál:

• Custom Commands = invocados explícitamente por ti (/review)
• Hooks = disparados automáticamente por eventos (al guardar archivo)

¿Cómo Divides Proyectos Grandes en Múltiples Sesiones?

No intentes hacer todo en una sola sesión. Ese es el principio fundamental de la gestión de contexto.

Divide los proyectos grandes en fragmentos del tamaño de una sesión:

Ejemplo de división por sesiones:

• Sesión 1: Refactorización del módulo de autenticación
• Sesión 2: Limpieza de endpoints de la API
• Sesión 3: Reestructuración del manejo de estado del frontend
• Sesión 4: Adición de tests y mejoras de cobertura

Registra los traspasos en Markdown.

# session-handoff.md (update at session end)

## Completed
- Migrated src/auth/login.ts from JWT to Supabase Auth
- All existing tests passing

## Next Session
- Migrate src/auth/register.ts (same approach as login.ts)
- Update auth check in middleware.ts

## Notes
- Supabase Row Level Security stays enabled
- NEXT_PUBLIC_SUPABASE_URL already set in .env.local

Al inicio de la siguiente sesión, referencia este archivo en CLAUDE.md o pégalo al inicio de la conversación. El contexto se preserva incluso cuando las sesiones se interrumpen.

Traspasos de sesión en la era de Auto Memory: Con Auto Memory habilitado, Claude registra decisiones importantes automáticamente. Sin embargo, Auto Memory solo guarda lo que Claude juzga como importante. Los detalles específicos de traspaso del proyecto ("a continuación, trabaja en este archivo") aún deben escribirse manualmente en session-handoff.md para mayor confiabilidad.

¿Cómo Construyes un Hábito de Monitoreo de Contexto?

Simplemente ser consciente de la gestión de contexto cambia la calidad del output. Esta es la rutina que me ha funcionado.

Lista de verificación pre-sesión:

• ¿La tarea de hoy está claramente definida?
• ¿CLAUDE.md coincide con la tarea de hoy?
• ¿.claudeignore está excluyendo archivos innecesarios?
• ¿Hay una nota de traspaso de la última sesión?

Puntos de control durante la sesión:

• Revisar /context cada 30 minutos
• Ejecutar /compact ante la primera señal de desviación
• Ejecutar /clear después de cada tarea completada

Fin de sesión:

• Actualizar session-handoff.md
• Reflejar las decisiones tomadas en CLAUDE.md
• Anotar el contexto que se necesitará la próxima vez

La gestión de contexto es la base para obtener valor real de Claude Code. La herramienta tiene capacidades notables, pero desbloquearlas requiere pensar como un arquitecto — diseñar el entorno de información, no solo dar comandos. CLAUDE.md es tu plano. El contexto es tu recurso. Gestiona ambos bien y estarás trabajando a un nivel completamente diferente.

¿Cómo dividir CLAUDE.md en monorepos?

A medida que los proyectos crecen, poner todas las reglas en un solo CLAUDE.md no es práctico. Claude Code lee el directorio .claude/rules/ y los archivos CLAUDE.md de subdirectorios de forma jerárquica.

CLAUDE.md raíz (todo el proyecto):

# Reglas del Proyecto
- TypeScript strict mode obligatorio
- Tests con Vitest
- Mensajes de commit siguen Conventional Commits

.claude/rules/frontend.md (específico del frontend):

# Reglas del Frontend
- Preferir Server Components
- "use client" solo cuando sea necesario
- Usar clases utilitarias de Tailwind CSS v4

packages/api/CLAUDE.md (específico del paquete API):

# Reglas de la API
- Usar Hono
- Validar respuestas con esquemas zod
- Devolver errores en formato RFC 7807

Esta estructura jerárquica sigue tres principios:

1. La raíz solo contiene reglas compartidas — reglas mínimas que aplican a todos los paquetes
2. .claude/rules/ se divide por dominio — frontend, backend, infraestructura
3. CLAUDE.md en subdirectorios para reglas locales — se cargan solo al trabajar en ese directorio

Claude Code carga automáticamente los archivos CLAUDE.md relevantes según la ruta del archivo en el que trabajas. Al trabajar en packages/api/, se cargan tanto el CLAUDE.md raíz como packages/api/CLAUDE.md.

Regla práctica: Si el total de tu CLAUDE.md supera las 200 líneas, es hora de dividir. La raíz solo debe contener reglas que apliquen sin importar qué archivo estés editando.

Preguntas Frecuentes

¿Cuál es la diferencia entre CLAUDE.md y .claude/rules/?

CLAUDE.md en la raíz del proyecto se carga cada sesión sin importar qué archivo estés editando. Los archivos en .claude/rules/ también se cargan automáticamente pero son más adecuados para reglas específicas por dominio (frontend, backend, etc.). Usa CLAUDE.md raíz para reglas universales y .claude/rules/ para dividir por dominio. Consulta la documentación oficial de memoria para más detalles.

¿Funciona CLAUDE.md con la ventana de contexto de 1M?

Sí, y es aún más importante. Con 1M de tokens, Claude Code lee más archivos automáticamente, lo que significa más ruido compitiendo con tus reglas de CLAUDE.md. Mantener las reglas concisas asegura alta densidad de señal sin importar el tamaño de la ventana.

¿Cuántas líneas debería tener CLAUDE.md?

Apunta a 10–30 líneas en el CLAUDE.md raíz. Si el total de todos tus archivos CLAUDE.md supera las 200 líneas, es hora de dividir. Cada línea debería pasar la prueba: "¿Si elimino esto, Claude cometería un error?"

¿Puedo usar CLAUDE.md en un monorepo?

Absolutamente. Coloca un CLAUDE.md raíz mínimo con reglas compartidas, usa .claude/rules/ para reglas específicas por dominio, y añade archivos CLAUDE.md a nivel de paquete (ej: packages/api/CLAUDE.md). Claude carga todos los archivos aplicables según el directorio de trabajo.

¿Qué debería ir en CLAUDE.md vs Auto Memory?

CLAUDE.md es para reglas, restricciones y estructura del proyecto que tú escribes y mantienes. Auto Memory es para preferencias, feedback y estado del proyecto que Claude registra por sí mismo. No pongas "siempre usa este estilo de import" en Auto Memory — eso pertenece a CLAUDE.md.

¿.claudeignore realmente previene que Claude lea archivos?

Parcialmente. .claudeignore bloquea el descubrimiento automático de archivos (búsqueda, indexación), lo que reduce el consumo de tokens. Sin embargo, Claude puede leer un archivo explícitamente si tú o una herramienta lo referencia por ruta. Para control de acceso estricto, usa Hooks o permisos deny en settings.json.

¿Con qué frecuencia debería ejecutar /compact vs /clear?

Ejecuta /clear después de cada tarea completada — es el hábito más efectivo. Usa /compact cuando estás a mitad de tarea pero el contexto se siente pesado. Revisa /context periódicamente para ver los números reales antes de decidir.

¿Pueden los Hooks reemplazar completamente las reglas de CLAUDE.md?

No. Los Hooks aplican acciones específicas (bloquear escritura de archivos, ejecutar linters), pero no pueden reemplazar guías semánticas como "preferir funciones puras" o "usar Server Components por defecto." Usa CLAUDE.md para la intención y Hooks para la aplicación.

Conclusión

Si CLAUDE.md parece que está siendo ignorado, intenta reducirlo a la mitad primero. El miedo a dejar cosas fuera es menos dañino que la atención de Claude dispersándose demasiado.

Artículos relacionados:

• Claude Code vs GitHub Copilot: Veredicto Real de 3 Meses
• Soluciona el Error 'Context Window Exceeded' en Claude Code
• Cómo Reduje el Consumo de Tokens de Claude Code en un 50%
• Claude Code Solución de Problemas: Guía Completa
• Claude Code × TypeScript: Tips para Generación de Código Type-Safe
• Claude Code Memory Management: Guía para Sesiones Largas
• Claude Code Commands Cheatsheet