Module 3 — CLAUDE.md, règles et mémoire : apprendre le projet à Claude

Le module 2 a montré pourquoi Claude relit CLAUDE.md à chaque /compact. Ce module en tire les conséquences : ce qu'il faut y écrire, ce qu'il faut sortir dans des règles scopées, ce qu'on laisse à la mémoire automatique que Claude alimente seul. Sur Kiosque, on remplace le CLAUDE.md généré par /init par un fichier durable qui survit à trois refontes.

Deux mécanismes complémentaires

Chaque session démarre sur un contexte vide. Deux mécanismes le remplissent : les CLAUDE.md écrits par vous (instructions, règles, chargés à chaque session — projet, utilisateur, organisation) et la mémoire automatique écrite par Claude (votre rôle, préférences, ce que vous corrigez souvent, faits que Claude ne peut pas déduire du code).

Les deux sont du contexte, pas de la configuration exécutée. Une instruction reste une consigne qu'un modèle peut ignorer si elle est vague ou contradictoire. Pour bloquer quelque chose de manière déterministe — refuser une écriture sur .env, forcer un lint — il faut un hook PreToolUse (module 9). Le triptyque est : CLAUDE.md pour ce que Claude doit savoir, skills pour ce qu'il doit savoir faire à la demande, hooks pour ce qui doit arriver quoi qu'il en soit.

Hiérarchie des fichiers mémoire

Les CLAUDE.md peuvent vivre à plusieurs niveaux. L'ordre de chargement va du plus large au plus spécifique — chaque niveau s'ajoute, aucun ne remplace l'autre.

Portée	Emplacement	Usage
Politique gérée	macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux/WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md	Instructions gérées par l'IT ou DevOps, standards de sécurité, obligations légales
Utilisateur	~/.claude/CLAUDE.md	Préférences personnelles applicables à tous les projets
Projet (partagé)	./CLAUDE.md ou ./.claude/CLAUDE.md	Conventions d'équipe, commandes de build, décisions d'architecture. Commité
Local (perso)	./CLAUDE.local.md	Vos URL de bac à sable, données de test. Ajouté au .gitignore

Claude Code charge CLAUDE.md et CLAUDE.local.md depuis votre répertoire courant et tous les dossiers au-dessus, du haut de l'arborescence vers le bas. Les fichiers dans des sous-dossiers ne se chargent qu'à la demande — quand Claude lit un fichier dans ce sous-dossier. Ce comportement est précieux dans un monorepo : apps/back/CLAUDE.md n'entre pas dans le contexte tant qu'on ne touche pas au back.

Un CLAUDE.md de plus de 4 Mio est ignoré ; un fichier de plus de 200 lignes ou 25 Ko consomme beaucoup de contexte et fait chuter l'adhérence. L'usage par défaut est de rester sous 200 lignes.

Écrire des instructions efficaces

Les instructions verbales échouent : « formate correctement », « teste ton code ». Les instructions vérifiables passent : « utilise 2 espaces d'indentation », « lance make test avant de commiter », « les gestionnaires d'API vivent dans app/api/handlers/ ». Ajoutez à CLAUDE.md chaque fois que Claude fait deux fois la même erreur ou qu'un code review attrape quelque chose qu'il aurait dû savoir. Une phrase courte, un fait par ligne, vaut mieux qu'un paragraphe dense.

