CLAUDE.md, mémoire et configuration

Le chapitre 14 a posé le principe : ce qui se répète s’écrit une fois. Dans Claude Code, ce principe prend la forme d’une hiérarchie de fichiers, et il faut savoir lequel sert à quoi.

C’est aussi le chapitre qui explique pourquoi certaines instructions ne sont jamais suivies.

La hiérarchie, dans l’ordre de chargement#

Les fichiers d’instructions se cumulent : ils ne s’écrasent pas. Ils sont concaténés du plus général au plus spécifique, ce qui donne au plus proche le dernier mot.

Claude remonte l’arborescence depuis le répertoire de lancement : lancé dans services/api/, il charge les fichiers de services/api/, de services/, et de la racine. Les CLAUDE.md situés dans des sous-dossiers ne sont pas chargés au démarrage : ils arrivent quand Claude lit un fichier de ce dossier.

Deux erreurs classiques découlent de ce tableau.

Mettre ses préférences personnelles dans le CLAUDE.md du projet. Vous les imposez à toute l’équipe. Elles vont dans ~/.claude/CLAUDE.md ou dans CLAUDE.local.md.

Ne pas ignorer CLAUDE.local.md. Ajoutez-le à .gitignore, sinon il finit versionné.

Instruction n’est pas contrainte#

C’est la distinction la plus importante du chapitre, et celle qui explique le plus de déceptions.

Un CLAUDE.md est du contexte. Il est injecté dans la conversation, Claude le lit et essaie de le suivre. Ce n’est pas une configuration appliquée par le programme.

Pour empêcher une action de façon certaine, il faut :

• une règle de permission dans settings.json — chapitre 25 ;
• ou un hook, qui s’exécute quoi qu’il arrive.

Écrire « ne modifie jamais les fichiers de migration » dans CLAUDE.md réduit la probabilité. Écrire "deny": ["Edit(./migrations/**)"] l’empêche.

Écrire un CLAUDE.md que Claude suit#

Quatre principes, tirés de ce qui rate en pratique.

Court. Visez moins de 200 lignes. Un fichier long consomme du contexte à chaque session et l’adhérence baisse. C’est mesurable et contre-intuitif : ajouter des instructions peut réduire le respect des instructions.

Ce qu’il ne peut pas deviner. Il voit l’arborescence, les dépendances, les noms de fichiers. Il ne voit pas pourquoi vous avez fait comme ça.

Vérifiable. « Utilise une indentation de 2 espaces » plutôt que « formate correctement ». « Lance npm run verify avant de proposer un commit » plutôt que « teste ton travail ».

Sans contradiction. Deux règles opposées, et Claude en choisit une au hasard. Relisez périodiquement, y compris les CLAUDE.md des dossiers parents.

Voici la forme qui fonctionne.

# Projet — API de facturation

## Commandes
- Vérification complète : `npm run verify` (lint + types + tests)
- Tests d'un seul fichier : `npm test -- chemin/du/fichier`
- Base de données locale : `docker compose up -d db`

Lance toujours `npm run verify` avant de proposer un commit.

## Ce qu'il faut savoir avant de toucher au code
- Les montants sont en centimes, en entiers. Jamais de flottant.
  Toute conversion passe par `lib/money.ts`.
- `src/legacy/` est en cours de retrait. N'y ajoute rien ; si une
  correction s'y impose, signale-le au lieu de la faire.
- Les migrations sont irréversibles en production. Ne modifie jamais
  une migration existante, ajoutes-en une nouvelle.

## Conventions
- Les erreurs métier héritent de `AppError`, jamais de `Error`.
- Les handlers HTTP ne contiennent pas de logique : ils appellent un
  service de `src/services/`.
- Un test par comportement, nommé « devrait … quand … ».

## Pièges connus
- Le client de paiement expire silencieusement au bout de 30 s. Tout
  appel doit passer par `withTimeout()`.
- Les tests d'intégration échouent si la base n'est pas vide : lance
  `npm run db:reset` avant.

<!-- Note pour les mainteneurs : ce fichier est relu à chaque revue
     trimestrielle. Les commentaires HTML ne sont pas envoyés au modèle. -->

Remarquez ce qui n’y est pas : pas d’arborescence, pas de liste de dépendances, pas de description de l’architecture. Tout cela se lit dans le code.

Découper avec .claude/rules/#

Quand les instructions grossissent, la bonne réponse n’est pas de réduire au chausse-pied : c’est de les faire arriver au bon moment.

