Chaque session repart de zéro. Donnez une carte à l'agent

Un système de gestion du contexte, c’est un ensemble de fichiers texte, versionnés dans le dépôt, qui met une carte entre les mains d’un agent IA fraîchement démarré : quoi lire d’abord, où vit la vérité actuelle, quelles décisions sont closes. Le mien a connu plusieurs refontes. Voici la version qui a survécu, coûts mesurés inclus.

Qu’est-ce qu’un système de gestion du contexte ?

Un ensemble de fichiers qui dit à l’agent où regarder au lieu de le laisser chercher : un fichier d’instructions que chaque session charge d’elle-même, et qui pointe vers les quelques documents disant ce qui est vrai en ce moment, ce qui a été décidé et pourquoi, et où vit le code de chaque zone.

La condition de départ qui le justifie figure noir sur blanc dans la documentation de Claude Code : « Chaque session de Claude Code commence avec une fenêtre de contexte vierge » [1]. Chaque session est une nouvelle recrue amnésique. Compétente, mais qui n’a jamais vu votre dépôt et ne se souviendra jamais de l’avoir vu.

La comparaison à laquelle je reviens toujours, c’est Google Maps. Quand je demande un changement de facturation dans un dépôt cartographié, la première lecture de l’agent le route : le fichier de règles pointe vers un index, l’index a une ligne pour la facturation, la ligne nomme deux documents et un dossier. Il y va. Sans la carte, il fait des grep, ouvre ce qui correspond et assemble son image du système à partir des cinq fichiers qu’il a vus en premier, par hasard.

Cette image est le produit. Tout ce que l’agent fait ensuite en hérite.

Que coûte vraiment une session vierge ?

Deux choses : de la qualité et des tokens. Un agent qui s’oriente à la chance des mots-clés comprend le système trop superficiellement et livre des changements plausibles mais faux. Et l’orientation elle-même consume la fenêtre de contexte avant que le vrai travail commence, ce qui se révèle être la moitié la plus chère.

Le contexte n’est pas une ressource plate qu’on dépense sans compter. Chroma Research a évalué 18 modèles et constaté que la performance se dégrade à mesure que l’entrée s’allonge, même sur des tâches qu’un prompt court résout proprement [2]. Drew Breunig a catalogué les modes d’échec : des contextes qui s’empoisonnent avec des erreurs antérieures, qui poussent le modèle à répéter des actions passées ou qui se contredisent en interne ; il cite une étude Databricks où la justesse commence à chuter vers 32 000 tokens sur Llama 3.1 405B, et des agents qui déclinent au-delà de 100 000 tokens sur des modèles à fenêtre d’un million [3]. L’équipe d’ingénierie d’Anthropic appelle ce budget par son nom, l’attention : chaque token dépensé à s’orienter est de l’attention que le modèle n’a plus pour le changement demandé [4].

Mon dépôt principal rend l’arithmétique concrète. Son corpus de documentation compte 418 fichiers markdown, environ 7 Mo de texte. Tout lire coûterait entre 5,7 et 8,75 fois une fenêtre de contexte de 200 000 tokens, selon la méthode d’estimation. Ça ne rentre pas, et aucune feuille de route de modèles ne le fait rentrer élégamment. La question n’a donc jamais été de savoir si l’agent lit un sous-ensemble. C’est qui choisit ce sous-ensemble : l’agent, à la chance du grep, ou moi, par conception.

Quatre couches et une phrase

Le système où j’ai atterri, ce sont quatre couches de texte brut. Rien n’y est astucieux, et après avoir vu échouer les versions plus astucieuses (j’y viens), je considère que c’est la qualité principale.

AGENTS.md            # the rules; auto-loaded (CLAUDE.md is a symlink to it)
docs/
  STATE.md           # current truth: live, in flight, not yet verified
  INDEX.md           # the router: which docs to read for which task
  decisions/         # one numbered file per decision; superseded, never edited
  sessions/          # history: what happened when, explicitly not authority

Le fichier de règles est la porte d’entrée parce que c’est le seul fichier que les agents chargent d’eux-mêmes. AGENTS.md est un standard ouvert utilisé par plus de 60 000 projets open source [5] ; Claude Code lit CLAUDE.md à la place, et sa documentation recommande exactement le pont que j’utilise, un symlink, avec une cible de taille sous les 200 lignes [1]. Le mien a passé ses premières semaines en deux fichiers séparés, entretenus depuis deux outils différents, et les règles ont divergé en silence jusqu’à ce que le symlink règle le problème par construction. Un fichier, tous les agents, dérive impossible.

