Le fichier claude.md sert à donner une mémoire de travail claire à Claude Code. J’y mets le contexte, les règles et les conventions du projet pour éviter de tout répéter. Bien utilisé, il rend l’agent plus cohérent, plus rapide, et franchement moins fatigant à piloter.
Où placer le fichier claude.md ?
Le fichier claude.md se place à la racine du projet, dans le répertoire principal, pour que Claude Code puisse le charger automatiquement au démarrage d’une session.
C’est important parce que ce fichier est lu avant les premiers échanges. Claude Code démarre avec les bonnes consignes, le bon contexte, les bons réflexes. Il n’a pas besoin de découvrir le projet petit à petit pendant que vous lui expliquez pourquoi tel dossier est sensible, pourquoi telle commande casse tout, ou pourquoi l’auth ne doit pas être modifiée sans vérifier trois dépendances derrière.
Je le vois comme une mémoire projet persistante. Pas une documentation complète. Pas un remplacement des tests. Pas une excuse pour écrire du code flou. Juste un point d’ancrage pour que l’agent comprenne où il met les pieds. La documentation officielle de Claude Code parle d’ailleurs de mémoire projet et de mémoire utilisateur. En gros, il y a ce qui concerne le projet, et ce qui concerne vos préférences de travail. Ici, on parle bien du projet.
Dans un projet simple, je le place comme ça :
- mon-projet/
- claude.md
- src/
- tests/
- package.json
- README.md
Quand j’arrive chez un client avec une base de code déjà vivante, je mets au minimum les repères qui évitent les erreurs bêtes. C’est souvent là qu’on gagne du temps. Pas avec un prompt magique, mais avec un contexte propre.
- Nom du projet et objectif métier.
- Stack technique backend, frontend, base de données, auth.
- Structure des dossiers avec les zones à ne pas toucher sans raison.
- Commandes utiles pour lancer, tester ou vérifier le projet.
Un exemple tout simple : Si le dossier billing contient une logique de facturation sensible, je l’écris. Si les migrations doivent passer par une commande interne, je l’écris aussi. Claude Code n’a pas besoin de deviner.
Maintenant qu’on sait où ce fichier vit, le vrai sujet c’est ce qu’on met dedans pour que Claude Code arrive vraiment orienté dès le départ.
Que doit contenir un bon claude.md ?
Un bon claude.md contient le briefing technique que je ne veux pas répéter à chaque session. Il doit rester court, précis et utile. Ce n’est pas un roman, ni une documentation complète du projet. C’est le contexte opérationnel dont l’agent a besoin pour faire de meilleurs choix, éviter les fausses pistes, et respecter votre manière de travailler.
Je le vois comme quatre blocs simples. Si une information n’aide pas Claude Code à coder, tester, modifier ou raisonner correctement, je ne la mets pas dedans.
| Contexte du projet | Je donne l’objectif du produit, les utilisateurs clés, et les contraintes business ou techniques importantes. Par exemple, une application interne n’a pas les mêmes priorités qu’un SaaS public. |
| Architecture et stack | Je précise les grandes briques : frontend, backend, base de données, authentification, services externes. Pas besoin de tout détailler, juste ce qui évite les mauvaises hypothèses. |
| Conventions et standards | Je note les règles qui comptent vraiment : TypeScript strict, style de code, nommage, structure des fichiers, niveau attendu sur les tests. |
| Notes de travail | Je garde les commandes utiles, les pièges connus, les dossiers sensibles, et les zones à ne pas toucher sans validation. |
Un exemple concis peut ressembler à ça. L’idée n’est pas d’impressionner, c’est de donner juste assez de contexte pour que l’agent travaille proprement.
- Projet Application web interne pour gérer des demandes clients.
- Stack Frontend TypeScript, backend API, base relationnelle, authentification existante.
- Standards Privilégier le code lisible, garder TypeScript strict, respecter les conventions déjà présentes.
- Commandes Lancer les tests avant de proposer une modification importante.
- Attention Ne pas modifier l’authentification sans validation explicite.
Chez les clients, je remarque souvent un truc assez simple : le problème n’est pas que l’IA manque d’intelligence. Le problème, c’est qu’on lui donne un contexte flou, incomplet, parfois contradictoire. Elle fait alors ce qu’elle peut, avec les infos qu’elle a.
Le fichier claude.md règle une bonne partie du sujet au niveau du projet. Mais il y a aussi des préférences globales utiles sur tous les projets, comme votre style de réponse, vos outils préférés, ou vos habitudes de développement.
À quoi sert le claude.md global ?
Le claude.md global sert à garder mes préférences personnelles ou d’équipe sur tous les projets. C’est le fichier qui dit à Claude Code comment j’aime travailler, indépendamment du dépôt ouvert.
La différence avec le claude.md projet est simple. Le fichier projet décrit le contexte d’un dépôt précis. Il parle du code, de l’architecture, de la stack, des conventions locales, des commandes utiles. Le fichier global décrit plutôt ma façon de travailler, mes préférences de sortie, mes standards généraux, le niveau de détail que j’attends.
D’après sa documentation, Claude Code prend en charge une mémoire utilisateur globale. Je n’ai pas besoin de rentrer dans un chemin technique absolu ici. L’idée importante, c’est que certaines consignes peuvent me suivre partout, sans les recopier dans chaque projet.
Dans un claude.md global, je peux mettre des règles comme :
- Répondre en français par défaut.
- Être direct, sans phrases longues ni bla-bla.
- Demander confirmation avant une action risquée, comme supprimer des fichiers ou lancer une migration.
- Produire des réponses structurées quand le sujet est complexe.
- Éviter les changements massifs sans justification claire.
- Signaler les hypothèses au lieu de faire semblant de savoir.
Cette séparation est saine. Si je mets tout dans le claude.md projet, je mélange mes préférences personnelles avec des informations propres au code. Le prochain développeur qui ouvre le dépôt n’a pas forcément besoin de savoir que je préfère des réponses courtes ou que je veux toujours un résumé avant le détail.
À l’inverse, si je mets le contexte projet dans le global, je pollue tous mes autres travaux. J’ai déjà vu ça chez un client avec des consignes React qui se retrouvaient appliquées sur un projet Python. Résultat, Claude proposait des choses bizarres, pas complètement fausses, mais hors contexte.
| Type de fichier | Ce que j’y mets | Ce que j’évite |
| claude.md projet | Architecture, stack, conventions du dépôt | Mes préférences personnelles génériques |
| claude.md global | Style de réponse, standards généraux, habitudes de travail | Détails d’un projet unique |
Le bon réflexe, c’est donc simple. Je garde le global pour les habitudes durables, et le projet pour le contexte local. Une fois le bon contexte au bon endroit, le vrai bénéfice apparaît dans la qualité des réponses et dans la stabilité des sessions.
Pourquoi le contexte change tout ?
Le contexte change tout parce qu’un agent IA code mieux quand il comprend le projet, ses limites et ses conventions. Claude Code n’échappe pas à ça. Si les infos essentielles sont chargées dès le départ, ses réponses deviennent plus cohérentes, plus utiles, et surtout moins à côté de la plaque.
Ce n’est pas magique non plus. Un fichier claude.md ne transforme pas un mauvais prompt en consigne parfaite. Il ne remplace pas votre jugement, ni une vraie revue de code. Mais il réduit les oublis bêtes. Il évite de répéter dix fois “On utilise TypeScript strict”, “Pas de nouvelle dépendance sans validation”, “Les tests sont obligatoires”, ou “On suit cette architecture-là”.
Le vrai sujet, c’est la dérive de contexte. Dans une longue session, les consignes importantes finissent par se diluer. Entre deux sessions, c’est encore pire. On repart presque de zéro, on oublie un détail, l’agent interprète, et parfois il part dans une direction qui semble logique pour lui mais pas du tout pour votre projet.
Le claude.md limite ça parce que les instructions essentielles sont relues au démarrage. C’est comme briefer un consultant avant qu’il touche au projet, au lieu de le laisser deviner les règles en cassant deux ou trois choses. Franchement, c’est souvent là que se gagne du temps.
J’ai vu des équipes perdre des heures à corriger des sorties IA juste parce que les règles de base n’étaient écrites nulle part. Une fois ces règles posées dans un claude.md propre, les échanges deviennent plus courts, les propositions plus alignées, et les revues moins pénibles. Pas parfaites. Mais moins fatigantes.
| Sans claude.md | Avec claude.md |
| Je répète le contexte à chaque session | Le contexte projet est chargé au démarrage |
| L’agent devine les conventions | L’agent suit les règles écrites |
| Les réponses varient davantage | Les réponses restent plus cohérentes |
| La revue demande plus d’effort | La revue se concentre davantage sur le fond |
Pour que ça marche vraiment, il faut maintenant le traiter comme un actif du projet, pas comme une note oubliée au fond du repo.
Comment maintenir un claude.md utile ?
Je maintiens un claude.md utile comme une documentation courte, vivante et vérifiable. Un fichier trop long finit ignoré, même par un humain. Un fichier trop vague n’aide pas l’agent. Le bon équilibre, c’est quelques règles fortes, du contexte clair, et des informations à jour.
Je le vois comme un petit contrat de travail entre le projet et Claude Code. Pas comme un wiki. Pas comme un endroit où je vide toutes mes notes internes. Si Claude doit ouvrir 400 lignes avant de comprendre comment bosser, on a déjà perdu une partie de l’intérêt.
Je mets à jour le fichier dans quelques cas très simples. Quand la stack change, par exemple si on passe de Jest à Vitest. Quand une convention devient officielle, comme un format de nommage ou une règle d’architecture. Quand un dossier sensible apparaît, par exemple un dossier legacy à ne pas refactorer sans validation. Quand une commande de test évolue, parce qu’une commande fausse pousse l’agent à faire n’importe quoi avec beaucoup de confiance.
Je supprime aussi les anciennes règles. C’est souvent là que les fichiers claude.md se dégradent. On ajoute, on ajoute, puis personne ne retire. Résultat, l’agent reçoit des consignes contradictoires. Et là, il improvise. Mauvais plan.
Je fais aussi très attention à ne jamais mettre de secrets dedans. Pas de token API, pas de mot de passe, pas de clé privée, pas d’URL interne sensible, pas d’information client confidentielle. Le fichier doit aider l’agent à travailler, pas devenir une poubelle de contexte risqué.
Ma règle perso est simple. Après deux ou trois corrections répétées à Claude Code, je me demande si la règle mérite d’être ajoutée dans claude.md. Si oui, je l’écris en une phrase claire. C’est souvent là qu’on gagne du temps, parce qu’on transforme une frustration récurrente en règle permanente.
- Clair chaque règle doit être compréhensible sans contexte oral
- Court garder uniquement ce qui aide vraiment l’agent
- À jour retirer les règles obsolètes
- Séparé projet dans le claude.md local, préférences dans le global
- Sûr aucun secret ni donnée sensible
Un bon claude.md n’est pas un gadget. C’est une petite couche d’alignement qui rend l’agent beaucoup plus exploitable au quotidien. Et quand il est bien entretenu, on passe moins de temps à répéter les mêmes consignes, et plus de temps à avancer vraiment.
Et si le vrai gain était juste de mieux briefer l’agent ?
Le fichier claude.md sert surtout à éviter de repartir de zéro à chaque session avec Claude Code. Je l’utilise comme un briefing projet persistant: contexte, stack, conventions, commandes utiles, limites à respecter. Le fichier global garde plutôt mes préférences générales. Ce duo aide à réduire la dérive de contexte, à stabiliser les réponses et à rendre l’agent plus prévisible. Ce n’est pas une baguette magique, mais c’est un réflexe simple qui change beaucoup de choses. Le bénéfice pour vous est clair: moins de répétitions, moins de corrections inutiles, et une IA qui travaille plus près de vos vraies contraintes.
FAQ
- Qu’est-ce qu’un fichier claude.md ? Le fichier claude.md est un fichier Markdown utilisé par Claude Code pour charger du contexte projet au démarrage d’une session. Il sert à donner à l’agent les règles, conventions et informations utiles avant même la première demande.
- Où faut-il placer le fichier claude.md ? Il doit être placé à la racine du projet pour que Claude Code puisse le charger comme mémoire projet. C’est là qu’il devient vraiment utile, parce qu’il accompagne le dépôt sur lequel l’agent travaille.
- Quelle est la différence entre claude.md projet et claude.md global ? Le claude.md projet décrit un dépôt précis: architecture, stack, conventions, commandes. Le claude.md global sert plutôt aux préférences durables, comme le style de réponse, le format attendu ou les standards généraux.
- Que faut-il éviter de mettre dans un claude.md ? J’évite les secrets, tokens, mots de passe, données sensibles, règles obsolètes et consignes contradictoires. Le fichier doit rester clair et exploitable, pas devenir une documentation fourre-tout.
- Pourquoi le fichier claude.md améliore les réponses de Claude Code ? Parce qu’il donne à l’agent un contexte stable dès le départ. Claude Code comprend mieux le projet, suit plus facilement les conventions, et risque moins d’oublier les consignes importantes entre les sessions.
A propos de l’auteur
Je suis Franck Scandolera, expert et formateur en tracking avancé server-side, Analytics Engineering, automatisation No/Low Code avec n8n, intégration de l’IA en entreprise et SEO/GEO. J’accompagne des équipes qui veulent rendre leurs données, leurs outils et leurs agents IA vraiment opérationnels, pas juste impressionnants en démo. J’ai travaillé avec des références comme Logis Hôtel, Yelloh Village, BazarChic, la Fédération Française de Football ou Texdecor. Je dirige l’agence webAnalyste et l’organisme Formations Analytics. Si vous voulez cadrer proprement vos usages IA et automatisation, 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é (GTM server, 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.