Claude Code et Codex : comment réduire les pertes de tokens avec trois fichiers markdown

Les agents IA pour le développement consomment du 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 parcourent à nouveau les répertoires, relisent des fichiers familiers et vérifient des serveurs comme s'ils voyaient le projet pour la première fois. Une analyse montre que pour une simple question sur les paiements, l'agent a dépensé plus de 80 000 tokens et plus de 15 appels d'outils, alors que la réponse elle-même n'a pris qu'environ 800 tokens.

En d'autres termes, presque tout le budget a été dépensé non pas en réflexion, mais en navigation. Le problème s'est avéré ne pas être une particularité locale de Claude Code, mais une limitation générale des agents de codage modernes. Cursor, Codex et Gemini CLI fonctionnent de la même manière : sans une carte de l'espace de travail, ils commencent chaque nouvelle session par une reconnaissance.

S'il y a un projet, c'est tolérable. Mais quand un développeur a des dizaines de dépôts, des instances VPS et des environnements de staging, l'agent d'abord fait grep le répertoire home, trouve des fichiers similaires dans les projets voisins, les lit, puis réalise qu'il a pris le mauvais chemin et lance une nouvelle ronde de recherche. Dans un exemple concret, une question sur les méthodes de paiement dans un bot s'est transformée en une recherche sur plusieurs projets, une relecture de six fichiers et même une vérification SSH de la configuration du serveur.

Un tel mode n'est pas seulement coûteux, mais aussi fragile : le modèle gaspille de l'énergie en orientation et manque facilement les endroits pertinents. L'auteur examine trois approches populaires qui sont généralement proposées comme remède. La première est RAG et la recherche vectorielle.

Elle trouve bien les fragments sémantiquement similaires, mais comprend mal la structure du projet : elle peut retourner des chunks avec auth, login et token, mais ne pas restaurer la chaîne exacte de dépendances entre le middleware, la logique de rafraîchissement et la configuration JWT. De plus, RAG nécessite une infrastructure séparée, un index et une réindexation, et chaque requête ajoute de la latence. Le deuxième chemin est l'analyse statique et les graphes de dépendances via AST et tree-sitter.

C'est utile au sein d'un dépôt, mais presque inutile au niveau d'un portefeuille de projets, où vous devez répondre non seulement à la question de savoir comment fonctionne une fonction, mais aussi où vit exactement le service nécessaire, sur quel serveur il s'exécute et quel est son statut. La troisième option est de conserver CLAUDE.md dans chaque projet.

Cela aide, mais seulement après que l'agent a déjà compris dans quel projet aller. Au lieu de cela, un contexte hiérarchique est proposé, qui guide l'agent de haut en bas. Au niveau zéro se trouve une carte mondiale des projets : un tableau court avec des noms, des chemins, des serveurs et des statuts, qui entre automatiquement dans chaque session.

Au premier niveau se trouve CLAUDE.md à la racine d'un projet spécifique avec la stack, les fichiers clés, les commandes de déploiement, le nom du service et les logs. Entre eux, une couche intermédiaire peut être ajoutée sous la forme de Graphify si la base de code est grande et qu'un graphe exact des dépendances est nécessaire.

Et comme troisième couche markdown, l'auteur propose de stocker les sessions passées et les solutions d'ingénierie sous forme de fichiers markdown avec un frontmatter YAML, de sorte que l'agent puisse se souvenir de ce qui a déjà été discuté, quels fichiers ont été modifiés et quelles solutions de débogage ou de paiement ont été prises une semaine plus tôt. L'idée est simple : d'abord la carte, puis la description du projet, puis la mémoire des discussions passées, et seulement ensuite le code source. Les mesures montrent qu'un tel schéma offre des gains non cosmétiques mais pratiques.

Pour une question sur l'architecture du projet, l'agent aveugle a eu besoin de 12 appels d'outils contre un seul avec la hiérarchie. Pour une question sur quels projets utilisent une bibliothèque spécifique, le mode aveugle a fait 44 appels, a balayé tout le disque et a tout de même manqué l'un des trois projets nécessaires ; la hiérarchie s'est inscrite dans deux requêtes précises et a donné une réponse complète. Dans le cas du déploiement, l'effet est encore plus remarquable : sans structure, l'agent lisait les configs et allait par SSH, mais avec un CLAUDE.

md correctement rempli, il a pu répondre directement à partir du contexte sans aucun appel supplémentaire. La conclusion importante ici est qu'un contexte plus organisé augmente non seulement la vitesse et l'économie de tokens, mais aussi la précision de la réponse. Pourquoi cela fonctionne-t-il mieux que le pipeline RAG familier ?

Parce que les fichiers markdown donnent à l'agent une latence nulle, de la prévisibilité et des mises à jour simples. Le développeur lui-même détermine ce qui est exactement important à savoir sur le projet, plutôt que d'espérer que le classifieur extraiera les chunks nécessaires de l'index. Si le déploiement a changé ou qu'un service a déménagé, il suffit de corriger une ligne.

La scalabilité semble aussi raisonnable : la carte des projets occupe environ 2 KB, et quinze fichiers de projet de 5 KB chacun donnent moins de 80 KB de contexte structuré au lieu de centaines de kilobytes de code source brut. Sur le fond de discussions sur des fenêtres d'un million de tokens, c'est particulièrement important : plus de tokens ne signifie pas toujours mieux. Les informations non pertinentes brouillent l'attention du modèle, et l'effet lost in the middle persiste toujours.

La principale conclusion de l'analyse est que le problème des tokens dans les agents de codage devrait généralement être résolu non pas par des modèles coûteux et non pas en compliquant la pile, mais par la discipline du contexte. Une carte mondiale des projets, un bon CLAUDE.md et une mémoire de sessions sauvegardées peuvent être assemblés littéralement en dix minutes, et le bénéfice apparaît immédiatement : moins de recherche aveugle, moins de répétitions, moins d'erreurs et un chemin plus court de la question au fichier nécessaire.