compaction-stratégique

Compétence de Compaction Stratégique

Suggère /compact manuel à des points stratégiques de votre flux de travail plutôt que de se fier à une compaction automatique arbitraire.

Quand l'activer

• Sessions longues qui approchent les limites de contexte (200K+ tokens)
• Travail sur des tâches multi-phases (recherche → planification → implémentation → test)
• Changement entre des tâches non liées dans la même session
• Après avoir terminé un jalon majeur et commencé un nouveau travail
• Quand les réponses ralentissent ou deviennent moins cohérentes (pression de contexte)

Pourquoi la compaction stratégique ?

La compaction automatique se déclenche à des moments arbitraires :

• Souvent en milieu de tâche, faisant perdre un contexte important
• Aucune conscience des limites logiques des tâches
• Peut interrompre des opérations multi-étapes complexes

La compaction stratégique aux limites logiques :

• Après l'exploration, avant l'exécution — Compacter le contexte de recherche, conserver le plan d'implémentation
• Après avoir terminé un jalon — Redémarrer à zéro pour la phase suivante
• Avant des changements de contexte majeurs — Effacer le contexte d'exploration avant une tâche différente

Comment ça fonctionne

Le script suggest-compact.js s'exécute lors de PreToolUse (Édition/Écriture) et combine deux signaux :

1. Taille du contexte (primaire) — Lit le dernier enregistrement usage à partir de la transcription de session (transcript_path dans la charge utile du hook) et somme input_tokens + cache_read_input_tokens + cache_creation_input_tokens (la vraie taille de contexte du tour). Suggère /compact à un seuil adapté à la fenêtre — 160k tokens sur une fenêtre de 200k, 250k sur une fenêtre de 1M (détectée à partir d'un marqueur de modèle [1m], ou inférée lorsque les tokens observés dépassent déjà 200k) — et rappelle après chaque tranche supplémentaire de 60k tokens de croissance du contexte.
2. Nombre d'appels d'outils (secondaire) — Compte les invocations d'outils dans la session ; suggère à un seuil configurable (par défaut : 50 appels), puis tous les 25 appels suivants.

Le nombre d'appels d'outils seul est un indicateur faible de la pression sur la fenêtre : quelques grandes lectures de fichiers ou réponses MCP peuvent remplir la fenêtre en très peu d'appels, tandis que de nombreux petits appels peuvent atteindre 50 avec une fenêtre presque vide. Le signal de taille de contexte se déclenche quand cela compte vraiment.

Configuration du Hook

Installé comme un plugin ? Aucune configuration n'est nécessaire. Le fichier hooks/hooks.json du plugin enregistre déjà suggest-compact.js (identifiant du hook pre:edit-write:suggest-compact, actif dans les profils de hook standard et strict). Ne copiez pas le bloc ci-dessous dans ~/.claude/settings.json — ~/.claude/scripts/ n'existe pas pour les installations via plugin, et dupliquer un hook de plugin provoque une double exécution.

Si installé manuellement (./install.sh), ajoutez à votre ~/.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" }]
      }
    ]
  }
}

Configuration

Variables d'environnement :

• COMPACT_THRESHOLD — Appels d'outils avant la première suggestion (par défaut : 50)
• COMPACT_CONTEXT_THRESHOLD — Tokens de contexte avant la suggestion liée à la taille (par défaut : 160000 pour une fenêtre de 200k, 250000 pour une fenêtre de 1M ; 0 désactive le signal de contexte)
• COMPACT_CONTEXT_INTERVAL — Tokens de contexte supplémentaires avant que la suggestion ne se répète (par défaut : 60000)
• COMPACT_STATE_TTL_DAYS — Jours avant que les fichiers d'état de session obsolètes dans le répertoire temporaire ne soient nettoyés (par défaut : 14)
• ECC_CONTEXT_WINDOW_TOKENS — Taille explicite de la fenêtre de contexte, en tokens, remplaçant la détection automatique. Définissez-la pour les modèles à grande fenêtre dont l'identifiant signalé ne comporte pas de marqueur [1m] (par exemple, Opus 4.x 400k, ou une nouvelle famille de modèles à fenêtre 1M) afin que le seuil s'adapte à la fenêtre réelle au lieu de par défaut à 200k et de surestimer l'utilisation du contexte.
• CLAUDE_CODE_AUTO_COMPACT_WINDOW — Surcharge native de la taille de fenêtre de Claude Code, en tokens ; utilisée comme solution de repli lorsque ECC_CONTEXT_WINDOW_TOKENS n'est pas défini.

La fenêtre de contexte est autrement détectée automatiquement à partir d'un marqueur de modèle [1m] ou inférée lorsque les tokens observés dépassent déjà 200k. Sur un modèle à grande fenêtre qui ne porte aucun de ces signaux, définissez l'une des surcharges ci-dessus pour que la suggestion /compact se déclenche au bon moment.