L’instantané est ce que le fichier de règles ordonne de lire en premier à chaque session : ce qui est en production, ce qui est en cours et, le plus précieux en pratique, ce qui n’est explicitement pas vérifié. Un agent qui sait qu’une chose n’est pas vérifiée cesse de s’y fier. Les registres de décisions suivent le motif ADR, un fichier qui capture une décision unique et son raisonnement [6] ; mon dépôt en a accumulé 74 en huit semaines, et une nouvelle décision remplace l’ancien fichier au lieu de l’éditer, donc la piste reste honnête. L’historique est la pile de journaux de session, en ajout seul, autorisée à être énorme précisément parce que rien n’a le droit de s’appuyer dessus.

Une seule phrase tient les couches ensemble, répétée à chaque porte d’entrée du dépôt : le code bat les registres de décisions, les registres battent l’instantané, l’instantané bat l’historique. Cet ordre est le vrai système. Une recherche par mot-clé dans un dépôt de cette taille renvoie cinq résultats de cinq époques ; la phrase dit à l’agent lequel gagne, et que les perdants se corrigent ou se signalent, jamais ne se croient en silence.

chaque session

• AGENTS.md règles et ordre de lecture, chargé automatiquement

pointe vers

la carte

• STATE.md vérité actuelle, à lire d'abord
• INDEX.md quels documents pour cette tâche

route vers

la tâche

• Docs de zone et code seulement ce que le changement touche
• decisions/ pourquoi c'est ainsi
• sessions/ historique, jamais une autorité

La couche d’historique exilée mérite la plus petite boîte du diagramme avec un chiffre : les journaux de session représentent 73 % de tous les octets de documentation de ce dépôt. Retirez-les du scénario tout-lire et le corpus restant tombe de 8,75 fenêtres de contexte à environ 2,3. Déclarer l’historique non autoritatif n’est pas du rangement. C’est ce qui rend le reste navigable tout court.

Qu’est-ce qui empêche la carte de mentir ?

Une règle, surtout : les docs font partie du changement. Un changement qui modifie un fait d’architecture met à jour le document concerné dans le même commit, pas dans un nettoyage qui ne vient jamais. Le fichier d’instructions de l’agent le dit, et le répète dans une auto-vérification au moment précis où l’agent décide qu’il a fini, parce que c’est le moment où les instructions ont son attention de façon fiable.

Ça marche mieux avec des machines que ça n’a jamais marché avec des humains, pour une raison peu flatteuse : un agent exécute réellement la vérification prescrite. Quand j’ai étendu la règle à la documentation destinée aux utilisateurs, la part des commits touchant l’UI qui mettaient à jour les docs correspondants dans le même commit est passée de 12,3 % à 31,9 %. Pas une conformité totale, mais 2,6 fois plus, et les ratés se concentrent là où aucun agent ne possédait le changement de bout en bout.

La seconde habitude coûte moins cher : l’agent écrit un court journal de session et rafraîchit l’instantané avant de s’arrêter, de sa propre initiative, en traitant « l’utilisateur est passé à autre chose » comme un signal de fin. La documentation qui attend que quelqu’un ait envie de documenter ne survit pas au contact d’un mardi ordinaire.

Pourquoi pas des embeddings ou un serveur MCP de mémoire ?

Parce que c’est ce que j’ai essayé en premier, et ça échouait toujours pareil : la récupération n’a jamais été le problème, la fraîcheur, si. Un serveur MCP de mémoire avec un index vectoriel devant mes dépôts renvoyait fidèlement le bon sujet du mauvais mois, et un embedding de l’architecture de mars n’a aucun moyen de savoir que le refactor de mardi l’a invalidé. Chacun de ces montages était en plus un second système dont je devais désormais entretenir la véracité, exactement l’échec que la carte existe pour empêcher. Et sur plusieurs des frameworks de mémoire open source que j’ai évalués, l’écart entre ce que promettait le README et ce que le code imposait était assez large pour que j’arrête d’évaluer.

Le guide de context engineering d’Anthropic atterrit là où j’ai atterri : garder en contexte des identifiants légers, chemins de fichiers et requêtes, et laisser l’agent charger le détail juste à temps plutôt que de précalculer tout ce dont il pourrait avoir besoin [4]. Les fichiers texte ont la propriété qui compte le plus pour cette stratégie : ils vieillissent au grand jour. On peut les passer au grep, au diff, et les relire dans la même pull request que le code qu’ils décrivent. Un markdown périmé est au moins visiblement périmé. Un index d’embeddings périmé trompe avec une confiance totale.

Les coûts honnêtes, mesurés

En juillet 2026, j’ai passé tout l’appareil de mon dépôt principal à un audit en lecture seule, un monorepo de production d’environ 277 000 lignes de TypeScript travaillé par trois outils d’agent différents. Version courte : la structure tient, la discipline de prose non.

des docs chargés automatiquement

0,22 %

un fichier de règles de 15,5 Ko contre un corpus de 7 Mo

d'une fenêtre 200K pour tout lire

8,75×

5,7× avec l'estimation par mots

de croissance de l'instantané en 26 jours

9,5×

de 75 lignes à 711, sans jamais rétrécir

L’écart entre les deux premiers chiffres, c’est tout le design : l’agent part de 0,22 % et navigue vers l’extérieur. Le troisième chiffre est l’échec permanent du design. L’instantané avait pour charte d’être un petit fichier réécrit sur place, et il a grossi de 9,5 fois en moins d’un mois. Pire : au moment de l’audit, son affirmation d’en-tête était fausse. Il avertissait qu’une pile de commits attendait d’être poussée alors que le push avait eu lieu des jours plus tôt. Le fichier que chaque session lit en premier affirmait un fait périmé avec une confiance totale.

Ce n’était pas le seul mensonge que l’audit a fait remonter. La première fois que j’ai synchronisé la documentation avec le code, le doc du schéma annonçait 20 à 25 tables là où le code en avait 34, et la passe a supprimé de la documentation pour des fonctionnalités qui n’avaient jamais existé. Sur 2 873 liens relatifs dans les docs, 82 étaient cassés. Et ma règle typographique fétiche tient à exactement zéro violation dans les chaînes d’UI, où un test l’impose, pendant qu’à peu près la moitié des fichiers de docs la casse, là où rien ne l’impose. Le motif est net : une règle en prose pourrit en proportion de sa distance à un test. Les seules parties déterministes de tout le système sont un symlink de neuf octets et le vérificateur de types. Le registre de décision qui a adopté la structure l’a dit d’emblée : « Cela réduit le taux d’échec, cela ne l’élimine pas. »

Le problème que je n’ai pas résolu, c’est le dosage. Trop peu dans la carte et l’agent devine ; trop et j’ai reconstruit la dégradation de contexte long de cette courbe de Chroma avec mes propres fichiers [2]. Je réajuste l’équilibre toutes les quelques semaines, et je pense que ce sera toujours le cas.

La version light que j’utilise au travail

Tout ce qui précède est mon montage de projets personnels, et je ne l’apporterais pas tel quel à un employeur. Dans un cadre professionnel, d’après mon expérience, autant d’appareillage d’agent se lit comme du vibe coding, et les équipes qui veulent l’IA comme outil de productivité plutôt que comme autrice autonome ont peu d’appétit pour un dépôt qui semble construit pour la machine. Juste ou pas, la perception fait partie de l’ingénierie.

Au travail, je déploie donc la même idée déguisée en ce qu’elle est aussi, sincèrement : de la documentation bien faite. Une porte d’entrée claire, des docs de zone aux noms stables, un index qui dit ce qui vit où. Des fichiers markdown qu’un nouveau collègue vous remercierait d’avoir écrits, et qui font au passage office de carte pour l’agent.

La séparation a une cause structurelle, pas seulement optique. Au travail, les décisions se prennent hors du dépôt, en réunion et sur le board, donc une couche du dépôt revendiquant l’autorité sur les décisions mentirait par omission dès le premier jour. Dans les projets personnels, il n’y a pas de dehors : si une décision n’est pas écrite dans le dépôt, elle cesse d’exister à la fin de la session. La version hardcore n’est pas de la discipline en plus pour le plaisir. C’est ce qu’exige un dépôt quand il est le seul endroit où quoi que ce soit peut vivre.

Par où je commencerais

Un fichier de règles sous les 200 lignes qui fixe les conventions et l’ordre de lecture ; la documentation de Claude Code suggère de l’enrichir chaque fois que l’agent refait la même erreur [1], ce qui est aussi le meilleur déclencheur de maintenance que je connaisse. Un fichier d’état vers lequel il pointe. Un index la semaine où les docs ne tiennent plus sur un écran. Des registres de décisions la première fois que l’agent rouvre un débat que vous aviez clos il y a un mois, et un dossier d’historique le jour où vous voulez une trace sans vouloir vous y fier.

Ensuite, traitez la carte comme du code. Quand l’agent se trompe deux fois de la même façon, le bug est en général dans la carte, et le correctif tient en une phrase dans le bon fichier. Le dernier texte que j’ai écrit plaidait pour des backends assez petits pour qu’un agent les garde en tête. Ceci est le même argument, pointé vers tout ce que le code ne peut pas dire de lui-même. L’agent ne cessera jamais de démarrer à vide. La carte est ce qui empêche que ça coûte cher.