CLAUDE.md : quoi écrire pour un Claude Code fiable

CLAUDE.md est un fichier texte que Claude Code lit à l’ouverture de chaque session : il contient les commandes, les conventions ainsi que les règles de votre projet, écrites une seule fois pour ne plus avoir à les répéter. Sur un projet client, c’est la différence entre un livrable propre et une semaine entière de retours, parce que Claude arrête de deviner ce que vous voulez. Le fichier le plus étoilé de GitHub sur ce thème tient en 65 lignes et quatre règles : vous les trouverez plus bas, reprises dans un exemple complet à adapter.

Ce que Claude Code fait de votre CLAUDE.md

Chaque session de Claude Code démarre avec une mémoire vide. CLAUDE.md est la première chose qu’il charge : le contenu arrive dans la conversation juste après le prompt système.

Claude le traite comme du contexte. Rien ne l’oblige à le suivre. La documentation d’Anthropic le dit en toutes lettres : il n’y a aucune garantie de respect strict, surtout pour une consigne vague ou contradictoire. Ce qui doit arriver à coup sûr, comme lancer les tests avant chaque commit, passe par un hook, qui s’exécute quoi que Claude décide.

Plus la consigne est précise, mieux elle est suivie : « indentation de 2 espaces » marche, « formate proprement » beaucoup moins.

Autre avantage sur le chat : le CLAUDE.md à la racine du projet est relu sur le disque après un /compact. Une consigne donnée seulement dans la conversation, elle, disparaît à la compaction.

Le guide complet de Claude Code présente le fichier en une section. Cet article entre dans le détail, jusqu’aux commandes qui prouvent qu’il est bien chargé.

Où mettre le fichier CLAUDE.md

Il existe quatre emplacements, du plus large au plus précis (documentation de Claude Code, octobre 2026) :

Les fichiers ne s’écrasent pas : ils s’additionnent. Claude Code charge au lancement ceux du dossier où vous l’ouvrez et de tous les dossiers au-dessus, du plus haut au plus proche. Le plus proche est donc lu en dernier. Un CLAUDE.md placé dans un sous-dossier se charge seulement quand Claude ouvre un fichier de ce sous-dossier.

Pour un freelance, le partage le plus simple :

• ~/.claude/CLAUDE.md pour votre façon de travailler (langue, style de commit, outils préférés) ;
• ./CLAUDE.md dans le dépôt du client, pour ce qui concerne son projet et que la personne suivante devra connaître ;
• ./CLAUDE.local.md pour ce qui ne regarde que vous.

Quand le fichier du projet grossit, découpez-le dans .claude/rules/, un fichier par sujet (tests.md, api.md). Une règle qui commence par un champ paths: ne se charge que lorsque Claude touche les fichiers concernés :

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

# Règles de l’API

- Chaque route valide ses entrées avec zod.
- Les erreurs suivent le format de `src/lib/erreurs.ts`.

CLAUDE.md ou AGENTS.md : lequel lit Claude Code

AGENTS.md est le fichier d’instructions commun à Codex, Cursor et la plupart des autres agents de code. Depuis la version 2.1.277, Claude Code le lit tout seul, selon cette règle :

Le piège est dans la deuxième ligne : le jour où vous ajoutez un CLAUDE.local.md pour vos notes perso, Claude cesse de lire l’AGENTS.md du projet. Pour garder les deux, réglez Project instructions sur claude-md-and-agents-md dans /config.

Sur un projet client où d’autres développeurs utilisent d’autres agents, gardez un seul fichier de référence, AGENTS.md, et un CLAUDE.md de trois lignes qui l’importe :

@AGENTS.md

## Claude Code

Passe en mode plan avant toute modification dans `src/facturation/`.

La syntaxe @chemin fonctionne pour n’importe quel fichier (@README.md, @docs/brief-client.md), jusqu’à quatre niveaux d’imports. Attention : un fichier importé se charge en entier avec celui qui l’importe. Il range, il ne fait pas économiser de contexte.

Quoi écrire dans CLAUDE.md, et quoi laisser dehors

La règle d’Anthropic tient en une phrase : CLAUDE.md, c’est ce que vous auriez à réexpliquer. Ajoutez une ligne quand Claude fait la même erreur une deuxième fois, quand une relecture trouve quelque chose qu’il aurait dû savoir, ou quand vous retapez la correction de la veille.

Ce qui y va :

• Les commandes : lancer le projet, les tests, le lint, le déploiement.
• Les conventions qui diffèrent des habitudes : la langue des noms de variables, le format des dates, la bibliothèque imposée par le client.
• Les pièges : le fichier généré à ne jamais modifier à la main, la table en production qu’aucun script ne doit toucher.
• Les raisons : pourquoi telle décision a été prise, pour que Claude ne la défasse pas en voulant bien faire.

Écrivez des consignes vérifiables. « Lance npm test avant de dire que c’est fini » se vérifie. « Teste tes changements » ne se vérifie pas.

Ce qui n’y va pas :

• Une procédure en plusieurs étapes (publier une version, préparer une démo) : c’est un skill, chargé seulement quand il sert.
• Une obligation sans exception : c’est un hook.
• Ce que Claude trouve seul dans le code : l’arborescence, la liste des dépendances. /doctor propose justement de couper ces passages.
• Les secrets : aucune clé d’API, aucun mot de passe, le fichier part dans Git.

