Módulo 6: Context Management para Proyectos Grandes

Context Window Reality — 1M Tokens

Descripción de la cápsula

"1 millón de tokens" suena como capacidad infinita. No lo es. En esta cápsula vas a entender los límites reales del context window, reconocer los síntomas de context pressure, y aprender las reglas prácticas que separan uso efectivo de desperdicio de contexto.

El dato clave: 1M tokens ≈ ~750K tokens de código (después del overhead de instrucciones del sistema) ≈ ~25K líneas efectivas de código. Eso cubre un proyecto mediano completo, pero no uno grande. Y la calidad de las respuestas de Claude Code degrada mucho antes de llegar al límite técnico.

Los Números Reales

De 1M tokens a líneas de código

1,000,000 tokens (context window total)
  - ~100,000 tokens (system prompt, instrucciones, conversation history)
  - ~150,000 tokens (overhead de herramientas y formato)
  = ~750,000 tokens disponibles para código
  
750,000 tokens ÷ ~3 tokens por línea de código Python
  = ~250,000 líneas teóricas
  
PERO: la calidad degrada significativamente después de ~50K tokens de código
  = ~15,000-25,000 líneas efectivas de alta calidad

La regla del 70%

En la práctica, usa máximo el 70% del context window para código. El 30% restante es para:

Conversación (tus prompts + respuestas de Claude)
System prompt y herramientas
Margen para que Claude "piense" (reasoning tokens)

Regla práctica: si tu proyecto tiene 20K líneas, cabe. Si tiene 100K líneas, necesitas chunking.

Síntomas de Context Pressure

Cómo reconocer que Claude Code pierde contexto

# Síntoma 1: Respuestas inconsistentes
> "Agrega type hints a user_service.py"
# Claude agrega type hints correctos

> "Ahora agrega type hints a order_service.py"
# Claude usa convenciones DIFERENTES a las de user_service
# (e.g., dict vs Dict, str | None vs Optional[str])

# Síntoma 2: "Olvidar" archivos
> "Actualiza el import de UserService en todos los archivos"
# Claude actualiza 7 de 9 archivos — olvidó 2

# Síntoma 3: Código contradictorio
> "Crea una función para calcular tax"
# Claude crea calculate_tax() con tasa 16%

# 50 mensajes después:
> "Usa la función de tax en order_service"
# Claude crea OTRA función calculate_tax() con tasa 21%
# Olvidó que ya había creado una

# Síntoma 4: Respuestas genéricas
> "¿Cómo maneja errores este proyecto?"
# Claude da una respuesta genérica sobre error handling
# en lugar de describir el patrón específico del proyecto

Qué hacer cuando detectas estos síntomas

Reducir context: quita archivos no relevantes de la conversación
Nueva sesión: empieza fresco con solo los archivos necesarios
CLAUDE.md: agrega contexto del proyecto que no requiere archivos completos
Chunking: divide el trabajo en piezas más pequeñas

Qué Incluir y Qué Excluir

Siempre incluir

Tipo	Por qué	Ejemplo
Interfaces/types	Definen contratos entre módulos	`models.py`, `types.py`, `schemas.py`
El archivo que modificas	Claude necesita ver el código actual	`order_service.py`
CLAUDE.md	Contexto persistente del proyecto	`.claude/CLAUDE.md`
Tests relevantes	Para verificar cambios	`test_order_service.py`
Config relevante	Para entender el entorno	`settings.py` (solo secciones relevantes)

Incluir selectivamente

Tipo	Cuándo incluir	Cuándo excluir
Implementaciones	Si las vas a modificar	Si solo necesitas la interfaz
Docs	Si informan la tarea	Si son README genérico
Tests de otros módulos	Si testean código que afectas	Si son independientes
Migrations	Si cambias schema	Si no tocas DB

Nunca incluir

Tipo	Por qué no
node_modules / venv	Miles de archivos irrelevantes
Build artifacts	Generados, no informativos
Imágenes / binarios	No son código
Logs	Cambiantes y largos
Todo el codebase "por si acaso"	Diluye lo importante

Progressive Context Loading

