Claude Code : réduire le contexte et les coûts

Comment éviter qu’une longue session Claude Code ralentisse et devienne coûteuse

Une longue session Claude Code ralentit et devient coûteuse, car chaque tour renvoie l’intégralité du contexte, qui ne cesse de s’allonger. La solution consiste à appliquer une hygiène stricte, dans un ordre précis. Exécutez /context pour voir ce qui remplit la fenêtre de contexte, supprimez les éléments facturés à chaque requête, puis utilisez /clear entre deux tâches sans rapport et /compact avec une instruction au sein d’une même tâche longue. Travaillez par séquences continues, car un cache de prompt froid transforme une lecture peu coûteuse en une réécriture complète de tout ce que vous avez indiqué.

La raison pour laquelle le compteur avance est expliquée dans le compteur de tokens utilisé par une session d’agent.

Lisez le contexte avant toute modification

Ne devinez pas ce qui remplit 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 la croissance excessive de la mémoire ; all développe la ventilation par élément en mode plein écran. Interprétez le résultat comme cinq compartiments.

• L’invite système. Les instructions du propre harness de Claude Code. Elles restent fixes pendant la session.
• Les définitions des outils. Le schéma de chaque outil que l’agent peut appeler, y compris celui de chaque serveur MCP (Model Context Protocol) connecté.
• Les fichiers mémoire. CLAUDE.md et la mémoire automatique, chargés au début de la session.
• Les fichiers et les résultats des outils. Chaque fichier lu et tout ce que vos commandes renvoient.
• L’historique des messages. Vos tours et ses réponses.

Les trois premiers représentent un coût fixe, payé à chaque requête pendant toute la durée de la session. Les deux derniers augmentent. Réduisez le coût fixe une fois, au début, puis gérez en continu la partie croissante.

Deux chaînes 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 correspond à une limite stricte : la requête est refusée et l’erreur de l’API (application programming interface) correspondante est Prompt is too long. La seconde correspond à une fenêtre de compaction, qui peut être inférieure à la fenêtre de contexte réelle sur un modèle de 1 million de tokens. Les requêtes continuent donc de fonctionner au-delà de cette limite ; il s’agit d’un avertissement, pas d’un refus.

Avec un forfait payant, /usage ajoute l’autre moitié en signalant des comportements comme un contexte long ou des cache misses, et en attribuant l’utilisation récente aux skills, subagents et serveurs MCP concernés. S’il indique que le quota est déjà épuisé, la fenêtre de limites que vous attendez détermine si la réduction du contexte vous aidera maintenant ou si vous devez emprunter une autre voie pour reprendre le travail.

CLAUDE.md est une charge permanente : gardez-le concis

Votre CLAUDE.md est chargé au début de la session et reste dans le contexte. S’il contient une procédure de déploiement détaillée, ces tokens restent présents pendant que vous corrigez une faute dans un fichier de test. Les recommandations d’Anthropic sont de n’inclure que l’essentiel et de limiter le fichier à 200 lignes.

Déplacez les procédures dans des 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. Après une compaction, les skills disposent de leur propre budget : leur contenu est réinjecté, dans la limite de 5,000 tokens par skill et de 25,000 au total, les plus anciens étant supprimés en premier. La troncature conserve le début du fichier : placez donc les instructions les plus importantes près du début de SKILL.md.

Ce qui subsiste après une compaction détermine où une instruction doit être placée.

• Le prompt système et le format de sortie restent inchangés, car ils ne font pas partie de l’historique des messages.
• Le CLAUDE.md à la racine du projet, les règles non limitées à un périmètre et la mémoire automatique sont réinjectés depuis le disque.
• Une règle avec des métadonnées paths: est perdue jusqu’à la nouvelle lecture d’un fichier correspondant.
• Un CLAUDE.md imbriqué dans un sous-répertoire est perdu jusqu’à la lecture d’un fichier dans ce sous-répertoire.
• Les hooks continuent de s’exécuter, car un hook s’exécute comme du code ; seul le contexte qu’un hook a ajouté précédemment est résumé avec le reste de la conversation.

