compactage-stratégique

Compétence Compactage Stratégique

Suggère un /compact manuel à des points stratégiques de votre flux de travail plutôt que de compter sur un compactage automatique arbitraire.

Quand l'activer

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

Pourquoi un compactage stratégique ?

Le compactage automatique se déclenche à des moments arbitraires :

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

Le compactage stratégique aux limites logiques :

• Après l'exploration, avant l'exécution — Compacter le contexte de recherche, garder le plan d'implémentation
• Après avoir terminé un jalon — Nouveau départ 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 (Edition/Ecriture) et combine deux signaux :

1. Taille du contexte (primaire) — Lit le dernier enregistrement usage du transcript de session (transcript_path dans la charge utile du hook) et additionne 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é à partir d'un marqueur de modèle [1m], ou déduit 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 après.

Le seul nombre d'appels 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 dépasser 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 plugin ? Aucune configuration nécessaire. Le fichier hooks/hooks.json du plugin enregistre déjà suggest-compact.js (id 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 sur 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 basée sur la taille du contexte (par défaut : 160000 sur une fenêtre de 200k, 250000 sur 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 supprimé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 ceci pour les modèles à grande fenêtre dont l'identifiant rapporté n'a pas de marqueur [1m] (par exemple, Opus 4.x 400k, ou une nouvelle famille de modèles avec fenêtre de 1M) afin que le seuil s'adapte à la vraie fenêtre au lieu de prendre par défaut 200k et de surestimer l'utilisation du contexte.
• CLAUDE_CODE_AUTO_COMPACT_WINDOW — Remplacement natif de la taille de fenêtre de Claude Code, en tokens ; utilisé 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 déduite 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'un des remplacements ci-dessus pour que la suggestion /compact se déclenche au bon moment.

Guide de décision pour le compactage

Utilisez ce tableau pour décider quand compacter :

Transition de phase	Compacter ?	Pourquoi
Recherche → Planification	Oui	Le contexte de recherche est volumineux ; le plan en est le résultat distillé
Planification → Implémentation	Oui	Le plan est écrit (dans un fichier, ou dans la liste de tâches si vous en avez une) ; libérez du contexte pour le code
Implémentation → Tests	Peut-être	Gardez si les tests référencent le code récent ; compactez si vous changez de focus
Débogage → Fonctionnalité suivante	Oui	Les traces de débogage polluent le contexte pour un travail non lié
En pleine implémentation	Non	Perdre des noms de variables, des chemins de fichiers et un é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 au compactage

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

Persiste	Perdu
Instructions CLAUDE.md	Raisonnement et analyse intermédiaires
Fichiers sur le disque	Contenus de fichiers précédemment lus
Fichiers mémoire (~/.claude/memory/)	Contexte de conversation multi-étapes
État Git (commits, branches)	Historique et nombre d'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 ramène, 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 au compactage » 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 toutes les versions et tous les modèles. Traitez la liste de tâches comme une commodité qui peut être absente, jamais comme votre enregistrement durable.

Meilleures pratiques

1. Compactez après la planification — Une fois le plan finalisé et écrit dans un fichier, compactez pour repartir à neuf
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

Patterns d'optimisation des tokens

Chargement paresseux avec 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 aux chemins des compétences. Les compétences ne se chargent que lorsqu'elles sont déclenchées, réduisant le contexte de base de 50%+ :

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

Conscience de 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 à 5 K tokens
• Historique de conversation — Croît à 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 dans le projet .claude/rules/
• 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

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

Liens associés

• Le Guide Longform — Section sur l'optimisation des tokens
• Hooks de persistance mémoire — Pour un état qui survit au compactage
• Compétence apprentissage-continu — Extrait les motifs avant la fin de la session