Era tarde en la noche. Había delegado una refactorización grande a Claude Code y me fui. Cuando volví, ahí estaba: "context window exceeded." El trabajo se detuvo. No tenía idea de hasta dónde había llegado. Los archivos estaban en un estado a medio terminar, y no tenía el contexto en mi cabeza para retomar donde se quedó.
Esa dolorosa experiencia me enseñó todo lo que contiene este artículo. Al final, tendrás un playbook completo para prevenir errores de ventana de contexto, y recuperarte limpiamente cuando ocurran.
¿Qué Es el Error "Context Window Exceeded" en Claude Code?
El error "context window exceeded" significa que Claude Code ha alcanzado el límite superior de tokens que puede procesar en una sesión. Todo cuenta para ese límite: el historial completo de la conversación, cada archivo que ha leído, todo el código que ha generado.
La clave es que este límite no llega de repente, se acerca gradualmente. Claude Code rastrea el uso de contexto a lo largo de una sesión, y hay formas de monitorearlo. Eso significa que puedes actuar antes de que el error aparezca.
Hay cuatro estrategias principales:
- Usar
/compactpara resumir y comprimir el historial de conversación - Usar
.claudeignorepara evitar que archivos innecesarios se lean en primer lugar - Dividir sesiones largas por dominio para que nunca se salgan de control
- Usar el modo Plan para fijar decisiones de diseño por adelantado, minimizando el gasto de tokens durante la implementación
Cubriré cada una en detalle. Pero primero, qué hacer cuando el error ya ocurrió.
¿Cómo Recuperas Tu Trabajo Después de un Error de Ventana de Contexto?
Cuando el error aparece, la sesión ha terminado. No entres en pánico. Sigue estos pasos para entender la situación.
Paso 1: Revisa el diff con git
git diff HEAD
git status
Claude Code escribe los cambios en disco sobre la marcha. Incluso si la sesión terminó abruptamente, todo lo que tocó sigue ahí en el sistema de archivos. Ejecutar git diff te dice exactamente qué cambió y hasta dónde llegó el trabajo.
Paso 2: Guarda el estado actual
Incluso si el estado parece incompleto, guárdalo inmediatamente.
git add -A
git stash push -m "claude-code session 2026-02-26 interrupted"
O haz commit de las partes que se ven completas. De cualquier forma, asegura el trabajo antes de hacer cualquier otra cosa.
Paso 3: Inicia una nueva sesión con contexto mínimo
Abre una nueva sesión y describe lo que se necesita de forma compacta.
La sesión anterior terminó con context window exceeded.
Archivos modificados: src/components/Header.tsx, src/lib/api.ts
Tarea restante: corregir errores de tipo en el componente Footer
Por favor carga solo los archivos relevantes y continúa.
No se necesitan explicaciones largas. "Qué hacer" y "qué archivos" es todo lo que importa.
¿Cómo Monitoreas el Uso de Contexto en Claude Code?
Claude Code a veces muestra el uso de contexto en las respuestas durante una sesión, pero no es consistente. Necesitas desarrollar tu propia conciencia.
Ejecuta /context cuando una sesión empiece a sentirse larga
/context
Esto muestra un conteo aproximado de tokens. Si estás al 70-80%, es tu señal para actuar.
Guías aproximadas para el "peso" de la sesión
| Situación | Uso aproximado de tokens |
|---|---|
| Corrección de bug pequeño (1-2 archivos) | 10-30k |
| Adición de funcionalidad (5-10 archivos) | 50-150k |
| Refactorización grande (20+ archivos) | 200k+ — zona de peligro |
El uso de tokens escala más rápido de lo que esperarías conforme crece el número de archivos. Cada solicitud de "ya que estás, arregla esto también" te acelera hacia el límite.
La mentalidad correcta para la eficiencia de contexto
- Una sesión = una tarea, sin excepciones
- Nada de solicitudes de "ya que estás"
- Las tareas nuevas siempre empiezan en sesiones nuevas
¿Cómo Funciona /compact y Cuándo Deberías Usarlo?
El comando /compact resume tu historial de conversación y lo reemplaza con una versión comprimida. El ida y vuelta detallado se convierte en un resumen conciso de lo que se ha logrado. El conteo de tokens baja significativamente, y puedes seguir trabajando.
/compact
Claude extrae la información clave de la conversación y produce un resumen. El contexto de trabajo se mantiene, así que la sesión continúa naturalmente.
Buenos momentos para usar /compact
- Cuando el uso de contexto alcanza el 60-70%
- Al hacer la transición de una fase de investigación/diseño a implementación
- Cuando una sesión de depuración ha llegado a un punto de parada natural
Cuándo evitarlo
- En medio de una discusión de diseño compleja (el resumen puede perder matices importantes)
- Cuando se necesita preservar detalles precisos de código
/compact no es perfecto. Decisiones importantes pueden perderse en la sumarización. El hábito más seguro es escribir las decisiones clave en un archivo, o en CLAUDE.md, antes de compactar.
<!-- Qué registrar en CLAUDE.md antes de compactar -->
## Current Work
- Task: refactor user authentication module
- Decision: switch from JWT to session cookies
- Modified: src/auth/index.ts, src/middleware/auth.ts
- Remaining: update tests
¿Cómo Reduces el Uso de Tokens con .claudeignore?
La técnica de gestión de contexto más efectiva es evitar que archivos innecesarios se carguen en primer lugar. El archivo .claudeignore funciona como .gitignore: le dice a Claude Code qué archivos y directorios omitir al explorar el proyecto.
touch .claudeignore
# .claudeignore
# Dependencies (never load these)
node_modules/
vendor/
.venv/
__pycache__/
# Build artifacts
dist/
build/
.next/
out/
# Large data files
*.csv
*.json.bak
data/raw/
# Logs and caches
*.log
.cache/
coverage/
# Archive docs not needed for current work
docs/archive/
*.pdf
# Test snapshots
__snapshots__/
El impacto es real
Excluir solo node_modules/ puede ahorrar decenas de miles, a veces cientos de miles, de tokens por sesión. En un proyecto de Next.js, siempre excluye .next/. Un solo archivo .claudeignore puede duplicar o triplicar cuánto dura una sesión antes de alcanzar el límite.
¿Cómo Deberías Dividir Sesiones para Manejar Tareas de Larga Duración?
La solución más fundamental para la gestión de contexto es dividir una tarea grande en múltiples sesiones enfocadas.
Cómo se ve la división
Mal (una sesión intenta hacer todo):
- Diseñar el sistema de autenticación
- Diseñar el esquema de BD
- Implementar la API
- Construir el frontend
- Escribir tests
- Configurar el despliegue
Bien (sesiones separadas):
Sesión 1: Solo diseño (registrar decisiones en CLAUDE.md)
Sesión 2: BD + API
Sesión 3: Frontend
Sesión 4: Tests
Sesión 5: Configuración de despliegue
La mayor causa de explosión de contexto es intentar cargar el historial completo de una sesión anterior en una nueva. Cada sesión debería empezar fresca, con solo el contexto mínimo necesario.
Crea un archivo de traspaso entre sesiones
<!-- session-handover.md -->
## What was completed last session
- Auth implemented using JWT (RSA256)
- Files under src/auth/ are complete
- Tests not written yet
## What to do this session
- Add tests under src/auth/__tests__/
- Target: 80%+ code coverage
Pasa esto a Claude Code al inicio de cada sesión. La larga conversación explicativa se vuelve innecesaria.
¿Por Qué la Auto-Compactación Es Riesgosa?
Claude Code tiene una función de auto-compactación que resume automáticamente el contexto cuando cruza un umbral. Suena conveniente, pero la auto-compactación durante trabajo crítico puede causar problemas.
No puedes controlar cuándo se dispara. Si se activa en medio de una refactorización compleja, o mientras estás rastreando un bug sutil, suposiciones importantes pueden desaparecer del contexto, enviando el trabajo en la dirección equivocada.
{
"autoCompact": false
}
Desactivar la auto-compactación y ejecutar /compact manualmente en el momento que elijas es el enfoque más seguro. Revisa el resumen antes de continuar. Asegúrate de que nada crítico se haya perdido.
¿Cuál Es la Lista de Verificación para Prevenir Errores de Ventana de Contexto?
Aquí tienes todo de este artículo como una lista de verificación accionable. Configúrala una vez por proyecto y rara vez tendrás que pensar en ello de nuevo.
Inicialización del proyecto
- Crear
.claudeignore, excluyendonode_modules/,dist/,.next/ - Crear
CLAUDE.mdy establecer el hábito de registrar decisiones ahí - Desactivar la auto-compactación en configuración
Al inicio de cada sesión
- Una tarea por sesión, sin mezclar
- Pasar solo el contexto mínimo necesario de la sesión anterior
- Nunca pedirle a Claude Code que cargue archivos no relacionados con la tarea actual
Durante una sesión
- Ejecutar
/compactcuando el uso alcance el 60% - Resistir la tentación de agregar solicitudes de "ya que estás"
- Escribir decisiones de diseño en un archivo inmediatamente, no dejarlas solo en la conversación
Cuando el error ocurra
- Ejecutar
git diffpara ver qué cambió - Hacer stash o commit del estado actual
- Iniciar una nueva sesión con un mensaje de traspaso compacto y enfocado
Conclusión
"Context window exceeded" no es mala suerte. Es un problema de ingeniería con soluciones de ingeniería.
- Usa
.claudeignorepara controlar qué se carga - Aplica una sesión, una tarea
- Ejecuta
/compactmanualmente al 70% - Gestiona los traspasos entre sesiones con archivos, no con historial de conversación
Estas cuatro prácticas eliminan casi todas las interrupciones relacionadas con el contexto. Incluso refactorizaciones a gran escala a altas horas de la noche se vuelven manejables cuando las sesiones están correctamente delimitadas.
Empieza ahora mismo: crea un archivo .claudeignore en tu proyecto.