compactacion-estrategica

Habilidad de Compactación Estratégica

Sugiere /compact manual en puntos estratégicos de tu flujo de trabajo, en lugar de depender de la compactación automática arbitraria.

Cuándo activarla

• Sesiones largas que se acercan a los límites de contexto (200K+ tokens)
• Trabajar en tareas de múltiples fases (investigación → planificación → implementación → pruebas)
• Cambiar entre tareas no relacionadas dentro de la misma sesión
• Después de completar un hito importante y comenzar un nuevo trabajo
• Cuando las respuestas se vuelven lentas o menos coherentes (presión de contexto)

¿Por qué compactación estratégica?

La compactación automática se activa en puntos arbitrarios:

• A menudo a mitad de tarea, perdiendo contexto importante
• No tiene conocimiento de los límites lógicos de las tareas
• Puede interrumpir operaciones complejas de múltiples pasos

Compactación estratégica en límites lógicos:

• Después de la exploración, antes de la ejecución — Compacta el contexto de investigación, mantén el plan de implementación.
• Después de completar un hito — Nuevo comienzo para la siguiente fase.
• Ante cambios importantes de contexto — Limpia el contexto de exploración antes de una tarea diferente.

Cómo funciona

El script suggest-compact.js se ejecuta en PreToolUse (Editar/Escribir) y combina dos señales:

1. Tamaño del contexto (principal) — Lee el último registro de usage de la transcripción de la sesión (transcript_path en la carga útil del hook) y suma input_tokens + cache_read_input_tokens + cache_creation_input_tokens (el tamaño real del contexto de la ronda). Sugiere /compact en un umbral escalado por ventana: 160k tokens en una ventana de 200k, 250k en una ventana de 1M (detectado a partir de un marcador de modelo [1m], o inferido cuando los tokens observados ya superan los 200k), y lo recuerda nuevamente después de cada 60k tokens adicionales de crecimiento del contexto.
2. Recuento de llamadas a herramientas (secundario) — Cuenta las invocaciones de herramientas en la sesión; sugiere en un umbral configurable (por defecto: 50 llamadas), luego cada 25 llamadas después.

El recuento de herramientas por sí solo es un indicador débil de la presión de la ventana: unas pocas lecturas de archivos grandes o respuestas de MCP pueden llenar la ventana en muy pocas llamadas, mientras que muchas llamadas pequeñas pueden superar las 50 con la ventana casi vacía. La señal de tamaño de contexto se activa cuando realmente importa.

Configuración del Hook

¿Instalado como plugin? No se necesita configuración. El hooks/hooks.json del plugin ya registra suggest-compact.js (id del hook pre:edit-write:suggest-compact, activo en los perfiles de hook standard y strict). No copies el bloque de abajo en ~/.claude/settings.json — ~/.claude/scripts/ no existe en las instalaciones de plugins, y duplicar un hook de plugin causa doble ejecución.

Si se instaló manualmente (./install.sh), agrégalo a tu ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
      }
    ]
  }
}

Configuración

Variables de entorno:

• COMPACT_THRESHOLD — Llamadas a herramientas antes de la primera sugerencia (por defecto: 50)
• COMPACT_CONTEXT_THRESHOLD — Tokens de contexto antes de la sugerencia por tamaño de contexto (por defecto: 160000 en una ventana de 200k, 250000 en una ventana de 1M; 0 deshabilita la señal de contexto)
• COMPACT_CONTEXT_INTERVAL — Tokens de contexto adicionales antes de que se repita la sugerencia (por defecto: 60000)
• COMPACT_STATE_TTL_DAYS — Días antes de que se eliminen los archivos de estado por sesión obsoletos en el directorio temporal (por defecto: 14)
• ECC_CONTEXT_WINDOW_TOKENS — Tamaño explícito de la ventana de contexto, en tokens, anulando la detección automática. Establécelo para modelos de ventana grande cuyo ID informado carece de un marcador [1m] (por ejemplo, Opus 4.x de 400k, o una nueva familia de modelos de ventana de 1M) para que el umbral se escale a la ventana real en lugar de usar por defecto 200k y exagerar el uso del contexto.
• CLAUDE_CODE_AUTO_COMPACT_WINDOW — Anulación nativa del tamaño de ventana de Claude Code, en tokens; se respeta como alternativa cuando ECC_CONTEXT_WINDOW_TOKENS no está configurada.

La ventana de contexto se detecta automáticamente a partir de un marcador de modelo [1m] o se infiere cuando los tokens observados ya superan los 200k. En un modelo de ventana grande que no lleva ninguna de las dos señales, configura una de las anulaciones anteriores para que la sugerencia de /compact se active en el punto correcto.

Guía de Decisión de Compactación

Usa esta tabla para decidir cuándo compactar:

