Comment je travaille avec les agents d'IA : un guide pratique sur le contexte et la mémoire

Plus je m’aventure dans l’univers des outils de programmation avec l’IA, plus je continue de trouver des modèles, des benchmarks, du “raisonnement” et toutes sortes de marketing et de “wishful thinking”. Mais avant tout, j’ai constaté que ce qui sépare vraiment un agent qui vous fait gagner des heures d’un agent qui vous en fait perdre, ce n’est pas le modèle sous-jacent (même si cela aide), c’est le contexte que vous lui donnez (ainsi que la mémoire qu’il conserve de ce qui a été décidé a priori). La plupart des critiques et guides d’outils oublient cette partie. Je partage ceci à partir de mon expérience professionnelle, avec les outils que j’utilise actuellement au quotidien.

Pour moi, il est plus facile de penser à un agent d’IA comme à un collègue rapide et compétent qui vient d’arriver et qui n’a pas encore vu votre codebase. À une telle personne, vous ne lui donneriez pas un ticket en espérant qu’elle le résolve à l’aveuglette. Vous lui demanderiez de s’asseoir, vous lui montreriez le projet, vous lui expliqueriez ce qui a été décidé la semaine dernière et pourquoi, et ce n’est qu’ensuite que vous la laisseriez travailler. Tout l’enjeu avec ces outils est d’obtenir ce comportement, de manière systématique, avec une gestion du contexte et de la mémoire plutôt que de l’espoir. En pensant à mon expérience personnelle, l’intégration (onboarding) pouvait prendre de 2 semaines à 3 mois selon la complexité du projet (je l’ai vécu personnellement), alors comment pourrions-nous faire un onboarding correct pour une IA ?

D’abord le contexte, puis le code

Actuellement, l’erreur la plus courante que je vois est des gens qui demandent à un agent de “corriger ceci” sans lui donner plus d’informations. Ce n’est presque jamais la faute de l’agent, c’est la nôtre. Nous voulons un partenaire intelligent et nous le traitons comme un simple champ de recherche. Je lui fais donc lire d’abord le projet, le langage, le framework, les conventions existantes, et s’adapter à ce qui est réellement en place au lieu d’imposer une pile technologique préférée qu’il a apprise dans ses données d’entraînement. Et je lui dis la même chose que je dirais à un nouvel ingénieur : ne redécouvrez pas la codebase à chaque session, synchronisez-vous avec la documentation et avec ce qui a déjà été décidé, car un agent qui devine votre architecture est exactement aussi dangereux qu’un ingénieur qui la devine.

Pour la partie structurelle de ce contexte, je m’appuie sur CodeGraph, qui construit un graphe de connaissances de chaque symbole, arête et fichier de l’espace de travail, analysé avec tree-sitter. Il répond aux questions que grep ne peut pas, comme “qui appelle ceci ?” ou “que se casserait-il si je changeais cela ?”, en sub-millisecondes (npmjs.com/package/@colbymchenry/codegraph). Je l’utilise pour la structure et je laisse grep pour le texte littéral. Il convertit un contexte que l’agent aurait à construire en lisant des fichiers entiers en un contexte qui est déjà là.

Ce qu’il fait fondamentalement, c’est de maintenir localement un index des fonctions, des appels, de la structure générale, ce qui permet une recherche immédiate plutôt qu’un cycle éternel de grep + find. Il existe de nombreux projets similaires, mais celui-ci fait partie de ceux qui ont une communauté assez grande et stable.

La mémoire est la partie dont personne ne parle

N’importe quel modèle oublie tout ce qu’il a fait dès la fin de la session. Pour cela, j’utilise deux outils : une mémoire partagée et une documentation “vivante” avec OpenWiki (que j’explique plus loin). Dans mon cas, j’ai fini par traiter la mémoire persistante comme le véritable atout. Il y a deux couches que je maintiens délibérément séparées : il y a la mémoire privée, qui est comme les notes que l’agent garde pour lui-même sur vos décisions, bugs et conventions, stockée par projet pour que le travail sur un dépôt ne révèle jamais les décisions d’un autre dépôt. Et il y a la documentation du dépôt lui-même, la wiki qui vit dans la codebase et que la prochaine personne, ou la prochaine session, lit comme source de vérité. La différence est que la mémoire privée est ce dont se souvient la prochaine session, et la wiki est ce que lit la prochaine personne, et vous avez besoin des deux, pas d’une seule.

