Comment réduire l’usage des tokens Claude Code ?

Vous pouvez réduire l’usage des tokens Claude Code en contrôlant ce qui fait partie du contexte (modèle, CLAUDE.md, subagents, fichiers, compaction). Cet article propose 5 méthodes pratiques, templates de prompts et workflows pour diminuer coûts et itérations.

Quel modèle choisir selon la tâche

Adapter le modèle à la complexité de la tâche réduit significativement l’usage de tokens en évitant que des modèles « lourds » traitent des tâches simples. Commencer avec un modèle léger, n’escalader que si nécessaire et passer à un modèle plus puissant uniquement quand la tâche l’exige permet d’économiser du contexte, du temps et de l’argent.

Principe d’escalade progressive : Démarrer petit (Sonnet) pour vérifier le besoin, analyser la sortie, puis escalader vers Opus seulement si la qualité, la profondeur d’analyse ou la compréhension cross-file manquent. N’activer Haiku que pour des opérations répétitives, rapides et à faible contexte.

Critères pratiques pour basculer :

• Durée estimée : Choisir Opus si la réponse demande une synthèse longue ou un raisonnement soutenu (> quelques centaines de mots).
• Nombre d’itérations prévues : Rester sur Sonnet si on prévoit >5 itérations rapides ; escalader si les itérations restent inefficaces.
• Besoin de refactoring global : Passer à Opus si la tâche requiert une modification structurelle du code ou compréhension cross-file.
• Compréhension cross-file : Choisir Opus quand la logique traverse plusieurs fichiers et nécessite maintien de contexte sur plusieurs dizaines de lignes.

/effort : Paramètre qui module la profondeur et la verbosité de la génération. Plus l’effort augmente, plus le modèle va produire d’étapes intermédiaires et d’explications (donc plus de tokens). Choisir une valeur conservatrice réduit le texte produit ; commencer bas et augmenter seulement si la sortie manque d’étapes clés. Exemple d’usage conservateur :

/effort 0.2

Modèle	Cas d’usage et coût en effort	Exemple de prompt
Sonnet	Tâches simples, résumé courts, faible coût d’effort (low)	« Résume ce PR en 5 points clairs. /effort 0.2 »
Opus	Analyses profondes, refactorings, coût d’effort moyen à élevé (medium/high)	« Analyse l’architecture et propose refactorings cross-file. /effort 0.7 »
Haiku	Opérations répétitives et scripts rapides, faible coût d’effort (low)	« Génère 10 tests unitaires basés sur ce modèle. /effort 0.2 »

Références : Documentation Anthropic — https://www.anthropic.com/docs et https://www.anthropic.com/docs/models. Documentation sur les tokens et tokenisation (approx. 1 token ≈ 4 caractères) — https://platform.openai.com/docs/guides/tokenizer.

• Commencer la prochaine session avec Sonnet et un /effort bas pour valider le besoin.
• Définir un critère d’escalade chiffré (ex. : plus de 3 itérations ou >500 mots attendus) avant de passer à Opus.
• Noter les tokens consommés par tâche pendant 3 sessions pour ajuster le choix du modèle et la valeur /effort.

Comment garder CLAUDE.md utile et léger

Garder CLAUDE.md utile et léger évite d’alourdir chaque requête et réduit le coût et le risque d’atteindre la fenêtre contextuelle du modèle.

Définition du rôle et pourquoi ça pèse : CLAUDE.md doit rester un lookup concis de règles stables. Chaque octet de ce fichier peut être réinjecté dans le prompt système ou concaténé aux messages, et les modèles facturent et limitent par tokens. Un token ≈ 4 caractères et 1 000 tokens ≈ 750 mots, ce qui signifie qu’un document volumineux augmente latence, coût et risque de troncature.

Ce qu’il faut inclure (liste précise) :

• Règles d’exécution des tests — Commandes exactes et prérequis essentiels.
• Gestionnaire de paquets et versions — Pipenv/Poetry/NPM + versions contraintes.
• Règles de formatage — Exemples courts de lint et hooks (pre-commit).
• Contraintes architecturales — Décisions immuables (BDD, services critiques).
• Chemins à ignorer — Dossiers à exclure pour build ou scan (ex: /vendor, /build).

Ce qu’il faut éviter :

• Historiques détaillés de décisions — Conserver ailleurs (changelog, issues).
• Notes longues et narrations — Remplacer par énoncés synthétiques.
• Guides pas-à-pas complets — Laisser dans la doc utilisateur ou wiki.
• Dumps de code — Ne garder que snippets de 1–3 lignes quand nécessaire.

Bonne entrée (mini-template, 3 lignes) :

Test: pytest -q --maxfail=1
Package: poetry==1.4.0
Ignore: /vendor, /build

