Un développeur déplace le contexte de l'agent IA des chats vers le dépôt : l'utilitaire doubled-graph

Lorsque vous remplacez Claude Code par Codex ou un autre outil, la première pensée est : comment transférer l'historique des chats. L'auteur de cette analyse sur Habr estime que c'est la mauvaise question. Depuis six mois, il conserve le contexte du projet non pas dans les conversations, mais dans le dépôt, et affirme que changer d'agent n'est plus douloureux.

Pourquoi l'historique des chats est une mauvaise mémoire

La conversation conserve un échange autour du projet, pas les décisions finales. On y trouve du bruit, des répétitions, des idées abandonnées et des « ok » polis. Le nouvel agent doit tout lire et réinterpréter, sans moyen de vérifier son interprétation : le chat ne contient ni contrats, ni frontières de modules, ni critères de recette qu'on pourrait confronter au code.

Il y a un second inconvénient. La reconstitution du contexte devient une taxe à chaque nouvelle session. Chaque changement d'outil oblige à rassembler à nouveau les connaissances et à déterminer lequel des messages contradictoires était le dernier.

L'auteur propose un test simple de portabilité. Ouvrez le dépôt dans un agent qui n'a jamais vu le projet et donnez-lui un seul prompt : « lis ce qu'il y a ici et explique-moi comment le projet est conçu et ce qui s'y passe actuellement ». Si la réponse est exacte, le contexte vit réellement dans le dépôt.

Ce que contient le dépôt

La base est la méthodologie GRACE d'osovv (licence MIT) : l'intention, les frontières des modules et les vérifications sont stockées à côté du code. L'auteur a ajouté trois éléments : un scénario de migration du code existant, un graphe d'appels via CodeGraphContext et une enveloppe MCP. Ensemble, cela forme l'utilitaire doubled-graph.

Le code est balisé par des commentaires-ancres appariés. Un module possède un MODULE_CONTRACT avec son objectif, son périmètre et ses dépendances, une fonction possède un CONTRACT avec ses entrées, ses sorties et ses effets de bord, et la logique est découpée en blocs. Le champ LINKS relie le fichier au module, de sorte qu'un simple grep sur un identifiant comme M-AUTH-VALIDATE fournit à l'agent quelques paragraphes utiles au lieu de quarante fichiers. Le linter vérifie l'appariement des ancres, leur unicité et leur conformité aux exports réels.

Il y a deux graphes. Declared décrit l'intention et se trouve dans .grace/graph/. Computed est construit à partir de l'AST et montre la réalité : qui appelle qui. L'outil detect_changes les compare et trouve les écarts : code sans module, module sans code, dépendances obsolètes, module sans vérification, fichier sans balisage. Un hook post-commit met à jour le graphe computed, et detect_changes peut être branché sur le pre-commit ou la CI. Avant une modification, l'agent demande aussi quels éléments le changement va affecter.

Migration des anciens projets

Les méthodes du type « d'abord la spécification, ensuite le code » meurent généralement sur un projet vieux de dix ans, où il n'y a pas de spécification mais où le code fonctionne. Il existe donc deux modes. En migration, la vérité est dans le code : l'agent reconstitue l'intention, balise les fichiers et franchit des portes d'approbation humaine. En post_migration, la vérité est dans les artefacts, et tout écart est suspect. Trois issues sont alors possibles : mettre à jour l'artefact via un lot de modifications, ramener le code au contrat, ou consigner l'écart dans DRIFT.md et bloquer le module.

Une idée à part est le belief-state. Aux points critiques, l'agent écrit dans le journal quelle hypothèse non évidente il a retenue, avec l'ancre et le session_id. Lorsque, des mois plus tard, un log de production arrivera, on pourra restaurer l'état de l'IA à cet endroit.

Limites et conclusion

L'auteur prévient honnêtement : il n'y aura pas de chiffres, il n'a pas mené d'expérience contrôlée, tout repose sur des impressions. De plus, la méthode est exigeante : selon lui, il faut appliquer les dix principes dans leur ensemble, et une adoption partielle ne vaut pas l'effort. Le balisage par ancres ajoute du bruit dans le code, et les portes d'approbation ralentissent les corrections rapides. Pour de petits projets, cela peut être excessif.

Mais l'idée mérite l'attention même sans la méthodologie complète. Si vous travaillez avec plusieurs agents, placez dans le dépôt au moins les contrats de modules, le graphe de dépendances et la liste des vérifications, et laissez la CI détecter les écarts avec le code. Le résultat est facile à vérifier : donnez à un agent neuf ce fameux prompt unique. Pour essayer : pipx install doubled-graph, puis doubled-graph setup et le prompt de démarrage du dossier prompts.