Optimiser le contexte Claude Code

Comment éviter qu'une session Claude Code prolongée ne devienne lente et coûteuse

Une session Claude Code prolongée devient lente et coûteuse car chaque tour renvoie l'intégralité du contexte, et ce contexte ne fait que croître. La solution consiste à appliquer une hygiène de travail dans un ordre précis. Exécutez /context pour identifier les éléments qui saturent la fenêtre, supprimez les éléments payés à chaque requête, puis utilisez /clear entre deux tâches sans rapport et /compact avec une instruction lors d'une tâche unique et longue. Travaillez par sessions continues, car un prompt cache qui expire transforme une lecture peu coûteuse en une réécriture complète de tout votre historique.

L'explication du fonctionnement de la consommation est disponible dans le compteur de tokens d'une session agent.

Lisez /context avant de modifier quoi que ce soit

Ne devinez pas le contenu de la fenêtre. Claude Code vous l'indiquera.

/context [all] affiche l'utilisation actuelle du contexte sous forme de grille colorée, avec des suggestions d'optimisation pour les outils gourmands en contexte et l'augmentation de la mémoire ; all permet de détailler chaque élément en mode plein écran. Interprétez le résultat comme cinq catégories.

• Le system prompt. Les instructions internes de Claude Code. Elles sont fixes pour la session.
• Tool definitions. Le schéma de chaque outil que l'agent peut appeler, incluant chaque serveur MCP (Model Context Protocol) connecté.
• Memory files. CLAUDE.md et la mémoire automatique, chargés au début de la session.
• Files and tool results. Chaque fichier lu et tout ce que vos commandes ont renvoyé.
• Message history. Vos messages et ses réponses.

Les trois premiers éléments constituent une charge fixe, appliquée à chaque requête pendant toute la session. Les deux derniers augmentent. Réduisez la charge fixe une seule fois, au début ; gérez la partie croissante en continu.

Deux chaînes de caractères indiquent que la fenêtre est pleine :

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

La première est une limite stricte et la requête est refusée ; l'erreur de l'API correspondante est Prompt is too long. La seconde est une fenêtre de compaction, qui peut être inférieure à la fenêtre de contexte réelle du modèle sur un modèle de 1 million de tokens. Les requêtes réussissent encore au-delà de celle-ci ; il s'agit donc d'un avertissement plutôt que d'un refus.

Sur un plan payant, /usage ajoute la seconde moitié, signalant des comportements tels que le contexte long ou les cache misses et attribuant l'utilisation récente aux skills, subagents et serveurs MCP individuels.

CLAUDE.md est une taxe permanente, gardez-le léger

Votre CLAUDE.md est chargé dans le contexte au début de la session et y reste. S'il contient une procédure de déploiement détaillée, ces tokens sont présents même pour corriger une faute de frappe dans un fichier de test. Les recommandations d'Anthropic consistent à n'inclure que l'essentiel et à maintenir le fichier sous les 200 lignes.

Déplacez les procédures dans les skills. Un skill n'est chargé que lorsqu'il est invoqué ; un workflow exécuté deux fois par semaine ne coûte donc rien les autres jours. Les skills possèdent leur propre budget après une compaction : les corps de texte sont réinjectés, avec une limite de 5 000 tokens par skill et 25 000 au total, les plus anciens étant supprimés en priorité. La troncature conserve le début du fichier ; placez donc les instructions les plus importantes en haut de SKILL.md.

Ce qui survit à une compaction détermine l'emplacement d'une instruction.

• Le system prompt et le style de sortie ne changent pas, car ils ne font pas partie de l'historique des messages.
• Le CLAUDE.md à la racine du projet, les règles non scopées et l'auto memory sont réinjectés depuis le disque.
• Une règle avec un frontmatter paths: est perdue jusqu'à ce qu'un fichier correspondant soit relu.
• Un CLAUDE.md imbriqué dans un sous-répertoire est perdu jusqu'à ce qu'un fichier de ce sous-répertoire soit relu.
• Les hooks ne sont pas affectés, car un hook s'exécute comme du code et n'entre jamais dans le contexte.

Ainsi, une règle dont vous dépendez doit se trouver dans le CLAUDE.md à la racine du projet : Claude Code efface d'abord les anciens outputs d'outils puis résume, donc les instructions du début de la conversation peuvent être perdues. Éditez la mémoire avec /memory. Claude Code conserve la copie chargée au début de la session ; un élagage en cours de session préserve le prompt cache et ne s'applique qu'au prochain /clear, /compact, ou redémarrage.

