Manejo del contexto: técnicas avanzadas

Módulo: 9. Funciones avanzadas | Tiempo: ~30 min de teoría + 25 min de práctica

Lo esencial

La ventana de contexto (context, el texto que la IA ve) es como la memoria RAM de una computadora: todo lo que no cabe ahí no está disponible para el agente (un ejecutor autónomo) en ese momento. El arte de trabajar con proyectos grandes es el arte de manejar qué hay en la memoria en cada momento.

Términos de la lección: context (contexto, el texto que la IA ve), token (unidad de texto para la IA), agent (agente, un ejecutor autónomo), prompt (la solicitud que le haces a la IA), API (interfaz de programación).

Conceptos clave

La ventana de contexto como recurso limitado
5 técnicas para manejar el contexto
El patrón de delegación: los subagentes como espacios de trabajo aislados
Búsqueda semántica en una base de código grande

Teoría

Qué es la ventana de contexto

🎨 Imagínalo así: la ventana de contexto es como un escritorio. Puedes extender cientos de hojas de papel. Cuando el escritorio está lleno, ya no hay dónde poner una hoja nueva. El agente empieza a "olvidar" lo del principio, como si hubieras tirado las hojas viejas al piso.

El tamaño de la ventana de contexto (en tokens, las unidades de texto de la IA) depende del modelo. A octubre de 2026, Claude Opus 5.5, Sonnet 5.5 y Fable 5.1 tienen una ventana de 1 millón de tokens, y Haiku 4.5, una más pequeña. Cifras vigentes: Lo vigente. Pero ni un millón es infinito: un proyecto real grande lo llena con facilidad, y cada token de más cuesta dinero y agrega ruido:

100 archivos de 500 líneas de código = ~300,000 tokens
Súmale el historial de la conversación (50 mensajes) = otros ~20,000 tokens
Súmale los resultados de las herramientas (salida de bash, resultados de grep) = otros ~30,000 tokens

Total: ~350,000 tokens. Para una ventana de 200 mil eso es un desbordamiento, y para una de un millón ya es un tercio: la sesión se vuelve más lenta y más cara. El agente empieza a "olvidar" el inicio de la conversación o a confundirse con los detalles. Cuando la ventana se acerca al límite, Claude Code comprime el historial por su cuenta, pero lo hace a su criterio; es mejor que tú controles la compresión.

Señales de desbordamiento:

El agente repite preguntas que ya había hecho
El agente "no sabe" de archivos que leyó hace 20 mensajes
Las respuestas se vuelven menos precisas
La velocidad baja y el costo sube

Técnica 1: un claude.md ligero, el archivo de contexto mínimo

🎨 Imagínalo así: un CLAUDE.md gordo es como llevar a una reunión todas las carpetas del archivero en lugar de una hoja con la agenda. Un CLAUDE.md ligero es la agenda: "Arquitectura: ver carpeta A; tareas: ver carpeta B". Si necesitas la carpeta, la abres.

claude.md son las instrucciones que Claude Code lee al empezar la sesión. Los principiantes meten ahí de todo: arquitectura, convenciones, la historia del proyecto, y lo convierten en un monstruo de 5000 palabras.

El enfoque correcto: claude.md contiene solo punteros, no el contenido.

Escribe esto en el chat

# Proyecto: Invoice Automation

## Arquitectura
Ver: docs/architecture.md

## Documentación de la API
Ver: docs/api-reference.md

## Tareas actuales
Ver: docs/current-sprint.md

## Convenciones de código
- Python 3.11+, tipado obligatorio
- Pruebas con pytest, cobertura >80%
- Formato: black + ruff

Cuando el agente necesita la arquitectura, lee docs/architecture.md. Cuando no la necesita, no la lee y no ensucia el contexto.

Regla: claude.md debe caber en una pantalla (la documentación de Claude Code recomienda mantenerlo en menos de 200 líneas). Todo lo demás va en archivos aparte que se leen cuando hace falta, o en reglas dentro de .claude/rules/. El archivo se crea con el comando /init. Además, Claude Code lleva una memoria automática (auto memory): anota por sí solo lo que aprende de tus correcciones entre sesiones. Puedes verla y corregirla con el comando /memory.

Técnica 2: delegar en subagentes

🎨 Imagínalo así: un subagente es como un asistente de investigación. ¿Lees tú 50 libros o contratas a alguien? Él los lee y te hace un resumen de 1 página: tú solo necesitas esa página. Su escritorio queda lleno de libros; el tuyo, limpio.

Un subagente trabaja en su propio contexto aislado (más detalles en la lección Subagentes). Esta es la idea clave. La excepción es el fork: hereda toda la conversación, así que para ahorrar contexto usa un subagente normal.

El patrón de delegación:

En lugar de leer tú mismo 50 archivos y tenerlo todo en memoria:

Escribe esto en el chat

Agente principal: "Subagente, investiga la carpeta src/payments/
y regrésame: la lista de funciones, para qué sirve cada una y los 3 problemas principales"

