CLAUDE.md
configurer Claude Code comme un pro en 2026

Sur le fond, même principe : un fichier de contexte local au projet que l’agent IA lit pour adapter son comportement. Sur la forme, CLAUDE.md offre plusieurs avantages par rapport à .cursorrules. D’abord, la hiérarchie : Claude Code lit les CLAUDE.md imbriqués dans les sous-dossiers, permettant à chaque module d’un monorepo d’avoir ses propres règles qui s’ajoutent au contexte global. Les .cursorrules sont plats.

Ensuite, la flexibilité de syntaxe : CLAUDE.md est du Markdown libre, sans syntaxe imposée ni limite de taille stricte. Vous structurez exactement comme vous voulez. Certains .cursorrules attendent un format plus rigide.

Enfin, la portabilité : CLAUDE.md est versionné dans Git avec le reste du code, donc tout le monde dans l’équipe bénéficie automatiquement des mises à jour. Il n’y a pas besoin de synchroniser un fichier de config séparé entre les membres de l’équipe. C’est un actif permanent du projet, pas une config personnelle.

La taille idéale se situe entre 100 et 300 lignes pour la grande majorité des projets. En dessous de 50 lignes, le fichier manque de contexte et Claude Code doit deviner trop de choses. Au-delà de 500 lignes, l’attention de Claude commence à se diluer et certaines règles en fin de fichier peuvent être moins bien respectées.

Un bon indicateur : si vous pouvez lire votre CLAUDE.md en 5 minutes et en retenir l’essentiel, c’est la bonne taille. Si vous avez besoin de faire défiler longtemps et que vous ne vous souvenez plus de ce qui est au début quand vous arrivez à la fin, c’est trop long. Élaguer est souvent plus bénéfique qu’ajouter.

Pour les très gros projets ou monorepos, la solution n’est pas un CLAUDE.md de 1000 lignes mais plusieurs CLAUDE.md hiérarchiques : un CLAUDE.md global de 150 lignes à la racine, et des CLAUDE.md spécialisés de 50 à 100 lignes dans chaque sous-module. Claude Code lit les deux et les combine, ce qui donne un contexte plus précis sans surcharge.

La meilleure approche est de le traiter comme un document vivant avec des révisions légères et fréquentes plutôt que des refontes massives rares. Le signal d’une règle manquante : quand Claude Code fait la même erreur deux fois de suite sur le même point, c’est qu’une règle manque dans votre CLAUDE.md.

Je relis et mets à jour le CLAUDE.md toutes les 2 à 4 semaines sur un projet actif. Chaque mise à jour ne dure que 10 minutes : j’ajoute 1 à 3 lignes qui corrigent les comportements incorrects observés dans la semaine. Ce rythme maintient le fichier à jour sans effort excessif.

Un piège à éviter : laisser dans le CLAUDE.md des règles obsolètes après un refactoring ou un changement de stack. Une règle incorrecte est pire qu’une règle manquante — elle induit activement Claude Code en erreur. Lors d’un changement significatif de l’architecture, prenez 30 minutes pour faire le ménage dans le CLAUDE.md.

CLAUDE.md est une fonctionnalité spécifique à Claude Code, l’outil CLI d’Anthropic. Pour les appels directs à l’API Claude via /v1/messages, il n’y a pas de mécanisme natif de lecture de fichier local — vous devez injecter manuellement le contenu de votre CLAUDE.md dans le system prompt de chaque requête.

Sur claude.ai (interface web), vous pouvez simuler l’effet de CLAUDE.md en uploadant le fichier dans les fichiers d’un Project. Claude le lit et l’utilise comme contexte pour toutes les conversations du Project. Ce n’est pas aussi automatique que Claude Code, mais c’est une bonne alternative pour les équipes qui n’utilisent pas l’outil CLI.

Pour les développeurs qui construisent des agents sur l’API, le pattern recommandé est d’injecter le CLAUDE.md au début du system prompt de chaque appel. Vous pouvez créer un helper qui lit le fichier CLAUDE.md local et l’insère automatiquement — c’est quelques lignes de code qui reproduisent le comportement de Claude Code.

Oui, et c’est même recommandé pour les projets complexes. Claude Code supporte les CLAUDE.md hiérarchiques : le fichier à la racine définit les règles globales du projet, et les CLAUDE.md dans les sous-dossiers ajoutent des règles spécifiques à leur contexte. Quand vous travaillez sur un fichier dans un sous-dossier, Claude Code lit les deux niveaux et les combine.

Un cas typique dans un monorepo : CLAUDE.md à la racine (conventions globales, stack, commandes de build), CLAUDE.md dans /apps/frontend (conventions React, composants disponibles, design system), CLAUDE.md dans /packages/api (conventions REST, authentification, gestion des erreurs). Chaque développeur travaillant dans son module obtient un contexte précis sans se noyer dans les règles des autres modules.

Une bonne pratique : gardez le CLAUDE.md de la racine concis et axé sur les informations qui s’appliquent vraiment à tout le projet. Mettez les spécificités dans les CLAUDE.md des sous-modules. Un CLAUDE.md racine de 100 lignes + des CLAUDE.md de sous-modules de 50 lignes est plus efficace qu’un seul CLAUDE.md racine de 300 lignes que personne ne maintient correctement.

