Optimisation des coûts Claude Code : checklist en 25 points

Activer cache_control sur votre prompt système

Si vous appelez l'API directement, encapsulez votre prompt système (ou tout grand bloc de contexte répété sur plusieurs requêtes) dans un bloc cache_control: {"type": "ephemeral"}. Les tokens en cache coûtent 10 % du tarif des tokens d'entrée non mis en cache. Sur un prompt système de 10 000 tokens répété 50 fois par jour, ce sont 4,5 M de tokens économisés chaque jour.

system=[{
  "type": "text",
  "text": your_large_system_prompt,
  "cache_control": {"type": "ephemeral"}
}]

Mettre en cache les documents avant des requêtes répétées

Si vous lancez plusieurs prompts contre le même document (un pan de base de code, une spec, un PDF), mettez le document en cache à la première requête. Chaque requête suivante qui touche le cache paie 10 % pour le document. Le seuil de rentabilité est à 2 requêtes ; le gain s'observe à partir de 3.

Surveiller le taux de hits cache via les en-têtes de réponse

Lisez usage.cache_read_input_tokens dans chaque réponse API. Si votre taux de hits cache passe sous les 60 % pour une application au prompt système lourd, le cache expire avant que vous puissiez l'utiliser. Le cache éphémère dure 5 minutes ; assurez-vous que vos requêtes arrivent dans cette fenêtre.

Garder le contenu mis en cache en tête de prompt

Le cache est indexé sur le contenu et sa position. Si vous placez du contenu dynamique (message utilisateur, date du jour) avant votre prompt système mis en cache, le cache ne sera pas touché. Mettez le bloc statique et volumineux en premier. Mettez le contenu dynamique en dernier.

