Problemas y soluciones para la función de compactación de Claude Code

Más tarde, creé un plugin que puede incluir automáticamente el siguiente contenido y mejorar de forma transparente la función compacta.

https://x.com/u1/status/2073742408555343968

Cómo funciona realmente Compact de Claude Code

Como premisa, el compact de Claude Code se ejecuta a través de dos rutas:

• Compact manual (/compact): Se activa explícitamente por el usuario. Se puede ejecutar en cualquier momento.
• Compact automático: Se ejecuta automáticamente cuando el uso del contexto de la sesión se acerca al límite (aproximadamente 90-95% en la práctica). No se ejecuta en el momento exacto que el usuario pretende, sino en los límites de turno donde de repente te das cuenta de que se ha comprimido.

En ambas rutas, el contenido es el mismo: el historial de conversación anterior se envía al LLM para crear un resumen en lenguaje natural, y el resumen + los turnos recientes + el prompt del sistema se reconstruyen como un nuevo contexto. El resumen se convierte en una descripción narrativa de "lo que se hizo" y, como resultado, la estructura de decisiones, como "por qué se tomó esa decisión", "qué planes fueron rechazados" y "en qué fase nos encontramos actualmente", se debilita. Además, una vez que se ejecuta la compresión, es una operación irreversible; no se puede volver a los registros sin procesar anteriores a la compresión.

Desde una perspectiva de hooks, la compresión se puede capturar con el evento PostCompact. Sin embargo, el hook PostCompact no puede devolver additionalContext, por lo que no hay una ruta para inyectar instrucciones directamente al agente inmediatamente después de la compresión. Para insertar instrucciones, se debe pasar por el evento UserPromptSubmit posterior. Esta restricción dicta el diseño del hook en este artículo.

Qué está mal con el Compact estándar

El /compact de Claude Code resume el historial de la conversación, colocando el resultado como el contexto inicial para una nueva sesión. Si bien el resumen en sí es razonable, es un "registro de trabajo del pasado" en lugar de una "instrucción sobre qué hacer a continuación". En consecuencia, el agente posterior a la compresión se vuelve propenso a los siguientes conceptos erróneos:

• Perder el límite entre "instrucciones de trabajo" y "registros de trabajo". Si el resumen dice "Se consideró el Plan A", el agente podría comenzar a implementar el Plan A en lugar del Plan B realmente adoptado.
• Confundir la fase de verificación con la fase de implementación. La premisa de "verificar en la máquina real antes de implementar" desaparece del resumen y el agente podría saltar a operaciones de implementación destructivas en el siguiente turno.
• Volver a proponer enfoques incorrectos que ya fueron descartados. El resumen podría registrar que se "probó" un enfoque, pero no la "razón por la que fue rechazado".
• Perder el "estado de la sesión", como el modo de plan, la delegación de trabajadores o los árboles de tareas. El agente podría continuar trabajando fuera del modo de plan u olvidar la existencia de trabajadores que se ejecutan en tmux y comenzar a hacer el trabajo él mismo.

Qué tipo de accidentes ocurrieron realmente

Al revisar mis sesiones de la última semana, observé al menos cuatro patrones inmediatamente después de un compact. Todos parecen tener su origen en la falta de separación entre "instrucciones de trabajo" y "registros de trabajo":

• Implementación antes de la verificación: A pesar de acordar "verificar el comportamiento en la máquina antes de colocar los archivos", el agente solo vio la imagen de finalización en el resumen después de la compresión, omitió la verificación y sobrescribió el destino.
• Re-ejecución de atajos rechazados: Debido a que el resumen registró un enfoque de atajo fallido como un "procedimiento probado", el agente lo re-ejecutó y volvió a caer en el mismo error.
• Olvido de los principios de diseño: Principios establecidos durante la sesión, como "editar el repositorio fuente en lugar del destino", desaparecieron del resumen, lo que llevó al agente a hacer ediciones directas que funcionan a corto plazo pero no son reproducibles.
• Malentendido de los objetivos de la tarea: El propósito específico de una prueba fijada antes de la compresión se perdió, lo que llevó al agente a desviarse hacia investigaciones periféricas y comenzar a trabajar en una línea completamente diferente.

Estos ocurrieron varias veces dentro de la misma sesión, con diferentes tipos de conceptos erróneos después de cada compact. Veo esto como fallas estructurales de la especificación estándar de compact, más que como accidentes aislados.

Lo que construí

(1) Habilidad compact-prep

Una habilidad implementada como un comando de barra que el usuario ejecuta explícitamente antes de escribir /compact. Extrae la "estructura de decisiones" y el "estado de la sesión" que probablemente no encajarán en un resumen y los guarda en un archivo de estado en una ruta fija (${TMPDIR}/claude-compact-state/<session_id>.md) en un formato específico.

Los elementos guardados incluyen aquellos que son difíciles de capturar en los resúmenes:

• Plan Activo (ruta del archivo de plan y fase actual)
• Resumen de la Lista de Tareas (tareas en curso y complementos)
• Decisiones de la Sesión (planes adoptados / planes rechazados / razones del rechazo)
• Restricciones y Bloqueadores
• Topología de Trabajadores (paneles de tmux-bridge / roles / asignaciones)
• Archivos en Edición (notas sobre cambios no guardados o no verificados)
• Notas de Recuperación (una carta para el yo posterior a la compresión)

El punto clave del diseño es la "aplicación mecánica". Utiliza una puerta estricta para evitar la creación de archivos si no se encuentra un session_id, una función de forzado con encabezados fijos para detectar omisiones y herramientas permitidas restringidas para evitar la corrupción del estado.

(2) Hook de dos etapas: PostCompact + UserPromptSubmit

