Mes agents IA oublient le dépôt. Je leur ai fait une carte

Mes agents de programmation oublient le dépôt entre les sessions, alors je leur donne un chemin de lecture fixe. Quatre couches de fichiers texte leur indiquent les faits à jour, les décisions déjà prises et l’emplacement du code utile. Ils consacrent moins de contexte à redécouvrir le projet, mais tenir cette carte à jour reste la partie difficile.

Qu’est-ce qu’un système de gestion du contexte ? Un chemin de lecture fixe

Pour une modification de la facturation, mon système de gestion du contexte envoie l’agent vers un index qui désigne deux documents et un dossier. Ce chemin de lecture fixe remplace une recherche sans limites dans le dépôt, et l’agent commence par les fichiers les plus susceptibles de lui servir.

La documentation de Claude Code explique pourquoi ce point de départ doit être reproductible : « Chaque session de Claude Code commence avec une fenêtre de contexte vierge » [1]. L’agent ne connaît pas le dépôt au départ et ne conserve pas pour la session suivante ce qu’il vient d’apprendre. La continuité doit donc venir d’informations qu’il peut retrouver.

La carte ne cherche pas à conserver tout ce dont l’agent pourrait avoir besoin. Un fichier d’instructions chargé automatiquement renvoie vers l’état actuel, les décisions passées et les emplacements utiles du code, puis l’agent ne charge les détails que si sa tâche les exige. Cette première sélection compte, car elle sert de base à toutes ses décisions ultérieures.

Que coûte une session vierge ? Des tokens et de la fiabilité

Une session vierge coûte à la fois en qualité et en tokens, car l’agent doit comprendre le système avant de pouvoir le modifier. Si cet apprentissage dépend de correspondances de mots-clés, il peut manquer un détail important et produire une modification crédible, mais incorrecte. La recherche elle-même consomme aussi du contexte avant le début du travail demandé.

Charger plus de fichiers ne résout pas le problème à lui seul, car un modèle ne maintient pas le même niveau d’attention dans toute une longue fenêtre de contexte. Chroma Research a testé 18 modèles et constaté que leurs performances baissaient à mesure que l’entrée s’allongeait, même sur des tâches qu’ils réussissaient avec un prompt court [2].

Les longs contextes peuvent échouer de plusieurs façons, pas seulement par manque de place. Drew Breunig explique que les premières erreurs peuvent affecter le raisonnement ultérieur, que les actions passées peuvent distraire le modèle et que différentes parties de l’entrée peuvent se contredire. Il cite aussi une étude Databricks dans laquelle Llama 3.1 405B commençait à perdre en justesse vers 32 000 tokens. Même avec des fenêtres d’un million de tokens, les agents devenaient moins efficaces au-delà de 100 000 tokens [3].

L’équipe d’ingénierie d’Anthropic présente la même contrainte comme un budget d’attention [4]. En pratique, chaque token consacré à la compréhension du dépôt laisse moins d’attention pour la modification demandée.

Les chiffres de mon dépôt principal rendent ce compromis inévitable. Ses 418 fichiers markdown contiennent environ 7 Mo de texte, et les lire tous nécessiterait entre 5,7 et 8,75 fenêtres de 200 000 tokens selon la méthode d’estimation. L’agent doit n’en lire qu’une partie, alors j’utilise un ordre de lecture documenté au lieu de laisser les premières correspondances de mots-clés la choisir.

Quatre couches de texte placent les faits actuels avant l’historique

Le système fait passer chaque session par des règles, l’état actuel, les décisions et, si nécessaire, l’historique. Des fichiers ordinaires du dépôt rendent ces quatre couches faciles à inspecter, à relire et à mettre à jour. Cela compte davantage pour moi qu’une méthode de recherche sophistiquée.

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

chaque session

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

pointe vers

la carte

• STATE.md état actuel, à lire d'abord
• INDEX.md documents utiles à cette tâche

oriente vers

la tâche

• Documentation de la zone et code seulement ce que la modification touche
• decisions/ pourquoi le système fonctionne ainsi
• sessions/ historique, jamais une autorité

Le fichier de règles vient en premier parce que les agents le chargent automatiquement. L’Agentic AI Foundation présente AGENTS.md comme un standard ouvert utilisé par plus de 60 000 projets open source [5], tandis que Claude Code lit CLAUDE.md. La documentation de Claude Code recommande la passerelle que j’utilise : faire de CLAUDE.md un lien symbolique vers AGENTS.md et limiter ce fichier commun à 200 lignes [1].

Au départ, j’entretenais un fichier distinct pour chaque outil, mais leurs règles ont progressivement divergé. Le lien symbolique a supprimé cette source de décalage en donnant le même fichier aux deux outils et en ne me laissant qu’une seule copie à mettre à jour.

