CLAUDE.md sert à donner une mémoire de travail permanente à Claude Code. Au lieu de répéter votre stack, vos commandes et vos conventions à chaque session, vous les écrivez une fois. Le vrai sujet : quoi mettre dedans, où le placer et comment rester précis sans saturer le contexte.
Qu’est-ce que CLAUDE.md ?
CLAUDE.md est un fichier Markdown lu automatiquement par Claude Code pour fournir des instructions persistantes au modèle au démarrage d’une session.
Ce fichier joue le rôle de brief permanent pour l’agent IA. Il décrit le projet, ses contraintes, ses conventions et toutes les informations que vous ne voulez pas répéter à chaque nouvelle session. En pratique, il aide Claude Code à comprendre le contexte avant de proposer une modification, d’écrire du code ou d’exécuter une commande.
Il faut éviter une confusion fréquente : CLAUDE.md n’est pas un fichier de configuration applicatif. Il ne remplace pas package.json, qui décrit les dépendances et scripts Node.js, ni tsconfig.json, qui configure TypeScript, ni .env, qui stocke des variables d’environnement. CLAUDE.md est destiné au modèle, pas directement à l’application.
Claude Code est l’outil d’Anthropic conçu pour travailler dans un terminal avec une base de code. Dans sa documentation officielle, Anthropic parle de mémoire projet et de mémoire utilisateur pour désigner ces instructions persistantes. La mémoire projet concerne les consignes liées à un dépôt précis. La mémoire utilisateur concerne plutôt vos préférences personnelles, applicables à plusieurs projets.
Le bénéfice est très concret :
- Moins d’explications répétées au début de chaque session.
- Moins de suppositions hasardeuses de la part du modèle.
- Plus de cohérence dans les décisions techniques entre deux sessions.
- Un agent plus efficace, car il démarre avec les bons repères.
Par exemple, au lieu de redire à chaque fois que le projet utilise Next.js 14, Prisma 5.x, PostgreSQL et pnpm, ces informations peuvent être placées dans CLAUDE.md. Le modèle sait alors qu’il doit respecter cet environnement, éviter npm ou yarn si pnpm est la convention, et tenir compte de Prisma pour les accès à la base de données.
Mais un bon CLAUDE.md ne dépend pas seulement de ce que vous écrivez dedans. Son efficacité dépend aussi de l’endroit où il est stocké, car Claude Code ne lit pas tous les fichiers de la même manière.
Où placer CLAUDE.md ?
CLAUDE.md peut être placé à plusieurs niveaux pour distinguer les préférences globales, le contexte projet et les règles propres à certains dossiers.
Le principe est simple : Plus l’information est générale, plus elle peut vivre haut dans la hiérarchie. Plus elle dépend d’un dépôt, d’un module ou d’une équipe, plus elle doit rester proche du code concerné.
Le premier niveau utile est le fichier global, situé dans ~/.claude/CLAUDE.md. Ce fichier sert à décrire mes préférences générales de travail avec Claude Code : style de réponse, niveau de détail attendu, habitudes de validation, façon de proposer des commandes, prudence avant modification de fichiers sensibles.
Le deuxième niveau est le fichier placé à la racine du dépôt, avec ./CLAUDE.md. C’est généralement le plus important pour un projet. Il décrit le contexte principal : stack technique, commandes de test, conventions de nommage, architecture, règles de contribution, pièges connus.
Le troisième niveau concerne les sous-répertoires. Un dossier api/, frontend/, tests/ ou data/ peut avoir son propre CLAUDE.md si les règles locales diffèrent du reste du projet. Claude Code combine alors les fichiers applicables selon le contexte de travail. En pratique : Le global décrit ma manière de travailler, le fichier racine décrit le projet, le fichier de sous-dossier décrit une zone précise.
| Emplacement | Usage recommandé | Exemple d’instruction |
| ~/.claude/CLAUDE.md | Préférences générales valables pour tous les projets | Réponds en français, propose un plan avant les changements risqués, explique les commandes destructrices. |
| ./CLAUDE.md | Contexte principal du dépôt courant | Utilise pnpm, lance les tests avec pnpm test, respecte l’architecture hexagonale du projet. |
| ./api/CLAUDE.md | Règles ciblées pour une zone du code | Dans ce dossier, les routes Express doivent valider les entrées avec Zod avant d’appeler les services. |
La bonne pratique consiste à éviter le fichier global fourre-tout. Les informations spécifiques au dépôt doivent rester dans le dépôt, car elles changent d’un projet à l’autre. Sinon, vous risquez de polluer Claude Code avec des règles valables hier, mais fausses aujourd’hui.
Une fois le bon niveau choisi, il faut structurer le contenu pour aider le modèle sans le noyer.
Que mettre dans CLAUDE.md ?
Un bon CLAUDE.md contient peu d’informations, mais les informations qui évitent réellement les mauvaises décisions du modèle. Pour l’aperçu projet, une ou deux phrases suffisent : ce que fait l’application, pour qui elle existe, et éventuellement la contrainte métier principale. Il ne faut pas recopier le README complet. Claude Code n’a pas besoin d’un dossier marketing, il a besoin de contexte opérationnel pour modifier le code sans partir dans une mauvaise direction.
La stack technique, c’est-à-dire l’ensemble des technologies utilisées, doit être précise, surtout sur les versions. Par exemple : Node.js 20, TypeScript 5.3, Next.js 14, Prisma 5.x avec PostgreSQL, Tailwind CSS 3.x, Vitest pour les tests unitaires et Playwright pour les tests end-to-end, c’est-à-dire les tests qui simulent un vrai parcours utilisateur dans le navigateur. Les versions comptent parce qu’elles évitent à Claude Code de proposer des API, des options de configuration ou des conventions qui n’existent pas dans votre projet.
Les commandes courantes doivent donner les chemins rapides, pas documenter tout le projet. L’agent doit pouvoir lancer le serveur, tester, migrer la base de données et compiler sans deviner. Les commandes utiles ressemblent souvent à ceci :
- Développement local : pnpm dev.
- Tests unitaires : pnpm test.
- Tests end-to-end : pnpm test:e2e.
- Migration de base de données : pnpm db:migrate.
- Build de production : pnpm build.
Les conventions de code doivent couvrir les décisions qui reviennent souvent. Préférer les exports nommés facilite les imports explicites et la recherche dans le projet. Utiliser const plutôt que let quand la variable n’est pas réassignée réduit les mutations inutiles. Gérer explicitement les erreurs asynchrones évite les promesses rejetées silencieusement. Limiter les commentaires évidents garde le code lisible. Respecter les conventions de nommage des fichiers évite de créer des composants, routes ou tests au mauvais endroit.
Un contenu compact peut ressembler à ceci :
- Projet : Application SaaS B2B de suivi des factures pour des équipes finance.
- Stack : Node.js 20, TypeScript 5.3, Next.js 14, Prisma 5.x, PostgreSQL, Tailwind CSS 3.x, Vitest, Playwright.
- Commandes : pnpm dev, pnpm test, pnpm test:e2e, pnpm db:migrate, pnpm build.
- Conventions : Exports nommés, const par défaut, erreurs async gérées avec try/catch ou retour typé, commentaires uniquement si la logique n’est pas évidente, fichiers en kebab-case.
Chaque ligne doit mériter sa place.
Comment éviter un CLAUDE.md trop lourd ?
Il faut garder CLAUDE.md court, car son contenu consomme une partie de la fenêtre de contexte disponible pour la session.
La fenêtre de contexte, c’est la quantité d’informations que le modèle peut prendre en compte à un instant donné dans une conversation : vos consignes, les fichiers lus, le code ouvert, l’historique des échanges et les réponses déjà produites. Anthropic documente de longues fenêtres de contexte pour les modèles Claude récents, par exemple jusqu’à 200 000 tokens sur plusieurs modèles selon les offres et les versions. Un token correspond grosso modo à un morceau de mot. Mais dans une vraie session de travail, cet espace reste limité.
Un CLAUDE.md trop long crée vite un mauvais compromis. Plus il contient de texte, plus il ajoute du bruit. Moins il reste de place pour le code en cours, les erreurs de test, les logs ou les fichiers vraiment utiles. Les consignes importantes peuvent aussi se retrouver noyées dans des détails secondaires. Résultat : Claude peut raisonner plus lentement, répondre de façon moins ciblée, ou appliquer une règle ancienne alors qu’elle ne concerne plus le problème actuel.
Je le traite donc comme une fiche de cadrage, pas comme une documentation complète. Pour le nettoyer, la méthode est simple :
- Supprimer ce qui est déjà évident dans le code, les noms de fichiers ou les conventions visibles.
- Remplacer les paragraphes longs par des listes courtes, actionnables et faciles à scanner.
- Séparer les règles globales, valables pour tous vos projets, des règles propres au dépôt.
- Déplacer les consignes très spécifiques dans les CLAUDE.md des sous-dossiers concernés.
- Mettre à jour le fichier dès qu’une commande, une version de framework ou une règle d’équipe change.
Cette checklist suffit souvent à éviter l’empilement :
- Cette ligne évite-t-elle une erreur fréquente ?
- Cette information change-t-elle selon le projet ?
- Cette règle appartient-elle au global, au dépôt ou à un sous-dossier ?
- Cette consigne est-elle encore vraie aujourd’hui ?
- Cette phrase peut-elle être remplacée par une règle plus courte ?
Un CLAUDE.md efficace n’est pas celui qui dit tout. C’est celui qui donne au modèle les bons repères au bon moment, avec assez peu de bruit pour laisser de la place au vrai travail : comprendre le code, raisonner sur le problème et produire une modification fiable.
Et si votre agent IA démarrait enfin avec le bon contexte ?
CLAUDE.md est l’un des leviers les plus simples pour rendre Claude Code plus utile au quotidien. Je l’utilise comme un brief permanent : le projet, la stack, les commandes, les conventions et les règles qui évitent les mauvaises hypothèses. Son efficacité dépend surtout de trois décisions : placer les instructions au bon niveau, écrire court, et garder uniquement ce qui améliore réellement les réponses. Un fichier trop long devient du bruit. Un fichier bien tenu devient un gain de temps à chaque session. Le bénéfice pour vous : moins de répétitions, moins d’erreurs et un agent IA plus aligné avec votre code.
FAQ
- CLAUDE.md est-il obligatoire pour utiliser Claude Code ?
Non. Claude Code peut fonctionner sans CLAUDE.md. Le fichier devient utile dès que vous voulez éviter de répéter les mêmes consignes : stack technique, commandes, conventions de code, structure projet ou règles d’équipe. - Quelle différence entre CLAUDE.md et un README ?
Le README s’adresse surtout aux humains qui découvrent le projet. CLAUDE.md s’adresse à l’agent IA. Il doit être plus court, plus opérationnel et centré sur ce que Claude Code doit savoir pour proposer du code cohérent. - Faut-il mettre les secrets ou variables d’environnement dans CLAUDE.md ?
Non. CLAUDE.md ne doit pas contenir de secrets, clés API, mots de passe ou jetons d’accès. Il peut mentionner qu’un fichier .env existe ou qu’une variable est nécessaire, mais jamais exposer sa valeur sensible. - Quelle longueur idéale pour un fichier CLAUDE.md ?
Il n’y a pas de taille universelle. La bonne règle est simple : chaque ligne doit aider Claude Code à éviter une erreur ou à agir plus vite. Si le fichier ressemble à une documentation complète, il est probablement trop long. - Peut-on avoir plusieurs fichiers CLAUDE.md dans un même projet ?
Oui. L’intérêt est de garder les instructions au bon niveau : globales pour vos préférences, projet pour le dépôt, locales pour un sous-dossier. Cette logique évite de charger des règles inutiles quand elles ne concernent qu’une partie du code.
A propos de l’auteur
Je suis Franck Scandolera, responsable de l’agence webAnalyste et de l’organisme Formations Analytics. J’accompagne des équipes sur le tracking avancé server-side, l’Analytics Engineering, l’automatisation No/Low Code avec n8n, l’intégration de l’IA en entreprise et le SEO/GEO. J’ai travaillé pour des organisations comme Logis Hôtel, Yelloh Village, BazarChic, la Fédération Française de Football ou Texdecor. Si vous voulez structurer vos usages IA, automatiser vos workflows ou fiabiliser vos données, je suis disponible pour vous aider : contactez-moi.
⭐ Analytics engineer, Data Analyst et Automatisation IA indépendant ⭐
- Ref clients : Logis Hôtel, Yelloh Village, BazarChic, Fédération Football Français, Texdecor…
Mon terrain de jeu :
- Data Analyst & Analytics engineering : tracking avancé (GA4, Matomo, Piano, GTM server, Tealium, Commander Act, e-commerce, CAPI, RGPD), entrepôt de données (BigQuery, Snowflake, PostgreSQL, ClickHouse), modèles (Airflow, dbt, Dataform), dashboards décisionnels (Looker, Power BI, Metabase, SQL, Python).
- Automatisation IA des taches Data, Marketing, RH, compta etc : conception de workflows intelligents robustes (n8n, App Script, scraping) connectés aux API de vos outils et LLM (OpenAI, Mistral, Claude…).
- Engineering IA pour créer des applications et agent IA sur mesure : intégration de LLM (OpenAI, Mistral…), RAG, assistants métier, génération de documents complexes, APIs, backends Node.js/Python.