Comment optimiser Claude Code ?

Guide pratique pour moins de tokens et plus de vibe 😉

Les plaintes sur Claude Code tournent toujours autour du même refrain : ça consomme trop, les limites tombent trop vite, ça coûte trop cher, le contexte explose.

Le problème existe. Mais il est souvent mal posé. Je travaille beaucoup avec Claude Code, et je n’ai pas ce problème-là au quotidien. Pas parce que j’ai un budget illimité. Pas parce que j’utilise une technique obscure. Pas parce que je vis dans un projet minuscule.

Dans Claude Code, le coût ne vient pas seulement du modèle. Il vient surtout de tout ce que vous laissez entrer dans le contexte : historique de conversation, contenus de fichiers, sorties de commandes, CLAUDE.md, auto memory, skills chargées, instructions système. Anthropic le dit clairement : plus le contexte grossit, plus la consommation de tokens monte. Claude Code compresse automatiquement l’historique quand il approche de la limite, mais cette compression arrive après coup. Entre-temps, vous avez déjà payé une partie de la facture, et la qualité peut commencer à dériver.

Autrement dit, le sujet n’est pas seulement “comment réduire les tokens sur Claude Code”. Le vrai sujet est : comment empêcher Claude Code de travailler dans un contexte sale, trop large ou mal segmenté. C’est là que se joue l’essentiel.

Pourquoi Claude Code consomme autant de tokens

Claude Code ne “voit” pas seulement votre dernier message. Sa fenêtre de contexte contient la conversation, les fichiers lus, les sorties de commandes, CLAUDE.md, l’auto memory, les skills chargées et les instructions système. À mesure que vous travaillez, tout cela s’accumule. Quand ça déborde, Claude Code commence par purger les sorties d’outils les plus anciennes, puis résume la conversation si nécessaire. Les requêtes importantes et les extraits de code clés sont préservés, mais certaines instructions détaillées peuvent se perdre.

Découvrez égalementComment Claude Skills automatise vos workflows ?

C’est précisément pour ça que tant d’utilisateurs ont l’impression que “Claude devient moins bon au fil de la session”. Ce n’est pas forcément le modèle qui se dégrade. C’est souvent le contexte qui devient un mélange de vieux essais, de logs verbeux, de fichiers lus trop largement et de consignes mal hiérarchisées. Anthropic recommande d’ailleurs de consulter /context pour voir ce qui prend de la place, et de gérer le contexte de façon proactive.

Les 4 causes les plus fréquentes de surconsommation

1. Vous gardez trop longtemps la même session

Anthropic recommande explicitement d’utiliser /clear entre les tâches non liées, parce qu’un contexte obsolète gaspille des tokens à chaque message suivant. Les bonnes pratiques officielles vont dans le même sens : longues sessions + contexte hors sujet = baisse de performance et consommation inutile.

Exemple classique : vous commencez par un bug CSS, vous enchaînez avec un refactor d’API, puis un audit sécurité, puis une génération de tests. Tout ça dans la même session. Résultat : Claude transporte du bruit à chaque tour.

2. Vous chargez trop d’instructions au démarrage

CLAUDE.md est lu au début de chaque session. Anthropic recommande de viser moins de 200 lignes par fichier CLAUDE.md, justement parce qu’il est chargé en contexte au démarrage et consomme des tokens avec le reste de la conversation. Si vous y collez des workflows détaillés qui ne servent qu’occasionnellement, vous payez ce surcoût à chaque session.

3. Vous utilisez le mauvais modèle

Découvrez égalementComment choisir les meilleures Claude Skills sur GitHub ?

Anthropic recommande Sonnet pour la plupart des tâches de code et réserve Opus aux décisions d’architecture complexes ou au raisonnement multi-étapes. Concrètement : lancer Opus pour une édition simple ou un nettoyage de code est souvent une dépense inutile.

4. Vous laissez Claude ingérer du bruit

Sorties de tests trop longues, logs massifs, documentation bruyante, outils MCP inutiles, trop de fichiers lus en exploration. Anthropic propose plusieurs contre-mesures officielles : privilégier les CLI quand elles existent, désactiver les serveurs MCP non utilisés, utiliser des hooks pour prétraiter les sorties et des subagents pour isoler les tâches verbeuses dans un autre contexte.

Ce qu’il faut faire concrètement

