Pourquoi Claude Code envoie 33k tokens avant votre prompt (et que faire)

Comprendre le surcoût en tokens de Claude Code

Tous les outils de développement agentiques chargent du contexte avant même de voir votre prompt. Le modèle doit savoir qui il est, quels outils il peut appeler et dans quel environnement il intervient. Claude Code se situe parmi les plus gourmands à cet égard. Un démarrage à froid représente généralement environ 33k tokens de préambule ; une solution minimale comme OpenCode affiche un volume plus proche de 7k.

Cet écart est réel, mais il ne constitue pas un classement de qualité. C’est un choix de conception. Les 33k apportent des outils intégrés plus riches et un comportement agentique plus fiable ; les 7k permettent une empreinte plus réduite et des démarrages à froid moins coûteux. Aucun des deux n’est « correct » : ils occupent des positions différentes sur une courbe de compromis entre capacités et coût.

Voici une répartition approximative du budget de démarrage de Claude Code. Les chiffres exacts varient selon les versions : considérez-les comme des proportions, et non comme des constantes fixes :

Le poste le plus important est presque toujours celui des définitions des outils. Cela surprend ceux qui s’attendent à ce que le prompt système domine.

Pourquoi les schémas d’outils sont si volumineux

Chaque outil que le modèle peut appeler est fourni sous forme de schéma structuré : un nom, une description et un schéma JSON complet pour ses paramètres. Un seul outil bien documenté peut représenter 500–1,500 tokens si l’on compte les descriptions de paramètres imbriqués et les énumérations. Claude Code active par défaut un large ensemble d’outils (lecture et écriture de fichiers, modification, bash, glob, grep, récupération de contenu web, lancement de tâches et d’agents, suivi des tâches à faire, etc.), et chacun est présent dans chaque requête.

Le schéma simplifié d’un outil ressemble à ceci :

{
  "name": "edit_file",
  "description": "Make a targeted edit to an existing file. Use this instead of rewriting the whole file when possible...",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "Absolute path to the file" },
      "old_string": { "type": "string", "description": "Exact text to replace, including surrounding context for uniqueness" },
      "new_string": { "type": "string", "description": "Replacement text" }
    },
    "required": ["path", "old_string", "new_string"]
  }
}

Multipliez cela par plus d’une douzaine d’outils, puis ajoutez tous les outils exposés par les serveurs MCP que vous avez connectés, et le volume des schémas augmente rapidement. Un piège courant : quelqu’un installe trois serveurs MCP « pour les essayer », chacun exposant 8–15 outils, et son volume de base augmente de 10k tokens auxquels il ne pense plus jamais.

Le contexte d’environnement que vous n’avez pas demandé

Lorsque Claude Code démarre dans un dépôt, il injecte des informations sur la situation afin que l’agent n’ait pas à consacrer un échange à des questions élémentaires. En pratique, cela comprend notamment :

Working directory: /home/ryan/projects/api-gateway
Platform: linux
Git branch: feature/rate-limiting
Git status: 4 modified, 1 untracked
Recent commits: ...

C’est réellement utile : c’est pourquoi l’agent sait déjà que vous êtes sur une branche de fonctionnalité. Mais cela représente tout de même des tokens, et dans un grand monorepo, l’instantané du répertoire peut être conséquent.

Ce que ce surcoût vous apporte réellement

Avant de chercher à éliminer ce surcoût, évaluez honnêtement le compromis. Ces 33k permettent à Claude Code, dès sa toute première réponse, de modifier le bon fichier avec le bon contexte environnant, d’exécuter vos tests, de lancer un sous-agent pour une tâche parallèle et de respecter les conventions de votre projet, sans aucune série de questions de clarification. Un agent à 7k tokens doit souvent acquérir ce contexte au fil d’échanges supplémentaires, ce qui implique davantage de requêtes, plus de latence et parfois davantage de tokens au total sur une session complète.

La comparaison n’est donc pas « 33k gaspilleurs contre 7k efficaces ». Elle oppose :

• Moins de requêtes, plus volumineuses (Claude Code) à davantage de requêtes, plus légères (agents minimalistes)
• Des capacités immédiatement disponibles à des capacités constituées à la demande
• Un coût fixe plus élevé par session à un coût variable plus élevé par tâche

Pour une session de débogage de cinq messages, le surcoût fixe s’amortit bien. Pour une demande ponctuelle d’une ligne, il semble excessif. Les deux réactions sont justifiées dans leur contexte.

Les leviers que vous maîtrisez réellement

