Les fichiers mémoire (CLAUDE.md & co)

Voici une vérité un peu déprimante sur les agents de code : ils n’ont aucune mémoire. Vous pouvez passer deux heures à expliquer votre projet, à corriger dix fois la même erreur, à poser vos règles, et à la session suivante, l’agent revient page blanche. Il a tout oublié. Le LLM ne se souvient que de ce qui tient dans la conversation en cours. Fermez la fenêtre, et tout part.

Sauf une chose : le fichier mémoire. C’est un fichier texte que l’agent lit automatiquement au démarrage de chaque session, avant même que vous tapiez quoi que ce soit. Vous y écrivez une fois ce qu’il doit retenir pour toujours. C’est exactement ce qui vous fait arrêter de vous répéter.

Le fichier, et son jumeau global

Tous les agents lisent un fichier mémoire. Le nom change selon l’outil, mais l’idée est identique.

• Claude Code lit un fichier nommé CLAUDE.md. Depuis sa version 2.1.277, il lit aussi AGENTS.md quand le projet n’a pas de CLAUDE.md.
• Codex lit un fichier nommé AGENTS.md, à la racine du dépôt et dans chaque sous-dossier jusqu’à celui où vous travaillez. Il ne lit pas CLAUDE.md de lui-même, mais une ligne dans ~/.codex/config.toml le lui fait prendre là où AGENTS.md manque : project_doc_fallback_filenames = ["CLAUDE.md"].
• OpenCode lit un fichier nommé AGENTS.md, et se rabat sur CLAUDE.md s’il n’en trouve pas.

AGENTS.md est devenu la convention commune : au-delà de Codex et d’OpenCode, Cursor, Gemini CLI, GitHub Copilot et bien d’autres outils le lisent, et le format est désormais porté par l’Agentic AI Foundation, sous l’égide de la Linux Foundation (agents.md). Pour voir quels outils de code existent et quels modèles chacun propose, Quelle IA tient une page des outils.

Même mécanisme, juste un nom de fichier différent. Et dans les deux cas, il existe deux niveaux :

• Le fichier projet, à la racine de votre dépôt. Il décrit ce projet-là : son but, sa pile, ses règles. Il voyage avec le code, donc toute personne (ou tout agent) qui ouvre le dépôt en hérite.
• Le fichier global, au niveau de votre utilisateur. Il porte vos préférences permanentes, valables sur tous vos projets. Pour Claude Code, c’est ~/.claude/CLAUDE.md ; pour Codex, ~/.codex/AGENTS.md ; pour OpenCode, ~/.config/opencode/AGENTS.md.

./CLAUDE.md          # mémoire du projet (à la racine du dépôt)
~/.claude/CLAUDE.md  # mémoire globale (toutes tes sessions)

./AGENTS.md              # mémoire du projet (à la racine du dépôt)
~/.config/opencode/AGENTS.md  # mémoire globale (toutes tes sessions)

./AGENTS.md                # mémoire du projet (à la racine du dépôt)
./sous-dossier/AGENTS.md   # règles propres à un dossier, lues après celles de la racine
~/.codex/AGENTS.md         # mémoire globale (toutes vos sessions)

Ce qui doit y aller (la vraie matière)

Un bon fichier mémoire tient en quatre rubriques. Pas plus.

• Le contexte du projet. Ce que c’est, et surtout l’objectif en une phrase : celui que vous avez déjà extrait dans votre cahier des charges. C’est la boussole de l’agent.
• Les conventions et les règles. Les choix que l’agent ne peut pas deviner et que vous ne voulez pas re-justifier : « toujours montrer les commandes sudo avant de les lancer », « pas de secret en clair », « on utilise React, pas Vue », « ne touche jamais au dossier legacy/ ».
• Les commandes qui comptent. Comment on lance, build, teste, déploie ce projet. L’agent les répétera fidèlement au lieu d’inventer une commande qui n’existe pas.
• Les leçons apprises à la dure. Le piège récurrent, le truc contre-intuitif, le bug sur lequel vous vous êtes cassé les dents. « L’API renvoie du 429 si on tape plus de 5 fois/s, throttle. » Ce genre de savoir vaut de l’or et se perd sinon.

Ce qui ne doit PAS y aller

Un fichier mémoire obèse, c’est pire qu’un fichier vide : il mange du contexte à chaque session sans rien apporter. Gardez-le sec.

• Ce que le code dit déjà. Pas besoin de recopier l’arborescence ni de lister chaque fichier : l’agent sait lire le dépôt. La mémoire sert à ce qui n’est pas dans le code.
• Les secrets. Jamais. Pas une clé API, pas un mot de passe. Le fichier voyage avec le dépôt, voyez Sécuriser les accès.
• Les détails d’une seule conversation. « Hier on a renommé tel bouton » n’a rien à faire là. La mémoire, c’est le permanent, pas le journal de bord.

Un exemple concret et réutilisable

Voici à quoi ressemble un CLAUDE.md honnête pour un petit projet web. Dense, utile, sans gras :

# Kino, tableau de bord ciné

## Objectif
Regrouper les sorties ciné de la semaine (affiches, notes, synopsis),
consultable depuis mon téléphone. Usage perso, mono-utilisateur.

## Pile
- Front : Astro + TypeScript, déployé en statique.
- Données : API TMDB (clé en variable d'env `TMDB_KEY`, jamais en dur).
- Pas de base de données, pas d'auth, pas de backend en v1.

## Règles
- Montre toujours les commandes destructives (rm, git push --force) avant.
- Pas de secret en clair : tout passe par .env (déjà gitignored).
- TypeScript strict. Pas de `any` sans commentaire qui justifie.
- Ne touche jamais au dossier `vendor/` (code tiers figé).

## Commandes
- Dev : `npm run dev` (port 4321)
- Build : `npm run build`
- Tests : `npm test` (Vitest)
- Lint : `npm run lint`

## Gotchas
- TMDB renvoie du 429 au-delà de ~40 req/10s : on cache les réponses 24h.
- Les affiches manquantes arrivent en `null`, pas en chaîne vide, tester `== null`.

Vous pouvez le lire en quinze secondes. C’est l’objectif : un agent qui l’avale au démarrage repart avec tout le contexte que vous auriez dû lui réexpliquer.

La mémoire globale, pour vos préférences à vous

Le fichier global, lui, ne parle d’aucun projet en particulier. Il porte votre manière de travailler, partout :

# Préférences globales
- Réponds toujours en français.
- Préfère les solutions simples : moins de dépendances, moins d'abstraction.
- Avant toute commande sudo ou destructive, montre-la et attends mon accord.
- Pas de commentaires évidents dans le code. Commente le pourquoi, pas le quoi.

Écrivez ça une fois, et chaque nouveau projet démarre déjà à votre main.

Comment l’amorcer sans partir de zéro

Vous n’avez pas à écrire le fichier projet à la main devant une page blanche. La plupart des agents savent le générer en scannant votre dépôt, puis vous l’affinez.

La mémoire grandit avec le frottement

Ne cherchez pas à écrire le fichier parfait du premier coup. La mémoire se construit à l’usage, et il y a un signal très net : le jour où vous corrigez l’agent deux fois sur la même chose, promouvez la correction en règle.

Il refait une requête SQL non échappée ? → une ligne dans la mémoire. Il oublie systématiquement de lancer le lint avant de committer ? → une ligne. Chaque friction récurrente devient une règle, et la friction disparaît. C’est exactement le « ↻ on reboucle » du guide de cadrage : le projet vit, et la mémoire apprend avec lui.