Voici la version courte et illustrée.

Tuto complet : optimiser Claude Code, étape par étape

Étape 1 — Voir ce qui vous coûte vraiment cher

Avant de corriger, mesurez.

Anthropic recommande d’utiliser /cost pour l’usage API et /stats pour les abonnés Pro/Max, car /cost n’est pas pertinent pour la facturation des abonnés qui ont l’usage inclus dans leur offre. La doc recommande aussi d’afficher ces données dans la status line si vous voulez suivre la consommation en continu.

Commandes utiles

/cost
/stats
/context

• /cost : utile si vous utilisez Claude Code via API.
• /stats : utile si vous êtes sur abonnement Pro/Max.
• /context : indispensable pour voir ce qui gonfle la fenêtre de contexte.

Ce qu’il faut observer

Découvrez égalementClaude Sonnet 4.6 : pourquoi l'adopter pour vos devs en 2026?

Cherchez trois choses :

1. Une session qui continue alors que le sujet a changé.
2. Un contexte initial trop gros avant même votre premier prompt.
3. Des sorties de commandes ou des lectures de fichiers qui prennent une place absurde.

Étape 2 — Utiliser /clear comme un outil normal, pas comme un aveu d’échec

C’est probablement la mesure la plus rentable.

Anthropic écrit noir sur blanc que /clear doit être utilisé entre tâches non liées pour repartir proprement. La doc ajoute même qu’après plus de deux corrections sur le même problème dans une session, il vaut souvent mieux repartir d’une session neuve avec un meilleur prompt.

Quand lancer /clear

Lancez /clear quand :

• vous changez vraiment de sujet ;
• la session a accumulé plusieurs fausses pistes ;
• vous sentez que Claude “traîne” des hypothèses obsolètes ;
• le contexte est déjà très chargé.

Exemple concret

Mauvais usage :

- Corrige le bug d’auth
- Maintenant regarde ce test flaky
- Finalement refactore l’API billing
- Et au fait, documente le module notifications

Bon usage :

Session 1 : bug d’auth
/clear
Session 2 : test flaky
/clear
Session 3 : refactor API billing
/clear
Session 4 : documentation notifications

C’est moins “confortable” psychologiquement. C’est beaucoup plus propre techniquement.

Étape 3 — Compacter tôt, avec une intention

Claude Code compacte automatiquement l’historique quand il approche des limites de contexte. Mais Anthropic recommande aussi l’usage manuel de /compact <instructions> pour garder le contrôle sur ce qui doit survivre au résumé. Vous pouvez même définir des instructions de compaction dans CLAUDE.md.

Commande de base

/compact Focus on the API changes

Pourquoi c’est utile

Sans instruction, Claude résume ce qu’il estime important. Parfois il vise juste. Parfois il écrase un détail qui comptait vraiment pour vous : une commande de test, une convention de nommage, une hypothèse d’architecture, une liste de fichiers modifiés.

Bonnes consignes de compaction

Vous pouvez ajouter dans CLAUDE.md quelque chose comme :

# Compact instructionsWhen compacting, always preserve:
- the list of modified files
- test commands that were run
- API contract decisions
- unresolved risks

Anthropic documente explicitement cette possibilité.

Quand compacter

Ne laissez pas l’auto-compact être votre seule stratégie. Compactez :

• avant un gros pivot de tâche dans la même session ;
• après une phase d’exploration lourde ;
• quand vous sentez que la discussion devient plus longue que utile.

Étape 4 — Réduire CLAUDE.md sans perdre de valeur

Le piège classique, c’est de transformer CLAUDE.md en manuel d’exploitation de 3 000 mots.

Anthropic explique que CLAUDE.md est chargé au démarrage de chaque session, qu’il doit rester concis, structuré, spécifique, et que la cible recommandée est moins de 200 lignes. La doc précise aussi qu’il faut y mettre ce qui doit être vrai dans toutes les sessions, et déplacer les procédures spécialisées vers des skills ou des règles scoppées par chemin.

Ce qui doit rester dans CLAUDE.md

Gardez seulement :

• commandes de build/test utiles partout ;
• conventions de code globales ;
• structure générale du projet ;
• règles permanentes du type “toujours faire X”.

Ce qui doit sortir de CLAUDE.md

Déplacez ailleurs :

