compactación-estratégica

Skill 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 activarlo

• Sesiones largas que se acercan a los límites de contexto (200K+ tokens)
• Trabajo en tareas multi-fase (investigación → planificación → implementación → prueba)
• Cambio 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 una tarea, perdiendo contexto importante
• Sin conciencia de los límites lógicos de la tarea
• Puede interrumpir operaciones complejas de varios pasos

La 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, conserva el plan de implementación
• Después de completar un hito — Nuevo comienzo para la siguiente fase
• Antes de cambios de contexto importantes — 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 de contexto real del turno). Sugiere /compact en un umbral escalado a la 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 vuelve a recordar después de cada 60k tokens adicionales de crecimiento del contexto
2. Conteo de llamadas a herramientas (secundario) — Cuenta las invocaciones de herramientas en la sesión; sugiere en un umbral configurable (predeterminado: 50 llamadas), luego cada 25 llamadas después

El conteo de herramientas por sí solo es un proxy débil para la presión de la ventana: unas pocas lecturas grandes de archivos o respuestas de MCP pueden llenar la ventana en muy pocas llamadas, mientras que muchas llamadas pequeñas pueden superar 50 con una 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 archivo 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 plugin, y duplicar un hook de plugin provoca doble ejecución.

Si se instala 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 (predeterminado: 50)
• COMPACT_CONTEXT_THRESHOLD — Tokens de contexto antes de la sugerencia por tamaño de contexto (predeterminado: 160000 en una ventana de 200k, 250000 en una ventana de 1M; 0 desactiva la señal de contexto)
• COMPACT_CONTEXT_INTERVAL — Tokens de contexto adicionales antes de que se repita la sugerencia (predeterminado: 60000)
• COMPACT_STATE_TTL_DAYS — Días antes de que los archivos de estado por sesión obsoletos en el directorio temporal se eliminen (predeterminado: 14)
• ECC_CONTEXT_WINDOW_TOKENS — Tamaño explícito de la ventana de contexto, en tokens, que anula la detección automática. Establécelo para modelos de ventana grande cuyo ID informado carece de un marcador [1m] (p. ej., 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 200k por defecto y exagerar el uso del contexto.
• CLAUDE_CODE_AUTO_COMPACT_WINDOW — Anulación del tamaño de ventana nativa de Claude Code, en tokens; se respeta como alternativa cuando ECC_CONTEXT_WINDOW_TOKENS no está establecida.

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 tenga ninguna de estas señales, establece 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 función	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 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 CLAUDE.md	Razonamiento y análisis intermedios
Archivos en disco	Contenido de archivos que leíste previamente
Archivos de memoria (~/.claude/memory/)	Contexto de conversación de varios pasos
Estado de Git (commits, ramas)	Historial de llamadas a herramientas y conteos
La lista de tareas — solo si tienes las herramientas de tareas pendientes (ver más abajo)	Preferencias de usuario matizadas indicadas 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 pendientes por defecto en Opus 4.8, Sonnet 5, Fable 5, Mythos 5 y modelos más recientes (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 este skill, por lo que no se puede 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 todas las versiones y todos los modelos. 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 — Agrega 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 Tablas de Disparo

En lugar de cargar todo el contenido del skill al inicio de la sesión, usa una tabla de disparo que asigne palabras clave a rutas de skills. Los skills se cargan solo cuando se activan, reduciendo el contexto base en un 50%+:

Disparador	Skill	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
• Skills cargados — Cada skill agrega 1-5K tokens
• Historial de conversación — Crece con cada intercambio
• Resultados de herramientas — Lecturas de archivos, resultados de búsqueda agregan volumen

Detección de Instrucciones Duplicadas

Fuentes comunes de contexto duplicado:

• Mismas reglas en ~/.claude/rules/ y en el proyecto .claude/rules/
• Skills que repiten instrucciones de CLAUDE.md
• Múltiples skills que cubren dominios superpuestos

Herramientas de Optimización de Contexto

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

Relacionados

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