CLAUDE.md & mémoire

CLAUDE.md est un fichier Markdown à la racine du projet (ou dans des sous-dossiers) que Claude Code charge automatiquement au démarrage de chaque session. C'est l'endroit idéal pour documenter ce qui n'est pas évident en lisant juste le code :

• conventions de code spécifiques au projet
• commandes utiles (build, test, lint, déploiement)
• architecture générale et décisions techniques
• pièges connus, comportements contre-intuitifs
• règles de workflow (toujours créer une branche, ne jamais toucher à tel dossier...)

/init génère une première version en analysant automatiquement le repo (package.json, structure de dossiers, README...).

Claude Code combine plusieurs niveaux de mémoire, du plus général au plus spécifique :

1. Mémoire utilisateur (~/.claude/CLAUDE.md) : préférences valables sur tous vos projets
2. Mémoire projet (./CLAUDE.md à la racine) : partagée avec l'équipe via git
3. Mémoire locale (./CLAUDE.local.md, non commitée) : vos préférences perso sur ce projet
4. CLAUDE.md de sous-dossier : contexte spécifique à un module/package dans un monorepo

Plus le fichier est « proche » du travail en cours, plus son contenu est pertinent et prioritaire en cas de conflit.

• Restez concis et actionnable : une liste de règles claires vaut mieux qu'un essai.
• Documentez le pourquoi, pas seulement le quoi, quand une règle est contre-intuitive.
• Mettez à jour le fichier quand vous corrigez Claude Code en session : ça évite de répéter la même correction.
• Évitez les répétitions trouvables dans le code (architecture déductible du code n'a pas besoin d'être réécrite).
• Utilisez # en début de message dans le REPL pour ajouter rapidement une instruction à la mémoire sans éditer le fichier à la main.

# CLAUDE.md
## Commandes
- Build: `npm run build`
- Tests: `npm test -- --watch=false`

## Conventions
- Toujours utiliser des composants serveur sauf si interactivité requise.
- Ne jamais modifier les fichiers sous `legacy/`.

Au-delà de CLAUDE.md, Claude Code peut tenir un système de mémoire structuré (un fichier par souvenir, dans un dossier dédié) pour se souvenir, entre les sessions, d'informations sur l'utilisateur, le projet et les retours qu'il a reçus. Elle se distingue de CLAUDE.md sur un point essentiel : elle est gérée par l'agent lui-même, qui décide quand écrire un nouveau souvenir, plutôt qu'éditée manuellement par vous.

Ce que cette mémoire retient se répartit en quatre types :

Type	Ce qu'il capture	Exemple
user	Rôle, préférences, niveau d'expertise	« Data engineer, préfère les réponses courtes et chiffrées »
feedback	Une correction ou une validation données en session	« Ne pas mocker la base dans les tests d'intégration : incident passé en prod »
project	Une décision ou un contexte propre à un projet en cours	« Gel des merges après le 5 mars, coupure de la branche de release mobile »
reference	Un pointeur vers un système externe (tracker, dashboard)	« Les bugs du pipeline sont suivis dans le projet Linear "INGEST" »

Chaque souvenir est un petit fichier avec un nom, une description et son type, et un fichier index récapitule en une ligne chacun d'eux pour qu'ils restent repérables sans tout recharger.

Une mémoire enregistrée un jour peut devenir fausse le lendemain : un fichier cité a pu être renommé, une fonction supprimée, une décision de projet annulée. Avant d'agir sur la base d'un souvenir, en particulier s'il nomme un chemin de fichier, une fonction ou un identifiant précis, mieux vaut vérifier l'état actuel (le fichier existe-t-il encore ? la fonction est-elle toujours là ?) plutôt que de supposer que le souvenir est encore exact.

Ce que cette mémoire ne doit pas contenir : tout ce qui se déduit du code lui-même (conventions, architecture) ou de l'historique git (qui a changé quoi), déjà consultable directement sans avoir besoin d'être dupliqué.