Vous lancez Claude Code sur un nouveau repo. Il invente des commandes, ignore vos conventions et touche des dossiers sensibles. Le correctif tient en un fichier : CLAUDE.md. Voici ce que c'est, comment /init le crée, et comment le rendre utile en équipe.
Réponse courte
CLAUDE.md est le fichier d'instructions persistantes que Claude Code lit au démarrage d'un projet. Il décrit la stack, les conventions, les commandes et les interdits. La commande /init le génère en scannant le dépôt. Vous le relisez, vous le corrigez, vous le versionnez. Ensuite, Claude s'appuie dessus à chaque session au lieu de rediscourir le contexte.
CLAUDE.md, c'est quoi exactement ?
CLAUDE.md vit à la racine du repo (ou dans un dossier que Claude Code reconnaît). Ce n'est pas un README marketing. Ce n'est pas non plus un prompt jetable collé dans le chat.
C'est la mémoire projet de Claude Code :
- Ce que fait le projet en quelques lignes.
- Comment on code ici (langage, framework, style, structure des dossiers).
- Comment on lance build, tests, lint, migrations.
- Ce qu'il ne faut pas toucher (secrets, prod, dossiers générés).
En clair : CLAUDE.md transforme Claude Code d'un assistant générique en collègue qui connaît déjà votre repo.
Si vous démarrez Claude Code de zéro, ma formation Claude Code pose les bases avant ce fichier.
Comment /init crée le fichier CLAUDE.md
- Ouvrez le projet dans Claude Code.
- Lancez
/init. Claude scanne la structure, les manifests (package.json, pyproject, Cargo.toml…), les scripts et les fichiers de config. - Claude écrit un premier CLAUDE.md à la racine.
- Vous relisez. Complétez les trous, retirez le bruit, ajoutez les interdits métier.
- Committez. Le fichier devient une source de vérité partagée par toute l'équipe.
/init accélère. Il ne remplace pas votre jugement. Un CLAUDE.md généré et jamais relu finit souvent trop long ou trop vague.
Que mettre dans un fichier CLAUDE.md
Gardez une structure simple. Une à trois pages maximum.
Projet
Objectif du produit, stack principale, architecture en 5 lignes. Pas d'historique de tickets.
Conventions
Noms de fichiers, emplacement des tests, style (TypeScript strict, Python ruff, etc.), patterns à réutiliser.
Commandes
Les vraies commandes du repo : npm test, make migrate, pnpm lint. Claude Code les exécute. Si elles sont fausses, il perd du temps.
Interdits
Chemins exclus, secrets, fichiers générés, branches protégées. Dites explicitement ce qu'il ne doit pas modifier.
Contexte métier (court)
Clients, contraintes réglementaires, liens vers la doc interne. Une liste, pas un roman.
Astuce : si une procédure se répète souvent, préférez un Claude Skill plutôt que d'alourdir CLAUDE.md. Le fichier mémoire reste le cadre. Les skills portent les recettes détaillées.
CLAUDE.md vs AGENTS.md
Deux fichiers circulent dans l'écosystème des agents de code. Ils ne jouent pas le même rôle.
| Fichier | Rôle principal | Quand l'utiliser |
|---|---|---|
| CLAUDE.md | Mémoire et règles du projet pour Claude Code | Toujours, dès qu'un repo est suivi avec Claude Code |
| AGENTS.md | Instructions partagées pour d'autres agents / outils multi-agents | Quand plusieurs agents ou outils hors Claude Code doivent partager des règles |
CLAUDE.md est le fichier natif de Claude Code. C'est celui que /init crée et que Claude recharge en session.
AGENTS.md apparaît dans des setups multi-agents ou des conventions d'équipe plus larges. Vous pouvez le mentionner dans CLAUDE.md (« voir aussi AGENTS.md pour les règles cross-outils ») sans dupliquer tout le contenu.
En clair : pour Claude Code, CLAUDE.md est prioritaire. AGENTS.md complète quand d'autres agents entrent en jeu. Pas besoin d'une page séparée pour comparer les deux au quotidien.
Pour le branchement d'outils externes (bases, tickets, CRM), le Model Context Protocol (MCP) complète CLAUDE.md : le fichier donne le contexte, MCP donne l'accès live.
Bonnes pratiques en entreprise
- Un CLAUDE.md par repo, versionné. Pas de copie personnelle non commitée.
- Court et à jour. Après un changement de stack, mettez à jour le fichier le même jour.
- Interdits explicites. Claude Code agit. Les zones sensibles doivent être écrites noir sur blanc.
- Séparez mémoire et automatisation. CLAUDE.md pour le cadre. Skills pour les workflows. Scheduler Claude Code pour les tâches récurrentes (voir mon article sur le Claude Code Scheduler).
- Relisez après
/init. Le scan est utile. La validation humaine reste obligatoire avant de partager le fichier à l'équipe.
Un agent IA bien cadré commence souvent par un bon fichier d'instructions. CLAUDE.md est exactement ça pour le code.
Erreurs fréquentes
- Fichier trop long. Claude noie l'essentiel. Coupez.
- Commandes inventées. Copiez les scripts réels du repo.
- Aucun interdit. Claude touche alors des dossiers que vous vouliez protéger.
- Jamais mis à jour. Un CLAUDE.md d'il y a six mois ment sur la stack.
- Tout mettre dans CLAUDE.md. Les procédures longues vont dans des skills. Les connecteurs passent par MCP.
Checklist : CLAUDE.md prêt pour l'équipe
- Présent à la racine et versionné.
- À jour : stack et commandes réelles.
- Court : 1 à 3 pages.
- Interdits clairs (secrets, prod, générés).
- Relu par un humain après
/init.
FAQ
Qu'est-ce que le fichier CLAUDE.md ?
C'est le fichier d'instructions persistantes lu par Claude Code au démarrage d'un projet. Il décrit le contexte, les conventions, les commandes et les interdits pour que Claude ne reparte pas de zéro à chaque session.
Comment créer CLAUDE.md avec Claude Code ?
Ouvrez le projet dans Claude Code et lancez la commande /init. Claude scanne le dépôt et écrit un premier fichier. Relisez-le, corrigez-le, puis committez.
CLAUDE.md remplace-t-il le README ?
Non. Le README s'adresse aux humains (installation, contribution). CLAUDE.md s'adresse à Claude Code. Les deux peuvent coexister. Évitez de dupliquer des pages entières : pointez l'un vers l'autre si besoin.
Faut-il un CLAUDE.md et un AGENTS.md ?
Pour Claude Code seul, CLAUDE.md suffit. Ajoutez AGENTS.md si d'autres agents ou outils doivent partager des règles communes. Ne créez pas deux fichiers identiques.
Où placer CLAUDE.md dans un monorepo ?
Souvent à la racine avec des sections par package, ou un CLAUDE.md par package critique. L'important : Claude doit trouver les commandes et conventions du sous-projet sur lequel il travaille.
Où se former à Claude Code en français ?
Pour une formation en français pensée pour les non-développeurs, j'ai créé la formation Claude Code : 13 modules, de l'installation (Mac et Windows) aux skills et aux MCP, avec prompts et glossaire. Elle coûte 297 € en paiement unique (ou 2 fois 147 €), avec un accès à vie, 30 jours de communauté inclus et une garantie satisfait ou remboursé de 30 jours. Pour une équipe, je propose aussi un accompagnement sur mesure.
Vous voulez cadrer Claude Code (CLAUDE.md, skills, MCP, formation équipe) sans perdre le contrôle ? Réservez un appel avec moi ou découvrez mon accompagnement de consultant Claude.