Combien de tokens coûte un fichier CLAUDE.md ?

CLAUDE.md est un fichier Markdown d'instructions permanentes que Claude Code place dans la fenêtre de contexte au démarrage. Il ne fait pas partie du prompt système : Claude Code l'envoie comme message utilisateur juste après celui-ci. Claude le traite comme une consigne, pas comme une configuration garantie.

Le modèle ne garde rien entre les requêtes. Claude Code renvoie donc tout le contexte à chaque appel : prompt système, projet, messages antérieurs et résultats d'outils. Chaque usage d'outil crée un appel. Une demande qui fait lire cinq fichiers puis lancer les tests peut ainsi produire plusieurs requêtes contenant chacune votre CLAUDE.md entier.

Chaque ligne est donc payée à chaque requête : moins cher tant que le cache tient, plus cher lorsque le préfixe doit être réécrit. Gardez le fichier court et déplacez ce qui n'est pas utile à chaque tâche vers des fichiers chargés au besoin.

Quels fichiers sont chargés et quand

Claude Code réunit tous les fichiers de mémoire trouvés, sans qu'un niveau remplace le précédent. En septembre 2026, sa documentation distingue les sources suivantes :

• →Règle administrée : un CLAUDE.md déployé dans toute l'organisation, par exemple /etc/claude-code/CLAUDE.md sur Linux. On ne peut pas l'exclure.
• →Utilisateur : ~/.claude/CLAUDE.md et ~/.claude/rules/, appliqués à tous vos projets.
• →Projet : ./CLAUDE.md ou ./.claude/CLAUDE.md, ainsi que les règles .claude/rules/ sans champ paths, partageables dans Git.
• →Local : ./CLAUDE.local.md, notes personnelles propres au projet, ajoutées à .gitignore.
• →Mémoire automatique : les 200 premières lignes ou 25 Kio de l'index MEMORY.md. Les fichiers thématiques qu'il indique ne sont lus qu'au besoin.

Les fichiers du répertoire courant et de ses parents sont chargés au lancement. Le CLAUDE.md d'un sous-répertoire n'arrive que quand Claude y lit un fichier ; une règle dotée de paths n'arrive que pour un fichier concerné. Les imports sont trompeurs : @path/to/file charge immédiatement le fichier visé, jusqu'à quatre niveaux. Découper un long fichier en imports améliore le rangement, sans économiser de tokens.

Pourquoi le cache ne rend pas le fichier gratuit

Avec le cache des prompts, l'API compare le début de la requête avec les données traitées récemment et facture la partie identique à tarif réduit. Claude Code place en tête les éléments stables : prompt système et outils, puis contexte du projet et fichiers de mémoire, enfin conversation. Sur un tour ordinaire, CLAUDE.md est donc une lecture du cache.

Aux prix publics de l'API Anthropic en septembre 2026, cette lecture coûte un dixième du tarif d'entrée sur la plupart des modèles Claude, et moins sur quelques nouveaux modèles. Une écriture coûte 1,25 fois le tarif de base pour cinq minutes, ou deux fois pour une heure. Dès que le préfixe doit être reconstruit, CLAUDE.md revient plus cher que de l'entrée ordinaire. Plusieurs situations le provoquent :

• →Une pause au-delà de la durée du cache : une heure pour la conversation principale avec un abonnement Claude dans l'usage inclus, cinq minutes par défaut avec une clé API.
• →Un changement de modèle, chacun ayant son cache, ou de niveau d'effort sur la plupart des modèles.
• →Une modification des outils placés avant le fichier, par exemple la connexion d'un serveur MCP dont les définitions sont chargées d'emblée.
• →Un sous-agent autre que les agents intégrés Explore et Plan : chacun charge les CLAUDE.md dans son propre contexte et construit son propre cache, de cinq minutes par défaut même sur abonnement.
• →Une session lancée dans un autre arbre de travail ou répertoire, car le cache est pratiquement lié au répertoire.

Le cache change le prix, pas la taille. Le fichier occupe la fenêtre à chaque requête et laisse moins de place avant le compactage automatique. Les fichiers longs sont également moins bien suivis, chaque règle recevant moins d'attention. Sur abonnement, il n'y a pas de facture au token, mais le même contexte consomme vos limites d'usage.

Mesurer ce que coûte le vôtre

Ouvrez une nouvelle session et, avant toute demande, regardez ce qui occupe déjà la fenêtre :

$/context

/memory liste vos fichiers de mémoire et permet d'en ouvrir un dans l'éditeur. Depuis Claude Code v2.1.251, /usage ajoute une ligne Prompt cache (main) montrant la part de l'entrée servie depuis le cache et le nombre de ratés. Si ce nombre augmente, le préfixe, fichiers de mémoire compris, est réécrit régulièrement.

Ce qui doit y rester

