Universal Claude.md – Réduire les tokens de sortie de Claude

 (github.com/drona23)
2 points par GN⁺ 2026-04-01 | 1 commentaires | Partager sur WhatsApp
  • Un fichier de configuration qui réduit le gaspillage de tokens de sortie en supprimant chez les modèles Claude les introductions, conclusions et reformulations inutiles
  • En ajoutant CLAUDE.md à la racine du projet, l’effet est appliqué immédiatement sans modifier le code, avec une réduction moyenne de 63 % des tokens
  • Les réponses sont condensées grâce à 12 règles, dont sortie ASCII uniquement, interdiction de spéculer et limitation stricte au périmètre demandé
  • L’impact sur les coûts est important dans les environnements à fort volume de sortie, comme les pipelines d’automatisation, la génération de code ou les boucles d’agents, mais cela peut être inefficace pour une requête unique
  • Publié sous licence MIT, le projet permet une gestion des règles par profils, selon l’équipe ou la tâche, ainsi que des contributions de la communauté

Aperçu du problème

  • Dans Claude Code, chaque mot généré entraîne un coût en tokens, et les paramètres par défaut laissent peu de contrôle à l’utilisateur sur le format des réponses
  • Par défaut, le modèle ajoute automatiquement des formules de politesse d’ouverture comme "Sure!" ou "Great question!", des conclusions formelles comme "I hope this helps!", des reformulations de la question et des suggestions inutiles
  • Il utilise aussi des caractères susceptibles de casser les parseurs, comme les tirets cadratins, guillemets intelligents et caractères Unicode, et peut produire une abstraction excessive du code ou des marques d’accord erronées
  • Résultat : un gaspillage de tokens avec très peu de valeur informationnelle réelle

Solution

  • Ajouter un fichier CLAUDE.md à la racine du projet permet à Claude Code de le lire automatiquement et de modifier immédiatement son comportement de sortie
  • Cela fonctionne sans changement de code ni configuration supplémentaire, avec une baisse d’environ 63 % de l’usage des tokens de sortie
  • Exemple de structure 
    your-project/
└── CLAUDE.md

Cas favorables et défavorables

  • Cas favorables

    • Pipelines d’automatisation, boucles d’agents, génération de code et autres tâches à fort volume de sortie

      • Quand les réponses verbeuses et répétitives de Claude s’accumulent dans des tâches structurées et récurrentes
      • Dans un environnement d’équipe où un format de sortie cohérent entre les sessions est nécessaire

  • Cas défavorables

    • Pour une requête courte unique ou un usage ponctuel, CLAUDE.md consomme lui-même des tokens d’entrée à chaque fois, ce qui peut au contraire augmenter le coût
    • Aucun effet sur la correction des hallucinations ou des erreurs d’architecture nécessitant une résolution en profondeur
    • Dans les pipelines qui ouvrent une nouvelle session à chaque tâche, l’avantage lié à une session persistante disparaît
    • Pour garantir la fiabilité d’un parseur à grande échelle, un mode JSON ou des outils basés sur un schéma sont plus adaptés
    • Cela peut sembler trop contraignant pour des travaux exploratoires ou centrés sur la discussion

  • Compromis réel

    • Comme CLAUDE.md consomme lui-même des tokens d’entrée, le bénéfice net n’apparaît que lorsque le volume de sortie est suffisamment élevé
    • Pour les usages à faible volume, le coût peut être supérieur aux économies réalisées

Résultats du benchmark

  • Test réalisé avec les mêmes 5 prompts
    Test Standard Optimisé Réduction
    Explication de async/await 180 mots 65 mots 64 %
    Revue de code 120 mots 30 mots 75 %
    Explication d’une API REST 110 mots 55 mots 50 %
    Correction d’hallucination 55 mots 20 mots 64 %
    Total 465 mots 170 mots 63 %
  • Environ 295 mots économisés, sans perte d’information
  • Il s’agit toutefois d’un indicateur de tendance : aucun contrôle statistique ni expérimentation répétée n’a été effectué
  • Le gain net n’apparaît que dans les cas de fort volume de sortie

  • Exemple d’économies à grande échelle

    Volume d’usage Tokens économisés par jour Économie mensuelle (base Sonnet)
    100 fois/jour environ 9 600 environ $0.86
    1 000 fois/jour environ 96 000 environ $8.64
    3 projets environ 288 000 environ $25.92