Le dossier .claude/rules/ accueille des fichiers Markdown thématiques. Ceux qui portent un champ paths en frontmatter ne se chargent que lorsque Claude touche aux fichiers correspondants.

---
paths:
  - "src/api/**/*.ts"
---

# Règles des points d'entrée HTTP

- Toute entrée est validée par un schéma avant d'atteindre un service.
- Les erreurs sortent au format `{ code, message, details? }`.
- Aucun accès direct à la base : passe par `src/services/`.
- Chaque route nouvelle s'accompagne d'un test de contrat.

---
paths:
  - "**/*.test.ts"
  - "tests/**/*"
---

# Règles de test

- Un test par comportement, pas un test par fonction.
- Pas de `beforeEach` qui construit plus de deux objets : préfère une
  fabrique explicite.
- Les données de test sont des fabriques, jamais des fixtures figées.
- Interdiction de `sleep` : utilise les horloges factices.

Le gain est double : le contexte reste léger, et les instructions arrivent au moment où elles s’appliquent — ce qui améliore nettement leur respect.

Un fichier de .claude/rules/ sans champ paths se charge au démarrage, comme le CLAUDE.md.

Les règles personnelles vont dans ~/.claude/rules/, et s’appliquent à tous vos projets.

Les imports#

Un CLAUDE.md peut en inclure d’autres avec @chemin/vers/fichier. Les fichiers importés sont chargés au démarrage, comme le fichier qui les référence.

Voir @README.md pour le contexte général et @docs/architecture.md
pour les décisions structurantes.

# Préférences personnelles partagées entre mes worktrees
- @~/.claude/mes-regles-projet.md

Deux points à connaître.

L’import n’économise pas de contexte. Il organise. Pour économiser, il faut les règles à portée de chemin.

Un chemin entre accents graves n’est pas importé. Écrire `@README` mentionne le fichier ; @README l’importe.

Si votre dépôt utilise déjà AGENTS.md pour un autre outil, créez un CLAUDE.md qui l’importe plutôt que de dupliquer :

@AGENTS.md

## Spécifique à Claude Code
Utilise le mode plan pour toute modification sous `src/billing/`.

La mémoire automatique#

En parallèle du CLAUDE.md que vous écrivez, Claude Code tient ses propres notes : commandes de build découvertes, pièges rencontrés, préférences déduites de vos corrections.

Ces notes vivent dans ~/.claude/projects/<projet>/memory/, avec un MEMORY.md qui sert d’index — seules ses premières lignes sont chargées à chaque session, le détail partant dans des fichiers thématiques lus à la demande.

Deux différences avec CLAUDE.md : c’est Claude qui écrit, et c’est local à votre machine — rien n’est partagé avec l’équipe.

/memory permet de tout consulter et de tout modifier ; c’est du Markdown ordinaire. La désactivation se fait par le réglage autoMemoryEnabled.

Le réflexe utile : relisez-la de temps en temps. Le chapitre 13 l’a établi pour l’application, et cela vaut ici : un souvenir périmé s’applique en silence.

Diagnostiquer une instruction ignorée#

Dans l’ordre, et cela couvre presque tous les cas.

/context — le fichier est-il chargé ? S’il n’apparaît pas sous les fichiers de mémoire, Claude ne l’a jamais vu. C’est le cas le plus fréquent, et généralement une question d’emplacement.

Contradiction — une autre instruction, dans un CLAUDE.md parent ou dans une règle, dit-elle le contraire ?

Précision — l’instruction est-elle vérifiable ? « Écris du code propre » n’est pas applicable.

Nature — s’agit-il d’une intention ou d’une contrainte ? Si l’action doit être empêchée, il faut une permission ou un hook.

/doctor automatise une partie de ce diagnostic.

# Monorepo — règles communes

## Commandes
- Vérification d'un paquet : `pnpm --filter <paquet> verify`
- Vérification globale : `pnpm verify` (long, réservé à la CI)

## Règles communes à tous les paquets
- Aucune dépendance croisée entre `apps/` : passer par `packages/`.
- Les changements de schéma partagé exigent une revue des quatre équipes.
- Ne jamais modifier `packages/contracts/` sans mettre à jour les
  tests de contrat des consommateurs.

Les conventions propres à chaque domaine sont dans `.claude/rules/`.

.claude/rules/
├── api.md          → paths: apps/api/**
├── web.md          → paths: apps/web/**
├── data.md         → paths: packages/data/**
└── tests.md        → paths: **/*.test.ts

{
  "claudeMdExcludes": ["**/apps/legacy/CLAUDE.md"]
}

Ce qu’il faut retenir#