/clear entre les tâches, /compact au sein d'une même tâche

Ces deux commandes semblent interchangeables mais leurs coûts diffèrent largement.

/clear [name] démarre une nouvelle conversation avec un contexte vide. Elle n'envoie aucune requête, donc elle ne coûte rien. Passez un nom pour étiqueter la conversation précédente dans le sélecteur /resume ; /reset et /new sont des alias. Utilisez cette commande dès que vous passez à une tâche sans rapport, car sinon l'ancienne tâche sera renvoyée et facturée à nouveau lors de chaque message de la nouvelle.

/compact [instructions] libère le contexte tout en continuant la même conversation : elle résume l'historique actuel et le remplace. Utilisez cette commande lors d'une tâche longue où vous avez besoin de continuité.

Donnez toujours une instruction à /compact. Une commande /compact seule utilise un prompt par défaut qui ne sait pas quelle partie du travail vous devez encore effectuer. Une commande avec instruction conserve le contexte nécessaire :

/compact focus on the auth bug fix
/compact keep only the plan and the diff

Si vous effectuez un compactage pour la même raison à chaque fois, placez une instruction permanente dans le CLAUDE.md de votre projet sous un en-tête # Compact instructions. Dans une nouvelle session, /compact affiche Not enough messages to compact., ce qui signifie qu'il n'y a pas encore d'historique.

Deux types de coûts sont souvent confondus ici. La requête de résumé partage votre prefixe, elle lit donc le cache existant au lieu de retraiter l'historique, et la majeure partie du temps est consacrée à la génération du résumé. Compacter un contexte large reste une requête volumineuse, car la conversation résumée constitue l'input. Le tour suivant le compactage n'est pas l'étape lente : il reconstruit le cache pour un prompt beaucoup plus court.

Deux commandes moins coûteuses existent. /rewind [description] effectue un rollback du code et de la conversation vers un checkpoint ; pour un chemin que vous souhaitez abandonner totalement, elle est préférable au compactage car elle tronque l'historique jusqu'à un prefixe déjà mis en cache. /recap ajoute un résumé comme résultat de la commande au lieu de remplacer l'historique, ce qui laisse le prefixe mis en cache intact.

L'exécution automatique répétée du compactage affiche ceci :

Autocompact is thrashing: the context refilled to the limit...

Le compactage a réussi, mais la sortie d'un fichier ou d'un outil a rempli la fenêtre plusieurs fois de suite, Claude Code a donc arrêté de réessayer. Pour récupérer, lisez le fichier volumineux par plages de lignes, exécutez /compact avec un focus qui ignore la sortie volumineuse, déléguez ce travail à un subagent, ou utilisez /clear si la conversation précédente est terminée.

Les serveurs MCP génèrent un overhead fixe

Chaque serveur MCP connecté augmente la taille de chaque requête pour toute la session. La consommation de tokens s'applique même si vous n'appelez pas l'outil.

Claude Code atténue ce problème. Par défaut, les définitions des outils MCP sont différées ; seuls les noms des outils sont inclus dans le contexte jusqu'à ce que Claude utilise un outil spécifique. Utilisez /context pour voir le coût réel de vos serveurs, et /mcp disable <name> pour supprimer un serveur inutile aujourd'hui. Si vous exécutez vos propres serveurs MCP sur un VPS, la même logique limite le nombre d'outils qu'un serveur doit exposer.

Effectuez cette opération au début d'une session. Bien que les définitions restent différées, la connexion ou la déconnexion d'un serveur s'ajoute uniquement à la conversation, et le cache est conservé. En revanche, si les définitions sont chargées dans le prefix (parce que la recherche d'outils est désactivée ou qu'un serveur est exempté de déferrement), ce changement force la relecture de l'intégralité du contenu lors de la requête suivante.

Filtrer la sortie verbeuse d'un outil avant l'envoi au contexte

Le résultat d'un outil est une entrée (input), et cet input est renvoyé à chaque nouveau tour. Un test générant 20 000 tokens de sortie n'est pas un coût unique : vous payez à nouveau pour ces tokens à chaque tour jusqu'à ce qu'ils sortent de la fenêtre de contexte.

Filtrez à la source. Un hook qui réduit le résultat d'un test à ses seules erreurs avant que Claude ne le reçoive transforme ce mur de texte en quelques centaines de tokens, pour ce tour et pour chaque renvoi ultérieur :

npm test 2>&1 | grep -E "FAIL|Error:" | head -40

