Chapitre 3.4 — Mémoire : hiérarchie & persistance

⏱️ TL;DR — Au-delà du fichier, la mémoire est une pratique : ajouter vite une règle (#), factoriser via des imports, et surtout maintenir l’ensemble à jour. Une mémoire périmée est pire que pas de mémoire : elle fait travailler l’agent sur une réalité qui n’existe plus. Tu gères deux échelles — ta mémoire globale (toi, partout) et la mémoire projet (le repo, partagée) — et tu les jardines au même titre que le code.

🎯 Objectifs

• Ajouter une règle à la volée avec # et factoriser avec des imports.
• Distinguer ce qui persiste au niveau global vs projet.
• Maintenir la mémoire à jour et éviter la mémoire périmée.
• Savoir quand externaliser vers un système de mémoire dédié.

Ajouter vite : le raccourci #

En pleine session, quand tu donnes une consigne que tu voudras garder, tu n’as pas besoin d’ouvrir le fichier : commence ton message par # et Claude Code te propose de l’ajouter à la mémoire (au bon fichier, au bon niveau).

# Toujours utiliser `pnpm`, pas `npm`, sur ce repo.

C’est le moyen le plus fluide de cristalliser une consigne volatile sans casser ton flux (rappel du chapitre 1.1 : transformer l’éphémère en persistant). Attention quand même à ne pas transformer # en déversoir : chaque ajout suit les mêmes règles (court, tranchable) — sinon tu regonfles le fichier.

💡 Réflexe d’architecte — Le bon moment pour #, c’est la deuxième fois que tu donnes la même consigne. La première, c’est peut-être ponctuel. La deuxième, c’est un pattern : cristallise-le. « Je l’ai déjà dit une fois » est le signal.

Factoriser : les imports

Un CLAUDE.md peut inclure d’autres fichiers, pour ne pas tout empiler dans un seul document et réutiliser des morceaux communs. La syntaxe d’import référence un chemin :

# TaskFlow — Guide agent
 
Voir nos conventions transverses : @../shared/CONVENTIONS-TS.md
 
## Spécifique à TaskFlow
- ...

Utile pour :

• mutualiser des conventions communes à plusieurs repos (une équipe, un monorepo) ;
• découper un guide qui, sinon, deviendrait long (mais rappelle-toi : découper n’est pas une excuse pour tout garder — l’import compte aussi dans le contexte).

⚠️ Piège — Se servir des imports pour contourner la règle de concision : « je mets tout, mais dans des fichiers séparés ». Le contenu importé est quand même chargé et pèse sur le contexte. Les imports servent à factoriser du partagé, pas à cacher de l’obésité.

Deux échelles de persistance

• Global : tes préférences de travail (langue, style, réflexes). Elles te suivent d’un projet à l’autre. Idéal pour ce qui est toi, pas le projet.
• Projet : la connaissance du repo, versionnée. Elle survit à toi : un collègue (ou un agent lancé par lui) hérite exactement du même cadre. C’est ça, « aider l’IA à continuer un projet » — la mémoire projet est le passage de relais.

🧭 Sur TaskFlow — Le CLAUDE.md de TaskFlow est committé. Résultat : que tu reprennes le projet dans trois semaines, sur une autre machine, ou qu’un collègue s’y mette, l’agent démarre avec les mêmes conventions. La continuité n’est pas dans ta tête ni dans une session — elle est dans le repo.

Le danger n°1 : la mémoire périmée

Une mémoire qui décrit une réalité révolue est activement nuisible : l’agent suit une règle abandonnée, cherche un fichier renommé, applique un pattern qu’on a remplacé. C’est le pendant de l’avertissement que tu vois parfois dans les outils : une note de mémoire reflète ce qui était vrai quand elle a été écrite — vérifie qu’elle est encore valide.

Règles d’hygiène :

• Quand une convention change, mets à jour la mémoire dans le même mouvement (comme on met à jour un test).
• Quand tu supprimes un pattern, supprime sa règle.
• De temps en temps, relis ton CLAUDE.md comme du code : est-ce encore vrai, ligne à ligne ?

💡 Réflexe d’architecte — Traite le CLAUDE.md comme un fichier de premier ordre dans tes PR : s’il faut le toucher parce qu’une convention évolue, ça fait partie du diff, pas d’un « je le ferai plus tard » qu’on ne fait jamais. Une mémoire à jour est un actif ; une mémoire périmée, un passif.

Quand externaliser vers un système de mémoire dédié

Le CLAUDE.md couvre les conventions stables. Pour la mémoire de travail (« où en est-on, qu’a-t-on décidé la semaine dernière »), il n’est pas le bon outil (ce n’est pas un journal). Deux options :

• Des docs / ADR (comme le docs/adr/ de ce playbook) pour les décisions.
• Des skills/outils de mémoire de la communauté (par ex. des systèmes qui capturent et réinjectent le contexte de session à session) si tu as un vrai besoin de continuité longue. On en reparle en Partie 9.

Ne charge pas le CLAUDE.md de ce rôle : garde-le pour « ce qui est vrai en permanence ».

✏️ Exercices

Exercice 1 — Le bon niveau, encore. Liste 3 choses que tu voudrais que l’agent « retienne ». Pour chacune : global, projet, ou plutôt doc/ADR (parce que c’est une décision datée, pas une convention permanente) ?

Exercice 2 — Chasse au périmé. Relis un CLAUDE.md que tu as depuis un moment. Trouve au moins une ligne qui n’est plus vraie (fichier renommé, règle abandonnée, script changé). Corrige ou supprime.

🧠 Quiz de révision

Chapitre suivant : Atelier — le CLAUDE.md de TaskFlow — on passe de la graine à un fichier solide, sans le faire gonfler.