Incluso si (1) escribe un archivo de estado, no tiene sentido si el agente posterior a la compresión no lo lee. Dado que PostCompact no puede devolver additionalContext, utilicé una configuración de dos etapas:

1. El hook PostCompact escribe un archivo marcador con el session_id (sin instrucciones, solo registra que ocurrió la compresión).
2. Cuando el siguiente hook UserPromptSubmit detecta el marcador, inyecta instrucciones a través de additionalContext: "Lee el archivo de plan / Lee el archivo de estado / Verifica la Lista de Tareas / Trata los próximos pasos del resumen como hipótesis / Confirma la reentrada si el modo de plan se desactivó", luego elimina el marcador.

Dado que Claude Code carece de un mecanismo de estado compartido entre hooks, un marcador en el sistema de archivos es la única ruta de comunicación. Esto mantiene cada hook ligero con una única responsabilidad. En los turnos normales, la sobrecarga es solo una comprobación test -f.

(3) Notificación del 60% (Para evitar el compact automático)

Las herramientas anteriores asumen que el usuario ejecuta manualmente /compact-prep → /compact. Sin embargo, el compact automático se ejecuta sin previo aviso, evitando este flujo. Si el compact automático se activa primero, el archivo de estado no se guarda y los registros sin procesar se trituran en un resumen, perdiendo el material de recuperación.

La solución es crear un estado en el que el usuario pueda ejecutar manualmente la preparación antes de que se active el compact automático. Este es el propósito de la notificación del 60%.

¿Por qué el 60%?

• Tiempo de anticipación suficiente: El compact automático se activa alrededor del 90-95%. El 60% proporciona un margen del 30%, lo que garantiza que el usuario vea la advertencia antes de que el siguiente turno active un compact automático.
• Espacio para llegar a un punto de parada: Al 60%, todavía hay un 30% de capacidad restante para terminar una subtarea antes de guardar el estado.
• Disparador mecánico: Actúa como una función de forzado cuando estás demasiado concentrado para notar el consumo de contexto.
• Suposición de contexto de 1M: Con un contexto de 200K, el 60% es demasiado pequeño. Yo uso el contexto de 1M (Opus 4.7), donde el 60% deja alrededor de 600K tokens, suficiente espacio para terminar el trabajo y ejecutar la preparación.

La implementación implica un hook de línea de estado que escribe un marcador de advertencia en el umbral, y un hook UserPromptSubmit que lo detecta para sugerir ejecutar /compact-prep.

Resultados

¡Las sesiones ahora son estables incluso después de aproximadamente 10 compactaciones sin fallos lógicos!

• La pérdida de trabajo debido a la compresión es casi nula.
• Las re-propuestas de ideas rechazadas han desaparecido.
• El modo de plan se mantiene.
• No más olvidos de la topología al ejecutar múltiples trabajadores en tmux.

Referencia: Código de implementación

A continuación se muestran los códigos reales de la habilidad y los hooks. Funcionan copiándolos al directorio estándar de Claude Code (~/.claude/).

A: Cuerpo de la habilidad compact-prep

Colocar en ~/.claude/skills/compact-prep/SKILL.md.

1---
2name: compact-prep
3description: |
4  Antes de ejecutar /compact en Claude Code, guarda el estado actual de la sesión en un archivo de estado temporal.
5  DISPARADORES OBLIGATORIOS: /compact-prep, compact-prep, preparación de compresión.
6  NO DISPARAR: recuperación después de compact, informes de progreso normales, creación de planes.
7strict_procedure: true
8argument-hint: "[notas de recuperación]"
9allowed-tools: Read Write Bash(~/.claude/scripts/get-session-id.sh *) Bash(mkdir *) Bash(date *) Bash(pwd)
10---
11
12# compact-prep
13
14Guarda el estado de la sesión que es difícil de mantener en los resúmenes de compresión en
15`${TMPDIR}/claude-compact-state/${SESSION_ID}.md` antes de `/compact`.
16
17## Perfil de procedimiento estricto
18
19- Estricción: procedimiento estricto.
20- Puertas estrictas: Detener si no se puede recuperar el session_id.
21- Función de forzado: Ruta fija y verificación obligatoria de encabezados después de guardar.
22- Recibo de finalización: Informar la ruta del archivo, los elementos guardados y la orientación para ejecutar `/compact`.
23
24## Procedimiento
25
261. Obtener session_id a través de `~/.claude/scripts/get-session-id.sh`.
272. Establecer la ruta en `${TMPDIR:-/tmp}/claude-compact-state/${SESSION_ID}.md`.
283. Verificar la Lista de Tareas, el plan activo, tmux-bridge y los archivos en edición.
294. Guardar los encabezados en orden: # Compact Prep State, ## Active Plan, ## Current Phase, ## TaskList Summary, ## Session Decisions, ## Constraints and Blockers, ## Worker Topology, ## Editing Files, ## Recovery Notes.
305. Verificar que todos los encabezados existan.
316. Decir al usuario: "Preparación completa. Por favor, ejecute `/compact`."

B: Hooks de recuperación (2 etapas)

B-1: Hook PostCompact

~/.claude/hooks/compaction-recovery.sh

B-2: Hook UserPromptSubmit (Inyección)

~/.claude/hooks/userpromptsubmit-compaction-recovery.sh

C: Notificación del 60%

C-1: Rama de umbral del hook statusline

Añadido a ~/.claude/hooks/statusline.sh.

C-2: Hook UserPromptSubmit (Recordatorio)

~/.claude/hooks/userpromptsubmit-compact-prep-reminder.sh

D: Registro en settings.json

Añadir los hooks a ~/.claude/settings.json.