Ce qu'il ne faut pas mettre : l'arborescence, la liste des dépendances, l'architecture (Claude le déduit) ; les procédures multi-étapes (c'est une skill, module 6) ; ce qui concerne un sous-dossier (c'est une règle scopée) ; des tokens ou secrets (le fichier est commité).

.claude/rules/ : découper par sujet, scoper par chemin

Le dossier .claude/rules/ permet de découper CLAUDE.md en fichiers de sujet. Tout .md sous ce dossier charge récursivement, avec la priorité de .claude/CLAUDE.md s'il n'a pas de frontmatter. Un fichier par sujet (api.md, front.md, security.md) reste plus facile à maintenir qu'un gros CLAUDE.md.

L'intérêt vient du frontmatter paths: : une règle scopée ne charge son contenu que quand Claude lit un fichier qui matche.

---
paths:
  - "app/**/*.py"
  - "tests/**/*.py"
---

# Règles API

- Toute route FastAPI valide ses entrées via Pydantic.
- Les réponses d'erreur suivent le format `{code, message, details}`.
- Les migrations SQLAlchemy sont générées avec `alembic`.
- Aucun accès direct à la session hors du dependency-injection.

Les patrons suivent la syntaxe glob habituelle : **/*.ts, src/api/**/*.ts, src/**/*.{ts,tsx} avec expansion à accolades (budget de 1 000 patrons développés et 4 Mio par règle). Un patron non lisible en expression bracket ne bloque plus depuis la v2.1.207 : il ne matche rien, la règle continue à fonctionner sur les autres.

Les règles s'appliquent quand Claude lit un fichier qui matche, pas à chaque appel d'outil. Depuis la v2.1.198, la correspondance fonctionne aussi via un chemin symlinké.

Imports @chemin

Un CLAUDE.md peut importer d'autres fichiers avec la syntaxe @chemin (relatif au fichier qui importe ou absolu). Les imports sont dépliés au démarrage, avec une profondeur maximale de quatre.

Voir @README pour la vue d'ensemble et @package.json pour les scripts.

## Conventions détaillées
- Style Python : @docs/conventions-python.md
- Style front : @docs/conventions-front.md

Les imports dans un fichier de portée projet dont le chemin résout hors du répertoire de travail (par exemple @~/notes.md) sont sensibles : la première fois, Claude Code ouvre un dialogue d'approbation ; un refus les désactive silencieusement. Les user-scope memory files chargent leurs imports sans dialogue. Pour partager les mêmes règles entre projets, un symlink fait l'affaire : ln -s ~/shared-claude-rules .claude/rules/shared.

AGENTS.md et compatibilité

Claude Code lit CLAUDE.md, pas AGENTS.md. Deux options si votre dépôt utilise déjà AGENTS.md : un CLAUDE.md qui l'importe (@AGENTS.md), ou un symlink ln -s AGENTS.md CLAUDE.md. /init lit en plus .cursor/rules/, .cursorrules, .github/copilot-instructions.md. Avec CLAUDE_CODE_NEW_INIT=1, il ajoute aussi AGENTS.md, .devin/rules/, .windsurf/rules/, .clinerules. La commande /import [codex|gemini] (v2.1.213+) apporte la configuration d'un autre agent en une passe.

La mémoire automatique

La mémoire automatique est activée par défaut. Chaque fois que Claude apprend quelque chose de durable, il l'écrit lui-même dans ~/.claude/projects/<projet>/memory/. Quatre types de notes marquées par un champ type : user (votre rôle, préférences), feedback (corrections données à Claude, approches validées), project (décisions, échéances, faits que Claude ne peut pas déduire du code), reference (où trouver de l'information hors du projet). Claude n'écrit pas à chaque session ; il décide au fil de l'eau si un fait vaut d'être retenu et évite ce que le code montre déjà.

Le dossier contient un index MEMORY.md — la seule chose chargée à chaque session (200 lignes ou 25 Ko) — et un fichier par sujet (user_role.md, feedback_testing.md) lu à la demande. Depuis la v2.1.214, chaque note reçoit un champ modified en ISO 8601 lors de la réécriture.

Pour désactiver : "autoMemoryEnabled": false dans le settings.json du projet, ou globalement CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. La clé autoMemoryDirectory change l'emplacement (chemin absolu ou ~/...). La mémoire de la session principale n'est pas chargée dans les sous-agents — sauf pour un fork, qui hérite de la conversation parente. Un sous-agent peut avoir sa propre mémoire via le champ memory de son frontmatter (module 10).

/init, /memory, /doctor

Trois commandes couvrent le cycle de vie complet :

• /init génère un premier CLAUDE.md en analysant le dépôt. Avec CLAUDE_CODE_NEW_INIT=1, la variante interactive propose aussi skills, hooks et fichiers de mémoire personnels, et lit d'éventuelles configurations AGENTS.md ou .cursor/rules/. C'est un brouillon : à retravailler avant de commiter.
• /memory liste vos CLAUDE.md, CLAUDE.local.md et fichiers de mémoire à toutes les portées, y compris ceux qui n'existent pas encore. Sélectionnez un item pour l'ouvrir dans votre éditeur ; s'il n'existe pas, /memory le crée d'abord. La commande donne aussi le toggle de mémoire automatique et un accès direct au dossier de mémoire.
• /doctor (alias /checkup) fait un diagnostic complet et propose des correctifs : installations en double, PATH, settings illisibles, skills non utilisées, serveurs MCP dormants, CLAUDE.md trop lourd. Depuis la v2.1.206, il dégraisse un CLAUDE.md commité : il coupe ce que Claude peut déduire du code (arborescence, dépendances) et garde les pièges, la rationale et les conventions qui divergent des défauts. Il migre l'inutile-toujours vers des skills ou des CLAUDE.md imbriqués qui se chargent à la demande.