Guide de décision pour la compaction

Utilisez ce tableau pour décider quand compacter :

Transition de phase	Compacter ?	Pourquoi
Recherche → Planification	Oui	Le contexte de recherche est volumineux ; le plan est le résultat distillé
Planification → Implémentation	Oui	Le plan est écrit (un fichier, ou la liste de tâches si vous en avez une) ; libérez du contexte pour le code
Implémentation → Test	Peut-être	Conservez si les tests font référence au code récent ; compactez si vous changez de focus
Débogage → Nouvelle fonctionnalité	Oui	Les traces de débogage polluent le contexte pour un travail non lié
En pleine implémentation	Non	Perdre les noms de variables, chemins de fichiers et état partiel est coûteux
Après une approche échouée	Oui	Effacez le raisonnement sans issue avant d'essayer une nouvelle approche

Ce qui survit à la compaction

Comprendre ce qui persiste vous aide à compacter en toute confiance :

Survit	Perdu
Instructions CLAUDE.md	Raisonnement et analyses intermédiaires
Fichiers sur disque	Contenus de fichiers que vous avez précédemment lus
Fichiers mémoire (~/.claude/memory/)	Contexte de conversation multi-étapes
État Git (commits, branches)	Historique et comptes des appels d'outils
La liste de tâches — seulement si vous avez les outils todo (voir ci-dessous)	Préférences utilisateur nuancées exprimées verbalement

Ne comptez pas sur la survie de la liste de tâches — elle peut ne pas exister

Claude Code 2.1.233 a supprimé les outils todo/tâche par défaut sur Opus 4.8, Sonnet 5, Fable 5, Mythos 5 et les modèles plus récents (TodoWrite, TaskCreate/Get/Update/List). CLAUDE_CODE_ENABLE_TODO_TOOLS=1 les rétablit, mais il s'agit d'un paramètre d'environnement par machine — il ne voyage pas avec cette compétence, vous ne pouvez donc pas supposer que le lecteur l'a.

Ceci est important car "ma liste de tâches survit à la compaction" est une raison pour laquelle les gens compactent *au lieu d'*écrire l'état. Si les outils sont absents, il n'y a pas de liste pour survivre, et le plan est simplement perdu. Écrivez le plan dans un fichier avant de compacter — un fichier persiste sur chaque version et chaque modèle. Traitez la liste de tâches comme une commodité qui peut manquer, jamais comme votre enregistrement durable.

Bonnes pratiques

1. Compactez après la planification — Une fois le plan finalisé et écrit dans un fichier, compactez pour repartir à zéro
2. Compactez après le débogage — Effacez le contexte de résolution d'erreur avant de continuer
3. Ne compactez pas en pleine implémentation — Préservez le contexte pour les modifications connexes
4. Lisez la suggestion — Le hook vous dit quand, vous décidez si
5. Écrivez avant de compacter — Sauvegardez le contexte important dans des fichiers ou la mémoire avant de compacter
6. Utilisez /compact avec un résumé — Ajoutez un message personnalisé : /compact Se concentrer sur l'implémentation du middleware d'authentification ensuite

Modèles d'optimisation des tokens

Chargement paresseux par table de déclenchement

Au lieu de charger le contenu complet de la compétence au début de la session, utilisez une table de déclenchement qui associe des mots-clés à des chemins de compétences. Les compétences ne se chargent que lorsqu'elles sont déclenchées, réduisant le contexte de base de 50% ou plus :

Déclencheur	Compétence	Charger quand
"test", "tdd", "couverture"	tdd-workflow	L'utilisateur mentionne les tests
"sécurité", "auth", "xss"	security-review	Travail lié à la sécurité
"déploiement", "ci/cd"	deployment-patterns	Contexte de déploiement

Sensibilisation à la composition du contexte

Surveillez ce qui consomme votre fenêtre de contexte :

• Fichiers CLAUDE.md — Toujours chargés, gardez-les légers
• Compétences chargées — Chaque compétence ajoute 1 à 5K tokens
• Historique de conversation — Augmente à chaque échange
• Résultats d'outils — Lectures de fichiers, résultats de recherche ajoutent du volume

Détection des instructions en double

Sources courantes de contexte en double :

• Mêmes règles dans ~/.claude/rules/ et .claude/rules/ du projet
• Compétences qui répètent les instructions de CLAUDE.md
• Plusieurs compétences couvrant des domaines qui se chevauchent

Outils d'optimisation du contexte

• token-optimizer MCP — Réduction automatisée de 95%+ des tokens via déduplication de contenu
• context-mode — Virtualisation du contexte (démontré de 315 Ko à 5,4 Ko)

Liens connexes

• The Longform Guide — Section sur l'optimisation des tokens
• Hooks de persistance mémoire — Pour un état qui survit à la compaction
• Compétence continuous-learning — Extrait des modèles avant la fin de session