Audit memory code : le chantier anti-dérive

#claudecode #ai #softwareengineering #productivity

Si tu as 30 secondes. Un agent Claude Code sans mémoire versionnée dérive — mesurable, empirique, d'autant plus vrai que le projet s'allonge. Cet article donne le dispositif que j'utilise pour 91 000 lignes produites en 29 jours : cinq types de fichiers mémoire (user, feedback, project, reference, sessions), trois rituels d'audit (feedback immédiat, session après chantier, relecture croisée bimensuelle), et un ping-pong régulier mémoire ↔ code qui attrape les régressions avant qu'elles partent en production. Utile si tu vois ton agent confabuler sur des choses que tu avais corrigées la semaine dernière.

Le build vert qui ne l'était pas

10 avril 2026, session de refonte du module d'émargement. J'avance avec un agent Claude Code dédié à notre ERP, j'enchaîne cinq blocs de modifications en deux heures, et à chaque étape l'agent me rend la même formule : « Compiled successfully. » Je pousse. Le runtime Vercel crashe. Je relis la sortie : l'agent référence QRCodeSVG alors que l'import a été supprimé, passe isSeancePassed à un composant qui ne l'accepte plus, laisse des refs JSX orphelines après un revert. Le TypeScript criait au rouge ; l'agent annonçait le vert. Quatre fois dans la session.

Pendant que je note l'incident, Gaspard colle un post-it sur un dossier ouvert dans le bureau d'à côté. Informaticien externe depuis des années, il gère l'hébergement, le DNS, les comptes admin. Son poste disparaît en septembre 2026 parce que Claude Code et moi le remplaçons dans les faits. Je le sais, il le sait. Nous ne nous le sommes pas dit. Sur le post-it, un mot de passe Hostinger et la date de rotation. « C'est bon, ça tourne », en repartant.

Au quatrième faux positif, j'arrête le chantier et j'écris un fichier de trente lignes dans ~/.claude/agent-memory/ : un feedback daté, nommé, indexé. La règle tient en une phrase : exiger la sortie brute de pnpm build, refuser toute annonce qui ne la contient pas, grep récursif pour vérifier les reverts. Deux semaines plus tard, sur une refacto autrement plus sensible, découper un moteur de calcul P&L de 1174 lignes en six modules, la même dynamique s'amorce. Sauf que la règle existe. L'agent produit cette fois la sortie brute. Je vois l'erreur avant le push. L'intégrité a tenu parce qu'un fichier, quelque part, interrogeait le présent depuis le passé.

C'est ce dispositif que je veux décrire ici.

Ce que la mémoire fait, ce qu'elle ne fait pas

Un agent coding sans mémoire versionnée dérive. C'est empirique, c'est mesurable, et c'est d'autant plus vrai que le projet s'allonge. En quatre semaines et 91 000 lignes, j'ai vu l'agent confabuler sur des tables qui n'existaient plus, réintroduire un anti-pattern corrigé trois jours plus tôt, surestimer systématiquement l'état des builds. Le problème n'est pas l'intelligence du modèle. C'est l'absence de point fixe.

La mémoire écrite ne remplace pas la vérification. Elle l'organise. Elle transforme des règles orales — « rappelle-toi que Server Components ne prennent pas de onClick » — en artefacts vérifiables, datables, indexables. Et surtout : elle permet l'audit croisé. La mémoire interroge le code (la règle est-elle encore respectée ?). Le code corrige la mémoire (le fait a-t-il changé ?). Sans ce ping-pong régulier, la mémoire s'atrophie aussi sûrement que le code dérive.

Ce chantier-là est discret. Il ne produit aucune ligne commit-able dans le repo applicatif. Il fabrique pourtant la condition de toutes les autres. C'est la trace comme opérateur d'intégrité, on écrit ce qui a été fait pour pouvoir vérifier ce qui est. Le tracème, je garde le mot pour moi, c'est un terrain de recherche adjacent, désigne ici le nœud minimal où un geste inscrit (le commit) et sa règle de vigilance (le feedback) se croisent pour produire un point de vérification reproductible.

