El error "context window exceeded" en Claude Code significa que la sesión alcanzó el límite de tokens y se detuvo. La solución: usa /compact para comprimir el historial, .claudeignore para bloquear archivos innecesarios, y divide tareas largas en múltiples sesiones. Prevenir es mejor que recuperar—monitorea el uso con /cost y actúa antes de que se llene.
Le delegas una refactorización grande a Claude Code, te vas, y al volver te encuentras con: "context window exceeded." El trabajo se detuvo. No tienes idea de hasta dónde llegó. Los archivos están a medio terminar, y no tienes el contexto en tu cabeza para retomar donde se quedó. Si esto te suena familiar, no estás solo—es una de las quejas más comunes en las comunidades de desarrolladores.
Este artículo cubre todo lo que necesitas: 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.
A marzo de 2026, Claude Code soporta una ventana de contexto de 200K tokens para la mayoría de modelos, y una ventana de 1M tokens para Opus 4.6 y Sonnet 4.6. Suena enorme, pero los codebases grandes y las conversaciones largas la consumen más rápido de lo que imaginas.
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 interrupted - context exceeded"
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. Lo peor que puedes hacer es pegar la conversación anterior completa en la nueva sesión—eso anula todo el propósito.
¿Cómo Monitoreas el Uso de Contexto en Claude Code?
La prevención empieza por la visibilidad. Si no sabes qué tan cerca estás del límite, no puedes actuar a tiempo.
Usa /cost para verificar el consumo de tokens
/cost
El comando /cost muestra el uso acumulado de tokens para la sesión actual. Si estás trabajando en una funcionalidad que involucra muchos archivos, revísalo cada 20-30 minutos.
Presta atención al mensaje de auto-compactación
Claude Code ejecuta auto-compactación cuando el uso de contexto alcanza aproximadamente el 80-85% de la ventana. Si ves un mensaje de auto-compactación, esa es tu advertencia tardía. Estás muy adentro de la ventana y deberías considerar cerrar la tarea actual.
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
También puedes pasar un tema de enfoque para guiar el resumen:
/compact enfócate en las decisiones de la refactorización de autenticación
Esto le dice a Claude qué priorizar al comprimir. Es útil cuando solo parte de la conversación sigue siendo relevante.
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.
## Trabajo actual
- Tarea: refactorizar módulo de autenticación de usuarios
- Decisión: cambiar de JWT a cookies de sesión
- Modificados: src/auth/index.ts, src/middleware/auth.ts
- Pendiente: actualizar tests
Registra las decisiones en CLAUDE.md, no solo en la conversación. Así /compact no puede perderlas.
¿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
# Dependencias (nunca cargar estos)
node_modules/
vendor/
.venv/
__pycache__/
# Artefactos de build
dist/
build/
.next/
out/
# Archivos de datos grandes
*.csv
*.json.bak
data/raw/
# Logs y caché
*.log
.cache/
coverage/
# Documentos de archivo no necesarios para el trabajo actual
docs/archive/
*.pdf
# Snapshots de tests
__snapshots__/
El impacto es real
En un proyecto Next.js de tamaño medio, agregar un .claudeignore que excluya node_modules/, .next/ y artefactos de build hace que las sesiones duren significativamente más antes de alcanzar el límite. Excluir solo node_modules/ puede ahorrar decenas de miles—a veces cientos de miles—de tokens por sesión.
¿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 -->
## Completado en la sesión anterior
- Autenticación implementada con JWT (RSA256)
- Archivos bajo src/auth/ completos
- Tests no escritos aún
## Qué hacer en esta sesión
- Agregar tests en src/auth/__tests__/
- Objetivo: 80%+ de cobertura de código
Pasa esto a Claude Code al inicio de cada sesión. La larga conversación explicativa se vuelve innecesaria.
Usa CLAUDE.md como memoria persistente
A diferencia del historial de conversación, CLAUDE.md sobrevive entre sesiones. Decisiones de arquitectura, convenciones de nomenclatura, reglas específicas del proyecto—ponlas en CLAUDE.md una vez y cada sesión tiene acceso. Esto es mucho más eficiente en tokens que re-explicar el contexto cada vez. Consulta Patrones de diseño CLAUDE.md para gestión de contexto para ver patrones prácticos.
¿Cómo Funciona la Auto-Compactación y Cuándo Deberías Desactivarla?
Claude Code tiene una función de auto-compactación que resume automáticamente el contexto cuando el uso cruza aproximadamente el 80-85% de la ventana. Suena conveniente, pero la auto-compactación durante trabajo crítico puede causar problemas.
Puedes controlar el umbral de auto-compactación con una variable de entorno:
# Bajar el umbral para activar la compactación más temprano (al 70%)
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70
O desactivarla completamente via la configuración del CLI:
claude config set -g autoCompactEnabled false
Desactivar la auto-compactación y ejecutar /compact manualmente es el enfoque más seguro para trabajo complejo. Revisa el resumen antes de continuar. Asegúrate de que nada crítico se haya perdido.
Para tareas rutinarias (correcciones simples de bugs, funcionalidades pequeñas), dejar la auto-compactación activada está bien—maneja el contexto silenciosamente y ni lo notas. El riesgo solo existe con trabajo que depende de continuidad precisa del contexto.
¿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í - Ajustar el umbral de auto-compactación o desactivarla para proyectos complejos
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
/costperiódicamente para monitorear el uso de tokens - Ejecutar
/compactcuando el uso alcance el 60-70% - 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
Preguntas Frecuentes
¿Qué tan grande es la ventana de contexto de Claude Code?
A marzo de 2026, Claude Code soporta 200K tokens para la mayoría de modelos y 1M tokens para Opus 4.6 y Sonnet 4.6. La auto-compactación reserva un búfer (aproximadamente 33K tokens en ventanas de 200K), así que tu límite de trabajo efectivo es menor que el número titular.
¿/compact elimina mi historial de conversación?
No exactamente. /compact reemplaza la conversación detallada con un resumen comprimido. Los mensajes originales desaparecen del contexto, pero la información clave se preserva en forma de resumen. Puedes seguir trabajando—Claude retoma donde se quedó basándose en el resumen.
¿.claudeignore es lo mismo que .gitignore?
Usan la misma sintaxis, pero tienen propósitos diferentes. .gitignore controla lo que Git rastrea. .claudeignore controla lo que Claude Code puede ver y leer. Muchas entradas se superponen (como node_modules/), pero .claudeignore te permite excluir archivos que Git sí rastrea pero que Claude no necesita—como fixtures de tests grandes, archivos de documentación, o archivos de datos.
¿Puedo aumentar el tamaño de la ventana de contexto?
No puedes aumentar el límite duro—está definido por el modelo. Pero puedes usar Claude Code con Opus 4.6 o Sonnet 4.6 para obtener 1M tokens en lugar de 200K. En los planes Max, Team o Enterprise, la ventana de 1M está disponible automáticamente.
¿Cuál es la diferencia entre /compact e iniciar una nueva sesión?
/compact preserva el contexto de trabajo en forma de resumen dentro de la misma sesión. Una nueva sesión empieza completamente desde cero—sin historial. Usa /compact cuando quieras continuar la misma tarea con menos overhead. Usa una nueva sesión cuando vayas a cambiar a una tarea completamente diferente.
¿El modo Plan ayuda con el uso de contexto?
Sí. El modo Plan te permite diseñar la implementación antes de escribir código. La conversación de diseño usa tokens, pero produce un plan claro que hace la fase de implementación más rápida y enfocada—frecuentemente usando menos tokens en total que una sesión de código sin planificación.
¿Cómo recupero archivos si Claude Code se cerró a mitad de una edición?
Claude Code escribe en disco mientras trabaja. Ejecuta git diff HEAD y git status para ver exactamente qué cambió. Luego haz stash o commit de los cambios antes de iniciar una nueva sesión. Nada se pierde—todo está en disco.
¿Por qué mi sesión se queda sin contexto más rápido de lo esperado?
Causas comunes: leer muchos archivos (especialmente grandes), conversaciones largas de ida y vuelta para depuración, y "ya que estás" que expanden el alcance. Cada lectura de archivo agrega su contenido completo al contexto. Usa .claudeignore y mantén las sesiones enfocadas en una sola tarea.
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
- Registra las decisiones en CLAUDE.md para que sobrevivan a la compactación
Estas prácticas eliminan casi todas las interrupciones relacionadas con el contexto. Incluso refactorizaciones a gran escala se vuelven manejables cuando las sesiones están correctamente delimitadas.
Empieza ahora mismo: crea un archivo .claudeignore en tu proyecto.
Artículos relacionados: