Tokens bruts ingérés en 7 jours
Coût pondéré réel (ce que vous payez)
Réduction du coût effectif par session
L'autonomie a un coût caché. Sorti de la boîte, Claude Code est un gouffre à tokens. Conçu pour la fluidité au détriment de l'efficacité économique, l'agent ingère aveuglément des milliers de lignes de logs, saturant son Context Window. Le résultat ? Une latence qui s'effondre, une facture d'API qui explose, et un LLM amnésique.
J'ai conçu une architecture en 6 phases pour discipliner cet agent via des Hooks et des Skills. Sur 14 sessions et 285 millions de tokens bruts, le coût pondéré réel est tombé à 50 millions d'unités. Ce n'est pas de la théorie. Ce sont mes logs JSONL.
L'architecture : intercepter avant que ça ne coûte
Claude Code fonctionne en boucle d'exécution. Votre prompt entre. Claude raisonne (tokens de thinking). Il appelle un outil : Read, Bash, Edit. Le résultat entre dans le Context Window. La boucle recommence. Chaque tour empile du contenu dans une fenêtre finie. Quand elle sature, Claude perd ses instructions initiales. La qualité s'effondre. La facture, elle, continue.
Le point d'intervention chirurgical : le PreToolUse Hook. Il se déclenche avant que l'outil ne s'exécute, avant que les tokens n'entrent dans le contexte. Si le fichier fait plus de 300 lignes, le hook le bloque et renvoie un message à Claude : utilise grep -n ou head à la place. Le hook ne suggère pas. Il décide.
#!/bin/bash
# .claude/hooks/guard-large-read.sh — PreToolUse Hook
INPUT=$(cat)
FILE=$(echo "$INPUT" | python3 -c "
import json, sys
print(json.load(sys.stdin).get('tool_input', {}).get('file_path', ''))
" 2>/dev/null || echo "")
if [ -z "$FILE" ] || [ ! -f "$FILE" ]; then exit 0; fi
LINES=$(wc -l < "$FILE" 2>/dev/null || echo 0)
if [ "$LINES" -gt 300 ]; then
python3 -c "
import json
print(json.dumps({
'decision': 'block',
'reason': '$FILE has $LINES lines. Use grep -n pattern $FILE | head -20'
}))
"
exit 0
fi
exit 0Ce hook s'est déclenché 75 fois en une semaine. Chaque blocage a intercepté entre 1 500 et 50 000 tokens. Faites le calcul : c'est potentiellement 3,75 millions de tokens gaspillés qui n'ont jamais atteint le Context Window.
Règle FinOps : Claude interprète vos demandes. Un Hook s'exécute, quoi qu'il arrive. C'est la différence entre une suggestion et une contrainte système. Ne confondez jamais un prompt poliment formulé avec une barrière d'architecture.
Le paradigme de Co-Coding : l'humain est le routeur
Le mythe de l'autonomie totale est le piège financier le plus cher de l'écosystème LLM. Laisser un agent explorer librement une codebase, c'est lui donner une carte bancaire illimitée dans un supermarché. Il achètera tout ce qui brille.
Voici un exemple concret, tiré de mon flux de travail quotidien : les agents sont bloqués par les hooks (Read > 300 lignes + Bash refusé en sous-agents). Que se passe-t-il ? Je fais l'extraction directement. 10 secondes. 0 token de recherche. Le contexte de Claude reste propre.
Ce n'est pas un frein. C'est une architecture de répartition des rôles :
L'humain est le routeur High-Level. Il a la cartographie mentale du projet. C'est lui qui fait l'extraction sémantique chirurgicale : copier les 15 lignes pertinentes d'un fichier de 2 000 lignes, ça prend 10 secondes et ça coûte 0 token de recherche.
L'agent est le générateur Low-Level. Il reçoit un contexte ultra-précis et produit la complexité syntaxique : refactoring, génération de code, tests unitaires. Forcer Claude à demander des autorisations n'est pas un frein. C'est un checkpoint FinOps indispensable pour éviter qu'il ne crame du budget dans des boucles infinies.
L'enjeu est clair : chaque token qui entre dans le Context Window est un coût irrécupérable. Le co-coding n'est pas un compromis entre vitesse et contrôle. C'est l'architecture optimale. L'humain route. L'agent génère. Les hooks arbitrent.
Le reste de l'arsenal : Skills, sous-agents et compaction
Tout ce qui est dans CLAUDE.md est chargé à chaque tour de conversation. Trois workflows mal placés ? C'est 2 400 tokens facturés par tour, même quand ils sont inutiles. La solution : les déplacer vers des Skills. Au démarrage, Claude ne charge que le nom (40 tokens). Le contenu complet se charge uniquement quand le skill est invoqué.
Pour l'exploration de codebase, je délègue à un sous-agent Haiku, dix fois moins cher que Sonnet, dans une fenêtre de contexte isolée. Il explore. Il retourne un résumé JSON de 200 mots maximum. La session principale reçoit la réponse, pas le bruit du chemin d'exploration.
Enfin, /compact toutes les 30 minutes remplace l'historique par un résumé dense. Et /clear entre les tâches. Mon CLAUDE.md fait 35 lignes : préférences de style et choix d'outils. Rien d'autre.
Passez à l'action : deux ressources, deux usages
Ces chiffres ne viennent pas d'un benchmark artificiel. Ils proviennent de mes vrais logs JSONL, analysés avec le script inclus dans le dépôt. Deux dépôts GitHub, deux fonctions distinctes :
Le Tool (Plug & Play)
github.com/papasega/claude-code-token-optimization
Le prompt chirurgical qui exécute l'audit et l'optimisation en 6 phases, en totale autonomie. Collez-le dans Claude Code. Il analyse vos settings, installe les hooks, mesure l'avant/après. Temps d'exécution : 5 minutes.
Le Framework (Gouvernance d'équipe)
github.com/papasega/claude-code-best-practice-playbook
Le playbook complet avec les règles de gouvernance, l'architecture des settings et les patterns de co-coding pour déployer Claude Code à l'échelle d'une équipe. Du prompt individuel au framework organisationnel.
285 millions de tokens bruts ne sont pas un problème. 50 millions d'unités pondérées sur 14 sessions, 75 blocages interceptés, un Context Window toujours propre. L'objectif n'a jamais été d'utiliser moins de tokens. L'objectif est de faire en sorte que chaque token qui entre dans la fenêtre serve la tâche en cours. Le reste n'a pas le droit d'entrer.