Exemple avant/après

  • Réponse standard à une revue de code (120 mots)

    • Inclut des compliments verbeux, des explications et des suggestions

  • Après application de CLAUDE.md (30 mots)

    • Transmet uniquement l’essentiel, sous une forme comme "Bug: <= causes an off-by-one error...", avec une réduction de 75 % des tokens

Éléments modifiés

N° Problème Méthode de correction
1 Introduction flatteuse Interdite - commencer la réponse dès la première ligne
2 Conclusion creuse Interdite - suppression de "I hope this helps!"
3 Reformulation de la question Interdite - exécution immédiate
4 Tirets cadratins, guillemets intelligents, Unicode Sortie ASCII uniquement imposée
5 Formule du type "As an AI..." Interdite
6 Avertissements inutiles Autorisés uniquement en cas de risque réel pour la sécurité
7 Suggestions hors demande Interdites - exécuter uniquement ce qui est demandé
8 Abstraction excessive du code Seul le code fonctionnel le plus simple est autorisé
9 Hallucinations sur des faits incertains Dire explicitement "je ne sais pas", spéculation interdite
10 Ignorer les corrections de l’utilisateur Les corrections deviennent des faits de référence pour la session
11 Relecture de fichiers en doublon Interdite pour un même fichier
12 Extension du périmètre Interdiction de modifier du code hors demande

Conseils de la communauté

  • Rédiger les règles en fonction des schémas d’échec réellement observés est le plus efficace
    • Exemple : si Claude avale les erreurs d’un pipeline -> ajouter une règle du type "en cas d’échec d’une étape, arrêter immédiatement et signaler l’erreur complète ainsi que la traceback"

  • Le fichier CLAUDE.md peut être fusionné de manière hiérarchique

    • Global (~/.claude/CLAUDE.md) : règles générales (ton, ASCII, etc.)
    • Racine du projet : contraintes propres au projet (ex. : interdiction de modifier /config)
    • Sous-répertoires : règles détaillées par tâche
    • Cela permet de répartir la gestion des règles et d’éviter qu’un fichier ne devienne trop volumineux

Configuration par profils

  • Il est possible de choisir un niveau de compression différent selon le type de projet
    Profil Usage recommandé
    CLAUDE.md Générique
    profiles/CLAUDE.coding.md Développement, revue de code, débogage
    profiles/CLAUDE.agents.md Automatisation, systèmes multi-agents
    profiles/CLAUDE.analysis.md Analyse de données, recherche, reporting

Mode d’emploi

Règle de priorité

  • Les commandes utilisateur priment toujours

    • Si l’utilisateur demande explicitement, par exemple, "explique en détail", Claude s’y conforme tel quel
    • CLAUDE.md n’entrave pas l’intention de l’utilisateur

Comment contribuer

  • Si vous identifiez un comportement perfectible, ouvrez une Issue
    1. Le comportement par défaut problématique
    2. Le prompt qui l’a déclenché
    3. La règle corrective proposée
  • Les propositions de la communauté seront intégrées dans une prochaine version, avec crédit attribué aux contributeurs

Vérification et références

  • Les résultats complets du benchmark sont disponibles dans BENCHMARK.md
  • Le projet a été conçu à partir de cas réels de mécontentement dans la communauté Claude
  • De nombreuses sources de référence associées sont incluses (issues GitHub, The Register, DEV Community, Medium, Anthropic Docs, etc.)

Licence

  • Licence MIT, utilisation, modification et redistribution libres

À lire aussi

