Guide d'utilisation de CLAUDE.md : graver les règles du projet dans sa mémoire

📚 Navigation dans la série : L'article précédent 17 Images et multimodalité vous a appris à fournir directement des captures d'écran et des images d'erreur à Claude. Cet article change de cap — comment graver les « règles » d'un projet dans sa mémoire une fois pour toutes, afin qu'il les respecte automatiquement à chaque fois qu'il se met au travail, sans que vous ayez à les répéter tous les jours.

On dit souvent que plus le fichier CLAUDE.md est détaillé, mieux c'est, mais pour être honnête, le CLAUDE.md le plus inutile est justement celui qui fait trois cents lignes et dont Claude ne respecte aucune consigne.

Imaginez un fichier CLAUDE.md laissé par un prédécesseur sur un projet que vous reprenez, rédigé de manière prolixe : l'historique de l'entreprise, la vision du produit, la présentation de l'équipe, les tenants et aboutissants des choix technologiques... Vous devez faire défiler l'écran jusqu'à la deuxième page pour trouver une consigne utile comme « utiliser pnpm et non npm ». Résultat ? Claude vous fera quand même un npm install à la moindre occasion.

Le problème n'est pas qu'il n'écoute pas, c'est que cette règle est enfouie sous deux cents lignes de bavardages et que son attention a été complètement diluée.

CLAUDE.md (le fichier de mémoire de projet de Claude) est un outil formidable s'il est bien rédigé, mais un fardeau s'il est mal fait — il occupe la fenêtre de contexte de votre session à chaque fois. Plus il est lourd, moins il reste d'espace pour le travail réel. Aujourd'hui, nous allons décortiquer ce sujet : quels sont ses différents niveaux, que faut-il y mettre, que ne faut-il pas y mettre, comment faire référence à d'autres fichiers, et comment le garder concis.

Après avoir lu cet article, vous saurez :

• Ce que gèrent les trois niveaux de CLAUDE.md (niveau utilisateur / niveau projet / niveau sous-répertoire) et leur ordre de chargement.
• Une liste de contrôle « À inclure vs À ne pas inclure », pour éviter 90 % des erreurs des débutants qui le remplissent de choses inutiles.
• La bonne façon d'utiliser la syntaxe @ pour référencer d'autres fichiers, et son véritable coût en termes de contexte.
• La méthode officielle pour ajouter temporairement une règle dans la mémoire pendant une session, accompagnée d'un tableau comparatif « Bonnes vs Mauvaises » règles comme modèle.

ℹ️ Cet article se concentre uniquement sur la façon de bien rédiger et de maintenir le fichier CLAUDE.md. L'utilisation de /init pour le générer en un clic a été abordée dans l'article 12 Initialisation du projet, et le mécanisme plus large de mémoire automatique (auto-memory) sera traité spécifiquement dans l'article 25 Système de mémoire.

---

01 Pour commencer : qu'est-ce que CLAUDE.md, au juste ?

Commençons par la conclusion : CLAUDE.md est une « instruction persistante » que vous écrivez pour Claude. À chaque nouvelle session, il la lit d'abord et la stocke dans son cerveau comme contexte du projet.

Pourquoi est-ce nécessaire ? Parce que chaque session de Claude Code commence à partir d'une page blanche — ce que vous lui avez expliqué avec insistance la dernière fois (« utilise pnpm, ne touche pas au répertoire legacy, exécute les tests de telle manière »), il l'aura complètement oublié. Sans CLAUDE.md, vous devriez réexpliquer tout cela à chaque fois, n'est-ce pas fastidieux ?

Analogie : le manuel d'intégration pour un nouvel employé. Le premier jour d'un nouveau, vous n'allez pas rester à côté de lui toute la journée pour lui dicter les règles. Vous lui donnez un manuel : le but du projet, comment commiter le code, les pièges à éviter. Il le lit et peut commencer à travailler. CLAUDE.md est ce manuel d'intégration pour Claude — et c'est un manuel qu'il relira chaque jour avant de commencer à travailler.

