Módulo 6: Context Management para Proyectos Grandes
Módulo 6: Context Management para Proyectos Grandes
Módulo 6: Context Management para Proyectos Grandes
Descripción de la cápsula
Los módulos anteriores funcionan bien para proyectos de tamaño mediano — 5K-20K líneas que Claude Code puede procesar sin problemas. Pero en la realidad profesional, los codebases son mucho más grandes: 50K, 100K, 500K+ líneas. Incluso con el context window de 1M tokens de Opus, hay límites prácticos. Este módulo te enseña cómo trabajar efectivamente dentro de esos límites.
La diferencia entre un usuario casual y un profesional de Claude Code es context management. El casual le da todo el codebase y espera que funcione. El profesional sabe qué incluir, qué excluir, cómo chunking el trabajo, y cómo CLAUDE.md da contexto persistente sin consumir context window.
Si en los módulos 4-5 sentiste que Claude Code perdía contexto, olvidaba archivos, o generaba código inconsistente — esos son síntomas de context pressure. Este módulo te da las soluciones.
Al terminar las 5 cápsulas, vas a poder trabajar con codebases de cualquier tamaño usando estrategias de context management, diagnosticar y resolver context pressure, escribir un CLAUDE.md que hace cada sesión productiva desde el primer mensaje, y diseñar una chunking strategy para proyectos 100K+.
Contexto del Módulo
¿Dónde estamos?
Guía #8, Phase 2: Refactoring, Módulo 6 de 6 (cierre de Phase 2).
Phase 2: Refactoring (Módulos 4-6)
├── Módulo 4: Refactoring Multi-File ✅
├── Módulo 5: Migración de Frameworks ✅
└── Módulo 6: Context Management ← ESTÁS AQUÍ
→ 1M tokens, chunking, CLAUDE.md, progressive context
Lo que ya sabes
De los módulos 4-5 dominas las técnicas de refactoring coordinado y migración de frameworks. Lo que probablemente ya notaste, sobre todo en proyectos no triviales: a veces Claude Code "pierde el hilo" — olvida un archivo que ya leíste, regenera código inconsistente con tu codebase, o repite preguntas obvias. Eso no es un bug del modelo. Es context pressure. Este módulo te enseña a prevenirlo.
¿Hacia dónde vamos?
Phase 3 aplica todo a legacy code. El Módulo 7 usa context management para modernizar código legacy en proyectos grandes. El Módulo 8 integra todo en una migración completa donde context management es esencial — sin él, simplemente no se puede ejecutar el proyecto integrador en un codebase real.
Objetivo Profesional
Al final de este módulo, podrás trabajar efectivamente con codebases de cualquier tamaño usando estrategias de context management.
Al final podrás:
- ✅ Entender los límites reales del context window (1M tokens ≠ 1M de código)
- ✅ Decidir qué incluir y excluir del context
- ✅ Aplicar chunking strategies: por feature, layer, o module
- ✅ Crear y mantener CLAUDE.md como project context file
- ✅ Implementar progressive context loading
- ✅ Gestionar sessions (cuándo empezar nueva vs continuar)
- ✅ Reconocer y resolver síntomas de context pressure
El Problema: Cuando 1M Tokens No Alcanzan
Para anclar el módulo, considera dos proyectos reales:
Proyecto chico (10K líneas) — sin problema
Codebase: ~10K líneas Python + tests
Tokens estimados: ~80K (8 tokens/línea promedio para código)
Capacidad del context window de Opus 1M:
→ El proyecto entero cabe ~12 veces
→ Puedes pegarlo todo y aún queda margen para razonamiento
→ Context management = lujo, no necesidad
Proyecto real (200K líneas) — la realidad de la industria
Codebase: ~200K líneas Python (un monolito de e-commerce típico)
Tokens estimados: ~1.6M
Capacidad del context window de Opus 1M:
→ El proyecto entero NO CABE
→ Aunque cupiera, llenar el context degrada la calidad
→ Context management = OBLIGATORIO
Sin context management:
→ Le pegas 30 archivos, Claude Code "olvida" la mitad
→ Generaste código que no usa el ORM correcto
→ Ignoraste convenciones del proyecto que están en docs/
→ Cada sesión repites el mismo onboarding
Con context management (este módulo):
→ CLAUDE.md persiste convenciones y reglas (cápsula 04)
→ Chunking strategy: trabajas por feature, no por todo (cápsula 03)
→ Progressive loading: empiezas con 5 archivos, expandes según necesites
→ Cada sesión es productiva desde el primer mensaje
El resultado tangible: sin context management, una task de 30 minutos en un proyecto chico se vuelve una task de 4 horas en un proyecto grande — lleno de retrabajo. Con context management, la task escala lineal con la complejidad del cambio, no con el tamaño del codebase.
Progresión del Módulo
Mapa del Módulo
| Cápsula | Tema | Qué aprenderás |
|---|---|---|
| 02 | Context Window Reality | Los límites reales de 1M tokens y síntomas de context pressure |
| 03 | Chunking Strategies | Dividir trabajo por feature, layer, o module |
| 04 | CLAUDE.md y Project Context | El archivo que hace cada sesión productiva desde el primer mensaje |
| 05 | Proyecto: Strategy para Proyecto 100K+ | Diseñar context strategy completa para un proyecto grande |
Flujo de aprendizaje
Empiezas entendiendo qué tan grande es 1M tokens en la realidad (cápsula 02) — y qué pasa cuando lo llenas. Después aprendes a particionar el trabajo (cápsula 03) para que nunca tengas que llenarlo. La cápsula 04 te da la herramienta de mayor leverage del módulo: CLAUDE.md, el archivo que da contexto sin consumir context window. Y el proyecto integra todo diseñando una strategy completa para un proyecto open-source de 100K+ líneas.
Conceptos Clave que Verás
Vista previa rápida de los conceptos centrales del módulo para que llegues con vocabulario:
Context Window
La cantidad máxima de tokens que el modelo puede procesar simultáneamente — input + output. En Opus actual: 1M de tokens. Pero caber y funcionar bien son cosas distintas (cápsula 02).
Context Pressure
Conjunto de síntomas que aparecen cuando el context se acerca al límite o contiene demasiada información irrelevante: el modelo "olvida" archivos, regenera código inconsistente, repite preguntas que ya respondiste. No es un bug — es información: necesitas reorganizar el contexto.
Chunking
Estrategia para particionar el trabajo (no el archivo): trabajas un feature/layer/module a la vez, no todo el codebase. Tres patterns principales:
- Feature chunking — ej. "tocar todo lo relacionado con autenticación"
- Layer chunking — ej. "modificar todos los repositories"
- Module chunking — ej. "trabajar dentro de
payments/solo"
CLAUDE.md
Archivo en la raíz del proyecto (o en .claude/) que persiste contexto entre sesiones: convenciones del codebase, naming, reglas de arquitectura, comandos frecuentes. Claude Code lo lee automáticamente. No consume tu context window dinámicamente — es contexto barato.
@-References
Sintaxis para incluir archivos específicos en un prompt sin pegarlos: @src/payments/processor.py. Permite selectividad quirúrgica: incluir 4 archivos relevantes vs pegar 40.
Progressive Context Loading
Patrón de empezar con el set mínimo de archivos y expandir cuando Claude Code te pida más (o cuando notes que falta contexto). Lo opuesto a "pego todo por si acaso".
Session Hygiene
Disciplina de cuándo cortar y empezar nueva sesión. Después de muchos turnos, el context acumulado puede degradar la calidad. A veces empezar fresco con un buen CLAUDE.md es más eficaz que continuar.
El Principio Central
Menos es más. Claude Code con 20 archivos relevantes es más efectivo que Claude Code con 200 archivos irrelevantes. Context management no es dar todo — es dar lo correcto.
Tres principios derivados:
- Selectividad sobre exhaustividad. Si el cambio es en
pricing/, no incluyasnotifications/. - Persistencia sobre repetición. Convenciones del proyecto van en CLAUDE.md, no se repiten en cada prompt.
- Progresión sobre todo-de-una-vez. Empieza con el set mínimo, expande cuando Claude Code te pida más.
Conexión con Proyecto
En el Proyecto del Módulo (cápsula 05), diseñas una context strategy completa para un proyecto open-source de 100K+ líneas: CLAUDE.md, chunking strategy, y templates de @-references para tareas comunes.
En el Módulo 8 (Proyecto Integrador), aplicas todo lo aprendido aquí al proyecto legacy real. Sin las técnicas de este módulo, el proyecto integrador es ejecutable solo en codebases pequeños — con ellas, escala a proyectos reales.
Síntomas de Context Pressure (Vista Previa)
Probablemente ya viste estos síntomas sin nombrarlos. La cápsula 02 los desarrolla — esta tabla te da una vista previa para que los reconozcas mientras lees el resto del módulo:
| Síntoma | Qué pasó | Solución (cápsula) |
|---|---|---|
| Claude Code "olvida" un archivo que ya leíste | El archivo se desplazó del foco de atención | Re-incluirlo o empezar sesión nueva (04) |
| Genera código inconsistente con tu codebase | No tiene presentes las convenciones | CLAUDE.md persistente (04) |
| Repite preguntas que ya respondiste | El contexto inicial se diluyó | Cortar sesión y reiniciar (04) |
| Código mezcla patterns de archivos no relevantes | Demasiado contexto irrelevante | Chunking + selectividad (03) |
| Respuestas más vagas a medida que avanza la sesión | Context window casi lleno | Compactación o nueva sesión (02, 04) |
| "Encontrar un import" toma muchas iteraciones | Falta orientación inicial del proyecto | CLAUDE.md con estructura del proyecto (04) |
Si llevaste el M01 (Onboarding) y M02 (Explore) sin ver ninguno de estos síntomas, probablemente trabajaste en proyectos chicos. En proyectos reales, vas a verlos — y ahora vas a saber qué hacer.
Anti-patrón frecuente: "Le doy más contexto y se arregla"
Cuando aparece el síntoma, la reacción intuitiva es dar más contexto ("dejame pegarle también este otro archivo"). Pero la causa común no es falta de contexto — es contexto mal organizado: archivos irrelevantes que diluyen la atención, o convenciones que el modelo no recuerda porque están en otra parte del prompt antiguo. La solución correcta suele ser menos:
- Empezar nueva sesión con el set mínimo de archivos
- Cargar CLAUDE.md (que persiste convenciones del proyecto)
- Usar @-references quirúrgicos en lugar de pegar bloques
La cápsula 02 desarrolla cómo diagnosticar correctamente, y la cápsula 04 cómo prevenirlo desde el inicio con un buen CLAUDE.md.
Trampas a Evitar al Cursar Este Módulo
Cinco malentendidos previsibles. Anticípalos antes de empezar.
1. "1M tokens significa que puedo pegar todo"
No. Caber y funcionar bien son cosas distintas. Llenar el context window degrada la atención del modelo: la información relevante se "diluye" entre la irrelevante. Estudios y experiencia práctica muestran que la calidad cae notoriamente al pasar el ~70% del context. La cápsula 02 desarrolla este punto con datos.
2. "CLAUDE.md es opcional"
En proyectos chicos sí. En proyectos grandes es el cambio de mayor leverage que puedes hacer. Sin CLAUDE.md, repites convenciones, naming, y reglas en cada sesión. Con CLAUDE.md, esas reglas son contexto persistente — Claude Code las "sabe" desde el primer mensaje. La cápsula 04 te enseña qué incluir y qué no.
3. "Chunking significa partir el archivo en pedazos"
No. Chunking aquí significa partir el trabajo: trabajas un feature a la vez, no todo el codebase. Si el cambio toca 8 archivos, esos 8 son tu chunk — no incluyes los 200 restantes. La cápsula 03 te da los 3 patterns (por feature, por layer, por module) y cuándo usar cada uno.
4. "Si Claude Code se confunde, le doy más contexto"
A veces. Pero más frecuentemente: menos contexto, mejor seleccionado. La confusión muchas veces viene de información contradictoria o duplicada. Eliminar archivos irrelevantes ayuda más que añadir explicaciones. La cápsula 02 te enseña a diagnosticar context pressure correctamente.
5. "Una sesión larga es mejor que muchas sesiones cortas"
Depende. Después de cierta cantidad de turnos, el context se acumula y degrada. Empezar una sesión nueva con un CLAUDE.md sólido y los archivos correctos es a menudo más eficaz que continuar una sesión larga. La cápsula 04 te da los criterios para decidir cuándo cortar.
Diagnóstico: ¿Cuál es tu Punto de Partida?
Cinco preguntas para calibrar antes de empezar.
Pregunta 1: ¿Has notado a Claude Code "olvidar" un archivo o detalle que mencionaste antes en la misma sesión?
Si sí: anota el caso. La cápsula 02 te da el vocabulario para entenderlo (context pressure, attention dilution) y las soluciones.
Si no: probablemente has trabajado en proyectos chicos. La cápsula 02 te prepara para cuando empieces a tocar codebases reales.
Pregunta 2: ¿Tienes un CLAUDE.md (o equivalente) en tus proyectos? ¿Qué hay dentro?
Si dijiste "sí, con convenciones y reglas": vas bien. La cápsula 04 te da una rúbrica para auditarlo y mejorarlo.
Si dijiste "no" o "está vacío": la cápsula 04 es la prioritaria del módulo. Es donde más leverage vas a obtener.
Pregunta 3: Cuando le das contexto a Claude Code, ¿sueles incluir más, menos, o lo justo?
Si dijiste "más, por si acaso": la trampa #1 te aplica. La cápsula 02 te muestra el costo de llenar el context.
Si dijiste "lo justo": ¿cómo decides "lo justo"? La cápsula 03 formaliza esto en chunking strategies.
Pregunta 4: ¿Sabes contar (estimar) cuántos tokens tiene tu codebase, o un subset?
Si sí: la cápsula 02 te da un mapa formal — lo que mide cada herramienta (tiktoken, Anthropic counter), las equivalencias prácticas (8 tokens/línea promedio).
Si no: lo vas a aprender. Es la base para tomar decisiones de context informadas.
Pregunta 5: ¿Cuándo empiezas una sesión nueva con Claude Code? ¿Por costumbre, por necesidad, nunca?
Si dijiste "cuando algo va mal": la cápsula 04 te enseña a anticipar el momento óptimo (no esperar al "algo va mal").
Si dijiste "siempre la misma sesión": la trampa #5 te aplica.
Si dudaste en 3 o más: este módulo es prioritario antes de Phase 3. Si respondiste todas con criterio, úsalo como repaso enfocado en CLAUDE.md (cápsula 04), que casi siempre se puede mejorar.
Evidencia de Éxito
Antes de avanzar al Módulo 7 (Modernizar Legacy Code), deberías poder:
- ✅ Estimar cuántos tokens tiene un codebase y predecir si cabrá completo en context
- ✅ Reconocer los 3-4 síntomas de context pressure y aplicar la solución correspondiente
- ✅ Diseñar una chunking strategy (feature / layer / module) para un proyecto que conozcas
- ✅ Escribir un CLAUDE.md útil — no genérico — para un proyecto real
- ✅ Decidir cuándo es momento de empezar una sesión nueva en lugar de continuar
- ✅ Trabajar con proyectos de 100K+ líneas sin context overflow ni degradación de calidad
Si alguno no se cumple al final, regresa a la cápsula correspondiente. El Módulo 7 y el Módulo 8 asumen estas técnicas — sin ellas, los proyectos de Phase 3 se vuelven inviables en codebases reales.
Resumen
- Context management es el skill que separa al casual del profesional
- 1M tokens tiene límites prácticos — este módulo te enseña a trabajar dentro de ellos
- CLAUDE.md es la herramienta más infrautilizada de Claude Code
- Menos es más: incluye lo relevante, no todo
- Chunking strategies (feature, layer, module) escalan a cualquier proyecto
- La diferencia entre "30 minutos" y "4 horas" del escenario inicial es exactamente este módulo
Siguiente cápsula: 02 — Context Window Reality — los límites prácticos del 1M tokens, qué pasa cuando los llenas, cómo medir tu codebase, y los síntomas de context pressure que ya probablemente has visto sin nombrarlos.
Recursos Adicionales
- Claude Code - CLAUDE.md Documentation - Referencia oficial
- Context Window Explained - Anthropic - Cómo funcionan los context windows
- Prompt Engineering Guide - Anthropic - Técnicas de gestión de contexto
- Anthropic Token Counting - Herramienta oficial para contar tokens
- Large Codebase Navigation - Herramientas complementarias para codebases grandes
- Token Counting - tiktoken - Herramienta para contar tokens (compatible con Anthropic aproximadamente)
- Effective Code Reading at Scale - Técnicas humanas que complementan AI