Une règle dont vous dépendez doit donc se trouver dans le CLAUDE.md à la racine du projet : Claude Code supprime d’abord les sorties d’outils les plus anciennes, puis effectue un résumé ; les instructions du début de la conversation peuvent donc être perdues. Modifiez la mémoire avec /memory. Claude Code conserve la copie chargée au début de la session : une réduction effectuée en cours de session conserve le prompt cache et ne s’applique qu’au prochain /clear, /compact ou redémarrage. La perte du contexte n’est qu’une des raisons pour lesquelles une règle cesse d’être suivie ; lorsque la règle est clairement toujours présente dans le contexte mais reste ignorée, analysez les autres causes avant de la réécrire.

Vider entre les tâches, compacter dans une même tâche

Ces deux opérations semblent interchangeables, mais leur coût est très différent.

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

/compact [instructions] libère de l’espace dans le contexte tout en poursuivant la même conversation : il résume l’historique jusque-là et le remplace par ce résumé. Utilisez-le au sein d’une longue tâche, lorsque vous devez conserver la continuité.

Donnez toujours une instruction à /compact. Un simple /compact résume l’historique avec une invite par défaut qui ne sait pas quelle partie du travail vous devez encore conserver. Une commande avec instruction la préserve :

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

Si vous compactez toujours pour la même raison, ajoutez une instruction permanente dans le CLAUDE.md de votre projet, sous un titre # Compact instructions. Dans une nouvelle session, /compact affiche Not enough messages to compact., ce qui signifie que la conversation ne contient pas assez de tours pour être résumée ; cela peut arriver même avec un contexte plein, lorsqu’un seul collage volumineux l’a rempli.

Deux coûts sont souvent confondus ici. La requête de résumé partage votre préfixe. Elle lit donc le cache existant au lieu de retraiter l’historique, et l’essentiel de son temps est consacré à la génération du résumé. Compacter un contexte volumineux reste une requête volumineuse, car la conversation résumée constitue son entrée. Le tour qui suit la compaction n’est pas la partie lente : il reconstruit le cache pour une invite beaucoup plus courte.

Deux commandes moins coûteuses existent. /rewind restaure le code et la conversation à un point de contrôle ; pour un chemin que vous voulez entièrement abandonner, cette commande est préférable à la compaction, car elle tronque la conversation jusqu’à un préfixe déjà mis en cache. /recap ajoute un résumé comme sortie de commande au lieu de remplacer l’historique. Le préfixe mis en cache reste donc intact.

Lorsque la compaction automatique se déclenche plusieurs fois de suite, le message suivant s’affiche :

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

La compaction a réussi, mais un fichier ou une sortie d’outil a rempli à nouveau la fenêtre plusieurs fois de suite. Claude Code a donc cessé de réessayer. Pour récupérer, lisez le fichier volumineux par plages de lignes, exécutez /compact avec un focus qui exclut la sortie volumineuse, déplacez ce travail vers un sous-agent, ou utilisez /clear si la conversation précédente est terminée.

Les serveurs MCP représentent un coût fixe

Chaque serveur MCP que vous connectez augmente le coût de chaque requête pendant toute la session. Vous le payez même si vous ne l’appelez pas.

Claude Code atténue ce problème. Par défaut, les définitions des outils MCP sont chargées à la demande. Seuls les noms des outils sont donc placés dans le contexte, jusqu’à ce que Claude utilise un outil précis. Exécutez /context pour voir le coût réel de vos serveurs, et /mcp disable <name> pour supprimer celui que vous n’utiliserez pas aujourd’hui. Si vous exécutez vos propres serveurs MCP sur un VPS, la même contrainte détermine le nombre d’outils qu’un serveur doit exposer.

Faites-le au début d’une session. Tant que les définitions restent chargées à la demande, la connexion ou la déconnexion d’un serveur ajoute seulement des éléments à la conversation, et le cache est conservé. En revanche, lorsque les définitions sont chargées dans le préfixe parce que la recherche d’outils est désactivée, indisponible ou inférieure à son seuil auto, la même modification oblige la requête suivante à tout relire.

Filtrez la sortie verbeuse des outils avant son ajout au contexte