1 commentaires

 
GN⁺ 2026-04-01
Commentaires sur Hacker News

  • Le benchmark ici est biaisé vers des tâches explicatives uniques et ne me semble pas adapté aux boucles agentiques comme la génération de code
    Je me demande si, quand un projet est en cours, les explications verbeuses de Claude n’aident pas au contraire à maintenir la cohérence et la concentration de la session
    La règle « ne pas répéter le contexte redondant » est bonne, mais je pense au contraire qu’utiliser davantage de jetons de raisonnement orientés objectif peut aider
    On manque encore de données pour savoir si cette approche est réellement efficace en codage agentique

    • J’ai créé une skill appelée /handoff pour générer automatiquement un rapport Markdown avant que la session n’atteigne sa limite de compression
      Ce fichier sert d’archive permanente de la session et de « rapport quotidien », ce qui le rend pratique pour y revenir plus tard ou le partager à un manager
      Pour préserver la cohérence à long terme, je pense qu’une telle méthode de documentation résumée est meilleure
      J’ai publié la méthode d’installation ici
    • La règle « n’explique pas ce que tu vas faire, fais-le simplement » m’a permis de repérer immédiatement quand Claude partait dans la mauvaise direction et de corriger le prompt
    • Je ne comprends pas pourquoi les gens n’ajoutent pas à CLAUDE.md des règles pour bloquer le langage inutile
      D’après des recherches récentes, les chemins de raisonnement redondants (self-consistency) et les ensembles de modèles aident à améliorer les performances
    • Le scaling du temps de raisonnement est aussi important. Utiliser plus de jetons pour trouver une réponse améliore au contraire la qualité
      S’obséder sur une longueur minimale va à l’encontre de l’objectif d’apprentissage RL
    • J’ai lancé des tests de code avec plusieurs configurations, et dans l’ensemble cette approche a montré des performances inférieures sur 30 essais
      Le code de test est ici

  • Le planning mode de Claude Code ne fonctionne pas correctement, donc je suis sceptique vis-à-vis de l’approche par fichiers .md
    À mon avis, le planning mode devrait simplement être une fonctionnalité qui désactive l’écriture de fichiers

  • La règle « la réponse toujours à la 1re ligne, le raisonnement ensuite » ignore la nature autorégressive des LLM
    Fixer d’abord la réponse fait courir au raisonnement ultérieur un risque de biais de confirmation

    • L’idée de cette approche est bonne, mais la mise en œuvre me semble mauvaise
      Une méthode qui compresse le raisonnement, comme dans l’article Compressed Chain of Thought (CCoT), serait plus efficace
      Il y a une légère perte de qualité, mais des gains en vitesse et en coût (lien vers l’article)
    • Dans les sessions importantes, j’ajoute un prompt de seconde vérification comme « sanity check » pour réexaminer le plan initial
    • Les LLM de raisonnement peuvent générer en interne des milliers de jetons de raisonnement avant d’écrire la réponse
      Autrement dit, la règle « réponse d’abord » ne change que l’ordre de sortie, pas l’ordre réel du raisonnement
    • Claude Code n’a pas d’option « no thinking », et au minimum le mode low thinking est activé par défaut

  • Ce benchmark est dépourvu de sens car il compare seulement le nombre de jetons de sortie sans tenir compte de la précision
    Il serait facile d’obtenir un bon score avec un prompt du type « réponds toujours en un seul mot »
    Des règles comme « si l’utilisateur signale une erreur factuelle, accepte-la sans discuter » sont dangereuses

    • On parle de « retour du prompt engineering ? », mais ces 1 à 2 dernières années les méta-prompts n’ont guère apporté d’amélioration
    • Des règles du type « ne fais pas d’erreurs » ne sont pas réalistes

  • Je pense que ce genre de solution universelle risque surtout de perdre vite son intérêt ou d’être absorbé par CC
    Changer fréquemment de workflow est trop fatigant
    La configuration par défaut de Claude Code est pour l’instant la plus stable

    • Je pense pareil. Garder un paramétrage vanilla me semble meilleur sur le long terme
      J’aime bien les Skills, mais je n’utilise presque jamais MCP ni worktree
    • Comme Anthropic optimise déjà cela en interne par dogfooding, il est probable que les réglages par défaut soient les plus efficaces
      Il suffit de traiter CLAUDE.md comme une note de brouillon destinée à un collègue intelligent pour que cela fonctionne très bien
    • Je suis d’accord avec l’idée que « ça finira intégré à CC »
      Si Anthropic ne l’a pas ajouté directement, c’est probablement parce que le gain de performance n’a pas été démontré
    • Ces « couches d’amélioration de Claude » finissent surtout par provoquer une instabilité du workflow
      Même si elles sont utiles un temps, elles sont vite absorbées par les fonctions natives ou disparaissent
    • Claude lui-même reçoit en continu des fonctions d’optimisation md
      Donc, même en utilisant ce genre de scripts expérimentaux, on peut rester à jour en actualisant souvent les fichiers md

  • À la question « si le fichier est chargé dans le contexte à chaque message, n’est-ce pas du gaspillage de jetons ? »,
    je pense que la fonction de personnalisation de Claude joue déjà ce rôle
    À mes yeux, la concision n’a de valeur que lorsqu’elle améliore la qualité
    Les outils connexes vus sur Reddit sont aussi intéressants :
    Headroom compresse le contexte de 34 %,
    RTK compresse la sortie CLI de 60 à 90 %,
    MemStack fournit une mémoire persistante pour éviter des relectures de fichiers inutiles

  • J’ai l’impression que ce genre de tentative résulte plutôt d’une mauvaise compréhension des principes de base des LLM
    « Réponse d’abord, raisonnement ensuite » ignore la structure autorégressive des transformers
    Comme l’apprentissage RL ajuste déjà la longueur optimale et la qualité, des modifications excessives peuvent entraîner une baisse de performance

    • Si on réduit de force la longueur des réponses, la qualité du raisonnement et la cohérence se dégradent, et le risque d’hallucination augmente
      Le modèle a été entraîné à effectuer un raisonnement en plusieurs étapes à partir de l’anglais
    • La règle « réponse d’abord » ne change pas l’ordre réel du raisonnement. Le modèle a déjà terminé sa réflexion en interne avant de produire la réponse
    • L’auteur ne semble pas ignorer les transformers, il essaie plutôt un hack pour réduire le coût en jetons
      C’est une approche expérimentale qui vise l’efficacité plus que la qualité
    • La plupart des API proposent déjà des options de contrôle de la longueur du COT. Mieux vaut utiliser les réglages d’API que ce genre de contournement
    • Au final, je pense que les outils conçus par Anthropic sont les plus fiables.
      C’est pourquoi je n’utilise que des outils first-party plutôt que des solutions tierces comme OpenCode

  • Comme on le voit dans la vidéo de Karpathy, plus le modèle utilise de jetons, plus la précision a tendance à augmenter
    Cette approche pourrait au contraire dégrader le modèle

    • Cela dit, si l’objectif ici est de réduire les sorties de faible valeur (par ex. flatteries, bruit de formatage), cela peut se défendre
      Mais forcer le modèle à donner directement une réponse sans raisonnement risque de créer un biais de fixation précoce
    • Une sortie redondante sert à renforcer la direction suivie, donc la supprimer peut accroître l’ambiguïté

  • Je ne comprends pas pourquoi ce genre de projet sans intérêt devient tendance sur HN
    Les vrais outils pour réduire l’usage des jetons sont claude-mem et lumen

    • La raison est simple. L’algorithme de tendance de HN est optimisé pour l’engagement plutôt que pour l’exactitude

  • Autrefois, on faisait de la recherche sur de nouveaux algorithmes de hachage, de chiffrement et de compression
    Aujourd’hui, l’ironie est qu’on cherche comment dire à une IA de se taire