Pour la couche privée, j’utilise Engram, un stockage local dans SQLite + FTS5 qui survit entre les sessions et même à la compactage du contexte. Vous y enregistrez des observations typées et il vous signale un conflit au lieu de la surécriture silencieuse lorsqu’une nouvelle mémoire contredit une ancienne. Ainsi, vous terminez avec une conversation qui charge sa propre histoire au lieu d’un chat sans état qui repart de zéro chaque lundi (github.com/Gentleman-Programming/engram). Je l’utilise de manière proactive, pas quand on me le demande : contexte au début de la session, une recherche avant de commencer quoi que ce soit qui pourrait avoir été touché auparavant, un enregistrement immédiatement après toute décision ou changement de convention, et un résumé avant de fermer. Cela ressemble à une surcharge jusqu’à ce que vous réalisiez que l’alternative est de redécouvrir et de redécider la même chose chaque semaine.

Qu’est-ce que cela génère ?

Lorsque vous reprenez le travail sur le projet, au lieu de devoir réexpliquer ce que vous avez fait lors des dernières sessions, vous disposez d’un historique consultable sémantiquement, avec des décisions, des ajustements, des explications que l’agent peut facilement trouver. Il est même arrivé que je demande un changement et que l’agent me réponde : “Êtes-vous sûr ? Cela va à l’encontre de ce que nous avons fait il y a deux semaines.” Il me rappelle même ce que j’ai livré.

La wiki du dépôt est la mémoire publique

Et c’est ici qu’intervient la deuxième couche dont je vous parlais, car si Engram est ce dont l’agent se souvient en privé, OpenWiki est ce que le dépôt conserve en public : une wiki propre qui vit au sein de la codebase, encore une fois sous openwiki/, et que la prochaine personne, ou la prochaine session, lit comme source de vérité de l’état actuel du projet. Ce n’est pas un changelog que personne ne lit, mais une documentation réelle, enracinée dans les fichiers, l’historique Git et les décisions déjà prises. L’outil officiel s’intègre à GitHub et peut être déclenché après un merge ; cependant, si vous souhaitez le faire manuellement (cela fonctionne très bien aussi), il existe un plugin pour Claude Code (facilement adaptable comme “skill” à tout autre agent qui remplit la même fonction).

L’intégration à mon flux de travail suit une seule règle : après tout changement affectant l’architecture, une convention ou un workflow, j’exécute /openwiki:wiki update avant de considérer le ticket comme terminé. L’avantage est que c’est idempotent : il prend un instantané du wiki avant et après et ne met à jour que ce qui a réellement changé. Ainsi, l’exécuter souvent est peu coûteux et l’exécuter rarement est ce qui le rend coûteux. Le modèle complet est le suivant : Engram est ce dont se souvient la prochaine session, OpenWiki est ce que lit la prochaine personne, et vous avez besoin des deux, pas d’une seule. Si vous suivez la structure recommandée, cela aide l’agent à trouver des réponses beaucoup plus facilement. Dans mon cas, cela m’a même aidé à trouver des parties obsolètes de l’application, des sections nécessitant une mise à jour, et cela maintient l’idée d’ingénierie de base selon laquelle la documentation doit toujours être à jour.

La fenêtre de contexte est un budget, pas une poubelle

