Le problème de la session longue & La compaction

Le problème de la session longue : quand le contexte sature

L’idée en une phrase

Une session Claude Code n’oublie rien : chaque requête renvoie l’historique complet — prompts, réponses, résultats d’outils — si bien qu’une session qui dure accumule mécaniquement du contexte jusqu’à saturer sa fenêtre ; le tier Avancé s’ouvre donc sur la question que Reduce et Delegate ont repoussée sans la supprimer : que faire quand, malgré tout, la fenêtre se remplit ?

Analogie : un tableau blanc de salle de réunion que personne n’efface jamais. Les schémas de la réunion du matin se superposent à ceux de la veille, on écrit les décisions du jour dans les marges restantes, et chaque participant dépense son attention à trier l’actuel de l’obsolète au lieu de réfléchir. Le tableau n’est pas plein d’informations fausses — il est plein d’informations périmées, et c’est ce qui le rend inutilisable.

Points clés

• Le contexte d’une session ne fait que croître. Chaque tour ajoute le message, la réponse, et surtout les résultats d’outils (fichiers lus, sorties de build, diffs) — de loin le poste le plus lourd. Rien ne sort jamais de lui-même : une erreur corrigée depuis deux heures occupe toujours ses ~3 000 tokens.
• La dégradation précède la panne. Les lois d’échelle inverses (chapitre 2) mordent bien avant la limite dure : vers ~60-70 % d’occupation, l’agent commence à perdre des instructions, mélanger des versions successives d’un même fichier, re-proposer des pistes déjà écartées. Attendre le message d’erreur, c’est travailler longtemps avec un agent déjà diminué.
• La saturation se mesure, elle ne se devine pas. /context détaille l’occupation poste par poste — dont l’historique de conversation et la réserve d’auto-compaction ; /usage signale un comportement « long context » dès qu’il pèse ~10 % de la consommation récente. Ce sont les instruments du chapitre 2, appliqués dans la durée.
• Une longue session coûte aussi en tokens facturés. L’historique complet repart à chaque requête : une question d’une ligne posée dans une session de ~150 000 tokens fait relire ~150 000 tokens (au tarif du cache, mais relus quand même). Le poids mort se paie à chaque tour, pas une seule fois.
• La borne dure existe. Quand la conversation atteint la limite du modèle sans mécanisme de secours, l’API rejette la requête (erreur « prompt is too long ») : sans compaction, la session est terminée, quel que soit le travail en cours.

Exemple concret

Une session de refactorisation démarre proprement : ~15 000 tokens de préfixe (prompt système, outils, CLAUDE.md sobre — chapitre 5). Trois heures plus tard : ~40 fichiers lus (~60 000 tokens), ~15 sorties de build et de tests (~30 000 tokens), le fil de conversation (~35 000 tokens) — ~140 000 tokens, soit ~70 % d’une fenêtre de 200k. Or l’essentiel de cette masse est mort : les fichiers relus ont changé depuis, les builds rouges sont corrigés, les pistes abandonnées sont… abandonnées. L’état utile — objectif, décisions prises, fichiers en cours, prochaine étape — tiendrait en ~2 000 tokens. L’agent paie donc ~138 000 tokens de lest pour ~2 000 tokens de valeur, et son attention se dilue exactement comme le prédit le chapitre 2.

Anatomie d’une session de 3 heures — poids mort vs état utile

Contenu de la fenêtre	Poids approximatif	Encore utile ?
Préfixe fixe (système, outils, CLAUDE.md)	~15 000 tokens	Oui — incompressible
Fichiers lus, versions dépassées	~60 000 tokens	Non — le disque fait foi
Sorties de build/tests, erreurs corrigées	~30 000 tokens	Non — résolues
Fil de conversation, détours inclus	~35 000 tokens	~2 000 tokens de décisions
Total	~140 000 tokens (~70 %)	~17 000 tokens réellement utiles

Commande — instrumenter la dérive d’une session

# Le POURQUOI : la saturation se constate poste par poste, pas au ressenti.
# Dans la session, relever l'occupation — historique et réserve d'auto-compaction compris :
/context