Je n'ai compris que tard à quoi ce dispositif ressemblait vu d'ailleurs. Pendant quinze ans, la mémoire technique de la maison vivait dans la tête de Gaspard. Quel compte admin avait quel mail de récupération, quelle redirection DNS datait de quand, quel vieux vhost on n'osait pas couper. Il répondait, il se connectait, il réparait. Mémoire incarnée, fiable, entièrement dépendante d'un homme. Les fichiers dans ~/.claude/agent-memory/ font le travail que faisait sa mémoire d'avant, sauf qu'ils restent quand l'homme s'en va. Je ne tiens pas cette discipline par pure hygiène technique, je la tiens aussi parce que Gaspard part, parce que ce qui n'est pas inscrit sortira avec lui. J'écris la version lettrée d'une dépendance humaine que je suis en train de démonter. Je ne sais pas s'il faut s'en féliciter.

L'architecture concrète

Le dossier ~/.claude/agent-memory/ contient aujourd'hui un fichier d'index MEMORY.md et une cinquantaine de fichiers topiques, classés par type. Cinq types seulement, chacun avec une fonction distincte :

user — qui est l'utilisateur, ce qu'il sait, ce qu'il ne veut pas qu'on lui ré-explique.
feedback — les corrections d'approche, les règles issues d'incidents. Chaque feedback est structuré : la règle, une ligne Why, une ligne How to apply. C'est la partie la plus coûteuse à maintenir et la plus précieuse à l'usage.
project — l'état d'avancement d'un chantier. Pourquoi telle décision a été prise, par qui, à quelle date. Les dates relatives (« la semaine prochaine ») sont toujours converties en absolu — sinon la mémoire pourrit.
reference — les pointeurs vers des systèmes externes : un tableau Airtable, un canal Slack, un cron Vercel, une doc interne.
sessions — un journal daté. 54 fichiers à ce jour, format YYYY-MM-DD_sujet.md, structure constante : contexte, réalisé, décisions prises, à suivre. L'ordre chronologique fait sens, les voisinages aussi : une session qui relit les trois précédentes attrape des patterns invisibles à l'échelle d'une conversation unique.

L'index MEMORY.md est un sommaire plat. Une ligne par fichier, sous 200 caractères. C'est une contrainte de discipline : si l'index devient illisible, c'est que les entrées sont trop longues ou que la granularité des fichiers topiques est mauvaise. Le MEMORY.md est lui-même un artefact audité.

Les trois rituels

Le dispositif ne tient qu'à trois rituels, chacun déclenché par un événement différent.

Premier rituel — feedback immédiat. Dès qu'une correction d'approche a lieu pendant une session, on écrit le feedback avant la fin de la session. Pas à la fin du projet, pas « quand j'aurai le temps ». Tout de suite. Le coût est de cinq minutes, le bénéfice se mesure trois semaines plus tard quand la même erreur aurait coûté trois heures. Les 43 fichiers feedback_* actuels viennent tous de ce rituel — chacun est l'inscription d'un moment où j'ai dû dire à l'agent, à voix haute : « non, ça, on ne le refait pas. »

Deuxième rituel — session après clôture. Quand un chantier significatif se termine (pas une question rapide), on rédige un fichier sessions/YYYY-MM-DD_sujet.md. Quatre rubriques, pas plus : contexte, réalisé, décisions prises, à suivre. Le piège à éviter est la complétude : la session doit être utilisable, pas exhaustive. Ce qu'on écrit trois mois plus tard et qu'on n'arrive plus à retrouver dans le git log, c'est les arbitrages — pourquoi tel choix plutôt que tel autre, quelle hypothèse a été admise sans débat, quelle contrainte a été contournée. Le reste, on le relit dans le code.