C’est la partie qui a changé ma façon de travailler en réduisant incroyablement la consommation de tokens. Le mouvement naïf est de jeter chaque log, chaque diff, chaque page web dans la conversation et de laisser le modèle nager là-dedans. Mais j’ai appris à lui donner des outils qui traitent et indexent cela à la place. Ainsi, la sortie volumineuse est recherchée au lieu d’être collée, avec une base de connaissances consultable. Cela peut sembler être un détail d’implémentation, mais en pratique, c’est la différence entre un agent qui reste lucide après la deuxième heure et un agent qui se noie dans des tokens qu’il ne peut plus raisonner.

context-mode est mon outil de prédilection ici : il exécute la sortie des outils dans un sandbox et l’indexe. Ainsi, un log énorme ou un grand diff est traité et recherché au lieu d’être directement déversé dans la fenêtre de contexte, et seule la réponse dont vous avez besoin revient à la conversation (github.com/mksglu/context-mode). C’est l’un de ces outils que vous ne remarquez pas fonctionner jusqu’à ce que vous l’enleviez, et soudain l’agent recommence à lire des fichiers de mille lignes dans sa fenêtre et oublie ce qu’il était en train de faire.

Les tests sont l’instrument, pas la formalité

Et c’est ici qu’intervient la discipline qui donne un sens à tout ce qui précède, car un agent avec du contexte et de la mémoire mais sans tests n’est qu’un agent qui semble confiant. Le cycle est donc rouge, vert, refactoring : j’écris d’abord le test qui échoue pour le changement, ensuite le minimum de code pour qu’il passe, et enfin je nettoie ce qui est superflu. Je ne délègue pas cela à l’agent : je l’habitue à ce que chaque ticket réel exécute la suite complète et, surtout, à ce qu’il exécute la commande réelle et lise la sortie réelle avant d’affirmer que quelque chose fonctionne. Car je peux vous promettre qu’un test a passé, mais si vous ne l’avez pas exécuté et n’avez pas vu sa sortie, ce n’est qu’une affirmation (des preuves avant les affirmations).

Les yeux dont l’agent a besoin : Chrome DevTools

Et il reste une dernière pièce que presque personne n’utilise au démarrage, car une suite de tests vous dit si le code est logique, pas s’il s’affiche correctement dans un navigateur. Donc, à la question “cela fonctionne-t-il vraiment dans le navigateur ?” et non “cela compile-t-il ?”, j’ai donné des yeux à l’agent avec Chrome DevTools MCP, qui lui fournit un vrai Chrome qu’il peut manipuler : naviguer, cliquer, remplir des formulaires, prendre des instantanés du DOM et de l’arbre d’accessibilité, vérifier le réseau et la console, exécuter des traces de performance et même des audits Lighthouse et des captures d’écran. En pratique, c’est la différence entre un agent qui vous dit “le correctif compile” et un agent qui vous dit “j’ai ouvert la page, le flux de consentement s’affiche ainsi, la console ne montre pas d’erreurs et le LCP a diminué de deux secondes”. Et cela, combiné aux tests, transforme un assistant de terminal en quelque chose sur lequel vous pouvez vraiment vous appuyer pour livrer.

Superpowers : le processus comme extension

Et si le processus est la source de valeur, la façon de ne pas l’oublier est de laisser une bibliothèque de “skills”, Superpowers. Il existe d’autres options, comme les Skills de Matt Pocock, mais dans mon cas, j’ai trouvé Superpowers beaucoup plus pratique pour mes besoins. Ainsi, je peux passer d’un processus strict à un processus plus détendu. Superpowers permet de réaliser l’alignement pour nous, il se charge automatiquement au début de la session et achemine chaque tâche vers le skill approprié (github.com/obra/superpowers). Les deux que j’utilise le plus sont le brainstorming et la planification : le premier m’oblige, et oblige l’agent, à transformer une idée diffuse en une conception convenue avant qu’il n’existe une seule ligne de code, à discuter des exigences et de l’approche au lieu de les supposer. Le second décompose cette conception déjà approuvée en un petit plan d’implémentation, en utilisant le TDD où il définit d’abord les tests qui échouent, crée une spécification (SPEC), puis un plan, et ce n’est qu’alors que nous passons à l’implémentation. Ainsi, je ne lui délègue pas le “quoi”, je lui délègue le “comment” d’un problème que nous avons déjà défini ensemble. Et ce qui me semble important, c’est qu’il utilise le système de fichiers de manière à ce que même si vous fermez la session, vous puissiez continuer à partir des fichiers avec un HANDOFF, ce qui peut ensuite se transformer en documentation au sein d’OpenWiki.