El patrón más efectivo

En vez de dar todo al inicio, carga contexto progresivamente:

# Sesión: Refactorizar order_service.py

# Paso 1: Contexto mínimo
> "Lee src/services/order_service.py y dime qué hace
   cada función"
# Claude lee 1 archivo, responde con análisis

# Paso 2: Agregar lo necesario
> "Ahora lee también src/models/order.py y
   src/models/product.py para entender los tipos"
# Claude tiene 3 archivos

# Paso 3: Agregar tests
> "Lee tests/test_order_service.py para entender
   el comportamiento esperado"
# Claude tiene 4 archivos — suficiente para refactorizar

# NUNCA: "Lee todo src/ para entender el proyecto"

Comparación: Estrategias de Context

Estrategia	Context usado	Calidad	Cuándo usar
Todo el codebase	100%	Baja (diluido)	Nunca en proyectos grandes
Solo archivos afectados	10-20%	Alta	Refactoring específico
Interfaces + afectados	20-30%	Muy alta	Cambios que cruzan módulos
Progressive loading	Incrementa	Alta	Exploración + modificación
CLAUDE.md + afectados	15-25%	Muy alta	Cualquier tarea con CLAUDE.md

Conexión con Proyecto

En el Proyecto del Módulo (cápsula 05), diseñas una context strategy para un proyecto de 100K+ líneas. Necesitas saber los límites reales para hacer recomendaciones prácticas.

Troubleshooting

Problema 1: Claude "olvida" lo que le dije hace 20 mensajes

Solución: Empieza nueva sesión con CLAUDE.md + archivos relevantes. Las sesiones largas acumulan context viejo.

Problema 2: Claude genera código inconsistente con el proyecto

Solución: Incluye CLAUDE.md con conventions del proyecto: naming, patterns, style.

Problema 3: No sé cuánto context estoy usando

Solución: Regla heurística — cada archivo Python ~100-300 tokens por línea de código. Un archivo de 200 líneas ≈ 3K-5K tokens.

Ejercicios

Ejercicio 1: Decidir qué incluir (Fácil)

Vas a refactorizar payment_service.py. ¿Cuáles de estos archivos incluyes?

payment_service.py (el archivo a modificar)
models/payment.py (model usado)
models/user.py (model de usuario)
services/email_service.py (envía confirmación)
utils/string_utils.py (utilidad genérica)
README.md
tests/test_payment_service.py
config/settings.py

Ver solución

✅ 1. payment_service.py — es el archivo a modificar
✅ 2. models/payment.py — define los tipos que usa
❌ 3. models/user.py — solo si payment_service lo importa directamente
⚠️ 4. email_service.py — solo si vas a modificar la integración
❌ 5. string_utils.py — irrelevante para payment
❌ 6. README.md — no informa el refactoring
✅ 7. tests/test_payment_service.py — para verificar comportamiento
⚠️ 8. config/settings.py — solo la sección de payment config

Resultado: 3 archivos siempre + 2 condicionales = 3-5 archivos, no 8.

Ejercicio 2: Detectar context pressure (Medio)

Lee estos outputs de Claude Code e identifica cuáles son síntomas de context pressure:

Claude sugiere crear una función que ya existe en otro archivo
Claude usa Optional[str] en un archivo y str | None en otro
Claude no encuentra un archivo que le pediste
Claude da una respuesta genérica sobre testing en vez de mencionar pytest fixtures específicas del proyecto

Ver solución

✅ Context pressure — olvidó que la función ya existe
✅ Context pressure — perdió las conventions del proyecto
❌ No es context pressure — probablemente un path incorrecto
✅ Context pressure — no tiene el contexto del proyecto para dar respuesta específica

Errores Comunes con el Context Window

Error 1: "Llenar el context aprovecha más capacidad"

Síntoma: Pegas todo el codebase para "darle más información a Claude" y la calidad de las respuestas baja.

Por qué pasa: El modelo distribuye su atención sobre todo el contenido. Información irrelevante "compite" con la relevante. Más contexto ≠ mejor contexto. Estudios y experiencia muestran que la calidad cae notoriamente después del ~70% del context.