Vous ne pouvez pas réécrire l’ensemble des outils de base de Claude Code, mais trois réglages modifient sensiblement votre volume de base.

1. Réduisez CLAUDE.md sans concession

CLAUDE.md est injecté intégralement dans chaque requête. C’est la seule partie du préambule qui vous appartient à 100 %, et c’est là que je constate le plus de gaspillage : des fichiers de 4k tokens remplis de guides de style idéalistes que le modèle suit déjà par défaut.

Gardez-le concis et essentiel. Privilégiez :

# Project: api-gateway

- Package manager: pnpm (never npm)
- Tests: `pnpm test` — must pass before any commit
- Do NOT edit files in /generated
- API errors use the AppError class in src/errors.ts

Supprimez tout ce que le modèle ferait de toute façon (« écrire du code propre », « ajouter des commentaires »). Une bonne règle pratique : si supprimer une ligne ne change pas le comportement de l’agent, elle vous coûte des tokens pour rien. Pour un contexte approfondi, placez-le dans un fichier référencé que l’agent lit à la demande au lieu de le coller dans la mémoire.

2. Désactivez les serveurs MCP et les outils inutilisés

C’est la mesure qui a le plus d’effet pour la plupart des utilisateurs. Passez en revue ce qui est réellement connecté :

claude mcp list

Si vous voyez des serveurs ajoutés il y a des mois et que vous n’utilisez jamais, supprimez-les :

claude mcp remove some-unused-server

Vous pouvez aussi restreindre les outils autorisés pour exclure leurs schémas du contexte. Dans les paramètres de votre projet ou de votre utilisateur :

{
  "permissions": {
    "allow": ["Read", "Edit", "Bash", "Grep", "Glob"],
    "deny": ["WebFetch"]
  }
}

Chaque outil que vous excluez représente un schéma dont vous ne payez pas l’envoi à chaque échange. En pratique, désactiver un seul serveur MCP verbeux m’a fait économiser plus de tokens que n’importe quel ajustement de prompt.

3. Misez largement sur la mise en cache des prompts

C’est le levier majeur, et il change entièrement le calcul. Le prompt système, les définitions des outils et le contexte stable du projet sont identiques à chaque requête au sein d’une session , ce qui les rend idéaux pour la mise en cache des prompts. Les tokens d’entrée en cache sont nettement moins chers que les nouveaux tokens, si bien que ce préambule de 33k perd l’essentiel de son importance après le premier appel.

Claude Code utilise automatiquement la mise en cache, mais vous pouvez l’aider en veillant à ce que la partie stable de votre contexte reste vraiment stable :

• Évitez de réécrire CLAUDE.md en cours de session : une modification invalide le cache de tout ce qui suit.
• Placez le contexte statique au début ; gardez les détails variables dans vos messages, pas dans le préambule.
• L’ordre compte : la mise en cache porte sur un préfixe, donc toute modification au début invalide tout ce qui suit.

En pratique : optimisez le nombre de tokens de votre première requête pour réduire le coût, mais optimisez votre session pour favoriser les accès au cache. Un préfixe stable de 33k qui se met correctement en cache est souvent moins cher sur une véritable session de travail qu’un préfixe de 7k qui n’est jamais mis en cache parce qu’il est reconstruit à chaque échange.

Si vous exécutez des charges de travail agentiques à grande échelle et surveillez de près les coûts par token, c’est aussi là qu’un accès API moins cher, comme celui qu’AI Prime Tech propose pour les modèles Claude, se combine avantageusement avec de bonnes pratiques de mise en cache.

Conseils pratiques à retenir

• Le coût de démarrage d’environ 33k provient surtout des schémas d’outils, et non du prompt système. Les définitions des outils et les serveurs MCP dominent le budget.
• C’est un compromis, pas du gaspillage. Le surcoût apporte des capacités immédiates et réduit les allers-retours conversationnels ; les agents plus légers déplacent le coût du fixe vers le variable.
• Passez d’abord vos serveurs MCP en revue. Supprimer les serveurs inutilisés et interdire les outils inutilisés est la mesure de réduction la plus efficace.
• Gardez CLAUDE.md essentiel. Supprimez tout ce que le modèle fait par défaut ; référencez la documentation approfondie pour une lecture à la demande au lieu de la coller.
• Concevez votre contexte pour favoriser les accès au cache, pas seulement pour réduire la première requête. Un préambule stable qui se met correctement en cache est préférable à un préambule minuscule reconstruit à chaque échange.
• Mesurez par session, pas par message. Évaluez le surcoût sur l’ensemble de la tâche, où les coûts fixes s’amortissent.