• les procédures de revue PR ;
• les workflows de migration de base ;
• les consignes réservées à un sous-dossier ;
• les playbooks longs.

Exemple de bon CLAUDE.md

# Project rules- Run `pnpm test` before proposing a final patch.
- Use kebab-case for route paths.
- Never edit generated files under `src/generated/`.
- For backend changes, check `docs/api-contract.md`.
- For billing code, prefer plan mode before editing.

Court. Chargé à chaque session. Justifié.

Importer sans gonfler bêtement

Anthropic documente aussi les imports avec @path et explique que c’est utile pour organiser les instructions, mais il ne faut pas oublier qu’un import chargé au démarrage reste du contexte chargé au démarrage. Ce n’est pas de la magie, juste une meilleure organisation.

Étape 5 — Déplacer les workflows lourds vers des skills

Anthropic est très clair : quand vous répétez le même playbook, la même checklist ou la même procédure multi-étapes, il faut créer une skill. Les skills sont chargées à la demande, alors que CLAUDE.md charge dès le début de la session.

Quand créer une skill

Créez une skill si vous répétez souvent :

• “fais un audit sécurité” ;
• “prépare une PR propre” ;
• “corrige une issue GitHub” ;
• “analyse le code billing avant modification”.

Exemple simple

Fichier :

.claude/skills/fix-issue/SKILL.md

Contenu :

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---Analyze and fix the GitHub issue: $ARGUMENTS.
1. Read the issue
2. Find impacted files
3. Implement fix
4. Run tests
5. Summarize risks

Anthropic montre exactement ce type d’usage dans sa doc skills.

Pourquoi ça réduit les tokens

Parce que vous évitez de réinjecter sans cesse la même procédure dans le chat. Et surtout, vous retirez cette procédure du contexte de base.

Étape 6 — Mettre Sonnet par défaut, pas Opus

Anthropic recommande Sonnet pour la plupart des tâches de code et réserve Opus aux cas plus lourds. C’est l’un des leviers les plus simples et les plus efficaces.

Commande utile

/model

ou via :

/config

Règle simple

Utilisez :

• Sonnet pour le quotidien ;
• Opus pour architecture, raisonnement complexe, multi-fichiers difficiles ;
• Haiku pour des sous-tâches simples de subagent quand c’est pertinent.

Décision pratique

Étape 7 — Réduire le thinking étendu

Anthropic documente explicitement le fait que le thinking étendu est activé par défaut sur les tâches complexes, que ses tokens sont facturés comme des tokens de sortie, et que le budget peut monter à des dizaines de milliers de tokens par requête selon le modèle. La doc propose plusieurs leviers : /effort, réglages dans /model, désactivation dans /config, CLAUDE_CODE_DISABLE_THINKING=1 ou MAX_THINKING_TOKENS.

Cas 1 — baisse légère : réduire l’effort

/effort

ou via /model / /config.

Cas 2 — réglage shell

export MAX_THINKING_TOKENS=8000
claude

Anthropic documente bien MAX_THINKING_TOKENS et précise que 0 désactive complètement la réflexion.

Cas 3 — désactivation franche

export CLAUDE_CODE_DISABLE_THINKING=1
claude

Cas 4 — configuration persistante

Dans les réglages ou settings.json, vous pouvez aussi poser un effort par défaut ou des variables d’environnement. La doc settings et env-vars l’indique.

Quand réduire le thinking

Réduisez-le pour :

• édition simple ;
• refactor local ;
• correction de test évidente ;
• reformulation de code ou commentaire ;
• tâches mécaniques.

Gardez un budget plus élevé pour :

• design système ;
• debug obscur ;
• arbitrage d’architecture ;
• analyses de causes profondes.

Étape 8 — Filtrer le bruit avec des hooks

C’est un levier sous-utilisé, alors que la doc Anthropic le documente très bien.

Les hooks sont des commandes shell, endpoints HTTP ou prompts qui s’exécutent automatiquement à certains moments du cycle Claude Code. Anthropic insiste sur un point essentiel : contrairement à CLAUDE.md, les hooks sont déterministes. Si vous voulez qu’une action arrive à chaque fois, sans exception, les hooks sont le bon outil.

Côté coût, la doc “Manage costs” donne un exemple très parlant : plutôt que de laisser Claude lire un log de 10 000 lignes, un hook peut filtrer les erreurs et ne renvoyer que les lignes utiles, faisant tomber le contexte de dizaines de milliers de tokens à quelques centaines.