Mais il y a une notion clé ici, et la documentation officielle est très franche à ce sujet :

Le contenu de CLAUDE.md est transmis comme un message utilisateur après le prompt système, et ne fait pas partie du prompt système lui-même. Claude le lit et tente de le suivre, mais il n'y a pas de garantie de respect strict.

En clair : CLAUDE.md est une « forte recommandation », pas une « règle d'or (loi d'airain) ». Il façonne le comportement de Claude, mais ce n'est pas une contrainte stricte et obligatoire. Par conséquent, plus vous êtes précis et concis, mieux il sera respecté. Espérer qu'il bloquera à 100 % une action dangereuse ? C'est le rôle des Hooks (crochets), pas de CLAUDE.md — la division de ces tâches sera expliquée dans les prochains chapitres.

Quand faut-il y ajouter du contenu ? La documentation officielle donne plusieurs signaux très concrets :

• Claude fait la même erreur une deuxième fois — Cela indique que cette règle doit y être inscrite pour être fixée.
• Vous tapez à nouveau au cours de cette session la même correction que vous aviez tapée lors de la session précédente.
• Lors de la révision du code, vous réalisez qu'il aurait dû connaître une certaine convention de cette base de code.
• De nouveaux coéquipiers ont besoin du même contexte pour s'intégrer rapidement.

💡 En résumé : CLAUDE.md est le manuel d'intégration que Claude doit lire à chaque début de travail, c'est une recommandation « forte » mais non « absolue ». Plus il est rédigé de manière spécifique, plus il est efficace.

---

02 Les trois niveaux : qui gère le global, qui gère le projet unique

Il n'y a pas qu'un seul fichier CLAUDE.md, il peut être placé à plusieurs endroits, avec une portée allant de la plus large à la plus restreinte. C'est ici que les débutants s'y perdent le plus facilement, clarifions cela une fois pour toutes.

Selon la documentation officielle, les trois niveaux les plus courants (plus une variante locale) sont :

Niveau	Emplacement	Portée de l'effet	Inclure dans git ?
Niveau Utilisateur	~/.claude/CLAUDE.md	Tous les projets sur cette machine	Non, pure préférence personnelle
Niveau Projet	./CLAUDE.md ou ./.claude/CLAUDE.md	Ce projet actuel	✅ Oui, partagé avec l'équipe
Niveau Sous-répertoire	N'importe quel sous-répertoire/CLAUDE.md	Chargé uniquement lorsque Claude lit un fichier de ce répertoire	✅ Oui, adapté aux dépôts multi-modules
Niveau Local (Variante)	./CLAUDE.local.md	Projet actuel, uniquement pour vous	❌ À ajouter dans .gitignore

Il existe également un niveau « de stratégie gérée », déployé par les administrateurs informatiques dans les répertoires système (sur macOS, /Library/Application Support/ClaudeCode/CLAUDE.md), qui est chargé avant le niveau utilisateur et ne peut pas être contourné par l'utilisateur. Les utilisateurs personnels ne le rencontrent généralement pas, il est donc omis dans cet article ; les utilisateurs en entreprise peuvent consulter la documentation officielle.

Comment répartir les tâches ? Retenez une phrase : les habitudes personnelles vont dans le niveau utilisateur, les règles de l'équipe vont dans le niveau projet.

• Niveau Utilisateur (~/.claude/CLAUDE.md) : Placez-y vos préférences personnelles communes à tous les projets. Par exemple, « répondre en français », « expliquer la logique avant de modifier le code », « écrire les messages de commit en anglais ». Ces points ne sont pas liés à un projet spécifique, ce sont vos habitudes « à vous », elles s'appliquent donc à tous les projets et ne sont ajoutées au git d'aucun projet.
• Niveau Projet (./CLAUDE.md) : Placez-y les règles exclusives à ce projet et que toute l'équipe doit respecter. La pile technologique, les commandes de build, les conventions de répertoires, les listes de fichiers à ne pas modifier. Il est versionné avec le code, et lorsqu'un nouveau collègue le clone, il obtient automatiquement ces règles.
• Niveau Sous-répertoire : Utile principalement pour les gros dépôts. Par exemple, placez un fichier spécifique au front-end dans le répertoire front-end, et un spécifique au back-end dans le répertoire back-end. Normalement, il n'est pas chargé, mais seulement lorsque Claude lit effectivement des fichiers dans ce répertoire, il intègre ce CLAUDE.md supplémentaire — ce qui économise du contexte.