Ce qui survit à /compact

Après /compact, le CLAUDE.md du dépôt et les règles sans paths: sont ré-injectés depuis le disque. Une instruction ajoutée en conversation disparaît, un ajout au CLAUDE.md survit à toutes les compactions. Le bon réflexe quand vous corrigez Claude deux fois : ajouter la règle. /memory le fait en trois pressions de touches.

Gestion en équipe

CLAUDE.md est commité ; CLAUDE.local.md ne l'est pas. On code les conventions partagées dans le premier, les préférences personnelles dans le second. Une organisation peut pousser un CLAUDE.md géré ou un claudeMd dans managed-settings.json que les settings utilisateur, projet et local ne peuvent pas écraser — utile pour les rappels de conformité, pas pour les conventions de code (qui vivent dans le dépôt).

Dans un monorepo, la clé claudeMdExcludes (dans un settings.json de toute portée sauf managed policy) skip les CLAUDE.md d'autres équipes qui traînent dans les dossiers parents ; les patrons portent sur le chemin absolu. Le CLAUDE.md managed policy ne peut jamais être exclu.

Fil rouge Kiosque : un vrai CLAUDE.md

/init au module 1 a produit un fichier bavard. On le réécrit à la main pour qu'il tienne en une quarantaine de lignes utiles :

# CLAUDE.md — Kiosque

Application de prise de commandes pour food-trucks : API FastAPI dans
`app/`, front React dans `web/`, SQLite via SQLAlchemy.

## Commandes

- `make dev`   : lance l'API `:8000` et le front `:5173`.
- `make test`  : pytest ; ne jamais commiter si rouge.
- `make lint`  : `ruff format` puis `ruff check --fix`.
- `mypy app/`  : avant chaque PR touchant l'API.

## Conventions

- **Entités en français** : `commande`, `paiement`, `menu`. Le code
  anglais est un legacy à convertir, pas à imiter.
- Routes dans `app/routers/`, modèles dans `app/models.py`, services
  purs dans `app/services/`.
- Schémas Pydantic en `In` / `Out` (`CommandeIn`, `CommandeOut`).
- `httpx` pour les appels sortants, jamais `requests`.

## Pièges

- `test_paiements_delai` instable — pas de conclusion sur un run isolé.
- `.env` **jamais** lu ni écrit par Claude.
- Migrations SQLAlchemy via Alembic ; pas de DDL direct.

## Compact instructions

- Garder décisions d'architecture et conventions.
- Jeter les extraits de code lus et les explorations ponctuelles.

À côté, .claude/rules/api.md scopé sur app/**/*.py et tests/**/*.py (Pydantic, format d'erreur {code, message, details}, migrations Alembic) et .claude/rules/front.md scopé sur web/**/*.{ts,tsx} (composants fonctionnels, TanStack Query, Tailwind). On ajoute .env au .gitignore. Le module 9 posera un hook PreToolUse refusant l'écriture sur .env : la belt-and-suspenders qui rend la règle irréfutable.

Erreur fréquente : « pourquoi Claude ne suit pas ma règle ? »

Trois causes reviennent : la règle n'est pas chargée — /context liste les Memory files ; un fichier absent n'a aucun effet, vérifiez le chemin et, pour une règle scopée, que Claude a bien lu un fichier qui matche ; la règle est vague — « format properly » ne vaut rien face à « 2 espaces d'indentation » ; la règle contredit une autre, Claude tranche arbitrairement (/doctor détecte parfois la duplication). Un dernier levier : le hook InstructionsLoaded (module 9) trace exactement quels fichiers d'instructions chargent, quand et pourquoi.

En résumé

• Deux mécanismes : CLAUDE.md que vous écrivez, mémoire automatique que Claude alimente. Tous deux ne sont que du contexte.
• Hiérarchie : managed policy → user → project → local ; les niveaux s'ajoutent.
• .claude/rules/*.md avec paths: évite de faire grossir le CLAUDE.md principal.
• Imports @chemin dépliés à quatre niveaux ; symlinks pour partager des règles entre projets.
• AGENTS.md : n'est pas lu par défaut ; utilisez @AGENTS.md ou un symlink, ou lancez /import.
• Mémoire automatique : quatre types (user, feedback, project, reference) dans ~/.claude/projects/<projet>/memory/.
• /init produit un brouillon, /memory édite, /doctor dégraisse. Un CLAUDE.md sous 200 lignes tient la distance.

Module suivant : Commandes slash intégrées (1/2) : session, contexte, configuration et modèle — la référence exhaustive des huit familles avec chaque alias et chaque argument.