Le résultat d’un outil devient une entrée, puis est renvoyé à chaque tour suivant. Une exécution de test qui produit 20,000 tokens de sortie ne représente pas un coût ponctuel : vous le payez à nouveau à chaque tour jusqu’à ce que cette sortie quitte la fenêtre de contexte.

Filtrez à la source. Un hook qui réduit une exécution de test à ses échecs avant que Claude ne la reçoive transforme cette sortie interminable en quelques centaines de tokens, lors de ce tour et à chaque renvoi :

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

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

Cadrer ce que l’agent lit et déléguer les tâches verbeuses

Un prompt qui nomme le fichier et le symptôme lit ce fichier. Une demande ouverte visant à nettoyer le projet lit tous les éléments que l’agent juge pertinents, et chacune de ces lectures reste dans le contexte.

Déléguez les tâches verbeuses à un sous-agent. Les exécutions de tests et le traitement des journaux consomment tous deux une part réelle du contexte ; un sous-agent conserve cette sortie dans sa propre fenêtre et ne renvoie qu’un résumé. En contrepartie, un sous-agent construit son propre cache, sans aucun hit lors du premier appel, et utilise la durée de vie du cache de cinq minutes, même avec un abonnement. La délégation protège efficacement votre contexte principal. Elle ne réduit pas toujours le nombre total de tokens.

L’horloge du cache : travaillez par sessions continues

Le prompt caching rend les renvois abordables. L’écriture du préfixe coûte 1.25x le tarif d’entrée de base, ou 2x avec la durée de vie d’une heure. La relecture coûte 0.1x sur Haiku 5.5, 0.05x sur Opus 5.5 et Sonnet 5.5 ($0.20 et $0.10 par million de tokens), et 0.025x sur Fable 5.1 ($0.25 par million). Chaque utilisation actualise l’entrée sans coût supplémentaire : l’horloge repart donc de la dernière utilisation. Ces multiplicateurs indiquent la structure de la facture, mais pas son montant. Associez-les à ce que coûte réellement un million de tokens pour convertir une fenêtre de contexte complète en montant en dollars.

La durée de vie dépend de votre méthode d’authentification. C’est pourquoi l’affirmation générale « votre cache expire après cinq minutes » est incorrecte.

• Avec un abonnement Claude, Claude Code demande automatiquement la durée de vie d’une heure.
• Une fois la limite de votre forfait dépassée et les crédits d’utilisation consommés, cette utilisation vous est facturée : la durée de vie repasse donc à cinq minutes.
• Avec une clé API ou un cloud provider, elle reste fixée à cinq minutes. Définir promptCacheTtl sur 1h, ou sur ENABLE_PROMPT_CACHING_1H=1, active la durée de vie d’une heure. FORCE_PROMPT_CACHING_5M=1 la ramène à cinq minutes.

Le conseil concernant le rythme reste le même : travaillez par sessions continues. Une période d’inactivité qui dépasse la durée de vie oblige votre prochaine requête à réécrire tout le préfixe accumulé. Une session Claude Code détachée dans tmux ne coûte rien pendant son inactivité. En revanche, cette période d’inactivité fait perdre le cache chaud.

Certaines actions suppriment le cache alors que vous travaillez encore : changer de modèle, modifier le niveau d’effort sur les anciens modèles, activer le fast mode, connecter ou déconnecter un serveur MCP, refuser un outil complet lors du chargement initial des définitions d’outils, activer ou désactiver un plugin qui ajoute des outils, compacter le contexte, supprimer d’anciennes images lorsqu’une conversation en contient trop, et mettre à niveau Claude Code. Sur Opus 5.5, Sonnet 5.5, Haiku 5.5 et Fable 5.1, avec une clé API ou un abonnement, modifier le niveau d’effort conserve désormais le cache. /model est la surprise la plus fréquente, car chaque modèle possède son propre cache. La requête suivante relit donc tout l’historique sans aucun cache hit, même si le contenu est identique. Cette relecture est facturée aux tarifs du modèle cible comme une nouvelle écriture du cache. Ainsi, passer à Fable au milieu d’une session facture tout l’historique accumulé aux tarifs publiés de Fable pour l’écriture du cache : $12.50 par million de tokens avec une durée de vie de cinq minutes, ou $20 avec une durée de vie d’une heure. Le tarif est identique sur Fable 5 et Fable 5.1.