Les hooks n'entrent jamais dans le contexte car ils s'exécutent sous forme de code. Appliquez cette méthode pour tout outil dont la sortie dépasse la taille d'un écran. La même logique s'applique à un fichier de 3 000 lignes : demandez uniquement la plage de lignes nécessaire, car le fichier complet reste dans la fenêtre de contexte une fois reçu.

Définissez le périmètre de lecture de l'agent et déléguez les tâches verbeuses

Un prompt qui nomme un fichier permet à l'agent de lire ce fichier. Une requête ouverte pour organiser le projet permet à l'agent de lire tout ce qu'il juge pertinent, et chaque lecture reste dans la fenêtre de contexte.

Déléguez les tâches verbeuses à un subagent. L'exécution des tests et le traitement des logs consomment tous deux du contexte ; un subagent conserve ces sorties dans sa propre fenêtre et ne renvoie qu'un résumé. Le compromis : un subagent construit son propre cache sans aucun hit lors du premier appel, et utilise une durée de vie de cache de cinq minutes, même avec un abonnement. La délégation protège efficacement votre contexte principal. Elle ne réduit pas systématiquement le nombre total de tokens.

L'horloge du cache : travaillez par sessions

Le prompt caching rend le renvoi abordable : le coût de lecture du prefix est de 0,1x le tarif d'input de base, contre 1,25x pour l'écriture, ou 2x pour une durée de vie d'une heure. Chaque utilisation rafraîchit l'entrée sans coût supplémentaire ; le délai commence donc à partir de la dernière utilisation.

La durée de vie obtenue dépend de votre mode d'authentification. Dire simplement que « votre cache expire après cinq minutes » est donc incorrect.

• Avec un abonnement Claude, Claude Code demande automatiquement une durée de vie d'une heure.
• Une fois votre limite de forfait dépassée et l'utilisation de crédits de consommation activée, vous êtes facturé pour cet usage ; la durée passe alors à cinq minutes.
• Avec une clé API ou un fournisseur cloud, la durée reste de cinq minutes. ENABLE_PROMPT_CACHING_1H=1 permet d'utiliser la durée d'une heure, et FORCE_PROMPT_CACHING_5M=1 la force à revenir à cinq minutes.

Le conseil de rythme est identique dans les deux cas : travaillez par sessions continues. Un intervalle d'inactivité dépassant la durée de vie force la réécriture de tout le prefix accumulé lors de votre prochain tour. Une session Claude Code détachée dans tmux ne coûte rien pendant l'inactivité, mais l'inactivité fait perdre le cache chaud.

Certaines actions suppriment le cache pendant que vous travaillez : changer de modèle, modifier le niveau d'effort, activer le mode fast, connecter ou déconnecter un serveur MCP, activer ou désactiver un plugin, refuser un outil complet, compacter ou mettre à jour Claude Code. /model est la surprise habituelle, car chaque modèle possède son propre cache ; la requête suivante lit donc l'historique complet sans aucun cache hit, même si le contenu est identique.

L'édition de fichiers, l'édition de CLAUDE.md, l'invocation de skills et de commandes, l'exécution de /recap, le rewind et le lancement d'un subagent conservent le cache. Le cache est limité à une machine et un répertoire ; deux sessions dans des répertoires différents ne partagent pas leur cache.

Pour vérifier si le caching fonctionne, lisez current_usage. cache_creation_input_tokens a été écrit au tarif d'écriture du cache ; cache_read_input_tokens a été servi à environ un dixième du tarif d'input standard. Un ratio élevé entre lecture et création est un signe de bon fonctionnement. Si le taux de création reste élevé d'un tour à l'autre, un élément de votre prefix change continuellement.

Un contexte plus large résout-il ce problème ?

Partiellement. Plusieurs modèles actuels supportent une fenêtre de contexte de 1 million de tokens, et la compaction fonctionne de la même manière à cette limite élevée. L'aspect économique ne change pas, car le prompt complet est toujours renvoyé et toujours facturé à chaque tour. Une fenêtre plus large détermine le moment où vous êtes contraint d'agir ; l'hygiène détermine le coût. Si le problème est la facture plutôt que la limite, quel plan Claude correspond à votre flux de travail détermine si vous dépensez de l'argent ou votre quota de forfait.

L'édition de contexte et la compaction dans l'API sont deux fonctions distinctes

Si vous développez votre propre agent via l'API Messages, les slash commands n'existent pas et vous devez les implémenter vous-même. Deux fonctionnalités côté serveur remplissent ce rôle, et elles sont différentes.