Prémortem : le “skill” exigé par le ticket

Et à ce processus, j’ai ajouté un élément qui n’appartient pas à Superpowers mais s’installe seul, car c’est la porte obligatoire avant le retour de tout ticket terminé : le prémortem. Il s’agit d’assumer que le changement a déjà échoué en production et de travailler à rebours pour identifier les modes de défaillance, les régressions et les cas limites. Vous corrigez ce que vous trouvez, vous le réexécutez, et si quelque chose n’est délibérément pas corrigé, vous le mentionnez par écrit dans la livraison (Premortem Skill).

J’intègre tout cela dans mon “system prompt” de base, qui peut être CLAUDE.md ou AGENTS.md et est lu au démarrage (de manière globale, non par projet), pour obliger l’agent à passer par le processus de Prémortem avant de livrer quoi que ce soit. Je réfléchis à le transformer en sous-agent pour qu’il le fasse avec un contexte propre, mais pour l’instant, en tant que “Skill”, il a donné d’excellents résultats.

Toute avancée est un changement de processus, pas un changement de modèle

Les outils qui m’ont le plus marqué ne sont pas les prompts les plus ingénieux, mais les disciplines qui entourent l’ensemble du processus : le brainstorming avant de toucher au code, les tests avec refactoring, et surtout un prémortem avant que tout ticket terminé ne revienne, où l’on suppose que le changement a déjà échoué en production et l’on travaille à rebours pour rechercher les modes de défaillance, les régressions et les cas limites. C’est une porte, pas une suggestion. Et j’exécute la construction (build) réelle et je lis la sortie réelle avant que moi ou l’agent n’affirmions que quelque chose fonctionne, car les preuves priment sur les affirmations.

Pourquoi tous ces outils passent par un gestionnaire de runtime

Et voici un détail dont personne ne vous prévient : tous ces outils proviennent de langages et de runtimes différents collés ensemble – un binaire Go pour la mémoire, un paquet npm pour le graphe de connaissances et le sandbox, et ainsi de suite. Sur la machine moyenne, cela signifie que les outils globaux installés avec un simple npm install -g atterrissent sous la version de Node que nvm ou fnm a active à ce moment-là. Et dès que votre shell choisit un autre Node, dans un terminal, dans un autre dépôt au sein d’un autre projet, ce chemin tombe de votre PATH et l’outil disparaît en silence.

Je les gère donc avec mise, qui fixe un runtime explicite pour les outils globaux et possède ses shims en dehors des répertoires bin par version du gestionnaire de versions. Ainsi, le chemin reste stable au lieu de dépendre de la mode de la semaine dans votre .nvmrc (mise.jdx.dev). La règle que je garde en tête correspond exactement aux outils de cette liste : mise pour tout ce qui est un paquet de langage avec une entrée CLI, et un unique propriétaire par binaire, car deux gestionnaires de paquets mettant à jour le même outil selon des calendriers différents finiront toujours par se chamailler.

Je ne suis peut-être pas le meilleur dans ce domaine, mais après deux ans de travail avec ces agents sur des projets réels, voici ce que j’en ai retenu. Le résumé honnête est le suivant : nous devons traiter l’agent comme le partenaire qu’il pourrait être, lui donner du contexte, maintenir sa mémoire, et appliquer les mêmes disciplines que celles que vous appliqueriez à une personne. Car le modèle est peu coûteux, le contexte est ce que nous contrôlons, et la différence entre un outil qui vous impressionne lors d’une démo et un outil qui vous livre le travail est, dans tous les cas que j’ai vus, si vous avez pris la peine de gérer le contexte et la mémoire.