Exemple : filtrer la sortie des tests

Dans settings.json :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

Et côté script :

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","updatedInput":{"command":"$filtered_cmd"}}}"
else
  echo "{}"
fi

Cet exemple est directement inspiré de la doc officielle Anthropic.

À quoi ça sert dans la vraie vie

Très simple :

• ne remonter que les lignes ERROR ;
• tronquer les sorties de test à 100 lignes ;
• empêcher des commandes destructrices ;
• normaliser des commandes répétitives.

Étape 9 — Utiliser des subagents pour garder le contexte principal propre

Anthropic insiste sur ce point : les subagents tournent dans leur propre fenêtre de contexte et reviennent avec un résumé. C’est précieux quand une tâche demande de lire beaucoup de fichiers ou d’explorer le code en profondeur.

Exemple de prompt

Use subagents to investigate how our authentication system handles token refresh,
and whether we have any existing OAuth utilities I should reuse.

Anthropic donne pratiquement ce cas d’usage dans sa doc.

Quand utiliser un subagent

Utilisez un subagent pour :

• explorer une grosse base de code ;
• faire une revue sécurité ;
• analyser des logs ;
• vérifier des edge cases ;
• lire beaucoup de fichiers avant de modifier.

Pourquoi c’est rentable

Parce que la partie “enquête lourde” n’encombre pas votre session principale. Vous récupérez un résumé, pas toute la poussière.

Étape 10 — Réduire l’overhead MCP

Les serveurs MCP sont puissants. Ils peuvent aussi coûter plus qu’ils ne rapportent si vous les laissez tourner sans discipline.

Anthropic précise que les définitions d’outils MCP sont différées par défaut : seuls les noms d’outils entrent en contexte tant qu’un outil n’est pas utilisé. C’est déjà bien. Mais la doc recommande aussi de privilégier les CLI quand elles existent, car elles restent plus économes que les serveurs MCP, et de désactiver les serveurs non utilisés via /mcp.

Bon réflexe

Préférez parfois :

• gh plutôt qu’un MCP GitHub ;
• aws plutôt qu’un MCP AWS ;
• gcloud plutôt qu’un MCP cloud ;
• sentry-cli plutôt qu’un MCP Sentry.

Pas par dogmatisme. Par économie de contexte.

Vérifier

/mcp
/context

Étape 11 — Installer les bons plugins de code intelligence

Anthropic indique que les plugins de code intelligence pour langages typés permettent une navigation symbole précise, évitent des lectures multiples de fichiers et remontent automatiquement certaines erreurs de typage après édition. Ça réduit les lectures inutiles et donc la consommation de contexte.

Traduction : si Claude peut faire un “go to definition” propre, il a moins besoin de ratisser large avec grep + lecture de plusieurs candidats.

Étape 12 — Utiliser le mode --bare quand vous avez besoin d’un mode minimal

La référence CLI documente --bare comme un mode minimal qui désactive l’auto-découverte des hooks, skills, plugins, serveurs MCP, auto memory et CLAUDE.md, pour démarrer plus vite. Claude garde l’accès à Bash, lecture et édition de fichiers, mais vous partez sur une base plus nue.

Exemple

claude --bare -p "review this file and suggest a minimal patch"

Quand l’utiliser

Utilisez --bare pour :

• un script ponctuel ;
• une tâche très ciblée ;
• une exécution non interactive ;
• un test pour comparer la différence de coût avec votre setup normal.

Ce n’est pas le mode par défaut à adopter partout. C’est un outil utile quand vous voulez un environnement très léger.

Configuration recommandée : une base saine et sobre

Voici une base simple qui tient la route.

1. CLAUDE.md minimal

# Project rules- Run `pnpm test` before finalizing a patch.
- Never edit generated files under `src/generated/`.
- Billing changes require checking `docs/billing.md`.
- Prefer small diffs over broad rewrites.
- When compacting, preserve modified files, test commands, and open risks.

2. Variables d’environnement utiles

export MAX_THINKING_TOKENS=8000
# ou, pour couper franchement
# export CLAUDE_CODE_DISABLE_THINKING=1

Anthropic documente ces variables explicitement.

3. Routine de session