L'analogie du manuel d'intégration s'applique toujours : Niveau utilisateur = votre propre carnet d'habitudes de travail (que vous emportez en changeant d'entreprise) ; Niveau projet = le manuel de l'employé fourni par cette entreprise (que vous rendez en partant) ; Niveau sous-répertoire = les consignes spécifiques à un département (qui ne vous sont fournies que si vous êtes transféré dans ce département).

Voici un exemple de configuration courante au niveau utilisateur : mettre la phrase « Lorsque plusieurs solutions sont possibles, liste les options pour que je choisisse, plutôt que de décider silencieusement à ma place » dans ~/.claude/CLAUDE.md. Cette règle s'applique à tous vos projets, il est donc plus simple de la mettre au niveau utilisateur — une fois configurée, vous n'aurez plus jamais à la répéter dans un nouveau projet.

💡 En résumé : Écrivez vos habitudes personnelles au niveau utilisateur (~/.claude/CLAUDE.md), les règles de l'équipe au niveau projet (versionné avec ./CLAUDE.md dans git), et pour les grands dépôts, divisez par module en utilisant le niveau sous-répertoire.

---

03 Ordre de chargement : pourquoi le niveau projet a « le dernier mot »

La section précédente a répertorié trois niveaux, mais s'ils existent en même temps, lequel a la priorité ? C'est une autre source de confusion fréquente, il faut être précis.

Règle officielle : ils sont chargés séquentiellement de la portée la plus large à la portée la plus spécifique. Plus l'instruction est proche du répertoire à partir duquel vous avez démarré, plus elle est lue tardivement.

Comment s'organisent-ils concrètement ? Claude Code part de votre répertoire actuel et remonte tout au long de l'arborescence, en récupérant chaque CLAUDE.md qu'il trouve, pour finalement assembler le tout en un seul bloc de contexte. L'ordre ressemble à ceci :

Niveau Utilisateur ~/.claude/CLAUDE.md
        ↓ (Lu en premier)
CLAUDE.md des répertoires parents (plus haut dans l'arborescence)
        ↓
Racine du projet ./CLAUDE.md
        ↓ (Lu en dernier, le plus proche de vous)
CLAUDE.md du sous-répertoire (chargé uniquement si Claude lit des fichiers dans ce répertoire)

Notez deux points importants, tous deux issus de la documentation officielle :

Premièrement, tous les fichiers trouvés sont « concaténés », pas « écrasés ». Ils sont tous ajoutés au contexte, les derniers n'effacent pas les premiers. Donc le niveau utilisateur et le niveau projet sont actifs simultanément, il n'y a pas de scénario du type « si je configure le niveau projet, le niveau utilisateur est désactivé ».

Deuxièmement, les instructions plus proches du répertoire de travail sont « lues en dernier ». Lorsque deux règles se contredisent — par exemple, le niveau utilisateur dit « utilise des guillemets simples pour les chaînes » et le niveau projet dit « utilise des guillemets doubles » — le niveau projet, plus proche et l'ayant « dit » en dernier, a généralement le dessus. En clair, les règles du projet peuvent surpasser vos habitudes personnelles, et c'est exactement l'effet recherché pour le travail en équipe.

Cette image superpose les trois niveaux de haut en bas : Niveau Utilisateur (gère tous les projets, lu en premier), Niveau Projet (projet actuel, versionné), Niveau Sous-répertoire (au plus près du code, a la priorité en cas de conflit) ; la flèche à droite indique l'ordre de chargement « de haut en bas », la règle d'or en bas indique que les trois niveaux sont concaténés, non écrasés, et plus ils sont proches du code, plus ils sont lus tard et ont le dernier mot.

Il est nécessaire de corriger ici une idée fausse courante. De nombreux tutoriels en ligne décrivent la priorité comme « Local au projet → Racine du projet → Sous-répertoire → Global », ce qui est l'inverse de la direction de chargement décrite par la documentation officielle. Il est facile d'être induit en erreur par cette affirmation, mais consulter la documentation officielle dissipera la confusion : elle indique clairement qu'ils sont chargés « de la portée la plus large à la portée la plus spécifique », et que les instructions de projet apparaissent après les instructions utilisateur. Fiez-vous à la documentation officielle, ne retenez pas l'ordre à l'envers.

Encore un détail appréciable : le fichier CLAUDE.md à la racine du projet sera automatiquement relu depuis le disque après un /compact (compression de la conversation), il ne se perdra pas. Mais les CLAUDE.md imbriqués dans les sous-répertoires ne seront pas réinjectés automatiquement, ils ne reviendront que la prochaine fois que Claude lira un fichier dans ce répertoire. Par conséquent, essayez de placer les règles importantes à la racine du projet, ne les enfouissez pas trop profondément.

💡 En résumé : Les différents niveaux de CLAUDE.md sont concaténés et non écrasés, les plus proches du répertoire de travail sont lus plus tard et l'emportent en cas de conflit, c'est pourquoi les règles de projet l'emportent sur les habitudes personnelles — ne confondez pas le sens de chargement officiel.

---

04 Que faut-il inclure vs Que ne faut-il pas inclure

Cette section est le cœur du problème. Si CLAUDE.md n'est pas bon, c'est dans 90 % des cas parce que « ce qui devrait y être n'y est pas clair, et il est rempli de choses inutiles ».

Commençons par ce qu'il faut écrire — la documentation officielle le résume en une phrase : Écrivez « les faits que Claude doit garder à l'esprit dans chaque session ». Traduit en liste de contrôle, cela donne ces cinq catégories :

Catégorie	Ce qu'il faut écrire précisément	Exemple
Aperçu du projet	En une phrase, expliquer le but du projet	« Backend de gestion des commandes basé sur FastAPI »
Pile technologique	Langage, framework, base de données, outils clés	« Python 3.11 / PostgreSQL / pytest »
Commandes courantes	Comment lancer les tests, le build, les vérifications	uv run pytest, uv run ruff check .
Conventions de code	Style, nommage, pratiques obligatoires	« Les fonctions doivent avoir des annotations de type », « Chaînes de caractères avec des guillemets doubles »
« Ne pas faire » explicites	Pièges, fichiers interdits à la modification, actions nécessitant l'autorisation préalable	« Ne pas modifier les fichiers existants dans migrations/ »

Parmi eux, les commandes courantes sont les plus fréquemment consultées — Claude consultera ces commandes avant d'exécuter des tests ou un build, ce qui lui évite de deviner aveuglément ou de se tromper d'outil. La liste d'interdictions sert de garde-fou pour l'empêcher d'être « intelligent mais source de problèmes » : quels répertoires contiennent du code hérité uniquement en lecture, quels fichiers doivent être discutés avec vous avant modification, pour quels fichiers de clés secrètes l'affichage de leur contenu est interdit.

Parlons maintenant de ce qu'il ne faut pas écrire, le piège majeur pour les débutants :

• ❌ De longs paragraphes de contexte : Présentation de l'entreprise, vision du produit, contexte historique des choix technologiques — Claude n'en a pas besoin pour coder, cela ne fait que consommer du contexte.
• ❌ Informations obsolètes : Changer de gestionnaire de paquets sans mettre à jour CLAUDE.md, y laissant npm, ce qui finit par l'induire en erreur.
• ❌ Des informations que l'on peut déduire en lisant le code : Ne pas répéter à quoi sert chaque fichier dans l'arborescence, ne pas recopier les règles de style de code déjà définies dans la configuration ESLint. Claude sait lire le code lui-même, répéter ces choses est un gaspillage d'espace.

L'approche de la documentation officielle à ce sujet est très claire et définit des limites précises :

Essayez de limiter chaque fichier CLAUDE.md à moins de 200 lignes. Les fichiers plus longs consomment plus de contexte et diminuent le respect des règles.

Pourquoi la limite de 200 lignes est-elle si critique ? Parce que CLAUDE.md partage la même fenêtre de contexte que vos conversations. Si vous y mettez trois cents lignes de contenu inutile, c'est comme si vous occupiez une grande partie de l'espace de travail dès le début, l'espace restant pour les tâches réelles se réduit — et de plus, les règles importantes se noient dans les bavardages, l'attention se dilue, et le niveau de respect baisse au lieu de monter. C'est la racine du problème des « trois cents lignes que personne n'écoute » mentionné au début.

Il existe une astuce simple et efficace : avant d'écrire une règle, posez-vous la question : « Claude peut-il déduire cela par lui-même en regardant le code ? Si oui, supprimez-la ». Ce simple geste peut réduire un fichier CLAUDE.md hérité d'un ancien projet de plus de 300 lignes à environ 80 lignes, ne conservant que les contraintes dures qu'il ne pourrait pas deviner — après ce nettoyage, ses erreurs de gestionnaire de paquets diminueront visiblement.

💡 En résumé : Rédigez « les faits que Claude doit mémoriser à chaque session » (Aperçu / Pile techno / Commandes / Conventions / Interdictions), supprimez tout ce que Claude peut déduire en lisant le code, gardez l'ensemble en dessous de 200 lignes.

---

05 Référencer d'autres fichiers : la syntaxe @ et son coût

Parfois, vous avez déjà des documents de normes tout prêts dans votre projet — un guide de conception d'API, des conventions pour la base de données. Il n'est pas nécessaire de copier le contenu dans CLAUDE.md, il suffit d'utiliser la syntaxe @ pour les référencer.

L'écriture est très simple, écrivez @ suivi du chemin n'importe où dans CLAUDE.md :

Pour l'aperçu du projet, veuillez vous référer à @README, et pour les commandes disponibles, voir @package.json.

# Autres instructions
- Workflow git @docs/git-instructions.md

Lorsque Claude lit CLAUDE.md, il va déployer le contenu de ces fichiers référencés et les charger ensemble dans le contexte. Mémorisez ces quelques détails clarifiés par la documentation officielle pour éviter les pièges :

• Les chemins relatifs sont résolus par rapport au « fichier qui contient la référence », et non par rapport à votre répertoire de travail. C'est une erreur fréquente.
• Les chemins absolus fonctionnent également ; les fichiers référencés peuvent eux-mêmes référencer d'autres fichiers, avec une récursivité allant jusqu'à quatre niveaux.
• Lorsqu'une référence vers l'extérieur du projet est rencontrée pour la première fois, Claude Code fera apparaître une boîte de dialogue d'approbation listant ces fichiers pour que vous confirmiez ; si vous la refusez, la référence sera désactivée en permanence et la boîte de dialogue ne réapparaîtra plus.

Mais voici la considération clé, répétée par la documentation officielle, et qui est le piège le plus fréquent :

Les fichiers importés sont déployés et chargés dans le contexte au démarrage. Utiliser des imports @path aide à organiser, mais ne réduit pas la taille du contexte, car les fichiers importés sont chargés au démarrage.

En termes simples : les références @ servent à « organiser », pas à « économiser ». Beaucoup de gens croient qu'en externalisant le contenu dans des fichiers tiers et en raccourcissant le CLAUDE.md principal, ils économisent du contexte — c'est faux. Les fichiers référencés sont toujours entièrement chargés dans la fenêtre dès le début, et ils consomment tout autant de tokens (contexte). Imaginez diviser un guide de normes de 500 lignes et l'importer avec @ en pensant que vous l'avez allégé, si vous regardez /context (pour voir la consommation de contexte), aucun token n'a été épargné.

Le principe est donc le suivant : les références @ sont utilisées pour rendre la structure plus claire et faciliter la maintenance humaine, mais pour économiser du contexte, il faut « réduire le contenu » ou utiliser des « règles de cheminement », et non diviser les fichiers. Les fichiers individuels référencés ne doivent pas être trop volumineux non plus, sinon ils pèseront tout autant.

Au fait, un point connexe : si vous avez des préférences de projet purement personnelles que vous ne souhaitez pas inclure dans git (comme votre URL de sandbox locale, vos données de test préférées), ne les écrivez pas dans ./CLAUDE.md, écrivez-les dans ./CLAUDE.local.md, et ajoutez ce fichier à .gitignore. Il est chargé en même temps que CLAUDE.md et traité exactement de la même manière, à la différence qu'il ne sera pas commité et n'affectera pas vos coéquipiers.

💡 En résumé : Utiliser @chemin pour importer des documents externes sert à « clarifier la structure », mais le contenu référencé sera toujours entièrement chargé dans le contexte et n'économisera aucun token ; si vous voulez économiser de l'espace, vous devez réellement supprimer du contenu ; mettez vos préférences privées dans CLAUDE.local.md et ajoutez-le au .gitignore.

---

06 Maintenance : ajouts ponctuels pendant la session, allègement régulier

CLAUDE.md n'est pas un fichier que l'on écrit une fois pour toutes et qu'on laisse prendre la poussière, il doit évoluer avec le projet. Cette section couvre deux tâches de maintenance : comment ajouter ponctuellement une règle, et comment l'alléger régulièrement.

Que faire quand on veut ajouter une règle au fil de la discussion

Cela arrive souvent : en discutant, vous corrigez Claude et vous pensez « il devrait respecter cette règle à chaque fois, il faut la noter ». La méthode officielle la plus simple — lui dire directement dans la conversation :

Ajoute « Les opérations de base de données doivent passer par la couche Service, n'écris pas de SQL directement dans les routes » dans CLAUDE.md

Claude se chargera de rédiger cette règle dans le fichier CLAUDE.md. Vous pouvez également taper la commande /memory à tout moment, et il listera tous les fichiers CLAUDE.md, CLAUDE.local.md et de règles chargés dans la session en cours ; un simple clic l'ouvrira dans votre éditeur, vous permettant de le modifier manuellement. Si vous voulez que Claude décide lui-même de la formulation, utilisez la première méthode ; si vous voulez contrôler précisément la formulation, utilisez /memory pour l'éditer vous-même.

ℹ️ Un rappel sur les différences de version : dans les premières versions de Claude Code, taper une phrase commençant par # dans le champ de saisie permettait d'ajouter rapidement une mémoire. Dans les nouvelles versions, cette interaction a changé — fiez-vous à la méthode officielle actuelle : soit dire directement à Claude de « l'ajouter à CLAUDE.md », soit utiliser /memory pour l'éditer soi-même. Si vous tapez juste « retiens ça », Claude l'enregistrera probablement par défaut dans sa propre mémoire automatique (auto-memory, c'est le sujet de l'article 25 Système de mémoire) ; si vous voulez qu'il aille explicitement dans CLAUDE.md, formulez-le clairement comme « ajoute-le dans CLAUDE.md ».

Allègement régulier, suppression des règles obsolètes ou contradictoires

Un risque pointé par la documentation officielle : lorsque deux règles se contredisent, Claude peut en choisir une au hasard. Il faut donc faire un bilan régulier pour éliminer ce qui est obsolète ou contradictoire. Quand déclencher cet allègement :

• Changement de gestionnaire de paquets / outil de build (les anciennes commandes doivent être supprimées, sinon elles l'induiront en erreur)
• Ajout ou retrait de dépendances majeures
• Mise en place de nouvelles conventions de programmation (en profiter pour vérifier qu'elles n'entrent pas en conflit avec les anciennes règles)
• Découverte que CLAUDE.md a de nouveau dépassé discrètement les 200 lignes

Pour juger si une règle est bonne, il suffit de voir si elle ressemble à une « règle » plutôt qu'à de la « prose ». La comparaison donnée par la documentation officielle est très utile, je l'ai mise sous forme de tableau :

❌ Prose floue (Inutile)	✅ Règle précise (Efficace)
Le code devrait être plutôt propre	Les fonctions ne doivent pas dépasser 50 lignes, au-delà il faut les scinder
Essaie d'écrire des tests	Chaque nouvelle fonction doit avoir un test unitaire correspondant
Fais attention à la sécurité	Les saisies utilisateur doivent passer par sanitize() avant toute requête à la base de données
Le répertoire legacy n'est pas très important	Interdiction de modifier les fichiers du répertoire legacy/
C'est mieux d'utiliser pnpm	Pour la gestion des dépendances, utiliser uniquement pnpm, interdiction d'utiliser npm et yarn

Ceux de la colonne de gauche ne servent à rien — « propre », « essaie », « fais attention » sont des termes subjectifs, Claude ne peut pas les vérifier, et ne peut donc pas les exécuter de manière fiable. Chaque règle de droite est suffisamment précise pour être vérifiable : 50 lignes, doit avoir un test, doit passer par une fonction spécifique. La documentation officielle dit précisément de « rédiger des instructions suffisamment spécifiques pour être vérifiables ».

En écrivant un CLAUDE.md, il serait bon de prendre cette habitude stricte : pour chaque règle rédigée, jouez au juge et demandez-vous « est-ce que je peux savoir d'un coup d'œil si cette règle est enfreinte ? ». Si ce n'est pas le cas, c'est qu'elle est trop vague, retournez l'affiner.

💡 En résumé : Ajoutez une règle à la volée en demandant à Claude de « l'ajouter à CLAUDE.md » ou éditez-la avec /memory ; supprimez régulièrement les règles obsolètes ou contradictoires ; les bonnes règles ressemblent à des « règles vérifiables d'un coup d'œil », pas à de la « prose » comme « faire attention, au mieux, essayer ».

---

07 En pratique : fournir un CLAUDE.md conforme pour un petit projet démo

La théorie sans la pratique ne mène à rien. Prenons un projet minimal et suivons le processus complet : « création du fichier → rédaction des règles → vérification du chargement ». Suivez ces étapes, c'est l'affaire de cinq minutes.

Étape 1 : Créer un projet démo et l'initialiser avec git (Mac / Linux)

mkdir claude-md-demo
cd claude-md-demo
git init
echo 'def add(a, b):
    return a + b' > main.py

Résultat attendu : Le répertoire claude-md-demo contient un fichier main.py et un dossier .git. L'initialisation git permet à ce fichier CLAUDE.md d'entrer dans le système de contrôle de version (condition préalable au partage en équipe).

Étape 2 : Rédiger à la main un fichier CLAUDE.md au niveau du projet concis

Utilisez votre éditeur habituel pour créer un fichier CLAUDE.md à la racine du projet et collez-y ce contenu (notez qu'il fait très peu de lignes — c'est ainsi que doit être un bon CLAUDE.md) :

# add-demo — un projet Python minimal pour démonstration

Contient uniquement une fonction `add`, pour montrer comment écrire un fichier CLAUDE.md.

## Commandes courantes
- `python -m pytest` —— exécuter les tests

## Conventions de programmation
- Toutes les fonctions doivent avoir des annotations de type
- Les chaînes de caractères doivent toujours utiliser des guillemets doubles

## Précautions
- Ne pas modifier la signature de la fonction `add` dans `main.py`, ajouter de la logique uniquement à l'intérieur

Résultat attendu : Un fichier CLAUDE.md apparaît à la racine du projet, contenant les sections ci-dessus. Le tout fait moins de 15 lignes — retenez cette notion de taille, dans les vrais projets, ne le laissez pas enfler de manière incontrôlable.

Étape 3 : Démarrer Claude, vérifier qu'il l'a bien lu

Démarrez-le dans le répertoire du projet :

claude

Après le démarrage, tapez cette commande pour confirmer le chargement :

/memory

Résultat attendu : Vous pourrez voir votre nouveau fichier ./CLAUDE.md dans la liste. S'il y figure, cela confirme que Claude l'a bien intégré à son contexte pour cette session. C'est la méthode de dépannage recommandée par la documentation officielle — si une règle n'est pas suivie, la première chose à faire est d'utiliser /memory pour vérifier si le fichier a été chargé.

Étape 4 : Lui demander de faire une tâche qui « teste la règle », pour voir s'il s'y tient

Quittez /memory et retournez dans le champ de saisie, puis tapez :

Ajoute des annotations de type à la fonction add

Résultat attendu : Dans le diff proposé par Claude, l'annotation de type utilise le style défini par le projet, et il ne modifiera pas les parties en dehors de la signature de la fonction où il lui est interdit d'intervenir. S'il suit sagement la consigne « toutes les fonctions doivent avoir des annotations de type » définie dans votre CLAUDE.md — félicitations, ce manuel d'intégration est effectif.

⚠️ Si jamais vous remarquez qu'il ne suit pas le CLAUDE.md : d'abord, utilisez /memory pour confirmer que le fichier est chargé ; ensuite, vérifiez si la règle n'est pas rédigée de manière trop vague (comme le mot « propre ») ; enfin, cherchez s'il y a un conflit entre deux règles. Ce sont les trois étapes de dépannage standard données par la documentation, en les suivant vous devriez pouvoir identifier le problème.

💡 En résumé : Parcourez le flux « créer un fichier → écrire des règles concises de moins de 15 lignes → confirmer le chargement avec /memory → lui donner une tâche pour tester les règles », si cela ne marche pas, suivez cet ordre de dépannage officiel : vérifier avec /memory → vérifier le flou → vérifier les conflits.

---

08 Résumé

Dans cet article, vous avez exploré de fond en comble CLAUDE.md, la « mémoire de projet de Claude » :

Dimension	Conclusion clé
Ce que c'est	Le manuel d'intégration obligatoire à lire à chaque session, niveau « recommandation forte », non contraignant
Les niveaux	Utilisateur (personnel) / Projet (équipe via git) / Sous-répertoire (sur demande)
Ordre de chargement	Concaténation sans écrasement, plus proche = lu plus tard = prioritaire en cas de conflit
Ce qu'il faut écrire	Aperçu / Pile / Commandes / Conventions / Zones interdites, supprimer tout ce que le code peut prouver lui-même
Référence @	Sert à organiser la structure, n'économise pas de contexte (chargé entièrement dans tous les cas)
Maintenance	Dire à Claude de « l'ajouter à CLAUDE.md » ou éditer avec /memory ; nettoyer régulièrement les règles obsolètes ou contradictoires ; règles strictes, pas de prose

Maintenant, vous devriez être capable de : savoir si une information doit aller dans CLAUDE.md et à quel niveau ; rédiger des règles spécifiques et vérifiables plutôt que de belles phrases ; utiliser les références @ pour des documents externes en comprenant leur coût sur le contexte ; et savoir comment faire des ajouts ponctuels et un allègement régulier à mesure que le projet avance. En un mot : vous êtes désormais capable de rédiger un fichier CLAUDE.md que Claude écoutera volontiers, et non un pavé de trois cents lignes ignoré par tous.

---

Article suivant 19 « Gestion du contexte » — dans cet article, nous avons souvent mentionné que « CLAUDE.md occupe la fenêtre de contexte » et que « les références @ sont toujours chargées entièrement ». Mais qu'est-ce que c'est au juste que cette fenêtre de contexte ? Que se passe-t-il quand elle est pleine ? Comment utiliser /context et /compact ? Le prochain article explorera cet espace de travail de manière approfondie. Une petite question pour vous faire réfléchir : selon vous, qu'est-ce qui consomme le plus, les tokens d'un fichier CLAUDE.md ou une conversation complète de votre part ?

---

Lectures recommandées

• Dépannage FAQ (FAQ / Troubleshooting)
• Les quatre tâches les plus courantes : explorer le code, corriger les bugs, refactoriser, écrire des tests
• Mode vocal (Voice) : dictez vos prompts au lieu de les taper