Fichiers mémoire : donner à ton agent un cerveau de travail à court terme

Chaque agent de code a le même problème de mémoire : il oublie tout entre les sessions. Vous passez dix minutes à lui expliquer l’architecture du projet, les conventions de nommage, les décisions prises la veille, et le lendemain matin, il repart de zéro. Vous vous retrouvez à répéter les mêmes instructions, session après session, comme un manager qui briefe un nouveau stagiaire chaque lundi.

La solution n’est pas un meilleur modèle ou une fenêtre de contexte plus large. C’est un fichier. Un simple fichier que l’agent lit au démarrage et qui contient ce qu’il doit savoir pour travailler sur ce projet, ce jour-là.

Le fichier mémoire : l’idée

Un fichier mémoire est un document Markdown, versionné avec le projet, que l’agent charge automatiquement au début de chaque session. Il contient :

Les conventions du projet (nommage, structure, patterns utilisés)
Les décisions récentes (« on a choisi X plutôt que Y parce que Z »)
L’état courant (« la branche feature/auth est active, le composant Login est en cours »)
Les interdits (« ne jamais modifier les fichiers dans /generated/ », « pas de tailwind arbitraire »)

L’implémentation varie selon l’outil :

Claude Code lit automatiquement CLAUDE.md à la racine du projet.
Cursor utilise .cursorrules ou .cursor/rules/.
D’autres outils acceptent des system prompts personnalisés chargés depuis un fichier.

Le format importe peu. Ce qui compte, c’est que l’agent le lise à chaque session sans que vous ayez à y penser.

Ce que je mets dedans (et ce que j’en exclus)

Ce qui marche

Les conventions non évidentes :

## Conventions
- Les composants Astro vivent dans src/components/pages/ (pas src/pages/)
- Les strings UI sont dans src/data/copy.ts — jamais en dur dans le markup
- Les dates sont toujours YYYY-MM-DD dans le frontmatter

L’agent ne peut pas deviner ces choix en lisant le code, ou plutôt, il peut inférer un pattern à partir des fichiers existants, mais il va se tromper sur les cas limites. Écrire la règle est plus fiable qu’espérer qu’il la déduise.

Les décisions contextuelles :

## Décisions récentes
- On utilise Source Serif 4, pas Copernicus (licence)
- Le site est monolingue français — pas d'i18n
- Pas de shadows, pas de border-radius (design system)

Ces règles n’ont de sens que dans ce projet. Elles ne sont dans aucune documentation externe. Sans le fichier mémoire, l’agent va proposer des shadows, du border-radius, et des composants en anglais, parce que c’est ce qu’il a vu dans ses données d’entraînement.

Les limites strictes :

## Ne jamais faire
- Ne pas commit sans demander
- Ne pas modifier les fichiers `generated: true`
- Ne pas inventer de métriques (pas de subscribers, pas d'usage counts)
- Ne pas ajouter de dépendances sans accord explicite

Ce qui ne marche pas

L’architecture entière du projet. Trop long. L’agent lit le fichier à chaque session, s’il fait 2000 mots, c’est du contexte gaspillé. Gardez-le sous 500 mots.
L’historique des changements. C’est le travail de git log, pas du fichier mémoire.
Les instructions génériques. « Écris du bon code » n’ajoute rien. L’agent le fait déjà (ou pas, et un fichier ne changera rien).

Le cycle de vie du fichier mémoire

Un fichier mémoire n’est pas statique. Il évolue avec le projet :

Jour 1 : Conventions de base + décisions d’architecture.
Semaine 1 : Ajout des patterns récurrents que l’agent ne respecte pas spontanément.
Mois 1 : Élagage des règles devenues inutiles (l’agent les a intégrées via le code existant).
En continu : Mise à jour quand une décision change.

La règle d’or : si vous corrigez l’agent sur la même chose trois fois, ajoutez-la au fichier mémoire. Si une règle n’a pas été utile en un mois, retirez-la.

Multi-fichiers pour les projets complexes

Pour les projets de plus de 50 fichiers, un seul fichier mémoire devient trop large ou trop générique. La solution : plusieurs fichiers spécialisés.

.claude/
├── CLAUDE.md           # Conventions globales (lu toujours)
├── skills/
│   ├── blog/SKILL.md   # Règles spécifiques au blog
│   └── seo/SKILL.md    # Règles SEO
└── memory/
    └── MEMORY.md       # Faits persistants (rôle, préférences)

Chaque skill est chargé en contexte, uniquement quand l’agent travaille sur le sujet concerné. Le fichier global reste court (conventions transversales), et les détails vivent dans des fichiers spécialisés.

Le piège de la sur-documentation

J’ai vu des CLAUDE.md de 3 000 mots qui essayaient de tout couvrir. Résultat : l’agent les lit, consomme du contexte, et en retient une fraction. Un fichier mémoire trop long est pire qu’un fichier absent, il crée l’illusion que l’agent « sait », alors qu’il a noyé les règles importantes dans le bruit.

Visez la concision. Chaque ligne doit répondre à la question : « Est-ce que l’agent ferait une erreur sans cette ligne ? » Si la réponse est non, supprimez-la. Le fichier mémoire est un garde-fou, pas une documentation.

Si cela vous a parlé, vous aimerez Écrire des skills que votre agent de code utilisera vraiment et Arrêtez de coller du contexte : un meilleur workflow dans l’IDE. Abonnez-vous ci-dessous pour recevoir le billet de vendredi prochain.