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.

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.