# Et vérifier si le « long context » pèse déjà sur la consommation récente :
/usage

Piège courant : « tant qu’il n’y a pas de message d’erreur, la session va bien » est inexact — la limite dure est le dernier symptôme, pas le premier. La performance décroît continûment à mesure que la fenêtre se remplit (lois d’échelle inverses, chapitre 2) ; une session à ~70 % fonctionne, mais avec un agent qui a déjà perdu en précision. Le seuil d’action utile est bien avant le mur.

---

La compaction : /compact et l’auto-compaction

L’idée en une phrase

La compaction remplace l’historique de la conversation par un résumé qui en préserve l’essentiel — manuellement via /compact, ou automatiquement quand la session approche du seuil configuré ; c’est du Reduce curatif : au lieu d’empêcher les tokens d’entrer, on condense après coup ce qui s’est accumulé, en échangeant du détail contre de la place.

Analogie : le compte rendu d’une réunion-fleuve. À la fin, on ne conserve pas l’enregistrement des trois heures d’échanges : un secrétaire rédige une page — décisions, actions, points ouverts — et c’est elle qui fait référence ensuite. Tout tient dans la qualité du secrétaire : s’il ne sait pas ce qui compte pour la suite, le compte rendu sera fidèle… et inutile. D’où l’intérêt de lui donner des consignes.

Points clés

• /compact résume et repart. La commande fait rédiger un résumé de la conversation, puis la session continue avec ce résumé à la place de l’historique brut : ~140 000 tokens d’historique deviennent quelques milliers de tokens de synthèse. Dans une session neuve, elle répond « Not enough messages to compact. » — il n’y a rien à condenser.
• La compaction se pilote. /compact Concentre-toi sur les fichiers modifiés et les décisions oriente le résumé ; et une section # Compact instructions dans le CLAUDE.md du projet fixe ces consignes une fois pour toutes, pour les compactions manuelles comme automatiques.
• L’auto-compaction est le filet de sécurité. Sans réglage, Claude Code compacte de lui-même quand la conversation approche la limite du modèle (la borne des 200k pour les modèles à fenêtre de 200k). Le seuil se règle : commande /autocompact, drapeau --autocompact au lancement, ou variable CLAUDE_CODE_AUTO_COMPACT_WINDOW (de 100K à 1M, plafonnée à la fenêtre du modèle — la variable prime sur le reste). Auto-compaction coupée, la session s’arrête net sur l’erreur de limite.
• La compaction n’est pas gratuite. Pour résumer, il faut relire tout ce qu’on résume : compacter une session de ~160 000 tokens est une requête de ~160 000 tokens. Elle invalide en outre le cache de prompt — la requête suivante reconstruit le préfixe (le « expected rebuild » qu’affiche /usage). À utiliser comme un pit-stop délibéré, pas comme un tic.
• La compaction est avec perte. Le résumé garde ce que le rédacteur a jugé important ; le détail brut — la valeur exacte d’une config lue il y a deux heures, le message précis d’une erreur — peut disparaître. Quand la continuité n’a pas de valeur, /clear reste supérieur : gratuit, instantané, total (chapitre sur l’hygiène de session à venir : journal et context bundles offriront une continuité choisie).

Exemple concret

La session de refactorisation ci-dessus atteint ~140 000 tokens (~70 %). Un /compact Garde l'objectif, les fichiers modifiés avec leur chemin, les décisions d'architecture et la prochaine étape déclenche une requête lourde (~140 000 tokens relus) qui produit un résumé de ~2 500 tokens. La session repart : préfixe fixe ~15 000 tokens + résumé ~2 500 tokens = ~17 500 tokens, ~9 % de la fenêtre. On a rendu ~122 000 tokens (~61 % de la fenêtre) et l’agent retrouve la densité d’attention d’un début de session — au prix d’une grosse requête ponctuelle, d’un cache à reconstruire, et de la perte du détail brut : si la prochaine question porte sur la ligne exacte d’un fichier lu avant compaction, l’agent devra le relire depuis le disque. C’est le compromis exact du Reduce curatif : de la place contre du détail.

/compact, auto-compaction, /clear — trois sorties de crise