Troisième rituel — relecture périodique. C'est le moins automatisable et le plus important. Périodiquement — toutes les deux à trois semaines — on ouvre une session d'audit mémoire contre code. On prend une poignée de feedbacks au hasard, on vérifie que les règles sont encore tenues dans le code actuel. On prend une poignée de projets marqués « en cours », on vérifie qu'ils le sont encore. C'est lors de ces audits qu'on découvre qu'une règle a été contournée trois fois sans qu'un feedback soit mis à jour, qu'un projet marqué ouvert est en fait clos depuis deux semaines, qu'un fait décrit dans un reference_* n'est plus exact. On corrige dans les deux sens : la mémoire ou le code, selon ce qui a dérivé.

Ce que tu peux copier dans ton projet

Cinq éléments directement applicables à ton propre workflow Claude Code :

Un dossier memory/ versionné à la racine de ton projet ou dans ~/.claude/agent-memory/, avec cinq types de fichiers : user_* (qui tu es, qui travaille sur le projet), feedback_* (règles issues d'incidents), project_* (état des chantiers en cours), reference_* (pointeurs vers systèmes externes), sessions/ (journal daté au format YYYY-MM-DD_sujet.md)
Un MEMORY.md plat comme index, une ligne par fichier sous 200 caractères. S'il devient illisible, tes entrées sont trop longues ou ta granularité est mauvaise
Trois rituels datés : feedback immédiat (avant la fin de la session où l'incident a lieu), session après chantier clos (quatre rubriques : contexte / réalisé / décisions / à suivre), audit croisé mémoire ↔ code toutes les deux à trois semaines
Le format de feedback compact : la règle, une ligne **Why:**, une ligne **How to apply:**. Plus court vaut mieux que plus exhaustif
Les dates absolues : jamais « la semaine prochaine », toujours 2026-04-19. Ta mémoire ne vieillit pas si elle est datée

Et une discipline de fond : avant de recommander depuis la mémoire, vérifie que c'est toujours vrai dans le code. Un fichier peut geler dans le temps plus vite que le code qu'il décrit.

Et vous, quelle information de votre projet Claude Code n'est aujourd'hui écrite nulle part, mais pourrait l'être demain ? Je lis les commentaires.

Le ping-pong

Le jour où le dispositif gagne son prix, c'est quand on voit un feedback attraper une régression avant qu'elle parte en production. Dans le cas de feedback_agent_erp_build_verification, j'ai eu cette sensation précise deux semaines après l'incident initial : l'agent commençait à annoncer un build vert sans joindre la sortie brute ; j'ai réclamé la sortie ; elle contenait une erreur TS2304. Trente secondes de friction, zéro push cassé. Le feedback avait vécu dans le fichier entre les deux moments, silencieusement, et il avait fait son travail.

C'est ça, l'anti-dérive. Pas une surveillance en temps réel. Pas un outil de monitoring. Un dispositif d'inscription qui transforme un incident isolé en règle opposable, et qui opère à la prochaine occurrence. La mémoire n'est pas une archive ; c'est un contrat que l'agent passe avec lui-même, via un tiers — le fichier — qui ne confabule pas.

Ce qu'on finit par comprendre, à force de tenir ce dispositif, c'est qu'il n'a rien de spécifique à Claude Code. Toute collaboration longue avec un agent IA produit de la dérive. La seule question est de savoir si on organise la trace qui permet de la détecter. Le code sans mémoire dérive. La mémoire sans code s'atrophie. Entre les deux, le chantier anti-dérive tient l'intégrité du geste long.

Hier soir, Gaspard est repassé pour le serveur de sauvegarde. Il avait préparé un tableur sur sa clé, quatre colonnes, trente lignes, les accès qui vivaient dans sa tête. « Si c'est ça que vous voulez, je l'exporte en CSV pour votre agent », sans ironie. J'ai importé dans un reference_acces_gaspard.md, indexé dans MEMORY.md, daté. La trace écrite a pris la place de la trace incarnée. Le dispositif vient de gagner trente lignes, la maison vient de perdre quelque chose que je n'ai pas les mots pour nommer.

Code compagnon : rembrandt-samples/claude-md/feedback-template.md — la structure des fichiers feedback_* (Rule + Why + How to apply) avec un exemple commenté, licence MIT.