Optimiser sa consommation Claude Code — guide praticien

En bref

Claude Code consomme entre $2 et $210 par jour selon l’intensité d’usage, avec un cache read représentant plus de 95% des tokens. Les principaux leviers d’optimisation sont le prompt caching (×10 de réduction sur les tokens répétés), le dispatch de modèle par tâche (Haiku pour l’extraction, Sonnet pour l’analyse), et la gestion active du contexte via /compact. Cet article détaille les settings, les métriques et les anti-patterns identifiés après 30 jours d’usage intensif.

Pourquoi monitorer sa consommation

Imagine ta facture d’électricité. Tu sais à peu près combien coûte un radiateur, un four, un chauffe-eau. Mais le compteur global, lui, ne distingue pas — il additionne. Claude Code, c’est pareil : un sous-agent oublié, un CLAUDE.md gonflé, un effort high par défaut, et la facture s’envole sans que tu voies d’où ça vient. Le monitoring, c’est le sous-compteur qui te montre quel appareil tire le plus.

Claude Code ne facture pas directement l’utilisateur Max/Team — mais les tokens consommés déterminent les rate limits, la vitesse de réponse et le risque de throttling. Sur API, le coût est direct : Opus 4.6 facture $15/MTok en input et $75/MTok en output. Les tokens de thinking (extended thinking) comptent comme des tokens output.

Le problème n’est pas le coût d’un prompt isolé. C’est l’accumulation : un projet avec 10+ fichiers CLAUDE.md, 8 serveurs MCP et des sessions de 2 heures sans /compact peut consommer 200M+ tokens par jour. Et un sous-agent lancé sans cache coûte 10× plus cher qu’un prompt identique avec cache hit.

Nos observations sur 30 jours d’usage intensif : 4,1 milliards de tokens, dont 95,5% en cache read. Le coût médian d’un jour avec orchestration multi-agents est de $158, contre $7 pour un jour de travail direct léger. La différence est un facteur 22×.

En clair : 95 % des tokens consommés sont des relectures de cache à 10 % du prix normal. Tout le jeu d’optimisation consiste à maximiser ce ratio — donc à éviter de provoquer des ré-écritures de cache (changements fréquents de prompt système, sessions trop longues, sous-agents non cachés).

Les métriques qui comptent

Les 4 compteurs

Le ratio à surveiller : output / total. D’après nos mesures, il oscille entre 0.1% et 0.5%. En dessous de 0.1%, vous cachez efficacement mais produisez peu. Au-dessus de 1%, vos tokens output (donc votre thinking) dominent — réduisez l’effort.

Le cache est votre meilleur allié

Le prompt caching réutilise automatiquement le system prompt, les CLAUDE.md et l’historique de conversation. Un cache hit coûte 10% du prix normal. Sur nos 30 jours, le cache read a représenté 3,9 milliards de tokens sur 4,1 milliards — sans ce mécanisme, le coût aurait été multiplié par un facteur significatif.

Conditions d’activation : le bloc doit dépasser 4 096 tokens pour Opus/Haiku, ou 1 024 tokens pour Sonnet. En dessous, l’échec est silencieux — aucune erreur, juste un prix plein. Le cache expire après 5 minutes sans hit, mais chaque hit renouvelle le timer.

Piège documenté : la commande --resume a causé un cache miss complet entre les versions 2.1.69 et 2.1.90 de Claude Code. Corrigé depuis. Si vous utilisez une version antérieure, mettez à jour.

En clair : un cache hit, c’est 90 % d’économie sur la portion cachée. Un cache miss silencieux (bloc trop court, version buguée, parent → enfant), c’est 100 % du prix plein. La différence vaut la peine de vérifier régulièrement le cache hit rate dans /cost.

Settings d’optimisation

ENABLE_TOOL_SEARCH — le gain le plus immédiat

Si vous utilisez des serveurs MCP (Model Context Protocol), ce paramètre est le premier à vérifier.

D’après un rapport communautaire, 8 serveurs MCP avec false consomment 70,5K tokens dès le démarrage — soit 35% d’une fenêtre de 200K tokens, avant même d’avoir posé une question [NON VÉRIFIÉ — mesure utilisateur unique].

Configuration dans ~/.claude/settings.json :

{
  "env": {
    "ENABLE_TOOL_SEARCH": "true"
  }
}

Thinking et effort — le curseur coût/qualité

Les tokens de thinking sont facturés au tarif output ($75/MTok pour Opus). C’est le poste de dépense qui croît le plus vite en utilisation intensive.

La commande /effort low en début de session réduit le budget thinking pour la session courante. Pour un réglage permanent :

{
  "effortLevel": "medium"
}

Conseil pratique : restez en medium par défaut. Passez en high uniquement quand le raisonnement est nécessaire (pas pour du copier-coller ou de la restructuration). D’après nos observations, la majorité des tâches quotidiennes (commits, éditions ciblées, recherches dans le code) ne bénéficient pas de thinking étendu.

Dispatch modèle — choisir le bon outil

Tous les modèles Claude ne coûtent pas pareil. L’extraction mécanique sur Opus est un gaspillage.

Pour les sous-agents, le modèle se configure dans le frontmatter de l’agent :

model: sonnet  # ou haiku, opus