Pour Anthropic, la question à poser à chaque ligne est simple : sa suppression ferait-elle commettre une erreur à Claude ? Sinon, retirez-la. Le contenu réellement nécessaire est généralement court :

• →Commandes de compilation, de test et de contrôle que Claude ne peut pas deviner.
• →Règles de style différentes des défauts, sans répéter ce qu'impose déjà le formateur.
• →Conventions du dépôt : noms de branches, commits et demandes de fusion.
• →Décisions d'architecture propres au projet.
• →Particularités de l'environnement, comme une variable obligatoire ou un service à lancer.
• →Pièges dont le comportement peu évident a déjà coûté du temps.

Rédigez des règles vérifiables : « Lancez npm test avant le commit » est plus utile que « testez vos modifications ». La documentation vise moins de 200 lignes par fichier.

Quoi déplacer, et où

La plupart des éléments d'un CLAUDE.md trop long ne sont pas erronés ; ils se trouvent au mauvais endroit. Chaque catégorie a une place moins coûteuse :

• →Ce que Claude peut lire dans le code, comme l'arborescence, les dépendances et les descriptions de fichiers : supprimez-le.
• →Une longue référence d'API ou un guide de style : conservez-le séparément et mentionnez son chemin sans @, afin que Claude ne l'ouvre que si la tâche le demande.
• →Une procédure en plusieurs étapes, comme une liste de livraison : transformez-la en skill. Seule sa courte description charge au départ ; le reste attend son usage.
• →Des règles limitées à une partie du code : un fichier .claude/rules/ avec paths, ou un CLAUDE.md dans le sous-répertoire concerné.
• →Une action obligatoire après chaque modification, comme le formatage : un hook. Il n'occupe pas le contexte s'il ne renvoie aucune sortie, et il s'exécute réellement.

Comment le raccourcir

Commencez par l'outil fourni avec Claude Code. Depuis v2.1.206, /doctor suggère des coupes dans un CLAUDE.md versionné : contenu déductible du code, habitudes sans valeur et consignes à déplacer vers des skills ou fichiers imbriqués. Il garde les pièges, leurs raisons et les conventions particulières.

$/doctor

Faites ensuite quelques vérifications manuelles :

• →Supprimez une règle que Claude suit déjà spontanément, puis vérifiez si son comportement change.
• →Placez les notes pour les mainteneurs dans des commentaires HTML en bloc <!-- ... -->, retirés avant l'envoi au modèle.
• →Résolvez les contradictions : deux règles opposées coûtent deux fois et Claude peut suivre l'une ou l'autre.
• →Dans un monorepo, excluez les fichiers des autres équipes avec claudeMdExcludes.
• →Pour un sous-agent personnalisé qui n'en a pas besoin, définissez omitClaudeMd: true (v2.1.271 ou plus).

AGENTS.md et Codex CLI

Codex CLI lit AGENTS.md à la place. D'après sa documentation en septembre 2026, il construit une chaîne d'instructions une fois par exécution, généralement une fois par session interactive :

• →Global : dans ~/.codex, ou CODEX_HOME s'il est défini, AGENTS.override.md s'il existe, sinon AGENTS.md.
• →Projet : de la racine, généralement celle de Git, au répertoire de lancement, au plus un fichier par niveau : AGENTS.override.md, puis AGENTS.md, puis les noms de project_doc_fallback_filenames.
• →Codex les joint de la racine vers le répertoire courant, ignore les fichiers vides et s'arrête à project_doc_max_bytes, soit 32 Kio par défaut.

Le résultat entre dans le premier tour, puis accompagne toutes les requêtes. Pour prolonger les limites d'usage, Codex conseille de réduire AGENTS.md et de placer les règles dans les répertoires concernés. En septembre 2026, sa grille de crédits facture l'entrée en cache à un dixième de l'entrée fraîche, sans frais distincts d'écriture. Pour voir les instructions reçues par le modèle :

$codex debug prompt-input

Un fichier peut servir aux deux agents. Depuis v2.1.277, Claude Code lit AGENTS.md s'il ne trouve ni CLAUDE.md ni CLAUDE.local.md dans le répertoire de travail ou ses parents. Sinon, placez @AGENTS.md au début de CLAUDE.md. Claude Code ne lit pas AGENTS.override.md.

Le coût fixe et le coût variable

Raccourcir les instructions diminue la part fixe de chaque requête. Le reste dépend de ce que la tâche ajoute : fichiers lus, sorties de commandes et historique. Indiquer le fichier concerné et ouvrir une session par tâche réduit cette part.

Pour lui imposer un plafond, capsul pilote le Claude Code ou Codex CLI auquel vous êtes déjà connecté, envoie ce que demande la tâche sous le budget de tokens fixé et indique ce qu'il a écarté. Les résultats mesurés figurent sur la page du banc d'essai.