Subagente: [lee 20 archivos, analiza, regresa un resumen de 500 líneas]

El agente principal recibe: un resumen compacto (500 palabras),
no 20 archivos pesados

El subagente "quema" su contexto en la investigación. El agente principal recibe solo el destilado. Es como tener un investigador que lee por ti y te trae solo lo importante.

Cuándo delegar:

Analizar una carpeta o un módulo grande
Buscar en toda la base de código
Generar mucho código (el subagente lo escribe y regresa el resultado listo)
Cualquier tarea donde el resultado sea más compacto que el proceso

Técnica 3: /clear, empezar de cero

🎨 Imagínalo así: /clear es como borrar el pizarrón del salón después de la clase. La siguiente tarea empieza en un pizarrón limpio, sin el gis de ayer. El agente no arrastra el peso de las discusiones anteriores.

Cuando termines una tarea, usa /clear para borrar el historial de la conversación. La siguiente tarea empieza con un contexto limpio.

Error típico: dejar una sola sesión abierta todo el día, pasando de una tarea a otra. Para la tarde, el agente carga en memoria todo el historial del día: lento, caro y menos preciso.

El ritmo correcto:

Tarea 1: depurar el inicio de sesión → /clear
Tarea 2: escribir pruebas → /clear
Tarea 3: escribir la documentación → /clear

Cada tarea, un contexto limpio. El agente no arrastra el peso de las tareas anteriores.

Cuándo NO usar /clear: si la siguiente tarea depende de decisiones tomadas en la actual. En ese caso, mejor termina las dos tareas en una misma sesión.

Técnica 4: archivos temporales para pasar datos

Cuando varios agentes deben trabajar juntos, intercambian datos por medio de archivos, no del contexto.

Ejemplo de flujo:

Código

Agente 1 (Researcher):
→ Analiza a la competencia
→ Escribe en analysis/competitor-research.md

Agente 2 (Writer):
→ Lee analysis/competitor-research.md
→ Escribe un artículo basado en la investigación

Agente 3 (SEO):
→ Lee article-draft.md
→ Lo optimiza para SEO
→ Escribe en article-final.md

Cada agente trabaja por su cuenta. Nadie guarda en memoria el trabajo del anterior, solo el resultado final.

Cómo nombrar los archivos temporales:

Escribe esto en el chat

_tmp/research-2026-10-04.md
_tmp/draft-v1.md
_tmp/seo-suggestions.md

El prefijo _tmp/ y la fecha dejan claro que son resultados intermedios. Agrega _tmp/ a .gitignore si no quieres hacer commit de los archivos de trabajo.

Técnica 5: carga progresiva

🎨 Imagínalo así: la carga progresiva es como el GPS del auto. Primero la ruta general (el mapa de la ciudad), luego la colonia en la que estás, luego el cruce concreto. No cargas el mundo entero de golpe, solo lo que necesitas en este momento.

No leas todo de una vez. Lee solo lo que necesitas ahora.

Mal:

Escribe esto en el chat

"Lee todo el proyecto y encuentra dónde está el problema con el inicio de sesión"

El agente lo lee todo y llena el contexto de archivos innecesarios.

Bien:

Código

"¿Qué archivos podrían encargarse del inicio de sesión? Haz la lista, no los leas."
→ [El agente da la lista: auth.py, middleware.py, routes/users.py]

"Ahora lee solo auth.py y encuentra el problema"
→ [Lee un archivo, encuentra el problema]

Carga progresiva: primero el mapa, luego los detalles. No al revés.

Búsqueda semántica en una base de código grande

Cuando el proyecto es grande, grep busca texto exacto. La búsqueda semántica busca por significado.

Ejemplo: buscas "dónde se manejan los errores de pago". Grep encontrará líneas con payment_error o PaymentException, pero solo si conoces las palabras exactas. La búsqueda semántica encuentra todo el código relacionado con el manejo de errores de pago, aunque se llame distinto.

Por defecto, Claude Code se orienta en el proyecto buscando por nombres de archivo y por texto (glob y grep): prueba varias formas de las palabras y lee lo que encuentra. La documentación no menciona un índice semántico propio. Si necesitas búsqueda por significado o memoria entre sesiones, se conectan herramientas externas, por ejemplo claude-mem (un proyecto de la comunidad) o servidores MCP con índice. Las búsquedas pesadas conviene dárselas al subagente Explore: lee muchos archivos en su propio contexto y regresa un resumen corto.

Patrón práctico:

Escribe esto en el chat

"Encuentra todos los lugares del código donde pase
algo parecido a reintentar solicitudes fallidas"

El agente prueba distintas formulaciones y busca con ellas: encuentra el patrón de retry aunque las funciones se llamen attempt_again, with_backoff o safe_execute.

Métrica: el comando /context

🎨 Imagínalo así: /context es el Administrador de tareas de la ventana de contexto. ¿Ves que docs/architecture.md se come 12K tokens y ya no lo necesitas? Es como cerrar una pestaña del navegador que estaba alentando la computadora.

