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

Pasé horas creando el CLAUDE.md perfecto, solo para ver cómo Claude Code lo ignoraba por completo. "Ni siquiera lo leíste, ¿verdad?" — he tenido ese pensamiento más veces de las que puedo contar. Resultó que el problema no era Claude. Era cómo estaba escribiendo mi CLAUDE.md.

Este artículo cubre los patrones prácticos de gestión de contexto que he desarrollado durante tres meses de uso diario de Claude Code. Combinando los patrones de diseño correctos para CLAUDE.md con .claudeignore y Plan mode, he logrado un aumento significativo en productividad — aquí te explico exactamente cómo.

¿Por Qué la Ventana de Contexto de 200,000 Tokens se Llena Tan Rápido?

La ventana de contexto de Claude Code actualmente es de 200,000 tokens. Suena enorme, pero en el trabajo real de desarrollo se llena más rápido de lo que esperarías.

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 y el código generado, y te acercas al límite rápidamente.

¿Qué pasa cuando el contexto se desborda? Claude empieza a olvidar información anterior. En el peor de los casos, simplemente ignora las reglas que escribiste en CLAUDE.md y sigue adelante como si no existieran. Esa es la verdadera razón por la que CLAUDE.md se "ignora."

Estimaciones aproximadas de tokens (por experiencia):

Un CLAUDE.md típico: 2,000–5,000 tokens
Un archivo fuente (500 líneas): ~5,000 tokens
Una sesión de conversación larga: 20,000–50,000 tokens

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

¿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)

markdown

# 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)

markdown

# 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)

markdown

# 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)

markdown

## 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 para activar Plan mode.

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.

bash

# Toggle Plan mode with Shift+Tab, then give your instruction
> 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, desactiva 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.

bash

> /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 el desglose del uso de contexto de la sesión. Claude Code también muestra un indicador de uso de contexto en la parte inferior de la pantalla.

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.

¿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.

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.

¿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.

Conclusión

Qué Hacer	Cómo
Mantener CLAUDE.md corto y específico	Apunta a 10–30 líneas. Solo reglas verificables mecánicamente
Usar ubicación jerárquica	Sub-archivos CLAUDE.md por módulo
.claudeignore es innegociable	Excluir node_modules, .next, *.lock como mínimo
Usar Plan mode para cambios grandes	Todo lo que toque más de 10 archivos debería empezar con un plan
Dividir sesiones por tarea	Una sesión = una tarea como regla general
Escribir notas de traspaso	session-handoff.md preserva el contexto entre sesiones

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.

¿Por Qué la Ventana de Contexto de 200,000 Tokens se Llena Tan Rápido?

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

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

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

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

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

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

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

Conclusión

Artículos Relacionados