Critère	/compact (manuel)	Auto-compaction	/clear
Déclenchement	choisi (le bon moment)	au seuil configuré	choisi
Coût immédiat	~1 requête de la taille de l’historique	idem, au pire moment	aucun
Ce qui survit	un résumé orientable	un résumé générique	rien
Continuité du travail	oui, avec perte de détail	oui, avec perte de détail	non
Bon usage	pit-stop entre deux phases	filet de sécurité	changement de tâche

Config — régler le seuil d’auto-compaction

# Le POURQUOI : compacter à un moment choisi plutôt que subi.
# Régler le seuil depuis la session (persistant) :
/autocompact 160000

# Ou pour un seul lancement, sans toucher au réglage sauvegardé :
claude --autocompact 160000

# Ou en environnement scripté/CI — cette variable prime sur tout le reste :
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=160000

Piège courant : « /compact vide le contexte » est inexact — c’est /clear qui vide. /compact remplace l’historique par un résumé : la session conserve une mémoire, mais une mémoire reconstruite et avec perte, et l’opération elle-même coûte une requête de la taille de tout l’historique plus un cache à rebâtir. Compacter par réflexe toutes les dix minutes cumule les coûts sans bénéfice ; compacter (ou nettoyer) entre deux phases de travail, avec des consignes, est le geste juste.

---

Fil rouge — Reduce ou Delegate ?

Ce chapitre est du Reduce, mais un Reduce d’un genre nouveau : curatif et non préventif. Les chapitres 4, 5 et 9 réduisaient ce qui entre (MCP à la demande, CLAUDE.md sobre, priming) ; la compaction réduit ce qui s’est déjà accumulé — ~140 000 tokens d’historique condensés en ~2 500, soit ~61 % d’une fenêtre de 200k rendus en une opération. Rien n’est délégué : le résumé est rédigé dans la session elle-même, et son coût (une requête de la taille de l’historique, un cache invalidé) se paie dans la fenêtre principale. L’attention restaurée est réelle — l’agent repart à ~9 % d’occupation, dense et précis — mais elle s’achète contre du détail perdu : le Reduce préventif des chapitres précédents reste la stratégie première, la compaction le filet quand la session doit durer malgré tout.

---

---

Travaux pratiques

À chaque leçon, un petit artefact à déposer dans ton .claude/ — commande, sous-agent, hook, mémo… — pour te bâtir, au fil du livre, une boîte à outils de context engineering réutilisable.

Un bloc CLAUDE.md maison — # Compact instructions

La qualité d’une compaction, c’est la qualité de son secrétaire de séance : sans consignes, le résumé est générique et perd souvent ce qui aurait servi la suite. Ce bloc, à coller à la fin du CLAUDE.md du projet, fixe une fois pour toutes ce que chaque compaction — manuelle ou automatique — doit préserver et ce qu’elle peut jeter. C’est du Reduce appliqué au Reduce lui-même : on réduit l’historique, mais en gardant exactement les ~2 000 tokens qui portent l’état du travail.

# Compact instructions

Lors d'une compaction, préserver en priorité, dans cet ordre :

1. L'objectif de la session, en une phrase.
2. Les décisions prises et leur POURQUOI (choix d'architecture, pistes écartées et
   la raison de l'abandon — pour ne pas les re-proposer).
3. La liste des fichiers modifiés, avec leur chemin exact.
4. L'état courant : dernière action réussie, build vert ou rouge, prochaine étape prévue.
5. Les commandes de vérification utilisées (build, tests) telles quelles.

Peut être résumé agressivement ou omis :

- Le contenu intégral des fichiers lus (le disque fait foi : ils seront relus au besoin).
- Les sorties de build et de tests des erreurs déjà corrigées.
- Les allers-retours de mise au point qui n'ont pas abouti à une décision.

Une fois le bloc en place, chaque /compact (et chaque auto-compaction) produit un résumé structuré autour de l’état utile identifié dans la fiche — ~80 tokens permanents dans le CLAUDE.md, contre des compactions qui rendent ~60 % de fenêtre sans perdre les décisions ni les chemins de fichiers : le détail jetable part, l’état mental reste.