Contexte et coûts

Les quatre leviers de contexte

Le skill context-optimization de Pierre formalise quatre techniques pour étendre la capacité effective du contexte sans agrandir la fenêtre ni changer de modèle. Appliquez-les dans cet ordre :

1. Optimisation du cache KV : conservez un préfixe de prompt stable en haut (prompt système, règles, contexte fixe) afin que le modèle réutilise le cache au lieu de tout recalculer. Ne réordonnez pas ce qui ne change pas. Effet : plus rapide et moins coûteux.
2. Masquage des observations : compactez les sorties d'outils volumineuses. Après la lecture d'un fichier de 2000 lignes, vous n'avez plus besoin des 2000 lignes brutes dans le contexte : gardez le résultat utile, masquez le reste.
3. Compaction : quand l'utilisation dépasse environ 70 %, résumer l'ancien contexte (c'est ce que fait /compact). Conservez la substance, éliminez le verbatim.
4. Partitionnement du contexte : déplacez le travail volumineux vers des sous-agents à contexte isolé (module 5). L'agent principal ne voit que les conclusions.

Résultat combiné : vous pouvez soutenir des sessions beaucoup plus longues et plus complexes sans dégrader la qualité ni exploser les coûts. "Plus de capacité" ne vient pas d'une fenêtre plus grande, mais d'une meilleure hygiène du contexte.

Quota, débit et alternance de modèles

Le coût en argent n'est pas le seul plafond. Il y a aussi le débit : l'organisation de Pierre est plafonnée à 4000 tokens de sortie par minute sur Opus. Les appels Claude sont gratuits dans son environnement, mais ce débit étouffe les workflows massivement parallèles ou à forte charge de réflexion, qui déclenchent des erreurs 429 (rate limit).

Les contremesures concrètes qu'il a codifiées :

• Réduire le parallélisme de lecture (un paramètre comme PLAN_READS=1 dans ses outils) pour ne pas saturer le débit.
• Baisser max_tokens et l'effort de réflexion lors du lancement de nombreux agents.
• Prévoir des relances avec backoff sur les 429.
• Alterner les modèles : Opus pour ce qui exige de la puissance (architecture, debug), Sonnet/Haiku pour les tâches répétitives déléguées. Cela répartit la charge et respecte le débit.

La règle économique de Pierre, contre-intuitive mais structurante : les appels Claude sont la ressource bon marché ; seuls les services externes payants comptent vraiment. On n'hésite donc pas à multiplier les lectures et les agents Claude pour la qualité, on surveille surtout le débit et les coûts externes.

Mise à jour, juillet 2026 : ce plafond appartient au passé. Le 4 juillet 2026, la limite de 4000 tokens par minute de cette étude de cas a été levée, et les plafonds mesurés sont passés à plusieurs millions de tokens de sortie par minute, avec un pool distinct par famille de modèles. La méthode ci-dessus (mesurer, alterner les modèles, sortir le travail de masse de votre pool principal) est ce qui survit : un quota est un fait avec une date de péremption, re-mesurez le vôtre (un appel de 1 token qui lit les en-têtes anthropic-ratelimit suffit) au lieu de faire confiance à de vieux chiffres.

Auditer votre budget de contexte

Chaque conversation avec Claude se déroule dans une fenêtre de contexte (le nombre total de tokens, approximativement des fragments de mots, qui tiennent dans une session). Claude Code affiche l'utilisation en temps réel dans sa barre de statut. Lorsque la fenêtre est pleine, le contenu le plus ancien est supprimé ou le modèle commence à se dégrader. Savoir ce qui consomme votre budget vous permet de réduire les bonnes choses.

Les plus grands consommateurs sont généralement : les lectures de fichiers volumineux, les historiques de conversation longs, les system prompts verbeux et les sorties d'outils qui déversent des réponses JSON entières. Utilisez /status dans une session Claude Code pour voir l'utilisation actuelle des tokens. L'option --verbose sur n'importe quelle commande claude affiche le nombre de tokens par tour.

Les principaux leviers pour réduire la consommation sont :

• Compacter la conversation : exécutez /compact dans Claude Code pour résumer l'historique sur place et récupérer des tokens.
• Limiter les lectures de fichiers : transmettez uniquement les lignes pertinentes plutôt que des fichiers entiers. Utilisez les paramètres offset et limit lors de la lecture.
• Réduire les sorties d'outils : si une recherche retourne des centaines de résultats, filtrez avant d'envoyer les résultats au modèle.
• Effacer et recommencer : exécutez /clear pour effacer entièrement la conversation lorsque vous démarrez une nouvelle tâche de zéro.

Du côté de l'API (quand vous appelez Claude par programmation), le prompt caching vous permet de marquer un bloc de contexte stable avec un point d'arrêt de cache. Anthropic stocke ce bloc côté serveur afin que vous ne payiez que 10 pourcent du coût d'entrée normal sur les accès au cache. Cela est particulièrement important pour les system prompts volumineux ou les documents de référence que vous envoyez à chaque appel.

/compact et /clear

Chaque message que vous envoyez et chaque réponse de Claude consomment une partie de la fenêtre de contexte (la quantité maximale de texte que Claude peut garder en mémoire à un instant donné). Lors d'une longue session de code, cette fenêtre se remplit rapidement. Claude Code vous propose deux commandes pour la gérer : /compact et /clear.

/compact résume la conversation en cours sous forme d'un court digest et remplace l'historique complet par ce résumé. Claude conserve une mémoire de travail de ce qui a été décidé, des fichiers modifiés et de l'objectif, mais les échanges bruts disparaissent. Utilisez /compact lorsque vous souhaitez continuer la même tâche sans perdre le fil.

/clear efface entièrement la conversation sans aucun résumé. Claude repart de zéro, comme si vous veniez d'ouvrir une nouvelle session. Utilisez /clear lorsque vous passez à une tâche sans rapport, que le contexte actuel est devenu erroné et induit Claude en erreur, ou que vous voulez simplement repartir sur une page blanche.

• /compact : conserve l'objectif, supprime le verbiage. Idéal pour les longues sessions de refactorisation.
• /clear : réinitialisation complète. Idéal entre des fonctionnalités ou des projets distincts.
• Aucune des deux commandes ne supprime vos fichiers. Elles n'affectent que ce dont Claude se souvient dans cette session.
• Après /compact, Claude peut vous demander de confirmer l'exactitude du résumé avant de continuer.

Le cache de prompt et le KV cache

Chaque fois que vous envoyez un message à Claude, le modèle traite l'intégralité de votre entrée depuis le début, jeton par jeton. C'est rapide pour les prompts courts, mais coûteux et lent lorsque vous répétez le même contexte volumineux (un prompt système, un long document, une grande base de code) sur de nombreux appels. Le cache de prompt résout ce problème en conservant la représentation calculée du contenu répété, afin qu'elle n'ait pas à être recalculée.

Le mécanisme sous-jacent est le KV cache (cache clé-valeur). Lors de l'inférence (l'acte de générer une réponse), le modèle construit un tableau de valeurs intermédiaires pour chaque jeton d'entrée. Normalement, ce tableau est supprimé après chaque appel. Lorsque le cache de prompt est activé, Anthropic maintient ce tableau en vie sur ses serveurs pendant une courte fenêtre, de sorte que l'appel suivant qui envoie le même préfixe peut ignorer entièrement le recalcul.

