Compactación y contextos largos

Por qué es necesaria la compactación

A medida que una sesión de Claude Code avanza, la ventana de contexto acumula mensajes, archivos leídos, salidas de comandos y respuestas del agente. Cuando el contexto alcanza un nivel de ocupación alto, la calidad de las respuestas se degrada: el modelo empieza a olvidar instrucciones anteriores, a repetir errores ya corregidos o a perder de vista el objetivo original de la tarea.

La compactación es el mecanismo que permite mantener sesiones largas sin reiniciar la conversación. Funciona resumiendo el historial más antiguo de la conversación y liberando espacio para nuevas interacciones, manteniendo la información más relevante.

La compactación no elimina contexto, lo resume. El objetivo es conservar las decisiones importantes, los patrones de código y el estado actual del trabajo, descartando los detalles intermedios que ya no son necesarios.

Tres niveles de compactación

Claude Code implementa un sistema de compactación en tres niveles, cada uno actuando en un momento y con un alcance diferente.

Microcompactación

La microcompactación actúa sobre las salidas individuales de las herramientas. Cuando un comando Bash, una lectura de archivo o un resultado de búsqueda generan una salida muy extensa, Claude Code la descarga a disco de forma temprana y solo mantiene en el contexto la porción más reciente o relevante.

Este proceso es transparente: ocurre automáticamente sin intervención del usuario y reduce el ritmo al que se llena la ventana de contexto, especialmente en sesiones con operaciones que generan grandes volúmenes de texto.

Autocompactación

La autocompactación se activa cuando el espacio libre en la ventana de contexto cae por debajo de un umbral reservado. Por defecto, este umbral se sitúa alrededor del 95% de ocupación del contexto.

Cuando se alcanza el umbral, Claude Code:

• 1. Resume el historial de la conversación, preservando las decisiones clave, los archivos modificados y el estado actual del trabajo.
• 2. Crea un bloque de compactación con el resumen.
• 3. Descarta los mensajes anteriores al bloque de compactación.
• 4. Relee los archivos CLAUDE.md del disco y los reinyecta en el contexto.

flowchart TD
    A["Contexto al 95%"] --> B["Resumir historial"]
    B --> C["Crear bloque<br>de compactación"]
    C --> D["Descartar mensajes<br>anteriores"]
    D --> E["Reinyectar CLAUDE.md"]
    E --> F["Sesión continua<br>con espacio libre"]

La autocompactación preserva:

• Todo el contenido de los archivos CLAUDE.md (se releen del disco)
• Las decisiones arquitectónicas y de diseño
• La lista de archivos modificados
• Los comandos de test y build relevantes
• El estado actual del trabajo en progreso

La variable de entorno CLAUDE_AUTOCOMPACT_PCT_OVERRIDE permite ajustar el porcentaje de contexto al que se activa la autocompactación:

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80

Un valor de 80 activaría la compactación cuando el contexto alcance el 80% de ocupación, lo que deja más margen antes de que la calidad empiece a degradarse.

Compactación manual

La compactación manual se invoca con el comando /compact y permite al usuario decidir cuándo y cómo resumir el contexto. Es especialmente útil en transiciones entre tareas dentro de la misma sesión, cuando se sabe que el contexto acumulado de la tarea anterior ya no es necesario.

/compact

El comando /compact también acepta instrucciones de enfoque opcionales que indican a Claude qué información priorizar en el resumen:

/compact Conserva la lista completa de archivos modificados y los comandos de test

/compact Enfocate en los cambios de la API, descarta la exploracion inicial

Estas instrucciones guían el proceso de resumen para que Claude retenga la información que el usuario considera más importante.

La compactación manual con /compact es la herramienta adecuada para los límites entre tareas. Al terminar una tarea y antes de empezar otra, compactar permite conservar los aprendizajes relevantes y liberar espacio para el nuevo trabajo.

Compactación parcial con rewind

Además de /compact, que resume toda la conversación, existe la opción de compactar parcialmente usando el sistema de rewind.

Pulsando Esc dos veces o ejecutando /rewind, se abre un menú con los checkpoints de la conversación. Al seleccionar un checkpoint, una de las opciones disponibles es "Summarize from here", que condensa los mensajes desde ese punto en adelante mientras mantiene intacto el contexto anterior.

Esta técnica resulta útil cuando una parte de la conversación (por ejemplo, una exploración inicial extensa) ha dejado de ser relevante, pero los mensajes anteriores a esa exploración sí deben conservarse completos.

Qué sobrevive a la compactación

Conocer qué información persiste y cuál se descarta durante la compactación ayuda a tomar mejores decisiones sobre dónde almacenar las instrucciones:

| Sobrevive | Se descarta | |---|---| | Archivos CLAUDE.md (se releen del disco) | Detalles intermedios de la exploración | | Decisiones y conclusiones clave | Intentos fallidos ya corregidos | | Lista de archivos modificados | Salidas completas de comandos extensos | | Contexto sobre la tarea en curso | Conversación casual no relacionada con código | | Lista de tareas (task list) | Contenido detallado de archivos leídos |

Las instrucciones proporcionadas solo en la conversación (y no escritas en CLAUDE.md) pueden perderse durante la compactación. Si una instrucción es importante para el resto de la sesión, conviene añadirla a CLAUDE.md para que persista de forma garantizada.

Estrategias para sesiones largas

Cuando una sesión se extiende durante horas o abarca múltiples tareas, algunas prácticas ayudan a mantener la calidad de las respuestas:

• Usar /clear entre tareas no relacionadas: en lugar de acumular contexto de tareas distintas, limpiar la conversación entre una y otra garantiza que Claude empiece con un contexto limpio y enfocado.

• Compactar en los límites de tarea: al terminar una fase de trabajo (exploración, implementación, testing), ejecutar /compact con instrucciones de enfoque para resumir lo acumulado.

• Delegar exploraciones a subagentes: las exploraciones de código consumen grandes cantidades de contexto. Delegarlas a subagentes mantiene limpio el contexto principal.

• Escribir instrucciones persistentes en CLAUDE.md: las instrucciones que deben sobrevivir a múltiples compactaciones deben estar en CLAUDE.md, no solo en la conversación.

• Monitorizar el contexto: usar /context periódicamente para ver cuánto espacio queda. Si el contexto supera el 80% en una tarea compleja con múltiples archivos, considerar reiniciar la sesión con un prompt más específico.

Si has corregido a Claude más de dos veces en la misma sesión sobre el mismo error, el contexto probablemente está contaminado con enfoques fallidos. En ese caso, es más efectivo hacer /clear y empezar con un prompt mejor que seguir corrigiendo.

Personalizar el comportamiento de compactación

Además de las instrucciones de enfoque que acepta /compact, el archivo CLAUDE.md puede incluir directrices sobre qué preservar durante la compactación:

# Reglas de compactacion
- Al compactar, conservar siempre la lista completa de archivos modificados
- Conservar los comandos de test y sus resultados
- Preservar las decisiones de diseño con su justificacion

Claude lee estas instrucciones al realizar la compactación (ya que relee CLAUDE.md del disco) y las aplica al proceso de resumen.