Claude Code et Codex : réduire le gaspillage de tokens avec trois fichiers markdown

Les agents IA de développement brûlent leur contexte non pas parce qu'ils répondent mal, mais parce qu'ils passent presque tout leur temps à chercher le bon endroit dans le code. Même avec une fenêtre d'un million de tokens, ils re-parcourent les répertoires, relisent des fichiers déjà connus et vérifient les serveurs comme s'ils découvraient le projet. L'analyse montre que, pour une simple question sur les paiements, l'agent a consommé plus de 80 000 tokens et plus de 15 appels d'outils, alors que la réponse elle-même tenait en environ 800 tokens.

Autrement dit, la quasi-totalité du budget est partie non pas dans le raisonnement, mais dans la navigation. Le problème n'a rien d'une particularité de Claude Code : c'est une limite commune aux agents de code actuels. Cursor, Codex et Gemini CLI fonctionnent selon le même schéma : sans carte de l'espace de travail, ils entament chaque nouvelle session par une phase de reconnaissance.

Avec un seul projet, c'est supportable. Mais quand un développeur gère des dizaines de dépôts, de VPS et d'environnements de staging, l'agent commence par lancer un grep sur le répertoire personnel, tombe sur des fichiers similaires dans des projets voisins, les lit, comprend qu'il fait fausse route, puis relance un nouveau cycle de recherche. Dans un cas réel, une question sur les moyens de paiement d'un bot s'est transformée en recherche à travers plusieurs projets, en relecture de six fichiers et même en vérification de configuration par SSH sur le serveur.

Ce mode de fonctionnement est non seulement coûteux, mais aussi fragile : le modèle s'épuise à s'orienter et passe facilement à côté des passages pertinents. L'auteur examine trois approches populaires, généralement présentées comme des remèdes. La première : le RAG et la recherche vectorielle.

Elle retrouve bien les fragments sémantiquement proches, mais comprend mal la structure d'un projet : elle peut renvoyer des chunks contenant auth, login et token, sans reconstituer la chaîne exacte de dépendances entre le middleware, la logique de refresh et la configuration JWT. Le RAG exige en outre une infrastructure dédiée, un index et des réindexations, et chaque requête ajoute de la latence. La deuxième voie : l'analyse statique et le graphe de dépendances via l'AST et tree-sitter.

Utile au sein d'un même dépôt, elle s'avère presque inutile à l'échelle d'un portefeuille de projets, où il faut savoir non seulement comment fonctionne une fonction, mais aussi où se trouve le service recherché, sur quel serveur il tourne et quel est son statut. Troisième option : maintenir un CLAUDE.md dans chaque projet.

Cela aide, mais seulement une fois que l'agent a compris dans quel projet aller. L'auteur propose à la place un contexte hiérarchique qui guide l'agent du général au particulier. Au niveau zéro se trouve une carte globale des projets : un court tableau avec les noms, les chemins, les serveurs et les statuts, injecté automatiquement dans chaque session.

Au niveau un, un CLAUDE.md à la racine de chaque projet, avec la stack, les fichiers clés, les commandes de déploiement, le nom du service et les logs. Entre les deux, on peut ajouter une couche intermédiaire sous forme de Graphify si la base de code est volumineuse et qu'un graphe précis des relations est nécessaire.

Enfin, comme troisième couche markdown, l'auteur suggère de stocker les sessions passées et les décisions techniques dans des fichiers markdown avec un frontmatter YAML, pour que l'agent puisse se rappeler ce qui a déjà été discuté, quels fichiers ont été modifiés et quelles décisions de débogage ou de paiement ont été prises la semaine précédente. L'idée est simple : d'abord la carte, puis la description du projet, ensuite la mémoire des échanges passés, et seulement après le code source. Les mesures montrent que ce schéma apporte un gain non pas cosmétique, mais concret.

Pour une question sur l'architecture d'un projet, l'agent aveugle a eu besoin de 12 tool calls, contre un seul avec la hiérarchie. Pour savoir quels projets utilisent une bibliothèque donnée, le mode aveugle a effectué 44 appels, scanné tout le disque et manqué malgré tout l'un des trois projets concernés ; la hiérarchie s'en est tenue à deux requêtes ciblées et a fourni une réponse complète. Sur le déploiement, l'effet est encore plus net : sans structure, l'agent lisait les configs et passait par SSH, alors qu'avec un CLAUDE.

md correctement rempli, il a pu répondre directement à partir du contexte, sans aucun appel supplémentaire. Conclusion importante : un contexte mieux organisé améliore non seulement la vitesse et l'économie de tokens, mais aussi la précision des réponses. Pourquoi cela fonctionne-t-il mieux qu'un pipeline RAG classique ?

Parce que les fichiers markdown offrent à l'agent une latence nulle, de la prévisibilité et une mise à jour simple. C'est le développeur qui définit ce qu'il faut savoir du projet, au lieu d'espérer que le ranker extraie les bons chunks de l'index. Si le déploiement change ou si un service migre, il suffit de corriger une ligne.

Le passage à l'échelle paraît lui aussi raisonnable : la carte des projets pèse environ 2 Ko, et quinze fichiers de projet de 5 Ko chacun représentent moins de 80 Ko de contexte structuré, au lieu de centaines de kilo-octets de code source brut. Alors que l'on parle de fenêtres de contexte d'un million de tokens, ce point compte particulièrement : plus de tokens ne signifie pas toujours mieux. L'information non pertinente dilue l'attention du modèle, et l'effet lost in the middle n'a pas disparu.

Principal enseignement de l'analyse : le problème des tokens chez les agents de code se règle le plus souvent non pas avec des modèles coûteux ni en complexifiant la stack, mais par la discipline du contexte. Une carte globale des projets, un bon CLAUDE.md et une mémoire des sessions conservée peuvent être mis en place en dix minutes à peine, et le bénéfice est immédiat : moins de recherche à l'aveugle, moins de répétitions, moins d'erreurs et un chemin plus court entre la question et le bon fichier.