Ou globalement via la variable d’environnement :

export CLAUDE_CODE_SUBAGENT_MODEL=sonnet

D’après nos tests, Sonnet produit des résultats équivalents à Opus sur les tâches d’extraction documentaire et d’analyse standard. L’écart ne se manifeste que sur le raisonnement multi-étapes complexe.

En clair : trois manettes principales à régler avant tout usage régulier — ENABLE_TOOL_SEARCH=true (libère 70 000 tokens de contexte MCP), effort medium par défaut (high réservé au raisonnement complexe), modèle assigné à la tâche (Haiku pour extraire, Sonnet pour analyser, Opus pour décider). Ces trois réglages couvrent ~80 % de la marge d’optimisation.

Anti-patterns coûteux

1. Sessions longues sans /compact

Le contexte grandit à chaque échange. Après 20+ tours, les tokens accumulés pèsent sur chaque requête. La commande /compact résume l’historique et libère de l’espace.

Règle simple : /compact après chaque changement d’axe de travail. /clear quand vous changez de sujet.

L’auto-compaction se déclenche à ~95% de la fenêtre, mais à ce stade vous payez déjà un contexte surchargé depuis plusieurs tours.

2. Sous-agents sans cache

C’est le piège le plus coûteux en orchestration multi-agents. Chaque sous-agent ouvre sa propre fenêtre de contexte. Le prompt caching du parent ne se propage pas aux enfants — c’est un bug documenté. Chaque sous-agent paie le prix plein de son contexte initial.

Impact concret : d’après nos mesures, le coût par sous-agent a augmenté de $0.85 à $2.50 au fur et à mesure que les prompts se sont complexifiés. Sur une session avec 40 sous-agents, la différence avec/sans cache hypothétique représente un multiple significatif.

Mitigation : gardez les prompts de sous-agents courts et auto-contenus. N’injectez que le contexte strictement nécessaire à la tâche.

3. CLAUDE.md surchargé

Un CLAUDE.md de 500 lignes est rechargé à chaque tour de conversation. Si vous avez des instructions rarement utilisées, déplacez-les dans des fichiers séparés chargés à la demande (via des skills ou des fichiers context).

4. Opus pour tout

Le réflexe d’utiliser le modèle le plus puissant pour chaque tâche est naturel mais coûteux. Opus coûte 5× plus que Sonnet en input et 5× plus en output. Pour une tâche de reformatage, de tri ou d’extraction de données, Haiku à $0.80/MTok en input fait le même travail qu’Opus à $15/MTok.

5. Pas de monitoring

Sans outil de suivi, vous ne savez pas où partent vos tokens. Les jours les plus coûteux ne sont pas toujours les plus productifs.

Outils de monitoring

/cost — le diagnostic rapide

Disponible depuis la version 2.1.92, /cost affiche le breakdown de la session en cours : tokens par modèle, cache hit rate, coût estimé. C’est la première commande à connaître.

/stats — patterns d’usage

Pour les abonnés, /stats montre les patterns d’utilisation sur la durée.

ccusage — suivi quotidien

L’outil ccusage (npx ccusage) fournit un tableau jour par jour avec input, output, cache create, cache read, total et coût estimé. C’est l’outil de référence pour identifier les journées aberrantes.

Pattern d’analyse : comparez le coût par jour avec le nombre de tâches accomplies. D’après notre suivi, les jours les plus coûteux (>$150) correspondent systématiquement à des sessions d’orchestration multi-agents (40-200+ sous-agents). Les jours de travail direct léger coûtent $2 à $12.

/context — radiographie du contexte

La commande /context affiche en temps réel ce qui occupe votre fenêtre de contexte : fichiers chargés, historique, system prompt. Utilisez-la quand vous suspectez un contexte surchargé.

Retour chiffré — ce que montre un mois d’usage

D’après notre suivi sur 30 jours actifs d’utilisation intensive (orchestration multi-agents quotidienne) :

Les leviers qui ont le plus d’impact :

1. ENABLE_TOOL_SEARCH=true : libère 70K+ tokens de contexte MCP immédiatement
2. Dispatch modèle : Haiku pour l’extraction mécanique réduit le coût par sous-agent de 5-10×
3. Effort adapté : low ou medium pour 80% des tâches, high uniquement quand le raisonnement le justifie
4. Prompts sous-agents courts : chaque token compte quand il n’y a pas de cache
5. /compact régulier : maintient le contexte en dessous de 50% de la fenêtre

Ce qu’il faut retenir

• Le cache read représente >95% des tokens : le prompt caching est le mécanisme d’optimisation le plus puissant. Assurez-vous qu’il fonctionne (version à jour, blocs > 4 096 tokens pour Opus).
• Le coût vient du output, pas du input : les tokens de thinking (effort high/max) sont facturés au tarif output. Ajustez l’effort à la tâche.
• Un sous-agent ne bénéficie pas du cache parent : gardez les prompts courts et auto-contenus.
• Monitorer pour comprendre : /cost, /context et ccusage rendent visible ce qui est habituellement opaque. Un jour à $150 n’est pas un problème s’il produit 100 fichiers structurés.
• Le dispatch modèle est un levier sous-utilisé : Haiku pour extraire, Sonnet pour analyser, Opus pour décider.