Après le fichier de règles, chaque session passe par l’état des lieux. Il indique ce qui est en production, ce qui reste en cours et, surtout, ce qui n’a pas encore été vérifié. Cette dernière catégorie empêche l’agent de traiter un travail inachevé ou une hypothèse non contrôlée comme un fait.

Les décisions et l’historique viennent ensuite. Le projet ADR définit un compte rendu de décision d’architecture comme un document consacré à une décision importante [6]. Dans mon système, chaque compte rendu explique aussi la raison de la décision. Mon dépôt en a accumulé 74 en huit semaines et, lorsqu’une décision change, un nouveau compte rendu remplace l’ancien au lieu de le réécrire. Les journaux de session ont un autre rôle : ils forment un historique auquel l’agent peut se référer, mais ne constituent jamais une source de vérité actuelle.

Un ordre d’autorité suffit à résoudre les contradictions

Ces couches ne fonctionnent que si l’agent sait comment résoudre leurs contradictions. Chaque point d’entrée du dépôt donne donc le même ordre d’autorité : le code prime sur les comptes rendus de décisions, qui priment sur l’état des lieux, lui-même prioritaire sur l’historique. Lorsqu’une recherche trouve cinq réponses rédigées à des dates différentes, l’agent peut suivre la source la plus fiable, puis mettre à jour ou signaler les autres.

Exclure l’historique du chemin de lecture normal a un effet pratique important. Les journaux de session représentent 73 % des octets de documentation dans ce dépôt. Sans eux, l’estimation nécessaire pour tout lire passe de 8,75 fenêtres de contexte à environ 2,3. La documentation actuelle reste volumineuse, mais l’agent peut s’y retrouver beaucoup plus facilement.

Comment garder les fichiers de contexte à jour ? Les modifier avec le code

Je traite la documentation comme une partie de la modification du code. Dès que le code change un fait d’architecture, le même commit doit mettre à jour le document concerné au lieu de remettre ce travail à plus tard. Le fichier d’instructions énonce cette règle dès le départ et la répète dans la vérification finale de l’agent, au moment où l’oubli est le plus difficile.

Dans mon dépôt, les agents ont suivi cette vérification plus régulièrement que les humains. Après avoir étendu la règle à la documentation destinée aux utilisateurs, la part des commits d’interface qui mettaient aussi à jour les documents correspondants est passée de 12,3 % à 31,9 %. Un taux de 31,9 % reste loin d’un respect systématique, mais il représente 2,6 fois le résultat précédent. La plupart des oublis venaient de modifications dont aucun agent n’était responsable du début à la fin.

J’applique une deuxième règle aux informations qui évoluent entre les sessions : avant de s’arrêter, l’agent rédige un bref journal de session et actualise l’état des lieux. Passer à une autre tâche déclenche la même procédure. Sans ce moment précis, une mise à jour qui semble facile à reporter devient tout aussi facile à oublier.

Pourquoi j’ai abandonné les embeddings et les serveurs MCP de mémoire

J’ai abandonné les deux parce que retrouver l’information n’était pas le problème. Ces systèmes trouvaient un contenu pertinent sans pouvoir dire de manière fiable s’il était encore actuel. Mon serveur MCP de mémoire et mon index vectoriel renvoyaient souvent le bon sujet, mais pour le mauvais mois, car les embeddings créés avant une refonte ignorent que l’architecture a changé.

Chaque solution ajoutait aussi une autre source d’informations à entretenir, ce qui recréait le problème que je cherchais à résoudre. Plusieurs frameworks de mémoire open source posaient une autre difficulté : leur code n’imposait souvent pas le comportement décrit dans le README. Dès qu’il a fallu vérifier à la fois la fraîcheur des informations et l’implémentation, j’ai cessé de les évaluer. Les agents hébergés posent la même question sur ce qui persiste entre les sessions, un point que je traite dans ce que garde l’Agents API d’OpenAI et ce que gère le harness de Codex.

Anthropic recommande de conserver dans le contexte des identifiants légers, comme des chemins de fichiers et des requêtes, puis de ne charger les détails que lorsque l’agent en a besoin [4]. Les fichiers texte conviennent bien à cette méthode, car on peut les rechercher, les comparer et les relire dans la même pull request que le code qu’ils décrivent. Un développeur peut repérer un ancien fichier markdown pendant la relecture, alors qu’un index d’embeddings obsolète est bien plus difficile à inspecter.

Combien ce système a-t-il coûté ? Moins de lecture, plus de maintenance

Le système a limité le chargement initial automatique à 0,22 % de la documentation de mon dépôt, mais il ne suffit pas à en garantir l’exactitude. Un audit mené en juillet 2026 a montré que l’état des lieux avait grossi 9,5 fois en 26 jours et contenait un avertissement obsolète.

