Problèmes et solutions pour la fonctionnalité Compact de Claude Code

Plus tard, j'ai créé un plugin qui peut inclure automatiquement le contenu suivant et améliorer de manière transparente la fonctionnalité compacte.

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

Comment fonctionne réellement le Compact de Claude Code

En préambule, le compact de Claude Code emprunte deux chemins :

• Compact manuel (/compact) : Déclenché explicitement par l'utilisateur. Peut être lancé à tout moment.
• Compact automatique : S'exécute automatiquement lorsque l'utilisation du contexte de la session approche de la limite (environ 90-95 % en pratique). Il ne se déclenche pas exactement au moment où l'utilisateur le souhaite, mais plutôt aux limites de tour où l'on réalise soudainement que la compression a eu lieu.

Dans les deux cas, le contenu est le même : l'historique de la conversation précédente est envoyé au LLM pour créer un résumé en langage naturel, et le résumé + les tours récents + l'invite système sont reconstruits en un nouveau contexte. Le résumé devient une description narrative de « ce qui a été fait », et par conséquent, la structure décisionnelle — comme « pourquoi ce choix a été fait », « quels plans ont été rejetés » et « dans quelle phase nous nous trouvons actuellement » — est affaiblie. De plus, une fois la compression effectuée, il s'agit d'une opération irréversible ; il est impossible de revenir aux journaux bruts d'avant la compression.

Du point de vue des hooks, la compression peut être interceptée par l'événement PostCompact. Cependant, le hook PostCompact ne peut pas renvoyer additionalContext, il n'y a donc aucun moyen d'injecter directement des instructions dans l'agent immédiatement après la compression. Pour insérer des instructions, il faut passer par l'événement UserPromptSubmit suivant. Cette contrainte dicte la conception du hook dans cet article.

Qu'est-ce qui ne va pas avec le Compact Standard

Le /compact de Claude Code résume l'historique de la conversation, plaçant le résultat comme contexte initial d'une nouvelle session. Bien que le résumé soit raisonnable, il s'agit d'un « journal de travail du passé » plutôt que d'une « instruction pour la suite à faire ». Par conséquent, l'agent post-compression devient sujet aux erreurs suivantes :

• Perte de la frontière entre « instructions de travail » et « journaux de travail ». Si le résumé indique « Le plan A a été envisagé », l'agent pourrait commencer à implémenter le plan A au lieu du plan B effectivement adopté.
• Confusion entre la phase de vérification et la phase d'implémentation. La prémisse de « vérifier sur la machine réelle avant de déployer » disparaît du résumé, et l'agent pourrait se lancer dans des opérations de déploiement destructrices au tour suivant.
• Reproposition d'approches incorrectes déjà écartées. Le résumé peut enregistrer qu'une approche a été « essayée » mais pas la « raison pour laquelle elle a été rejetée ».
• Perte de « l'état de session » comme le mode plan, la délégation de travailleurs ou les arbres de tâches. L'agent pourrait continuer le travail en dehors du mode plan ou oublier l'existence de travailleurs s'exécutant dans tmux et commencer à faire le travail lui-même.

Quels types d'accidents se sont réellement produits

En repensant à mes sessions de la semaine dernière, j'ai observé au moins quatre modèles immédiatement après un compact. Tous semblent provenir de l'incapacité à séparer les « instructions de travail » des « journaux de travail » :

• Déploiement avant vérification : Bien qu'ayant convenu de « vérifier le comportement sur la machine avant de placer les fichiers », l'agent n'a vu que l'image d'achèvement dans le résumé après compression, a sauté la vérification et a écrasé la destination.
• Réexécution de raccourcis rejetés : Parce que le résumé a enregistré une approche de raccourci ayant échoué comme une « procédure essayée », l'agent l'a réexécutée et est retombé dans le même échec.
• Oubli des principes de conception : Les principes établis pendant la session, comme « éditer le dépôt source au lieu de la destination », ont disparu du résumé, amenant l'agent à faire des modifications directes qui fonctionnent à court terme mais ne sont pas reproductibles.
• Mauvaise compréhension des objectifs de tâche : L'objectif spécifique d'un test fixé avant la compression a été perdu, amenant l'agent à dérailler vers des investigations périphériques et à commencer à travailler sur une toute autre ligne.

Ces problèmes se sont produits plusieurs fois au sein de la même session, avec différents types d'erreurs après chaque compact. Je considère cela comme des défaillances structurelles de la spécification standard du compact plutôt que des accidents isolés.

Ce que j'ai construit

(1) Compétence compact-prep

Une compétence implémentée en tant que commande slash que l'utilisateur déclenche explicitement avant de taper /compact. Elle extrait la « structure décisionnelle » et « l'état de session » qui ne tiendront probablement pas dans un résumé et les sauvegarde dans un fichier d'état à un chemin fixe (${TMPDIR}/claude-compact-state/<session_id>.md) dans un format spécifique.

Les éléments sauvegardés incluent ceux qui sont difficiles à capturer dans les résumés :

• Plan actif (chemin du fichier plan et phase en cours)
• Résumé de la liste de tâches (tâches en cours et suppléments)
• Décisions de session (plans adoptés / plans rejetés / raisons du rejet)
• Contraintes et blocages
• Topologie des travailleurs (volets tmux-bridge / rôles / affectations)
• Fichiers en cours d'édition (notes sur les modifications non sauvegardées ou non vérifiées)
• Notes de récupération (une lettre à soi-même après compression)

Le point clé de la conception est « l'application mécanique ». Elle utilise une barrière stricte pour empêcher la création de fichier si un session_id n'est pas trouvé, une fonction de forçage avec des titres fixes pour détecter les omissions, et des outils autorisés restreints pour éviter la corruption de l'état.

