Workbranch › Guides

Comment rédiger un fichier CLAUDE.md pour Claude Code

Chaque session Claude Code démarre avec un contexte vide : vous finissez par répéter les mêmes commandes de build et les mêmes règles maison. Un fichier CLAUDE.md règle ce problème. Ce guide explique où le placer, ce qu'il doit contenir et comment vérifier que Claude le lit bien.

Mis à jour le 30 octobre 2026

Les emplacements et commandes ci-dessous ont été vérifiés dans la documentation Claude Code d'Anthropic en octobre 2026. S'il manque quelque chose dans votre version, lancez claude update.

Où se trouvent les fichiers CLAUDE.md

Vous pouvez avoir plusieurs fichiers, chacun avec une portée différente. Claude Code les combine tous au lieu de laisser l'un remplacer l'autre ; les plus spécifiques sont lus en dernier.

Les fichiers du dossier depuis lequel vous lancez Claude et de tous les dossiers parents sont chargés au démarrage. Un CLAUDE.md placé dans un sous-dossier est chargé plus tard, dès que Claude lit ou modifie un fichier de ce sous-dossier.

Créer le fichier avec /init

1. Ouvrez un terminal à la racine du projet et lancez claude.
2. Tapez /init. Claude parcourt le code et rédige un CLAUDE.md de départ avec les commandes de build, les instructions de test et les conventions qu'il trouve. Si un CLAUDE.md existe déjà, il propose des améliorations au lieu de l'écraser.
3. Relisez le brouillon et supprimez ce qui est évident ou faux.
4. Ajoutez ce que Claude ne peut pas découvrir dans le code : décisions, particularités de l'environnement, règles du type « ne jamais faire X ».
5. Committez le fichier pour que vos collègues reçoivent les mêmes instructions.

Pour le modifier plus tard, lancez /memory. La commande liste les emplacements de vos CLAUDE.md et CLAUDE.local.md pour les portées utilisateur et projet, y compris ceux qui n'existent pas encore, et ouvre dans votre éditeur le fichier choisi. Vous pouvez aussi simplement dire ajoute ceci à CLAUDE.md.

Que mettre dedans

Un test simple : si vous avez dû dire quelque chose deux fois à Claude, cela a sa place dans le fichier. Moments typiques pour ajouter une ligne : Claude répète une erreur, une revue de code relève quelque chose qu'il aurait dû savoir, ou vous tapez la même correction qu'à la session précédente.

• Commandes : comment builder, tester, linter et lancer le projet.
• Structure : où se trouve le code important, par exemple les handlers d'API sont dans src/api/handlers/.
• Conventions : nommage, formatage, règles de branches et de commits.
• Leçons apprises : ce qui piégerait un nouveau collègue.

Écrivez des règles vérifiables. Lance npm test avant de committer fonctionne mieux que teste tes modifications. Regroupez les lignes sous des titres et des puces, et supprimez les instructions contradictoires, car Claude peut suivre l'une ou l'autre. Les procédures en plusieurs étapes ou les règles qui ne concernent qu'une partie du code ont plutôt leur place dans un skill ou une règle limitée à certains chemins.

Le garder court et organisé

• Taille : visez moins de 200 lignes par fichier. Les fichiers plus longs consomment plus de contexte et sont suivis moins fidèlement.
• Imports : écrivez @README ou @docs/git-instructions.md pour inclure un autre fichier. Les chemins sont relatifs au CLAUDE.md et les imports peuvent s'imbriquer jusqu'à quatre niveaux. Les fichiers importés consomment quand même du contexte : cela aide à organiser, pas à réduire la taille. La première fois qu'un projet importe un fichier situé hors du dossier, Claude Code vous demande de l'approuver.
• Dossier de règles : placez des fichiers thématiques comme testing.md dans .claude/rules/. Ajoutez un champ paths en tête (par exemple src/api/**/*.ts) et la règle ne se charge que lorsque Claude travaille sur des fichiers correspondants.
• Audit : dans les versions récentes, /doctor prompt-audit demande à Claude de repérer les instructions obsolètes ou contradictoires et de proposer des modifications, sans rien changer tant que vous ne l'avez pas validé.

CLAUDE.md ou mémoire automatique

Claude Code tient aussi ses propres notes, appelées auto memory (mémoire automatique). C'est vous qui écrivez CLAUDE.md ; Claude écrit la mémoire automatique à partir de vos corrections et préférences. Elle est stockée par dépôt dans ~/.claude/projects/<project>/memory/, avec un index MEMORY.md dont les 200 premières lignes (ou 25 Ko) sont chargées dans chaque session. Elle reste sur votre machine et n'est pas partagée via git. Quand vous dites retiens qu'il faut toujours utiliser pnpm, cela va dans la mémoire automatique ; activez ou désactivez la fonction avec l'interrupteur de /memory. Utilisez CLAUDE.md pour tout ce que l'équipe entière doit recevoir.

Bon à savoir

• Claude Code est inclus dans les offres Pro et Max, dans le même abonnement que les applications Claude ; les membres Team et Enterprise ont un article d'aide distinct.
• CLAUDE.md oriente le comportement mais ne l'impose pas. Bloquez des commandes ou des fichiers avec des règles de permission dans les paramètres.
• Le CLAUDE.md à la racine du projet est relu depuis le disque après /compact : les règles qui s'y trouvent survivent aux longues sessions, alors que celles que vous avez seulement tapées dans le chat peuvent se perdre. Les fichiers des sous-dossiers et les règles limitées à des chemins reviennent dès que Claude touche à nouveau des fichiers correspondants.
• Les fichiers des dossiers ajoutés avec --add-dir ne sont pas chargés, sauf si vous définissez CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.

Si cela ne fonctionne pas

• Claude ignore une instruction. Lancez /context et regardez sous Memory files (fichiers de mémoire). Si le fichier n'y figure pas, Claude ne le voit pas : vérifiez le nom du fichier et que vous avez lancé Claude dans le bon dossier.
• Les règles ne sont suivies qu'une partie du temps. Rendez-les plus précises, supprimez les contradictions avec d'autres fichiers CLAUDE.md ou de règles, et raccourcissez le fichier.
• Un import ne se charge pas. Un chemin contenant des espaces demande une barre oblique inverse avant chaque espace, un chemin entre guillemets n'est pas importé et un chemin entre accents graves reste littéral. Les imports depuis l'extérieur du projet demandent votre approbation une seule fois.
• Le CLAUDE.md d'un sous-dossier semble absent. Il ne se charge qu'après que Claude a touché un fichier de ce sous-dossier.

Gardez décisions et tâches hors du fichier

CLAUDE.md sert aux règles durables, pas aux tâches ouvertes de la semaine. Le plugin Workbranch pour Claude Code couvre cette partie : lancez /workbranch:save et Claude classe les tâches, décisions et questions ouvertes de la session dans un projet Workbranch ; quand une session démarre dans un dossier lié à un projet Workbranch, le plugin affiche ce qui reste ouvert. Un essai gratuit de 3 jours est disponible sur app.workbranch.ai.

Sources

• How Claude remembers your project (documentation Claude Code, consultée le 30 octobre 2026)
• Commands (documentation Claude Code, consultée le 30 octobre 2026)
• Use Claude Code with your Pro or Max plan (centre d'aide Claude, consulté le 30 octobre 2026)

Questions fréquentes