Modifier des fichiers, modifier CLAUDE.md, invoquer des skills et des commandes, exécuter /recap, revenir en arrière et lancer un subagent conservent le cache. Celui-ci est limité à une machine et à un répertoire. Deux sessions dans des répertoires différents n’utilisent donc pas le cache de l’autre. Cette portée dépend du CLI et non de votre compte. Rien ne se transfère donc vers l’application de bureau Claude, qui est sous Linux une installation beta distincte du CLI.

Pour vérifier que le caching fonctionne, consultez current_usage. cache_creation_input_tokens a été écrit au tarif d’écriture du cache. cache_read_input_tokens a été servi au tarif de lecture du cache du modèle, compris entre 2.5 % et 10 % du tarif d’entrée standard selon le modèle. Un ratio élevé entre les lectures et les créations est normal. Si les créations restent élevées à chaque tour, cela signifie qu’un élément de votre préfixe change continuellement.

Une fenêtre de contexte plus grande résout-elle le problème ?

En partie. Tous les modèles actuels (Fable 5.1, Opus 5.5, Sonnet 5.5 et Haiku 5.5) utilisent une fenêtre de contexte de 1 million de tokens, et la compaction fonctionne de la même manière avec cette limite plus élevée. Le modèle économique ne change pas, car l’intégralité du prompt est toujours renvoyée et facturée à chaque tour. Une fenêtre plus grande détermine le moment où vous devez intervenir ; une bonne hygiène détermine le coût. Si le problème est le montant facturé plutôt que la limite, le forfait Claude adapté à votre façon de travailler détermine si vous dépensez des dollars ou votre quota de forfait.

La modification du contexte et la compaction dans l’API sont deux opérations différentes

Si vous développez votre propre agent avec l’API Messages, aucune commande slash n’existe et vous devez implémenter cette fonction vous-même. Prévoyez ce travail dès le départ, car les quotas gratuits de l’API ne couvriront pas vos tokens. Les nouveaux utilisateurs reçoivent un petit montant de crédits gratuits pour tester l’API. Le quota permanent indiqué par Anthropic (50 heures gratuites par jour et par organisation sur la page des tarifs, 1 550 par mois dans la documentation) couvre le temps d’utilisation du conteneur d’exécution du code, facturé séparément des tokens. À chaque tour, l’historique non tronqué est renvoyé et facturé en totalité : au tarif de lecture du cache lorsque le préfixe est en cache, et au tarif d’entrée normal ou avec une majoration d’écriture du cache lorsqu’il ne l’est pas. Le fournisseur choisi détermine ce calcul avant toute troncation. Si votre choix n’est pas encore arrêté, calculez le coût de la même charge de travail sur les deux API au lieu de comparer les tarifs affichés par token. Deux fonctions côté serveur remplissent ce rôle, mais ce ne sont pas les mêmes.

La modification du contexte efface sélectivement certains contenus de l’historique de la conversation à mesure qu’il s’allonge. Chaque résultat effacé est remplacé par un texte d’espace réservé afin que Claude sache qu’un élément a été supprimé. Cette fonction est en bêta : envoyez anthropic-beta: context-management-2025-06-27 et configurez les stratégies sous context_management.edits. clear_tool_uses_20250919 efface les résultats des outils, et clear_thinking_20251015 gère les blocs de raisonnement. Sa valeur trigger par défaut est de 100 000 tokens d’entrée, keep conserve les 3 dernières utilisations d’outils, et clear_tool_inputs vaut false. Les entrées sont donc conservées et seuls les résultats sont supprimés.

La compaction génère un résumé et remplace l’historique complet de la conversation par ce résumé. Elle existe sous deux formes bêta. La compaction par seuil s’exécute dans vos requêtes ordinaires : envoyez anthropic-beta: compact-2026-01-12 et utilisez le type de modification compact_20260112. Le seuil est par défaut {"type": "input_tokens", "value": 150000}, et sa valeur doit être d’au moins 50 000. La compaction à la demande laisse votre code décider du moment : envoyez anthropic-beta: compact-2026-09-04 avec un "compaction": {"type": "summarize"} de niveau supérieur, et la réponse contient uniquement le bloc de résumé. La présentation générale de la compaction d’Anthropic recommande d’utiliser la compaction à la demande partout où elle est disponible.