(2) Hook en deux étapes : PostCompact + UserPromptSubmit

Même si (1) écrit un fichier d'état, cela ne sert à rien si l'agent post-compression ne le lit pas. Puisque PostCompact ne peut pas renvoyer additionalContext, j'ai utilisé une configuration en deux étapes :

1. Le hook PostCompact écrit un fichier marqueur avec le session_id (aucune instruction, juste l'enregistrement que la compression a eu lieu).
2. Lorsque le hook UserPromptSubmit suivant détecte le marqueur, il injecte des instructions via additionalContext : « Lire le fichier plan / Lire le fichier d'état / Vérifier la liste de tâches / Traiter les prochaines étapes du résumé comme des hypothèses / Confirmer la réentrée si le mode plan a été désactivé », puis supprime le marqueur.

Comme Claude Code manque d'un mécanisme d'état partagé entre les hooks, un marqueur sur le système de fichiers est le seul chemin de communication. Cela maintient chaque hook léger avec une seule responsabilité. Dans les tours normaux, la surcharge est juste une vérification test -f.

(3) Notification à 60 % (Pour éviter le compact automatique)

Les outils précédents supposent que l'utilisateur exécute manuellement /compact-prep → /compact. Cependant, le compact automatique s'exécute sans avertissement, contournant ce flux. Si le compact automatique se déclenche en premier, le fichier d'état n'est pas sauvegardé et les journaux bruts sont écrasés en un résumé, perdant ainsi le matériel de récupération.

La solution est de créer un état où l'utilisateur peut exécuter manuellement la préparation avant que le compact automatique ne se déclenche. C'est le but de la notification à 60 %.

Pourquoi 60 % ?

• Délai suffisant : Le compact automatique se déclenche autour de 90-95 %. 60 % offre une marge de 30 %, garantissant que l'utilisateur voit l'avertissement avant que le tour suivant ne déclenche un compact automatique.
• Marge pour atteindre un point d'arrêt : À 60 %, il reste encore 30 % de capacité pour terminer une sous-tâche avant de sauvegarder l'état.
• Déclencheur mécanique : Il agit comme une fonction de forçage lorsque vous êtes trop concentré pour remarquer la consommation de contexte.
• Hypothèse de contexte 1M : Avec un contexte de 200K, 60 % est trop petit. J'utilise le contexte 1M (Opus 4.7), où 60 % laisse environ 600K tokens — amplement de place pour terminer le travail et exécuter la préparation.

L'implémentation implique un hook statusline écrivant un marqueur d'avertissement au seuil, et un hook UserPromptSubmit le détectant pour suggérer d'exécuter /compact-prep.

Résultats

Les sessions sont maintenant stables même après environ 10 compactions sans rupture logique !

• La perte de travail due à la compression est presque nulle.
• Les repropositions d'idées rejetées ont disparu.
• Le mode plan est maintenu.
• Plus d'oubli de la topologie lors de l'exécution de plusieurs travailleurs dans tmux.

Référence : Code d'implémentation

Ci-dessous se trouvent les codes réels de la compétence et des hooks. Ils fonctionnent en les copiant dans le répertoire standard de Claude Code (~/.claude/).

A : Corps de la compétence compact-prep

Placer dans ~/.claude/skills/compact-prep/SKILL.md.

1---
2name: compact-prep
3description: |
4  Avant d'exécuter /compact dans Claude Code, sauvegarder l'état actuel de la session dans un fichier d'état temporaire.
5  DÉCLENCHEURS OBLIGATOIRES : /compact-prep, compact-prep, préparation à la compression.
6  NE PAS DÉCLENCHER : récupération après compact, rapports de progression normaux, création de plan.
7strict_procedure: true
8argument-hint: "[notes de récupération]"
9allowed-tools: Read Write Bash(~/.claude/scripts/get-session-id.sh *) Bash(mkdir *) Bash(date *) Bash(pwd)
10---
11
12# compact-prep
13
14Sauvegarde l'état de session difficile à conserver dans les résumés de compression
15dans `${TMPDIR}/claude-compact-state/${SESSION_ID}.md` avant `/compact`.
16
17## Profil de procédure stricte
18
19- Stricteté : procédure stricte.
20- Barrières strictes : Arrêter si session_id ne peut pas être récupéré.
21- Fonction de forçage : Chemin fixe et vérification obligatoire des titres après sauvegarde.
22- Reçu d'achèvement : Rapporter le chemin du fichier, les éléments sauvegardés et les instructions pour exécuter `/compact`.
23
24## Procédure
25
261. Obtenir session_id via `~/.claude/scripts/get-session-id.sh`.
272. Définir le chemin vers `${TMPDIR:-/tmp}/claude-compact-state/${SESSION_ID}.md`.
283. Vérifier la liste de tâches, le plan actif, tmux-bridge et les fichiers en cours d'édition.
294. Sauvegarder les titres dans l'ordre : # Compact Prep State, ## Active Plan, ## Current Phase, ## TaskList Summary, ## Session Decisions, ## Constraints and Blockers, ## Worker Topology, ## Editing Files, ## Recovery Notes.
305. Vérifier que tous les titres existent.
316. Dire à l'utilisateur : « Préparation terminée. Veuillez exécuter `/compact`. »

B : Hooks de récupération (2 étapes)

B-1 : Hook PostCompact

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

B-2 : Hook UserPromptSubmit (Injection)

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

C : Notification à 60 %

C-1 : Branche de seuil du hook statusline

Ajouté à ~/.claude/hooks/statusline.sh.

C-2 : Hook UserPromptSubmit (Rappel)

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

D : Enregistrement dans settings.json

Ajouter les hooks à ~/.claude/settings.json.