Discipline des tokens pour Claude Code : notre bilan honnête

Nous passons nos journées à mesurer les skills Claude des autres, et un même schéma revenait sans cesse dans la télémétrie : les sessions qui coûtaient cher ne coûtaient pas cher parce que Claude rédigeait de longues réponses. Elles coûtaient cher à cause de ce que Claude lisait. Des fichiers entiers ouverts pour trouver une seule fonction. Des fichiers relus juste après une modification réussie, « histoire de vérifier ». Un JSON de 16 000 enregistrements chargé dans le contexte comme s'il s'agissait d'un article de blog.

Nous avons donc construit un skill qui s'attaque à ce poste de la facture, l'avons publié sous licence MIT, et avons fait ce que nous exigeons de chaque skill que nous référençons : le benchmarker face à une baseline avec des runs contrôlés, puis publier les chiffres — y compris ceux qui ne l'avantagent pas.

Ce skill s'appelle token-discipline. Il est gratuit : github.com/Skillproofdev/token-discipline.

La faille commune à tous les skills de gestion des tokens étudiés

Avant d'écrire la moindre ligne, nous avons passé en revue huit skills et protocoles d'économie de tokens déjà publiés — depuis le ruleset de sobriété des sorties qui domine la niche avec ses 5 800 étoiles, jusqu'à des skills « d'urgence » qui se déclenchent à 40 % de contexte utilisé, en passant par des protocoles annonçant 76–93 % d'économies sans aucun mécanisme identifiable ni la moindre télémétrie.

Presque tous partagent le même angle mort : ils optimisent la sortie. Supprimer le préambule, raccourcir les réponses, arrêter de reformuler le plan. C'est réel, mais c'est la moitié la moins coûteuse de la facture. Dans les sessions agentiques — Claude Code qui travaille réellement dans un dépôt — c'est l'entrée qui domine : chaque fichier lu, chaque résultat de recherche, chaque sortie d'outil atterrit dans le contexte et repart à chaque requête suivante.

Trois techniques côté entrée n'apparaissaient dans aucun des huit sous forme de règle contraignante :

1. Chercher avant de lire. Localiser d'abord avec grep/glob, puis ne lire que la zone correspondante. Ne jamais ouvrir un fichier entier pour trouver quelque chose.
2. Regrouper les appels d'outils indépendants. Si trois lectures ne dépendent pas les unes des autres, elles doivent tenir dans un seul message. Chaque tour supplémentaire refacture des tokens de réflexion et de narration entre les appels.
3. Faire confiance à l'état déjà connu. Après une modification réussie de votre part, ne relisez pas le fichier pour vérifier — l'outil d'édition échoue bruyamment en cas d'échec. Les relectures servent aux changements externes, pas aux vôtres.

Ces trois règles forment le cœur du skill. Autour d'elles s'ajoutent six autres règles : lire des extraits plutôt que des fichiers entiers, interroger les gros JSON et logs avec python ou jq plutôt que de les ouvrir, résumer puis abandonner les sorties longues, déléguer l'exploration large à des subagents, garder le contexte compatible avec le cache (préfixe stable intact — le blog d'ingénierie d'Anthropic désigne le prompt caching comme le facteur de coût le plus déterminant), et, oui, la sobriété des sorties aussi. Neuf règles, chacune formulée comme une règle stricte assortie d'une alternative explicite, de sorte que la suivre ne coûte jamais en justesse.

Comment nous l'avons benchmarké

Même protocole que notre série Skill Bench : même modèle, même prompt, une seule variable. Chaque tâche a été exécutée deux fois — un agent Claude Sonnet sans skill, un autre qui lisait d'abord le SKILL.md et devait le suivre à la lettre. Les totaux de l'agent avec skill incluent le coût de lecture du skill lui-même. Le banc d'essai était notre propre base de code : un site Astro d'environ 9 000 lignes de templates, plus un jeu de données JSON de 16 682 enregistrements — assez volumineux pour qu'une lecture indisciplinée coûte réellement cher.