Visez moins de 200 lignes. Un fichier plus long coûte du contexte à chaque message et se suit moins bien, et ce contexte se paie en quota : c’est l’une des raisons pour lesquelles vous atteignez la limite de Claude plus vite que prévu.

Le fichier aux 225 000 étoiles : 4 règles de comportement

Les guides parlent du projet : commandes, structure, conventions. Le dépôt andrej-karpathy-skills ↗ (nouvel onglet) s’attaque à autre chose : la façon dont Claude travaille. C’est un CLAUDE.md de 65 lignes, tiré des observations publiées par Andrej Karpathy en janvier 2026 sur les défauts des modèles qui codent. Il comptait 225 200 étoiles sur GitHub le 27 octobre 2026.

Ses quatre règles, et le retour client que chacune évite :

1. Réfléchir avant de coder. Claude énonce ses hypothèses, présente les interprétations possibles au lieu d’en choisir une en silence, et s’arrête pour demander quand c’est flou. Vous évitez l’écran livré qui répond à une question que le client n’a pas posée.
2. La simplicité d’abord. Aucune fonction non demandée, aucune abstraction pour un code qui ne sert qu’une fois. Le fichier le dit ainsi : 200 lignes qui pourraient en faire 50 se réécrivent. Vous évitez l’usine à gaz qu’il faudra maintenir.
3. Des modifications chirurgicales. Claude ne touche que ce qui est demandé, garde le style existant et signale le code mort sans le supprimer. Chaque ligne modifiée doit se rattacher à la demande. Vous évitez la régression dans un module que personne n’avait demandé de changer.
4. Un objectif vérifiable. « Corrige le bug » devient « écris un test qui reproduit le bug, puis fais-le passer », avec un plan où chaque étape a sa vérification. Claude ne dit plus « c’est terminé » sans l’avoir prouvé.

Le fichier assume sa contrepartie dès ses premières lignes : il fait passer la prudence avant la vitesse. Claude pose plus de questions et va un peu moins vite. Sur une coquille ou une ligne évidente, le fichier vous laisse juger.

Pour l’installer dans tous vos projets, sous forme de plugin Claude Code :

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

Ou dans un seul projet, à la suite d’un CLAUDE.md existant :

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Une précaution pour le dépôt d’un client : le README annonce une licence MIT, mais le dépôt ne contient aucun fichier de licence. Reformuler les quatre règles dans le CLAUDE.md du projet, avec vos mots, évite la question.

Un exemple de CLAUDE.md pour un projet client

Voici un exemple complet, pour un outil interne type : une application Next.js qui prépare les relances d’impayés d’un cabinet comptable. Une quarantaine de lignes : le projet d’abord, le comportement ensuite.

# Relances impayés, cabinet Martin

Outil interne : lit les factures impayées dans Pennylane et prépare les
relances que l’assistante valide avant envoi. Brief du client : @docs/brief-client.md

## Commandes

- `npm run dev` : lance l’app sur le port 3000
- `npm test` : tests unitaires (vitest), à lancer avant de dire que c’est fini
- `npm run typecheck` : doit passer sans erreur
- Déploiement : un push sur `main` part en production, donc toujours une PR, jamais de push direct sur `main`

## Conventions

- Code et noms de variables en anglais, textes affichés en français
- Montants en centimes (entiers), jamais en flottants
- Dates au format JJ/MM/AAAA à l’écran, ISO en base
- Les appels à Pennylane passent tous par `lib/pennylane.ts`

## Pièges

- `generated/` est produit par `npm run codegen` : ne jamais l’éditer à la main
- Aucune relance ne part sans validation humaine : ne pas ajouter d’envoi automatique
- Les données de test sont dans `fixtures/`, jamais de vrais clients dans les tests

## Comportement

- Hypothèses énoncées avant de coder ; si la demande est floue, demande
- Le code minimal qui répond à la demande, rien de spéculatif
- Ne modifie que ce qui est demandé ; signale le code mort, ne le supprime pas
- Chaque tâche a son critère de fin vérifiable (un test qui passe, une page qui s’affiche)

## Livraison

- Un commit par changement, message en français à l’impératif
- Résume en fin de tâche : ce qui a changé, ce qui reste à vérifier par moi

Le bloc « Comportement » reprend les quatre règles en quatre lignes. Le bloc « Pièges » fait le plus gros du travail : c’est lui qui empêche Claude de casser ce que le client vous a dit de ne pas toucher.

Créer, ouvrir et vérifier votre CLAUDE.md

• /init génère un premier CLAUDE.md à partir du code (commandes, tests, conventions trouvées). Si le fichier existe déjà, il propose des améliorations au lieu de l’écraser. Il récupère aussi les règles de Cursor (.cursorrules) ou de Copilot si le projet en a.
• /memory liste vos fichiers CLAUDE.md et les ouvre dans votre éditeur. C’est aussi là que vous coupez la mémoire automatique, les notes que Claude prend seul dans ~/.claude/projects/.
• /context montre, sous Memory files, les fichiers réellement chargés. Si le vôtre n’y est pas, Claude ne le voit pas.
• /doctor prompt-audit (version 2.1.283 ou plus récente) cherche les consignes périmées, les fichiers cités qui n’existent plus et les contradictions entre fichiers. Rien ne change sans votre accord.

Le signe que le fichier marche se voit dans les diffs : moins de lignes modifiées hors sujet, et des questions posées avant le code plutôt qu’après l’erreur. Les notions de contexte et de tokens derrière tout ça sont détaillées dans les 23 concepts de Claude.