La compaction par seuil applique une règle de transmission qui peut discrètement 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 dans les requêtes suivantes ; l’API supprime alors tous les blocs de contenu qui le précèdent. En pratique, ajoutez l’intégralité de response.content, et pas seulement le texte. La compaction à la demande fonctionne à l’inverse : vous supprimez vous-même les messages résumés, placez le bloc renvoyé en premier dans messages, puis le renvoyez exactement tel qu’il a été retourné, signature comprise.

La documentation d’Anthropic présente la compaction côté serveur comme la stratégie principale de gestion du contexte dans les conversations longues, et la modification du contexte comme l’option offrant un contrôle plus précis sur les éléments effacés. Vérifiez d’abord la prise en charge par le modèle. Tous les modèles actuels prennent en charge les deux types de compaction, y compris Haiku 5.5 ; l’ancien modèle claude-haiku-4-5 ne les prend pas en charge, et chaque page consacrée à la compaction contient la liste à jour. Aucune de ces fonctions bêta ne pilote le /compact de Claude Code, que sa documentation décrit comme une requête de résumé distincte envoyée par le client avec votre historique.

FAQ

Pourquoi ma session Claude Code ralentit-elle et coûte-t-elle plus cher au fil du temps ?

Parce que toute la conversation est renvoyée à chaque tour. Ainsi, une question d’une ligne dans une session ouverte toute la journée contient toute la conversation de la journée. La mise en cache des prompts maintient ce coût à un niveau bas tant que le cache est disponible : une lecture coûte 0.1x du tarif d’entrée de base sur Haiku 5.5, 0.05x sur Opus 5.5 et Sonnet 5.5, et 0.025x sur Fable 5.1. Lorsqu’un tour ne trouve pas son contenu dans le cache, le même préfixe est réécrit au tarif de 1.25x, ou de 2x avec la durée de vie d’une heure. Exécutez /context pour voir ce qui remplit la fenêtre, puis consultez ce que vous facture 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. Il n’envoie aucune requête, ne coûte donc rien et constitue le bon choix entre deux tâches sans rapport. /compact conserve la même conversation et remplace l’historique par un résumé. C’est donc le bon choix au sein d’une même tâche longue. Indiquez-lui un objectif, comme dans /compact keep only the plan and the diff, car cette instruction détermine ce qui est conservé.

Comment voir ce qui consomme la fenêtre de contexte de Claude Code ?

Exécutez /context, ou /context all pour obtenir le détail complet par élément. La commande affiche le prompt système, les définitions des outils, les serveurs MCP, les fichiers de mémoire et l’historique sous forme de grille colorée. Elle propose aussi des suggestions concernant les outils qui consomment beaucoup de contexte et l’encombrement de la mémoire. Avec un forfait payant, /usage attribue également l’utilisation récente aux skills, aux sous-agents et aux serveurs MCP concernés.

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

Une fenêtre plus grande ne résout pas le problème. Elle en retarde seulement l’apparition. Tous les modèles actuels (Fable 5.1, Opus 5.5, Sonnet 5.5 et Haiku 5.5) utilisent une fenêtre de contexte de 1 million de tokens, et la compaction fonctionne de la même manière dans ce cas. À chaque tour, le prompt complet est toujours renvoyé et facturé. Une conversation de 400,000 tokens coûte donc cher, qu’elle tienne ou non dans la fenêtre.

Quelle est la différence entre la modification du contexte et la compaction dans l’API Claude ?

La modification du contexte efface sélectivement les anciens contenus, principalement les résultats des outils, et laisse à la place de chacun un texte indicatif afin que Claude sache qu’il a été supprimé. La compaction génère un résumé et remplace l’historique complet par celui-ci. La documentation d’Anthropic présente la compaction comme la stratégie principale pour les conversations longues et la modification du contexte comme l’option permettant un contrôle plus précis. Les deux fonctionnalités sont en version bêta et utilisent leurs propres en-têtes. Elles sont également distinctes de /compact dans Claude Code.