Oui, significativement. La section ‘Commandes utiles’ du CLAUDE.md est particulièrement importante pour les tests : quand Claude Code connaît la commande exacte pour lancer les tests, leur localisation et les conventions de nommage des fichiers de test, il génère des tests cohérents avec la structure existante et peut les exécuter directement.

La section ‘Conventions de code’ doit inclure votre approche des tests : niveau de couverture attendu, types de tests à écrire (unitaire, intégration, e2e), bibliothèques utilisées, patterns de mocking, gestion des fixtures. Sans ces informations, Claude Code génère des tests valides techniquement mais souvent pas dans le style de votre équipe.

Un ajout puissant dans le CLAUDE.md pour les tests : un exemple de test bien écrit dans votre style. Un exemple vaut mille lignes de description. ‘Voici un exemple de test unitaire qui respecte nos conventions : [10 lignes de code]’ donne à Claude Code une référence concrète bien plus utile que de décrire les conventions en prose.

C’est précisément le cas d’usage le plus fréquent, et Claude Code peut vous aider à bootstrapper son propre contexte. La méthode : créez un CLAUDE.md vide, démarrez Claude Code et demandez-lui ‘analyse ce projet et propose-moi un CLAUDE.md complet basé sur ce que tu vois dans le code’. Il va scanner la structure, détecter les conventions implicites, et produire un premier draft.

Ce premier draft sera imparfait — Claude Code ne peut pas deviner vos intentions non-documentées, les bugs connus, ou les conventions acquises par l’équipe par l’expérience. Mais il fournit 60 à 70% du travail. Votre rôle est de corriger les erreurs, ajouter les pièges connus que l’IA ne peut pas inférer du code, et valider les conventions détectées.

Pour un projet legacy de plusieurs années sans documentation, cette approche est particulièrement précieuse. Claude Code peut détecter les patterns répétés dans le code (nommage, structure, error handling) même quand personne dans l’équipe n’a jamais formalisé ces conventions. En 1 heure, vous avez un CLAUDE.md qui documente 10 ans de conventions implicites.

Oui, de façon significative. Les subagents Claude Code lisent le CLAUDE.md de la racine ainsi que leurs propres fichiers dans .claude/agents/. Le CLAUDE.md global fournit le contexte du projet, et le fichier de chaque subagent précise son rôle et ses permissions. Cette combinaison donne des subagents très précis sur leur périmètre.

La section ‘Pièges connus’ du CLAUDE.md est particulièrement utile pour les subagents : elle leur indique les zones du code à éviter, les modules à ne pas modifier, les patterns incorrects à ne pas reproduire. Sans ce garde-fou, un subagent backend peut modifier des fichiers frontend en croyant bien faire.

Pour les équipes qui utilisent les subagents intensivement, je recommande d’ajouter une section dédiée dans le CLAUDE.md : ‘Architecture multi-agents’. Elle liste les subagents configurés, leurs responsabilités, et les règles de coordination (quel agent modifie quoi, comment ils communiquent via les fichiers, quel fichier est le ‘contrat’ entre les agents).

Non. CLAUDE.md est un fichier versionné dans Git — tout ce que vous y mettez est visible par quiconque accède au repository. Ne jamais mettre dans CLAUDE.md : clés API, tokens d’authentification, mots de passe, informations personnelles d’utilisateurs, données de production.

Pour référencer des secrets dans le contexte de Claude Code, utilisez des variables d’environnement que vous référencez par nom dans CLAUDE.md sans donner leur valeur (‘les credentials AWS sont dans les variables d’environnement AWS_ACCESS_KEY_ID et AWS_SECRET_ACCESS_KEY, jamais en dur dans le code’). Claude Code comprend la référence sans avoir besoin de la valeur.

Pour les équipes avec des contraintes de sécurité très strictes, notez que Claude Code peut lire votre CLAUDE.md mais ne le transmet pas à Anthropic de façon distincte — il fait partie du contexte de la conversation comme tout autre message. Si vous avez des contraintes de confidentialité sur la description même de votre architecture, vérifiez les conditions d’utilisation applicables à votre plan.

Oui, plusieurs ressources existent. Sur GitHub, cherchez ‘awesome CLAUDE.md’ ou ‘claude code doc templates’ pour trouver des collections de templates par type de projet : SaaS React/Node.js, API Python FastAPI, projet data science, monorepo TypeScript. La qualité varie beaucoup selon l’auteur et la date de publication.

La documentation officielle d’Anthropic (docs.anthropic.com) donne des exemples courts et bien structurés dans la section Claude Code. Ces exemples sont minimalistes mais représentatifs de ce qu’Anthropic considère comme les bonnes pratiques. Ils constituent un bon point de départ avant de les enrichir.

Ma recommandation : prenez un template proche de votre stack comme point de départ, élaguez 70% du contenu générique, et ajoutez vos spécificités de projet. La plupart des templates publics sont trop longs pour un usage réel — ils essaient de tout documenter là où un bon CLAUDE.md documente seulement ce qui est non-évident pour quelqu’un qui découvre le projet.