Mauvaise entrée (exemple) :

Historique: On a essayé pipenv en 2019 puis pip3 en 2020, ensuite on a migré vers poetry parce que les scripts custom posaient problème... (trois paragraphes détaillant problèmes et solutions, captures d'écran, commits, etc.)

Méthode pratique pour transformer une longue note en lookup : Résumer le texte en une phrase par idée. Extraire les règles actionnables (imperatives, commandes, chemins). Stocker la version courte dans CLAUDE.md et lier la note longue depuis un wiki ou issue. Valider que chaque entrée reste ≤ 1–2 phrases.

Type de contenu	Mettre dans CLAUDE.md ?	Raison
Commandes de build	Oui	Actionnable et stable
Raisons historiques	Non	Gonfle le prompt, conserver en archive
Snippets courts	Oui (1–3 lignes)	Réutilisable sans surcharge

Conseils opérationnels et outils : Mettre en CI un script qui calcule les tokens et refuse les PRs si CLAUDE.md dépasse N tokens. Utiliser tiktoken (Python) ou équivalents JS pour mesurer les tokens. Exemple Python :

import tiktoken
enc = tiktoken.get_encoding("cl100k_base")
tokens = len(enc.encode(open("CLAUDE.md").read()))
if tokens>2000: raise SystemExit("CLAUDE.md trop long")

Automatiser en pre-commit et pipeline CI (intégration continue) pour maintenir la taille et ajouter tests qui valident la longueur en tokens.

Trois recommandations rapides :

• Limiter chaque entrée à 1–2 phrases actionnables et lier la doc complète ailleurs.
• Automatiser le contrôle de tokens en CI avec tiktoken ou équivalent.
• Archiver l’historique hors de CLAUDE.md et ne garder que les décisions immutables.

Quand et comment déléguer aux subagents

Déléguez les travaux verbeux et itératifs aux subagents quand la synthèse retournée au fil principal économise plus de tokens que le coût de démarrage du subagent.

Qu’est-ce qu’un subagent et pourquoi l’utiliser. Un subagent est une instance dédiée qui réalise une tâche autonome (par exemple parcourir des fichiers, lancer des tests, agréger des logs) et qui retourne uniquement une synthèse au fil principal. Cela isole la verbosité hors du contexte principal et réduit le nombre total de tokens échangés avec le modèle central.

Coûts de démarrage — estimation qualitative. Le démarrage inclut le prompt d’initialisation, la définition d’outils/accès, et 1–3 aller-retours initiaux. Ces coûts varient selon :

• Complexité du travail : Plus le travail est long, plus l’amortissement est favorable.
• Besoin de synchronisation : Si le subagent nécessite des validations fréquentes, le gain diminue.
• Sécurité et accès aux fichiers : Configuration et permissions augmentent l’overhead.
• Latence réseau : Peut rendre le parallélisme contre-productif malgré l’économie de tokens.

Méthode chiffrée pour décider. Estimer le volume verbeux attendu (caractères) et convertir en tokens avec 1 token ≈ 4 caractères (estimation OpenAI). Calculer :

• Estimation Tokens Travail = Longueur estimée (caractères) / 4.
• Overhead Subagent = TokensInitiaux (prompt + context) + 2×TokensAllerRetours.
• Décision = Utiliser si Estimation Tokens Travail − Overhead Subagent > Seuil (ex. 50 tokens).

Templates prompts.

Initialise Subagent:
Tu es un subagent chargé de {tâche}. Objectif: produire une synthèse <= {max_tokens} tokens. Accès: {fichiers/outils}. Format de sortie: JSON {clé1, clé2, résumé}. Contraintes: {sécurité, délais}.

Demande de synthèse (5 points):
Rends une synthèse en 5 points clairs avec éléments actionnables, priorité et estimation de risque. Utilise au maximum {max_tokens} tokens.

Retour au fil principal:
Fournis une synthèse résumée pour l'utilisateur final, 3 lignes max, puis un tableau de 5 points détaillés (titre, action, priorité).

Exemples concrets.

• Exécution de tests : Le subagent lance 200 tests, collecte échecs et stack traces, et renvoie 5 points prioritaires au lieu d'envoyer toutes les logs.
• Génération de documentation API : Le subagent parcourt le répertoire, extrait endpoints et schémas, puis renvoie une doc structurée en 5 sections compressées.

Mise en garde. Éviter les subagents pour les petites tâches (<500 caractères), quand la latence est critique, ou si la coordination multiplie les allers-retours.

Quand utiliser	Quand éviter
Travaux très verbeux (>2000 caractères)	Petites tâches rédhibitoires (<500 caractères)
Tâches parallélisables (tests, parsing fichiers)	Forte synchronisation requise
Accès fichier isolé et sûr	Problèmes d'autorisation fréquents
Besoin de synthèse claire et concise	Latence réseau inacceptable

• Vérifier que la synthèse attendue réduit les tokens plus que l'overhead estimé.
• Définir format de sortie strict (JSON/tableau/icônes).
• Lister accès et contraintes de sécurité avant initialisation.
• Planifier maximal 1–3 aller-retours initiaux pour valider le subagent.

Comment pointer précisément vers fichiers et plages de lignes

Ciblez les fichiers et plages de lignes exactes pour éviter des parcours coûteux du dépôt.

Les requêtes vagues entraînent l'exploration de multiples fichiers, l'envoi de contenus entiers et des réponses longues, ce qui augmente le nombre de tokens traités (entrée + sortie). Les tokens sont des unités de texte (un token correspond approximativement à 3-4 caractères en anglais) : plus il y a de tokens, plus le coût et la latence augmentent, et plus les itérations nécessaires pour converger sont nombreuses.

Les bonnes pratiques suivantes réduisent les parcours inutiles du dépôt :

• Préciser le chemin du fichier et la branche pour éviter l'analyse de l'historique.
• Limiter la plage de lignes quand vous ciblez une fonction ou un bug.
• Donner un objectif mesurable (par ex. "2 correctifs" ou "test unitaire couvrant X cas").

Exemples de prompts — vague vs ciblé :

// Vague (problématique)
Regarde le code auth

// Ciblé (précis)
Regarde le fichier src/auth/login.js sur la branche feature/login, lignes 120-210.
Vérifie la gestion des erreurs (catch, codes HTTP) et propose 2 correctifs concis.

Mode plan (Shift+Tab) — workflow en 3 étapes :

• Planifier sans exécuter : Demander un plan d'actions (étapes précises, fichiers et lignes concernés).
• Valider le plan : Relire et approuver le plan avant toute modification pour éviter les allers-retours.
• Exécuter : Lancer les modifications ciblées en demandant un patch ou un diff limité aux plages validées.

Prompts prêts à l'emploi :

// Fix bug localisé
Fichier: services/payments/processor.py, branche main, lignes 45-78.
Identifie la cause du bug (timeout/exception) et propose 1 patch diff prêt à appliquer.

// Refactoriser une fonction
Fichier: src/utils/format.ts, ligne 10-60.
Propose un refactor en 3 étapes pour améliorer lisibilité et couverture, avec diff minimal.

// Ajouter test unitaire
Fichier: tests/integration/test_orders.py, branche test, lignes 1-1 (nouveau fichier).
Ajoute un test couvrant le cas d'échec réseau et montre le snippet pytest.

Prompt	Portée	Avantage tokens
Regarde le code auth	Tout le dépôt	Très mauvais — exploration large
src/auth/login.js, lignes 120-210	Fichier + plage	Excellent — tokens minimisés
Branche feature/login, dossier src/auth	Dossier restreint	Bon — réduit l'étendue

Règles rapides pour pointer des segments de code :

• Commencez par un chemin de fichier précis (relatif ou absolu).
• Indiquez la branche si nécessaire pour éviter les ambiguïtés.
• Donnez start/end lines pour limiter le contexte.
• Formulez un objectif mesurable et limité (nombre de correctifs, critères de test).
• Utilisez le mode plan (Shift+Tab) : planifier, valider, exécuter.

Comment compacter, pruner et externaliser le contexte

Compacter proactivement la session (/compact), pruner l'historique et externaliser le contexte (embeddings, cache, checkpointing) réduisent fortement l'usage des tokens sur le long terme.

Compacter la session via /compact fuse les échanges en un résumé court côté modèle afin de libérer tokens futurs. La compaction proactive est préférable parce que la rétention d'un fil trop lourd entraîne des coûts visibles et une latence accrue avant la première compaction automatique. La contrainte connue est que la compaction peut être interrompue sur les premiers mots ; prévoir donc une vérification post-compaction. Recommander d'appeler /compact après une tâche majeure ou toutes les N itérations (ex : toutes les 10-20 interactions).

• Checkpointing : Synthétiser un fil en 2-4 phrases et remplacer l'historique par ce checkpoint pour garder l'essentiel sans les tokens détaillés.
• Externalisation via embeddings + retrieval (RAG) : Stocker documents volumineux en base vectorielle (Pinecone, Weaviate, Milvus) et ne ramener que les passages pertinents via recherche par similarité.
• Caching : Mettre en cache les réponses récurrentes et réutiliser la sortie sans renvoyer tout le contexte à chaque requête.
• Batching et streaming : Grouper requêtes ou utiliser streaming quand possible pour réduire l'overhead et le nombre total de tokens envoyés.

Pipeline en 5 étapes pour migrer d'un workflow verbeux à un workflow compact :

• Mesurer : Collecter tokens par requête et par session actuels.
• Checkpoint : Générer résumés 2-4 phrases pour fils importants.
• Externaliser : Indexer documents volumineux en vector DB.
• Configurer retrieval : Intégrer recherche par similarité avant chaque requête.
• Monitorer économies : Suivre tokens, latence et fréquence de compaction.

Exemples (pseudo-code simple) :

// Générer un checkpoint résumé
Prompt = "Résume ce fil en 3 phrases, garder décisions et actions."
Réponse = Model.call(prompt)  // Remplacer l'historique par Réponse

// Créer un embedding et stocker
vector = EmbeddingService.embed(documentText)
VectorDB.upsert(id, vector, metadata)

// Recherche par similarité
qVec = EmbeddingService.embed(queryText)
hits = VectorDB.similarity_search(qVec, top_k=5)

/compact
Conserver: décisions clés, actions en cours.
Synthétiser: 3 phrases maximum.
Supprimer: verbatims non pertinents.

Technique	Quand l'utiliser	Bénéfice attendu
Compaction (/compact)	Après tâche majeure ou toutes N interactions	Réduction immédiate des tokens historiques
Checkpointing	Fils longs et structurés	Conserver contexte utile en quelques tokens
Embeddings + RAG	Documents volumineux ou base de connaissance	Ramener seulement les passages pertinents
Caching / Batching	Requêtes répétitives	Moins d'appels et moindre consommation de tokens

Métriques à suivre pour valider les économies :

• Tokens par requête moyen.
• Tokens par session moyen.
• Latence moyenne (impact de retrieval vs contexte complet).
• Fréquence de compaction (/session ou par heure).

Références : OpenAI Tokenizer Guide - https://platform.openai.com/docs/guides/tokenizer ; Documentation Anthropic (contexte & opérations) - https://www.anthropic.com/docs

Prêt à appliquer ces méthodes pour réduire vos coûts de tokens et optimiser Claude ?

En contrôlant le modèle, en maintenant CLAUDE.md concis, en délégant la verbosité aux subagents, en pointant précisément les fichiers et en compactionnant/externalisant le contexte, on réduit significativement l'usage de tokens et le coût des workflows. Ces méthodes sont opérationnelles : templates de prompts, checklists et pipelines permettent d'appliquer les changements immédiatement. Vous en retirez moins d'itérations, des réponses plus pertinentes et une facture API plus maîtrisée.

FAQ

• Comment les tokens sont-ils comptés dans une session Claude ?
  Toutes les parties du contexte envoyées à l'API (messages précédents, CLAUDE.md, fichiers inclus, mémoires) sont tokenisées et comptées. En pratique on retient l'approximation 1 token ≈ 4 caractères (soit ~750 mots pour 1000 tokens) pour estimer rapidement la charge. Voir les docs d'Anthropic et le guide sur les tokens pour plus de précision.
• Quand utiliser un subagent plutôt que tout faire dans le fil principal ?
  Privilégiez un subagent si la tâche est très verbeuse ou itérative et que sa synthèse finale sera bien plus courte que l'historique qu'elle remplacerait. Évitez pour des petites corrections rapides où l'overhead de démarrage l'emporte.
• Que mettre absolument dans CLAUDE.md ?
  Seules les règles stables et utiles en lookup : commandes de test, gestionnaire de paquets, règles de formatage, contraintes architecturales, répertoires à ignorer. Évitez historiques, dumps de notes et longs guides.
• Quand lancer /compact et pourquoi proactivement ?
  Lancez /compact après une phase majeure (livrable, refactor, synthèse) ou toutes les N itérations pour réduire la redondance avant qu'elle n'alourdisse le fil. Agir proactivement évite d'accumuler coûts et itérations supplémentaires.
• Est-il utile d'utiliser embeddings et retrieval pour économiser des tokens ?
  Oui : externaliser documents volumineux dans une base vectorielle et ne ramener que les passages pertinents évite d'envoyer de gros blobs à chaque requête. C'est particulièrement efficace pour documentation, historiques et gros dumps de code.

 

 

A propos de l'auteur

Franck Scandolera — expert & formateur en tracking server-side, analytics engineering, automatisation no/low-code (n8n) et intégration de l'IA en entreprise. Responsable de l'agence webAnalyste et de l'organisme Formations Analytics. Références : Logis Hôtel, Yelloh Village, BazarChic, Fédération Française de Football, Texdecor. Disponible pour aider les entreprises à optimiser leurs usages d'IA et réduire leurs coûts => contactez-moi.