Le dépôt est un monorepo de production d’environ 277 000 lignes de TypeScript utilisé par trois outils à base d’agents. La structure remplissait son rôle en donnant à chaque outil un point d’entrée court et un ordre de lecture cohérent. Les informations placées dans cette structure étaient nettement moins fiables. La façon dont deux des agents de programmation actuels traitent de grandes fonctionnalités fait l’objet d’une autre comparaison : Claude face à Codex sur de grandes fonctionnalités multi-agents.

de la documentation chargée automatiquement

0,22 %

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

la capacité d'une fenêtre de 200K pour tout lire

8,75×

5,7× avec l'estimation fondée sur les mots

de croissance de l'état des lieux en 26 jours

9,5×

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

Les deux premiers chiffres montrent l’intérêt de l’ordre de lecture : l’agent commence avec 0,22 % de la documentation et n’en charge davantage que si la tâche l’exige. Le troisième chiffre révèle la faiblesse persistante du système. STATE.md devait rester court et être réécrit dans le même fichier, mais sa taille a été multipliée par 9,5 en moins d’un mois. Lors de l’audit, son avertissement principal était également faux : il indiquait que plusieurs commits devaient encore être poussés alors que cela avait été fait quelques jours auparavant.

Cet avertissement obsolète n’était pas un cas isolé. La documentation du schéma indiquait que le système comportait 20 à 25 tables, tandis que le code en contenait 34. L’audit a également supprimé la documentation de fonctionnalités qui n’avaient jamais existé, puis vérifié 2 873 liens relatifs et trouvé 82 liens cassés.

La différence la plus régulière concernait les instructions écrites et les contrôles automatiques. Un test impose ma règle typographique aux textes de l’interface, où l’audit n’a trouvé aucune infraction. En revanche, environ la moitié des fichiers de documentation enfreignaient cette même règle, car aucun contrôle ne la vérifiait. En pratique, le lien symbolique et le vérificateur de types étaient les seuls éléments dont l’application était déterministe. Le compte rendu de décision qui avait introduit le système en formulait clairement la limite : « Cela réduit le taux d’échec, cela ne l’élimine pas. »

Je n’ai toujours pas trouvé la bonne quantité d’informations à charger. Si les fichiers initiaux en contiennent trop peu, l’agent doit deviner. S’ils en contiennent trop, je recrée le problème des longs contextes mesuré par Chroma Research [2]. Cet équilibre évolue avec le dépôt, alors je l’ajuste toutes les quelques semaines au lieu de considérer la structure comme terminée.

Au travail, je garde le chemin de lecture sans tout le cérémonial

Au travail, je conserve le même principe de chemin de lecture, mais je le présente comme une documentation de projet ordinaire. Le système complet reste dans mes projets personnels car, d’après mon expérience, de nombreuses équipes considèrent une structure aussi spécifique aux agents comme du vibe coding plutôt que comme une documentation destinée aux développeurs.

En pratique, la version professionnelle ressemble à une documentation de projet classique : un point d’entrée clair, des documents stables pour chaque domaine et un index qui explique où trouver les informations. Ces fichiers markdown aident les nouveaux collègues, et les agents de programmation peuvent aussi les suivre.

Les deux versions ne diffèrent pas seulement par leur apparence. Au travail, les équipes prennent des décisions en réunion et sur des tableaux de planification. Le dépôt ne peut donc pas contenir tout l’historique des décisions quand une grande partie se trouve ailleurs. Mes projets personnels n’ont pas de registre externe équivalent : si je n’écris pas une décision dans le dépôt, la session suivante ne peut pas la retrouver.

Par où commencer ? Un fichier de règles de moins de 200 lignes

Je commencerais par un fichier de règles de moins de 200 lignes qui précise les conventions du dépôt et l’ordre dans lequel l’agent doit lire les autres fichiers. La documentation de Claude Code conseille d’ajouter une règle lorsque l’agent répète une erreur [1], et j’utilise le même signal pour entretenir mon système. Une erreur répétée signifie que le chemin de lecture n’a pas expliqué un point assez clairement.

Le reste peut arriver quand le besoin apparaît. Ajoutez un fichier d’état et référencez-le dans les règles, puis créez un index lorsque la documentation ne tient plus sur un écran. Rédigez le premier compte rendu de décision lorsqu’un agent remet en question un choix déjà arrêté, et ajoutez un dossier d’historique quand vous devez conserver les travaux passés sans les présenter comme la vérité actuelle. Un chemin de lecture clair a aussi changé la qualité du travail d’un modèle chez moi, ce que je décris dans mon workflow Opus 5 fait de plans clairs et de tâches plus petites.

Ensuite, entretenez ces fichiers avec le même soin que le code. Mon article précédent défendait des backends assez petits pour qu’un agent puisse les comprendre. Ce système applique le même principe aux informations que le code ne peut pas expliquer seul. L’agent commencera toujours chaque session sans mémoire, mais un chemin de lecture bien entretenu lui permet de trouver le bon contexte sans parcourir tout le dépôt.