Cinq paires de tâches, choisies pour couvrir tout le spectre, du trivial au vraiment multi-étapes :

Tâche	Baseline	Avec skill	Δ
Q&R sur la base de code — 8 questions tous sous-systèmes confondus	88 419	71 636	−19,0 %
Modification multi-fichiers — 4 changements coordonnés	68 219	54 637	−19,9 %
Traçage de code — one-shot	53 986	52 850	−2,1 %
Balayage d'audit — one-shot	44 691	44 705	+0,0 %
Digest de gros JSON — one-shot	42 726	45 164	+5,7 %

Ce que disent vraiment les chiffres

Sur un vrai travail multi-étapes, le skill fait économiser environ 20 %. Le Q&R en huit questions sur la base de code est ce qui se rapproche le plus d'une session de travail normale : tracer le flux d'authentification, expliquer le webhook, retrouver la logique de tri. L'agent baseline a répondu correctement, mais en chemin il a lu généreusement et vérifié de façon redondante. L'agent discipliné a répondu aux mêmes questions, avec la même précision (nous avons vérifié chaque référence file:line des deux côtés), pour 16 783 tokens de moins.

La modification multi-fichiers est le résultat le plus intéressant. Quatre changements coordonnés sur quatre fichiers. L'agent baseline a terminé puis — pour citer son propre rapport — a « vérifié en relisant les zones modifiées ». Cette seule habitude représente un cinquième de la facture. L'agent avec skill a appliqué les quatre mêmes changements, a sauté les relectures de pure forme, et a signalé la tâche terminée. Nous avons comparé les deux arborescences de travail : les modifications étaient équivalentes et correctes dans les deux cas. Rien n'a été perdu en faisant confiance à l'outil pour signaler bruyamment un échec, car c'est exactement ce que font les outils.

Sur les tâches simples en one-shot, c'est neutre — et nous le publions quand même. La tâche de digest JSON a en réalité coûté 5,7 % de plus avec le skill. Deux raisons, toutes deux instructives. D'abord, le skill lui-même coûte environ 1 400 tokens à lire, et une tâche qui se termine en deux appels d'outils ne laisse aucune marge pour amortir ce surcoût. Ensuite, un modèle de génération actuelle se comporte déjà bien sur les tâches faciles : l'agent baseline a jeté un œil à un JSON de 16 682 enregistrements et est directement passé par python plutôt que de l'ouvrir. Aucun skill nécessaire. La discipline paie là où l'indiscipline est possible — sessions longues, nombreux fichiers, contexte qui s'accumule — pas là où il n'y a rien à gaspiller.

Si vos sessions sont surtout des one-liners, le skill apporte sa propre réponse : un bloc condensé de 60 tokens que vous collez dans le CLAUDE.md au lieu d'installer le skill complet. Toujours actif, il coûte à peu près autant que cette phrase, et une seule lecture de fichier entier évitée le rentabilise plusieurs fois. (Nous avons construit un calculateur pour cette taxe permanente — le calcul sur les descriptions de déclencheurs s'applique aussi aux blocs de règles.)

Les neuf règles, en bref

Le SKILL.md complet fait environ 1 400 tokens et se lit en un seul écran ; voici sa structure :

1. Chercher avant de lire. D'abord grep ; puis lire le résultat ±30 lignes. Lire plus de ~200 lignes exige une raison formulable en une phrase.
2. Lire l'extrait, pas le fichier. Offset+limit pour tout ce qui est long ; python/jq pour tout ce qui est structuré. Un gros JSON est une base de données, pas un document.
3. Regrouper les appels d'outils indépendants. Un seul message, plusieurs appels, dès lors que les sorties n'alimentent pas les entrées suivantes.
4. Faire confiance à l'état déjà connu. Pas de relecture de vérification après vos propres modifications ; pas de relance de recherches dont les résultats sont déjà dans le contexte.
5. Ne pas recopier le code. Référencer file:line. Ne coller que ce que l'humain doit voir pour décider.
6. Résumer, puis abandonner. Après une sortie d'outil longue, ne garder que 2 à 5 faits, ne jamais redemander le log.
7. Déléguer l'exploration lourde. Les balayages larges vont à un subagent ; les lectures lourdes meurent dans son contexte, pas dans le vôtre.
8. Garder le contexte compatible avec le cache. Préfixe stable intact ; ajouter, ne pas réécrire ; surveiller le TTL du cache.
9. Discipline de sortie. Répondre d'abord, pas de préambule, pas de pavés de diff.