• Démarrage sur Sonnet
• /context si vous sentez que ça gonfle
• /compact avant la saturation
• /clear entre sujets
• subagent pour l’exploration lourde
• hook pour filtrer logs/tests

Exemple complet de workflow économe en tokens

Prenons un cas réel : un bug sur l’authentification.

Mauvaise version

Vous demandez :

Regarde pourquoi le refresh token plante, analyse l’architecture auth, lis les logs, fais les tests, puis corrige et documente.

Claude va probablement :

• lire beaucoup de fichiers ;
• ingérer des logs ;
• explorer large ;
• garder tout ça en contexte ;
• produire une session lourde.

Bonne version

1. Investigation séparée

Use subagents to investigate how refresh token handling works,
which files are involved, and what likely causes the failure.
Return only a concise summary with file paths and hypotheses.

2. Implémentation propre

Based on the summary, patch only the files involved.
Keep the diff minimal and run the relevant tests only.

3. Compaction ciblée

/compact Focus on auth flow decisions, modified files, and test commands

4. Nouvelle tâche ? nettoyage

/clear

Ce workflow suit précisément les recommandations Anthropic sur les subagents, la compaction et le clear.

Comment payer moins cher Claude Code

Il faut distinguer deux cas.

Cas 1 — vous utilisez Claude Code via API

Là, vous êtes facturé à la consommation de tokens. Anthropic précise que les coûts varient fortement selon le modèle, la taille du codebase et vos usages. La doc donne un ordre de grandeur en déploiement entreprise : environ 13 $ par développeur et par jour actif en moyenne, et 150 à 250 $ par mois par développeur, avec 90 % des utilisateurs sous 30 $ par jour actif.

Cas 2 — vous utilisez un abonnement Pro ou Max

Anthropic précise que /cost n’est pas pertinent pour la facturation des abonnés Pro/Max, car leur usage est inclus dans l’abonnement. En revanche, l’optimisation reste utile pour éviter de heurter les limites d’usage et pour garder des sessions stables et efficaces.

Dans les deux cas, le levier est le même : réduire la taille du contexte utile.

Les erreurs qui coûtent cher sans se voir

1. Croire que plus d’historique = plus d’intelligence

Faux réflexe. Au-delà d’un certain point, plus d’historique veut surtout dire plus de bruit.

2. Mettre tout dans CLAUDE.md

C’est le raccourci préféré des gens organisés… et la meilleure manière de surtaxer chaque session.

3. Utiliser Opus “au cas où”

C’est rassurant. Ce n’est pas rationnel.

4. Lancer des tests ou des logs bruts dans le chat

Si votre terminal crache 15 000 lignes, Claude n’a pas besoin d’en voir 15 000.

5. Confondre “persistance” et “pollution”

Certaines choses doivent survivre. Le reste doit être résumé, déplacé, ou supprimé.

La méthode simple à retenir

Si vous ne deviez retenir qu’une routine, prenez celle-ci :

1. Sonnet par défaut
2. CLAUDE.md court
3. skills pour les playbooks
4. hooks pour filtrer le bruit
5. subagents pour les enquêtes lourdes
6. /compact avant saturation
7. /clear entre sujets
8. thinking réduit quand la tâche est simple
9. MCP allégé
10. /context pour vérifier, pas pour deviner

Cette logique colle exactement à la documentation officielle : choisir le bon modèle, garder le contexte petit, déplacer les instructions spécialisées vers les skills, filtrer via hooks, utiliser les subagents pour les opérations verbeuses et surveiller l’espace consommé.

Ce qu’il faut retenir

Quand j’entends “Claude Code consomme trop”, je ne commence pas par blâmer le modèle.

Je regarde d’abord :

• est-ce que la session est devenue trop longue ?
• est-ce que CLAUDE.md est trop grosse ?
• est-ce que j’utilise le bon modèle ?
• est-ce que je laisse entrer trop de bruit ?
• est-ce que le thinking est surdimensionné ?
• est-ce qu’un subagent aurait dû faire le sale boulot ?
• est-ce que j’aurais dû faire /clear vingt minutes plus tôt ?

Dans la majorité des cas, le vrai problème est là.

Claude Code n’est pas “trop cher” par nature. Il devient cher quand on lui demande de porter un contexte gonflé, mal segmenté, trop verbeux et mal gouverné.

La vraie question, c’est : pourquoi Claude voit-il autant de choses inutiles dans votre session ?