Points clés sur le comportement du cache :

• La fenêtre de cache est de 5 minutes. Si votre prochain appel API arrive dans les 5 minutes et commence par le même préfixe, vous payez le prix de lecture du cache, moins élevé (environ 10 pour cent du prix normal d'entrée pour Opus claude-opus-4-8 et Sonnet claude-sonnet-4-6).
• Le premier appel qui remplit le cache paie le prix d'entrée normal plus un petit supplément d'écriture du cache (environ 25 pour cent de plus), car le serveur doit stocker le résultat.
• Le préfixe mis en cache doit être identique au niveau de l'octet. Même un caractère changé invalide le cache pour cette position et tout ce qui suit.
• Vous marquez les blocs pouvant être mis en cache explicitement dans l'API en utilisant un champ cache_control avec "type": "ephemeral". Claude Code et les SDK Claude gèrent cela automatiquement pour les prompts système lorsque vous utilisez l'option --cache ou le comportement par défaut du SDK.

L'effet pratique : la latence diminue car le modèle ignore le traitement de milliers de jetons, et le coût baisse car les jetons en cache sont facturés au tarif de lecture. Pour un flux de travail qui envoie le même document de 20 000 jetons à Claude 50 fois au cours d'une session, le cache peut réduire le coût d'entrée de plus de 80 pour cent.

La Batch API pour le travail en masse

La Batch API est le système d'Anthropic permettant d'envoyer des centaines (ou des milliers) de requêtes en une seule fois plutôt que les unes après les autres. Chaque groupe de requêtes s'appelle un batch. Les résultats sont retournés de façon asynchrone : vous soumettez le travail, vous passez à autre chose, puis vous récupérez les résultats quand ils sont prêts (généralement en quelques minutes pour une centaine de requêtes).

Les deux principales raisons d'utiliser la Batch API sont le coût et le débit. Vous bénéficiez d'une remise de 50 pour cent sur tous les coûts en tokens par rapport à l'API standard (synchrone). Vous disposez également d'une limite de débit indépendante, ce qui signifie que vos traitements en batch ne concurrencent pas vos appels en temps réel pour le quota disponible.

Cas d'usage typiques où la Batch API est avantageuse :

• Générer un grand jeu de données synthétique (par exemple, des milliers de paires question-réponse pour affiner un modèle)
• Appliquer le même prompt à chaque ligne d'un tableur ou d'une base de données
• Traduction, classification ou résumé en masse d'une archive de documents
• Évaluations nocturnes qui notent les sorties du modèle par rapport à un jeu de tests

Les requêtes étant traitées en arrière-plan, la Batch API ne convient pas aux usages nécessitant une réponse immédiate. Pour le chat interactif ou l'assistance au code en temps réel, utilisez l'API standard ou Claude Code directement. En revanche, pour les travaux que vous planifieriez de toute façon la nuit, les économies sont automatiques.

Aiguiller le travail vers le modèle le moins coûteux

Chaque appel à l'API Claude a un coût et prend du temps. Les trois modèles disponibles ont des tarifs très différents : Haiku (claude-haiku-4-5) est le plus rapide et le moins cher, Sonnet (claude-sonnet-4-6) se situe au milieu, et Opus (claude-opus-4-8) est le plus performant et le plus coûteux. Choisir le bon modèle pour chaque tâche, ce qu'on appelle le routage de modèle, est l'un des leviers les plus efficaces pour maîtriser les coûts.

La règle est simple : adapter le modèle à la charge cognitive de la tâche. Réservez Opus aux travaux qui nécessitent vraiment un raisonnement profond, comme les décisions d'architecture, le débogage complexe ou l'évaluation de compromis délicats. Tout le reste devrait aller en priorité vers Sonnet ou Haiku.

Tâches qui conviennent bien à Sonnet ou Haiku :

• Traduire du texte ou reformater des données en volume
• Résumer de longs documents lorsque la précision n'est pas critique
• Classifier ou étiqueter des éléments dans un jeu de données
• Générer du code générique à partir d'un gabarit clair
• Répondre à des questions de type FAQ avec un ensemble de réponses fixes
• Fonctionner comme sous-agent dans un pipeline plus large (routage, extraction, filtrage)

Dans Claude Code, vous pouvez changer le modèle actif à tout moment avec /model. Dans les appels API, définissez le paramètre model par requête, de sorte que différentes étapes de votre workflow puissent appeler des modèles différents sans infrastructure supplémentaire.

Compter les tokens avant de dépenser

Chaque appel à l'API a un coût déterminé par le nombre de tokens (environ quatre caractères par token en anglais) traités. Avant de lancer un batch coûteux ou une longue boucle agentique, l'API Anthropic expose un point de terminaison dédié au comptage de tokens qui vous indique exactement combien de tokens d'entrée votre requête consommerait, sans générer de réponse et sans vous facturer.

Le point de terminaison est POST /v1/messages/count_tokens. Vous lui envoyez la même charge utile que vous enverriez à /v1/messages (identifiant de modèle, prompt système, tableau de messages, outils), mais l'API renvoie un seul objet JSON contenant input_tokens. Les tokens de sortie ne peuvent pas être comptés à l'avance car ils dépendent de ce que le modèle génère, mais vous pouvez les plafonner avec le paramètre max_tokens pour fixer un plafond absolu de coût.

Pour estimer le coût total, vous combinez les deux chiffres :

• Coût d'entrée : tokens comptés multipliés par le prix d'entrée du modèle par million de tokens.
• Coût de sortie : vos tokens de sortie attendus (ou maximaux) multipliés par le prix de sortie par million de tokens.
• Économies de cache : si vous activez le prompt caching (le champ cache_control), les tokens du prompt système répétés sont stockés et relus à environ 10 % du prix d'entrée normal, réduisant les coûts sur les workflows de longue durée.
• Remise batch : le Batch API (/v1/messages/batches) offre une remise de 50 % sur l'entrée et la sortie pour les charges de travail asynchrones.

Dans Claude Code (l'agent CLI de codage), vous pouvez voir les chiffres de tokens et de coût en direct dans la ligne de statut après chaque tour. Le flag --max-turns limite les boucles agentiques et joue le rôle de régulateur de coût. Pour des vérifications ponctuelles en dehors d'une boucle, faites passer votre prompt par la méthode client.messages.countTokens() du SDK avant de vous engager dans l'appel complet.

Limites de débit et gestion d'une erreur 429

Une limite de débit est un plafond que l'API impose sur la quantité que vous pouvez envoyer ou recevoir dans une fenêtre de temps donnée. Lorsque vous l'atteignez, le serveur renvoie le statut HTTP 429 Too Many Requests. Dans Claude Code, cela se manifeste par un message d'erreur qui met en pause la tâche en cours jusqu'à la réinitialisation de la fenêtre.

Anthropic applique plusieurs limites indépendantes simultanément : des tokens de sortie par minute, des requêtes par minute, et parfois une fenêtre glissante plus longue (5 heures ou 7 jours). Dépasser l'une d'elles déclenche une erreur 429. Les deux causes les plus fréquentes sont : l'envoi de nombreuses requêtes rapides dans une boucle automatisée, et l'utilisation d'un paramètre max_tokens élevé ou d'un effort de raisonnement étendu qui force le modèle à générer des réponses très longues.

La stratégie de récupération standard est le backoff exponentiel avec nouvelles tentatives : attendre un court intervalle (par exemple 2 secondes), réessayer une fois, attendre deux fois plus longtemps en cas de nouvel échec, et ainsi de suite. La plupart des SDK Anthropic officiels gèrent cela automatiquement avec des valeurs par défaut raisonnables. Dans Claude Code, l'interface en ligne de commande gère les nouvelles tentatives en interne ; vous n'avez pas à les coder vous-même.

Quand le backoff seul ne suffit pas, réduisez directement la pression sur la limite :

• Réduire max_tokens : plus le plafond que vous définissez est bas, moins le modèle est autorisé à émettre de tokens par appel, ce qui réduit votre consommation par minute.
• Réduire l'effort de raisonnement (le paramètre budget_tokens pour le raisonnement étendu) : un budget moindre signifie moins de tokens de raisonnement interne comptabilisés contre votre limite.
• Répartir le travail sur le Batch API : les requêtes par lots s'exécutent sur un quota séparé, plus élevé, et coûtent 50 pour cent moins cher.
• Passer à un modèle plus léger : claude-haiku-4-5 est plus rapide et moins coûteux par token que claude-opus-4-8, donc le même débit consomme bien moins d'unités de limite de débit.

Masquage des observations

Chaque appel d'outil effectué par Claude (lecture d'un fichier, exécution d'une commande shell, récupération d'une URL) verse sa sortie complète dans la fenêtre de contexte (le tampon glissant de texte visible par le modèle à un instant donné). Si cette sortie est volumineuse ou obsolète, elle grignote des tokens et peut perturber le modèle en présentant des faits périmés côté à côté de données récentes. Le masquage des observations consiste à cacher ou à élaguer cette sortie d'outil pour qu'elle n'occupe plus d'espace dans la fenêtre.

Claude Code expose cette fonctionnalité via le flag --hide-tool-output et via les paramètres au niveau du projet. Lorsqu'un résultat d'outil est masqué, le modèle sait toujours que l'outil a été appelé et s'il a réussi, mais le texte brut est retiré de la fenêtre active. Cela permet de garder la fenêtre légère lors de longues sessions.

Situations courantes où le masquage est utile :

• Un grep ou un find qui a retourné des centaines de lignes sur lesquelles vous avez déjà agi.
• Un test dont la trace d'erreur complète n'est plus pertinente une fois le correctif appliqué.
• Des lectures répétées du même fichier volumineux sur de nombreuses itérations.
• Des journaux d'installation de dépendances qui ne sont plus que du bruit une fois l'installation réussie.

La contrepartie est une réduction de l'ancrage (le fait que le modèle dispose de preuves concrètes pour raisonner). Ne masquez que les sorties dont vous êtes certain qu'elles ne sont plus nécessaires. Un masquage trop agressif peut amener le modèle à répéter du travail ou à faire des suppositions inappropriées.

Limites de débit 2026 : nouveaux paliers, nouveau tokenizer

Deux changements survenus mi-2026 vous obligent à refaire les calculs de coût que vous aviez peut-être établis plus tôt dans ce cours. Le premier est un changement de limite de débit (rate limit) : le 26 juin 2026, Anthropic a relevé les limites de débit de l'API Claude (les limites de débit sont les plafonds sur le nombre de requêtes ou de tokens par minute que votre clé API peut envoyer), si bien que Sonnet et Haiku correspondent désormais à Opus à chaque palier d'utilisation. En même temps, l'ancien système à quatre paliers a été consolidé en trois paliers d'utilisation (usage tiers, des niveaux de compte basés sur les dépenses qui débloquent des limites plus élevées à mesure que votre historique de facturation grandit) : Start, Build et Scale. Si votre planification de capacité précédente supposait une échelle à quatre paliers avec Sonnet ou Haiku plafonné en dessous d'Opus, cette hypothèse est désormais fausse.

Le second changement est plus fondamental : chaque modèle depuis Opus 4.7, y compris Fable 5 et Sonnet 5, utilise un nouveau tokenizer (un tokenizer est l'algorithme qui découpe le texte en unités numériques, les tokens, que le modèle facture et comptabilise réellement dans sa limite de contexte). Ce tokenizer produit environ 30 % de tokens en plus pour le même texte anglais que le tokenizer utilisé par les anciens modèles. Concrètement, une fenêtre de contexte d'un million de tokens sur ces modèles plus récents contient environ 555 000 mots, et non le nombre de mots plus élevé que l'on pourrait attendre d'une règle empirique naïve du type "1 token équivaut à environ 0,75 mot", héritée des modèles précédents.

Ce décalage de 30 % n'est pas cosmétique. Tout chiffre que vous aviez calibré sur un ancien modèle, estimations de coût par requête, réglages de max_tokens (le paramètre qui plafonne le nombre de tokens qu'une seule réponse peut générer), budgets de fenêtre de contexte pour la quantité d'historique que vous pouvez tenir dans un prompt, et seuils de tokens à partir desquels la mise en cache de prompt devient rentable, tout cela doit être ré-étalonné par rapport au nouveau tokenizer. Un prompt qui coûtait auparavant 0,02 $ en tokens d'entrée sur un ancien modèle peut coûter plus cher sur un nouveau modèle, alors même que vous avez envoyé exactement la même phrase en anglais, uniquement parce qu'elle se découpe désormais en davantage de fragments. La solution n'est pas non plus une règle générale du type "ajouter 30 %", car le ratio varie selon le contenu : le code, le texte non anglais et l'écriture technique dense se tokenisent différemment d'une prose anglaise ordinaire. La seule méthode fiable consiste à appeler le point de terminaison de comptage de tokens sur vos prompts réels, avec le modèle réel que vous comptez utiliser, et à lire le chiffre exact ainsi obtenu.

Plus tôt dans ce cours, l'étude de cas fil rouge portait sur une organisation réelle dont l'accès à l'API Claude était plafonné à 4 000 tokens de sortie par minute, une limite suffisamment serrée pour imposer un traitement par lots et une mise en file d'attente rigoureux, juste pour obtenir un débit utile. Ce plafond a été levé le 4 juillet 2026. Après la levée, les limites de pool mesurées pour cette organisation ont bondi à plusieurs millions de tokens par minute par famille de modèle, avec des pools distincts suivis par modèle plutôt qu'un pool partagé unique. La leçon n'est pas "les quotas finissent par être corrigés, arrêtez de vous inquiéter". La leçon est que les quotas sont des faits avec une date de péremption. Un chiffre mémorisé en mars peut être faux en juillet, dans un sens comme dans l'autre, plus serré ou plus généreux, et le code ou les modèles mentaux construits sur l'ancien chiffre se comporteront mal en silence une fois que la limite réelle aura changé sous leurs pieds.

La solution est peu coûteuse : un simple appel API avec max_tokens réglé sur 1 ne coûte presque rien et vous permet de lire directement les limites en direct. Les en-têtes de réponse, en particulier la famille d'en-têtes préfixés anthropic-ratelimit-*, indiquent vos plafonds actuels de requêtes par minute et de tokens par minute, ainsi que la part déjà consommée de chacun. Effectuez cette sonde avant de coder en dur une hypothèse de débit dans un pipeline, et relancez-la périodiquement, car l'organisation de cette étude de cas démontre que ces chiffres évoluent. Au-delà de la simple mesure, concevez votre workflow pour qu'atteindre un plafond réel se dégrade en douceur, par exemple en mettant en file d'attente et en réessayant avec un backoff, plutôt que de casser franchement, par exemple en plantant ou en abandonnant silencieusement des requêtes, car même une limite généreuse peut être atteinte lors d'un pic de trafic.

Pour les travaux en masse, non sensibles à la latence, l'API Batch reste la méthode standard pour router le volume vers un pool moins cher disposant de ses propres limites de débit distinctes, et depuis mi-2026 elle prend en charge jusqu'à 300 000 tokens de sortie par requête sur Opus 4.8, Opus 4.7, Opus 4.6, et Sonnet 5 ou Sonnet 4.6, lorsque vous envoyez l'en-tête bêta output-300k-2026-03-24. Cette combinaison, un plafond de sortie par requête bien plus élevé associé à un pool de limite de débit qui ne rivalise pas avec votre trafic interactif, est le schéma durable pour les grands travaux hors ligne : balayages de classification, résumé en masse, ou génération de jeux de données qui n'ont pas besoin d'une réponse en quelques secondes.

Sous tous ces chiffres précis se cache une seule discipline durable : mesurer, ne pas supposer. Chaque fait de cette leçon, trois paliers d'utilisation, un décalage de tokenizer de 30 %, un plafond de 4 000 tokens levé, un plafond de batch de 300 000 tokens, aura lui-même une date de péremption. Les chiffres précis continueront de changer à mesure qu'Anthropic livre de nouveaux modèles et ajuste sa capacité. Ce qui ne change pas, c'est la méthode : lire les en-têtes de limite de débit plutôt que de faire confiance à une ancienne documentation, recalculer les comptages de tokens sur le modèle que vous appelez réellement, router le travail en masse vers le pool batch moins cher, et construire des workflows qui plient plutôt que de rompre quand un plafond bouge.