Utiliser le cache étendu (TTL d'une heure) pour les grands contextes stables

Le cache éphémère standard dure 5 minutes. Si votre contexte est volumineux (un index complet de base de code) et change peu, Anthropic propose un cache étendu avec TTL d'une heure, à un coût d'écriture cache légèrement supérieur mais à un coût de lecture cache plus bas par heure. Cela vaut la peine au-delà de 100K tokens de contexte.

Mettre en cache le contenu de CLAUDE.md sur les longues sessions

Dans une session Claude Code, le contenu de CLAUDE.md est ajouté en tête de chaque message. Si votre CLAUDE.md fait 5 000 tokens, ce sont 5 000 tokens facturés à chaque tour. Gardez CLAUDE.md sobre, et envisagez de séparer le contexte spécifique au projet dans un fichier référencé seulement quand c'est nécessaire, plutôt qu'injecté à chaque tour.

Utiliser Haiku pour les tâches de classification et de routage

Haiku 3.5 coûte 0,25 $ par million de tokens d'entrée contre 3 $ pour Sonnet 4.5. Pour les tâches qui sont fondamentalement de la mise en correspondance (classer cette erreur, catégoriser cette issue, ce texte respecte-t-il ces critères), Haiku produit une qualité équivalente à un douzième du prix. Auditez vos sous-agents—tout sous-agent à 3 tours maximum et à sortie de type classification doit tourner sous Haiku.

N'utiliser Sonnet que lorsque le raisonnement compte

Sonnet vaut son prix pour : la revue de code, l'audit de sécurité, le raisonnement multi-étapes, tout ce qui exige de synthétiser des informations contradictoires. Il ne le vaut pas pour : la génération de documentation, l'écriture de changelog, l'extraction de données structurées, ou tout ce qui suit un format déterministe.

Régler max_tokens prudemment, agent par agent

L'API facture les tokens générés, pas les tokens demandés. Mais positionner un max_tokens élevé sans nécessité incite Claude à produire plus que requis. Pour les sorties structurées (JSON, YAML, tableaux), un max_tokens plus bas force aussi Claude à être plus concis. Auditez la longueur de sortie réelle de chaque agent et fixez max_tokens à 120 % du p95 observé.

Utiliser le streaming pour les longues sorties ; couper tôt si nécessaire

Avec le streaming, vous pouvez interrompre en cours de flux dès que vous avez assez. Sur l'API, les réponses partielles en streaming sont facturées sur les tokens générés à ce moment, pas sur le max_tokens complet. Pour les applications qui n'ont souvent besoin que du début d'une longue sortie, streaming + interruption précoce peut réduire les coûts en sortie de 40 à 70 %.

Éviter Opus pour les tâches que Sonnet traite aussi bien

Opus coûte 15 $ par million de tokens d'entrée—5 fois Sonnet. L'écart de qualité entre Opus et Sonnet est significatif sur le travail créatif ouvert et le raisonnement complexe multi-étapes. Pour les tâches de code, les sorties structurées et la plupart des workflows développeur, Sonnet égale Opus à un cinquième du prix. Faites un benchmark avant de passer par défaut sur Opus.

Lancer /compact avant que les longues sessions ne dépassent 50K tokens

La commande /compact de Claude Code résume le contexte de session et le remplace par une version compressée. Une session de 100K tokens devient un résumé de 5K. La perte de qualité reste minime pour la continuité de la tâche ; l'économie est nette. Lancez-la toutes les 2 heures sur une session active.

Utiliser Grep et Read au lieu de laisser Claude explorer la base de code

Quand Claude explore une base de code sans direction, il lit beaucoup de fichiers pour saisir le contexte. Le pointer d'abord sur les fichiers utiles (« lis app/api/users.ts et le modèle User ») réduit le contexte d'un ordre de grandeur. Utilisez Grep pour trouver les fichiers pertinents avant de demander à Claude de les lire.

Garder CLAUDE.md sous les 300 lignes

Chaque ligne de CLAUDE.md est un token ajouté en tête de chaque message dans une session. Un CLAUDE.md de 3 000 lignes ajoute environ 4 500 tokens à chaque tour. Un CLAUDE.md de 300 lignes en ajoute environ 450. Le billet 3000-line CLAUDE.md problem détaille comment le structurer pour minimiser les tokens sans perdre en couverture.

Restreindre l'accès aux outils des sous-agents au strict nécessaire

Un sous-agent doté de tous les outils s'en servira. Un sous-agent restreint à [Read, Grep] ne pourra pas lancer un processus Bash et charger un journal de 10 Mo dans le contexte. La restriction d'outils est à la fois un garde-fou de coût et un contrôle de sécurité.

Passer des diffs, pas des fichiers complets, aux agents de revue

Pour un agent de revue de code, passez la sortie de git diff HEAD~1 plutôt que les fichiers entiers. Un fichier de 2 000 lignes avec 40 lignes modifiées coûte 2 000 tokens en passant le fichier et 200 tokens en passant le diff. Pour les workflows de revue, le diff suffit presque toujours.

Utiliser la Batch API pour toute charge non urgente

La Batch API d'Anthropic coûte 50 % de moins par token que l'API temps réel. Elle accepte jusqu'à 10 000 requêtes par lot, traitées en moins de 24 heures. Si votre cas d'usage n'a pas besoin d'une réponse en moins de 60 secondes, la Batch API est le bon choix. Analyse de documents, génération de tests, écriture de changelogs—tout cela est éligible au batch.

Dédupliquer les requêtes avant envoi à l'API

Si votre application risque d'envoyer deux fois le même prompt (requête utilisateur identique, même analyse de document), comparez votre requête à un hash local avant l'appel. Un hash SHA-256 de (model + system_prompt + user_message) identifie les doublons. Mettez en cache la réponse indexée sur ce hash. Un taux de doublons de 5 % dans une application à fort volume représente une économie substantielle sur un mois.

Regrouper des requêtes similaires dans un prompt multi-parties

Si vous devez exécuter la même opération sur 20 documents (résumé, classification, extraction), une requête multi-documents coûte souvent moins que 20 requêtes uni-documents, parce que le prompt système est payé une seule fois. Vérifiez l'arithmétique sur vos tokens réels—un lot trop volumineux peut excéder les limites de contexte et imposer une découpe quand même.

Implémenter une coalescence des requêtes pour les requêtes concurrentes identiques

Dans les applications à fort trafic, plusieurs utilisateurs peuvent déclencher le même appel API sous-jacent au même moment (même rapport, même analyse). Coalescence : quand une requête est en vol, les requêtes identiques suivantes attendent la première réponse et la partagent. Économies proportionnelles à la forme de vos pics de trafic.

Programmer les jobs batch en heures creuses pour gagner en priorité

Le temps de traitement de la Batch API varie selon la charge d'Anthropic. Soumettre les lots en heures creuses (UTC 02:00–08:00) accélère généralement la complétion sans coût supplémentaire. Pour des lots avec fenêtre de 24 heures, soumettre à minuit et récupérer les résultats au matin est un schéma fiable.

Plafonner le budget par session et par jour via des hooks PreToolUse

Un hook PreToolUse s'exécute avant chaque appel d'outil. Un script de 30 lignes qui lit le coût cumulé de votre session dans ~/.claude/projects/ et coupe au-dessus de 10 $ prévient les scénarios Tokenocalypse. Le hook se déclenche avant que l'appel API ne quitte votre machine ; il n'existe pas de point d'application plus en amont.

Imposer max_turns à tous les sous-agents

Un sous-agent sans limite max_turns peut tourner sans fin. Mettez max_turns: 10 sur la plupart des agents et max_turns: 5 sur les agents à tâches simples et bornées. Un sous-agent qui s'emballe à 50 tours coûte 5 à 10 fois plus qu'un agent bien borné sur la même tâche.

Journaliser et alerter sur les anomalies de coût, pas seulement le total mensuel

Les alertes de facturation mensuelle attrapent les Tokenocalypses une fois les dégâts faits. Les alertes quotidiennes (e-mail ou webhook Slack au-dessus de 2× le baseline) les attrapent à temps pour intervenir. La console Anthropic accepte des seuils d'alerte de dépense quotidienne. Mettez-les en place.

Tuer les sessions zombies avant qu'elles ne s'accumulent

Une session Claude Code laissée ouverte mais inactive peut continuer à facturer dès qu'un sous-agent passe un appel d'outil. Listez les sessions actives avec claude sessions list et fermez celles que vous n'utilisez plus. Sur une machine partagée entre plusieurs développeurs, les sessions zombies sont un poste de coût important et invisible.