El comando /context en Claude Code muestra el desglose de lo que ocupa espacio en el contexto actual, por categorías (instrucciones del sistema, herramientas, memoria y CLAUDE.md, skills, historial de la conversación), y da sugerencias para optimizar. El formato de la salida cambia de una versión a otra; abajo hay una ilustración, no una copia exacta:

Escribe esto en el chat

Contexto: 45 000 tokens de la ventana del modelo

Instrucciones del sistema y herramientas: ...
Memoria y CLAUDE.md: ...
Skills: ...
Historial de la conversación: ...

Míralo como el Administrador de tareas de la computadora. ¿Ves que la documentación de arquitectura ocupa mucho espacio y ya no la necesitas? Comprime la conversación con /compact indicando qué conservar (por ejemplo, /compact conserva las decisiones sobre el inicio de sesión), o empieza una tarea nueva con /clear. Para comprimir solo una parte de la conversación, usa /rewind: elige un mensaje y la opción Summarize from here.

Práctica

Tarea: diagnosticar el contexto de un proyecto real

Abre cualquier proyecto tuyo o crea uno de prueba con 5-10 archivos
Empieza una sesión de Claude Code y lee algunos archivos
Ejecuta /context y mira cómo se reparten los tokens
Encuentra el componente más "pesado" (un archivo o un bloque del historial)
Practica la delegación: pídele al agente "lanza un subagente que lea la carpeta X y regrese un resumen"
Después del resumen, ejecuta /clear y empieza una tarea nueva con el contexto limpio
Compara: ¿qué tanto más rápido responde el agente al inicio de una sesión nueva frente al final de una larga?

Comandos para manejar el contexto: hoja de referencia

Comando	Qué hace	Cuándo usarlo
`/clear`	Borra el historial de la conversación y empieza una sesión limpia	Al terminar una tarea, antes de un tema nuevo
`/compact`	Comprime el historial: el agente resume el contexto; puedes agregar una instrucción sobre qué conservar	Cuando el contexto se llena pero hay que conservar el contexto de la tarea actual
`/context`	Muestra el desglose del uso del contexto por categorías	Diagnóstico: ¿qué ocupa espacio?
`/usage`	Límites del plan, costo y estadísticas (`/cost` es un sinónimo)	Control del presupuesto
`/memory`	Abre los archivos de memoria y CLAUDE.md para verlos y editarlos	Revisar qué recuerda Claude del proyecto
`CLAUDE.md`	Se carga automáticamente al empezar	Donde viven las instrucciones permanentes del proyecto
Subagente	Trabaja en un contexto aislado	Analizar una carpeta grande, generar mucho código
Archivos `_tmp/`	Intercambio de datos entre agentes	Cuando varios agentes trabajan en cadena

Errores comunes

1. Nunca usar /compact Si el contexto se desborda, la sesión se degrada. /compact comprime el historial y conserva lo esencial. Claude Code también puede comprimir el contexto automáticamente, pero decide él qué es importante; un /compact manual con instrucción te deja controlar lo principal. Úsalo en sesiones largas, entre etapas del trabajo.

2. Cargar todo el proyecto en el contexto

Escribe esto en el chat

❌ "Lee todos los archivos de src/ y encuentra el problema"
✅ "¿Qué archivos de src/ tienen que ver con el inicio de sesión? Haz la lista sin leerlos."

La carga progresiva ahorra miles de tokens.

3. Una sesión interminable para todo el día Para la tarde, el agente carga en memoria todo el historial del día. Regla: una tarea = una sesión. /clear entre tareas.

4. Un CLAUDE.md enorme (más de ~200 líneas) CLAUDE.md se carga en CADA sesión. Si tiene 5000 palabras, son más de 5000 tokens de entrada. Usa punteros: "Arquitectura: ver docs/architecture.md".

5. No usar subagentes para tareas pesadas Si hay que analizar 20 archivos, delega en un subagente. Él "quema" su contexto y te regresa el destilado.

Herramientas y recursos

/context: comando integrado que muestra el uso del contexto
/clear: borra el historial de la conversación
/compact: comprime el historial conservando lo esencial
claude-mem (repositorio externo): un sistema de memoria a largo plazo basado en archivos
MCP filesystem: acceso ampliado al sistema de archivos
/memory: ver y editar la memoria automática y CLAUDE.md
Subagentes: contextos aislados para tareas pesadas (ver la lección Subagentes)

Conclusiones clave

La ventana de contexto es un recurso limitado. Úsala para lo más importante en este momento. El subagente "quema" su contexto y regresa un destilado: el agente principal se mantiene fresco. /clear después de cada tarea es higiene de desarrollador. No arrastres a hoy el peso de ayer.

Lecciones relacionadas

Tokens y contexto: lo básico de qué son los tokens y cómo se calcula el costo
Context rot y 28 hacks: más técnicas para trabajar bien con Claude Code, incluido el manejo del contexto

Qué sigue

→ GitHub y worktrees: desarrollo en paralelo