Transición de Fase	¿Compactar?	Por qué
Investigación → Planificación	Sí	El contexto de investigación es voluminoso; el plan es el resultado destilado
Planificación → Implementación	Sí	El plan está escrito (un archivo, o la lista de tareas si la tienes); libera contexto para el código
Implementación → Pruebas	Tal vez	Mantén si las pruebas hacen referencia al código reciente; compacta si cambias de enfoque
Depuración → Siguiente funcionalidad	Sí	Los rastros de depuración contaminan el contexto para trabajo no relacionado
A mitad de implementación	No	Perder nombres de variables, rutas de archivos y estado parcial es costoso
Después de un enfoque fallido	Sí	Limpia el razonamiento del callejón sin salida antes de probar un nuevo enfoque

Qué sobrevive a la compactación

Comprender qué persiste te ayuda a compactar con confianza:

Persiste	Se pierde
Instrucciones de CLAUDE.md	Razonamiento y análisis intermedios
Archivos en disco	Contenidos de archivos que leíste anteriormente
Archivos de memoria (~/.claude/memory/)	Contexto de conversación de múltiples pasos
Estado de Git (commits, ramas)	Historial y recuento de llamadas a herramientas
La lista de tareas — solo si tienes las herramientas de tareas (ver abajo)	Preferencias matizadas del usuario expresadas verbalmente

No confíes en que la lista de tareas sobreviva — puede que no exista

Claude Code 2.1.233 eliminó las herramientas de tareas (todo/task) por defecto en Opus 4.8, Sonnet 5, Fable 5, Mythos 5 y modelos más nuevos (TodoWrite, TaskCreate/Get/Update/List). CLAUDE_CODE_ENABLE_TODO_TOOLS=1 las recupera, pero esa es una configuración de entorno por máquina — no viaja con esta habilidad, por lo que no puedes asumir que el lector la tenga.

Esto es importante porque "mi lista de tareas sobrevive a la compactación" es una razón por la que la gente compacta en lugar de escribir el estado. Si las herramientas están ausentes, no hay lista que sobreviva, y el plan simplemente desaparece. Escribe el plan en un archivo antes de compactar — un archivo persiste en cada versión y en cada modelo. Trata la lista de tareas como una conveniencia que puede faltar, nunca como tu registro duradero.

Mejores Prácticas

1. Compacta después de planificar — Una vez que el plan esté finalizado y escrito en un archivo, compacta para empezar de nuevo.
2. Compacta después de depurar — Limpia el contexto de resolución de errores antes de continuar.
3. No compactes a mitad de implementación — Preserva el contexto para cambios relacionados.
4. Lee la sugerencia — El hook te dice cuándo, tú decides si.
5. Escribe antes de compactar — Guarda el contexto importante en archivos o memoria antes de compactar.
6. Usa /compact con un resumen — Añade un mensaje personalizado: /compact Enfócate en implementar el middleware de autenticación a continuación

Patrones de Optimización de Tokens

Carga Perezosa de Tabla de Disparo

En lugar de cargar el contenido completo de la habilidad al inicio de la sesión, usa una tabla de disparo que asigna palabras clave a rutas de habilidades. Las habilidades se cargan solo cuando se activan, reduciendo el contexto base en más del 50%:

Disparador	Habilidad	Cargar cuando
"test", "tdd", "coverage"	tdd-workflow	El usuario menciona pruebas
"security", "auth", "xss"	security-review	Trabajo relacionado con seguridad
"deploy", "ci/cd"	deployment-patterns	Contexto de despliegue

Conciencia de Composición del Contexto

Monitorea qué está consumiendo tu ventana de contexto:

• Archivos CLAUDE.md — Siempre cargados, mantenlos ligeros.
• Habilidades cargadas — Cada habilidad añade entre 1 y 5K tokens.
• Historial de conversación — Crece con cada intercambio.
• Resultados de herramientas — Las lecturas de archivos y los resultados de búsqueda añaden volumen.

Detección de Instrucciones Duplicadas

Fuentes comunes de contexto duplicado:

• Mismas reglas tanto en ~/.claude/rules/ como en el proyecto .claude/rules/.
• Habilidades que repiten instrucciones de CLAUDE.md.
• Múltiples habilidades que cubren dominios superpuestos.

Herramientas de Optimización de Contexto

• token-optimizer MCP — Reducción automatizada de más del 95% de tokens mediante deduplicación de contenido.
• context-mode — Virtualización de contexto (de 315KB a 5.4KB demostrado).

Relacionado

• La guía larga — Sección de optimización de tokens.
• Hooks de persistencia de memoria — Para estado que sobrevive a la compactación.
• Habilidad continuous-learning — Extrae patrones antes de que finalice la sesión.