S'y ajoutent un point de contrôle d'auto-audit (trois questions avant toute relecture importante) et une liste explicite de choses à ne pas faire, parce qu'un skill de tokens qui pousse un agent à sauter une vérification nécessaire ne fait rien économiser — il reporte simplement le travail. Si une véritable traque de bug exige de lire le fichier entier, la règle dit de le lire, en indiquant la raison.

Sa place dans l'équation globale des coûts

Des règles comme celles-ci constituent la moitié variable de votre facture. La moitié fixe — le préambule de 30 000 tokens des serveurs MCP, les fichiers CLAUDE.md trop chargés et les descriptions de skills toujours actives, renvoyées littéralement à chaque requête — est un problème différent, avec des correctifs différents, et généralement le gain le plus important pour les gros utilisateurs. Nous avons détaillé cet audit dans Réduire sa consommation de tokens Claude : 6 correctifs ; les deux articles se complètent : corrigez les coûts fixes une bonne fois pour toutes, puis laissez token-discipline maintenir les coûts variables au plus bas pendant toute la session.

Et si vous vous demandez si les skills en général font économiser des tokens : notre série Skill Bench a mesuré quatre skills populaires et a constaté que, la plupart du temps, ce n'est pas le cas — ils coûtent des tokens supplémentaires et achètent de la qualité et de la discipline à la place. token-discipline a été construit spécifiquement pour être l'exception, et même ainsi, il ne se rentabilise que sur le travail multi-étapes. C'est la limite honnête, et nous préférons la tracer nous-mêmes plutôt que de vous laisser la découvrir sur votre facture.

Installation

git clone https://github.com/Skillproofdev/token-discipline ~/.claude/skills/token-discipline

Redémarrez Claude Code. Il se déclenche sur « reduce token usage », « work token-efficiently », les plaintes de limite de contexte et les questions de coût — ou appliquez-le à toute la session via le bloc CLAUDE.md fourni à l'intérieur.

FAQ

Est-ce que cela remplace les skills de sobriété des sorties ? Non — il en inclut le cœur (règle 9) et ajoute le volet entrée qu'ils ignorent. Si vous utilisez déjà un ruleset de sortie concise, token-discipline le recoupe sur une règle sur neuf.

Est-ce que cela va rendre Claude plus négligent ? Le benchmark répond non : la modification multi-fichiers est ressortie équivalente et correcte des deux côtés, et la liste des choses à ne pas faire du skill protège explicitement les vérifications réellement nécessaires. Les règles remplacent les relectures de pure forme, pas les relectures nécessaires.

Pourquoi le skill lui-même est-il si court ? Parce qu'un skill d'économie de tokens qui coûterait des milliers de tokens à charger à chaque session friserait l'autoparodie. Le SKILL.md fait environ 1 400 tokens, chargés à la demande ; le bloc CLAUDE.md toujours actif fait environ 60 tokens.

Je suis sur un abonnement Pro/Max, pas sur l'API. Est-ce que ça change quelque chose ? Oui, en monnaie de plafond d'usage : les mêmes tokens qui facturent les utilisateurs de l'API consomment vos quotas d'utilisation. Vingt pour cent de tokens en moins sur les sessions de travail, c'est proportionnellement plus de travail possible avant d'atteindre le plafond.

Le benchmark a-t-il été trié sur le volet ? Les cinq tâches ont été conçues avant l'exécution de l'une ou l'autre variante, et nous avons publié les deux résultats où le skill perd. La télémétrie brute — nombre de tokens et nombre d'appels d'outils par run — se trouve dans le README du dépôt.