L'édition de contexte (context editing) supprime sélectivement certains contenus de l'historique de conversation au fur et à mesure de sa croissance. Elle remplace chaque élément supprimé par un texte de substitution pour que Claude sache qu'une donnée a été retirée. Cette fonction est en bêta : envoyez anthropic-beta: context-management-2025-06-27 et configurez les stratégies via context_management.edits. clear_tool_uses_20250919 supprime les résultats des outils, et clear_thinking_20251015 gère les blocs de réflexion (thinking blocks). Sa limite trigger est de 100 000 tokens en entrée, keep est de 3 derniers usages d'outils, et clear_tool_inputs est de false, ce qui permet de conserver les inputs et de ne supprimer que les résultats.

La compaction génère un résumé et remplace l'intégralité de l'historique de conversation par celui-ci. Cette fonction est également en bêta : envoyez anthropic-beta: compact-2026-01-12 et utilisez le type d'édition compact_20260112. Le déclencheur est réglé par défaut sur {"type": "input_tokens", "value": 150000}, et la valeur doit être d'au moins 50 000.

La compaction possède une règle de transfert qui peut casser les agents. La réponse commence par un bloc de contenu compaction contenant le résumé, suivi du bloc de texte normal. Vous devez renvoyer ce bloc lors des requêtes suivantes, sinon l'API supprimera tous les blocs de contenu précédents. En pratique : ajoutez l'intégralité de response.content, et pas seulement le texte.

La documentation d'Anthropic définit la compaction côté serveur comme la stratégie principale pour gérer le contexte dans les conversations longues, et l'édition de contexte comme l'option permettant un contrôle plus précis sur les éléments supprimés. Vérifiez d'abord la compatibilité du modèle. Les modèles Opus, Sonnet et Fable actuels supportent la compaction ; claude-haiku-4-5 ne la supporte pas. La page dédiée à la compaction contient la liste actualisée. Aucune de ces deux fonctions bêta ne pilote le /compact de Claude Code, que sa documentation décrit comme une requête de résumé unique envoyée par le client.

FAQ

Pourquoi ma session Claude Code devient-elle plus lente et plus coûteuse au fil du temps ?

La conversation entière est renvoyée à chaque tour. Une question d'une ligne dans une session ouverte toute la journée inclut donc tout l'historique de la journée. Le prompt caching réduit les coûts tant que le cache est chaud, à 0,1x le tarif d'entrée de base pour une lecture. Si un tour ne trouve pas le cache, le même préfixe est renvoyé à 1,25x. Exécutez /context pour voir ce qui remplit la fenêtre, et consultez ce qui est facturé pour une session Claude Code pour comprendre le mécanisme.

Quelle est la différence entre /clear et /compact dans Claude Code ?

/clear démarre une nouvelle conversation avec un contexte vide. Aucune requête n'est envoyée, donc cela ne coûte rien ; c'est le bon choix pour des tâches sans rapport. /compact conserve la même conversation mais remplace l'historique par un résumé ; c'est le bon choix pour une tâche unique et longue. Donnez-lui une instruction précise, comme dans /compact keep only the plan and the diff, car l'instruction détermine ce qui est conservé.

Comment voir ce qui utilise ma fenêtre de contexte Claude Code ?

Exécutez /context, ou /context all pour une décomposition complète par élément. Cela affiche le system prompt, les définitions de tools, les serveurs MCP, les fichiers de mémoire et l'historique sous forme de grille colorée. Des suggestions sont fournies pour les tools trop lourds ou l'excès de mémoire. Sur un plan payant, /usage attribue également l'utilisation récente aux skills, subagents et serveurs MCP individuels.

Dois-je utiliser une fenêtre de contexte de 1 million de tokens au lieu de la compaction ?

Une fenêtre plus large retarde le problème au lieu de le résoudre. Plusieurs modèles actuels supportent 1 million de tokens, dont Opus 4.8 et Sonnet 5, et la compaction fonctionne de la même manière sur ces modèles. Chaque tour renvoie toujours le prompt complet et est donc toujours facturé ; une conversation de 400 000 tokens reste coûteuse, qu'elle tienne dans la fenêtre ou non.

Quelle est la différence entre le context editing et la compaction dans l'API Claude ?

Le context editing efface sélectivement le contenu ancien, principalement les résultats de tools, en laissant un texte de remplacement là où ils se trouvaient pour que Claude sache qu'ils ont été supprimés. La compaction génère un résumé et remplace l'historique complet par celui-ci. La documentation d'Anthropic considère la compaction comme la stratégie principale pour les conversations longues, et le context editing comme l'option de précision. Les deux sont en bêta avec leurs propres headers, et les deux sont distincts du /compact de Claude Code.