Cómo corregir: Aplica la regla del 70%. Si tu codebase ocupa más, hace chunking (cápsula 03). Si cabe en menos del 70%, igualmente filtra lo irrelevante.

Error 2: Mantener una sesión por horas

Síntoma: Trabajas con Claude Code una sesión completa de 4 horas. Las últimas respuestas son notablemente peores que las primeras.

Por qué pasa: Cada turno acumula context. Después de 50+ turnos, el context tiene mucha conversación vieja que diluye lo importante. Aunque no llegues al límite técnico, la calidad degrada.

Cómo corregir: Sesiones de máximo 1-2 horas. Cuando notes degradación, empieza nueva sesión con CLAUDE.md + archivos relevantes. La cápsula 04 desarrolla criterios de session hygiene.

Error 3: No medir tokens de los archivos

Síntoma: Te sorprende cuando Claude Code dice "estás cerca del límite" — porque nunca calculaste.

Por qué pasa: "Tres archivos" suena chico. Pero un archivo Python de 500 líneas son ~5K tokens. Tres archivos así son 15K. Más conversación de 50 turnos a 500 tokens cada uno son 25K más. Suma rápido.

Cómo corregir: Estima antes de pegar. Heurística: ~3 tokens/línea de código Python, ~5 tokens/línea de YAML/HTML/JSON. Multiplica por archivos. Si pasas el 50% del context con código, tienes problema.

Error 4: Asumir que el problema es el modelo

Síntoma: Claude Code "se equivoca". Repites el prompt esperando mejor respuesta. No mejora.

Por qué pasa: El modelo no se equivocó — el contexto es malo. Falta información relevante o sobra irrelevante. El instinto es "ser más claro en el prompt", pero el problema está en qué archivos están cargados.

Cómo corregir: Diagnostica el contexto antes de re-prompt. ¿Qué archivos están en context? ¿Falta CLAUDE.md? ¿Sobra historial irrelevante? Empezar nueva sesión con context bien curado es muchas veces mejor que iterar prompts.

Resumen

1M tokens ≠ código ilimitado — en la práctica, 15-25K líneas efectivas
Síntomas de context pressure: inconsistencias, olvidos, respuestas genéricas
Incluye interfaces + archivos afectados, excluye todo lo demás
Progressive loading es más efectivo que dar todo al inicio
Nueva sesión cuando detectas context pressure — mejor que luchar contra ella
Mide tokens antes de pegar archivos
Sesiones cortas (1-2 hrs) mantienen calidad consistente

Próxima cápsula: Chunking Strategies — cómo dividir el trabajo cuando el proyecto no cabe en una sesión.

Conexión con el Resto de la Guía

Lo que aprendiste aquí (límites reales y síntomas de pressure) es la base para:

Cápsula 03 (Chunking) — la solución estructural cuando context no alcanza
Cápsula 04 (CLAUDE.md) — la solución de contexto persistente que no consume window dinámico
Cápsula 05 (Proyecto) — diseñar una strategy completa para 100K+ líneas
Módulo 7 (Modernizar Legacy) — donde modernizas codebases grandes que requieren chunking
Módulo 8 (Proyecto Integrador) — donde aplicas todo a un proyecto real

Si en algún momento posterior ves los síntomas que describimos arriba, la respuesta no es "darle más contexto a Claude" — es regresar a las técnicas de este módulo y diagnosticar qué tipo de pressure tienes.

El reflejo correcto en orden de costo: (1) revisar qué archivos están en context, (2) eliminar los irrelevantes, (3) consultar CLAUDE.md, (4) si nada resuelve, empezar nueva sesión.

Recursos Adicionales

Anthropic - Context Window - Specs oficiales de context windows
Claude Code - Best Practices - Prácticas recomendadas
Token Estimation for Code - Herramienta para estimar tokens
Managing AI Context - Prompt Engineering - Técnicas de Anthropic
Effective Context Management - Research sobre uso efectivo de context

← AnteriorMódulo 6: Context Management para Proyectos Grandes Siguiente →Chunking Strategies — Feature, Layer, Module