CLAUDE.md est un simple fichier texte que Claude Code lit au démarrage de chaque session. C’est le moyen le plus direct d’obtenir une IA qui connaît ton projet sans que tu aies à le réexpliquer — et c’est aussi le fichier le plus souvent mal écrit.
Cette page couvre l’essentiel : où le placer, quoi y mettre, quoi en retirer, et les erreurs qui le rendent inutile.
Où le placer
Deux emplacements, avec des rôles différents :
- À la racine de ton projet — c’est le cas normal. Le fichier décrit ce projet-là : son architecture, ses conventions, ses commandes.
- Dans ton dossier utilisateur (~/.claude/CLAUDE.md) — il s’applique alors à tous tes projets. C’est là que vont tes préférences personnelles, pas les détails d’un dépôt.
Les deux se cumulent. La bonne répartition : ce qui te concerne toi va dans le fichier utilisateur, ce qui concerne le code va dans celui du projet. Mélanger les deux est la première cause de fichiers illisibles.
Quoi y mettre
Le critère est simple : ce que le modèle ne peut pas deviner en lisant le code. Tout le reste est du remplissage qui dilue le signal.
Les commandes réelles
Comment on lance les tests, le serveur de développement, le build, le linter. Avec les vraies commandes, y compris celles qui ont un paramètre inhabituel. C’est ce qui évite qu’une IA invente un npm test qui n’existe pas.
Les conventions maison
Celles qui ne se déduisent pas d’un coup d’œil : où vont les nouveaux fichiers, comment sont nommés les composants, quel style de commit, quelle bibliothèque est imposée pour quoi. Si ton équipe a une règle que tu répètes en revue de code, elle a sa place ici.
Les pièges connus
C’est la section la plus sous-estimée. « Ce dossier est généré, ne pas l’éditer à la main. » « Ce test échoue en local, c’est normal. » « Cette dépendance est bloquée en version 2 à cause de X. » Chaque piège documenté ne se paie qu’une fois.
Ce qu’il ne faut jamais faire
Une liste courte d’interdits explicites vaut mieux qu’un long exposé de bonnes pratiques. « Ne jamais modifier les fichiers de migration existants. » « Ne pas ajouter de dépendance sans demander. »
Quoi ne PAS y mettre
- Ce que le code dit déjà. La liste des dossiers, la stack, les dépendances : le modèle les lit plus vite que toi.
- Des généralités. « Écris du code lisible », « pense aux tests » : sans effet, et ça noie le reste.
- Des secrets. Clés d’API, mots de passe, jetons. Le fichier est versionné et lu à chaque session — c’est le pire endroit. Écris où les trouver, pas leur valeur.
- De la documentation longue. Si une explication dépasse quelques lignes, mets-la dans un document dédié et fais-y référence.
La bonne longueur
Une page. Deux au maximum sur un gros projet.
Le fichier est chargé à chaque session : plus il est long, plus il coûte, et plus l’important se dilue. Un CLAUDE.md de 300 lignes n’est pas mieux respecté qu’un de 40 — il l’est moins bien, parce que rien n’y ressort.
Bonne méthode pour le calibrer : n’écris pas le fichier d’avance. Travaille, et chaque fois que tu corriges l’IA sur la même chose pour la deuxième fois, ajoute une ligne. Le fichier construit ainsi ne contient que ce qui sert réellement.
Les erreurs les plus fréquentes
- L’écrire d’un bloc le premier jour. Tu produis ce que tu crois important. Deux semaines plus tard, c’est à moitié faux et tu ne le rouvres plus.
- Ne jamais le relire. Un fichier qui décrit une architecture abandonnée fait activement du mal : l’IA suit une carte périmée avec assurance.
- Y écrire des politesses. « Sois rigoureux et attentif » n’a aucun effet mesurable. Une contrainte vérifiable, si.
- Tout mettre dans le fichier utilisateur. Tes règles de projet s’appliquent alors à des dépôts sans rapport, où elles n’ont aucun sens.
Un point de départ
Cinq sections suffisent pour la version projet :
- Ce qu’est ce projet — deux lignes, pas plus.
- Commandes — tests, dev, build, lint.
- Conventions — les règles qui ne se devinent pas.
- Pièges — ce qui a déjà fait perdre du temps.
- Interdits — ce qu’il ne faut jamais toucher.
Écris-en trois aujourd’hui, laisse les deux autres se remplir au fil du travail.
La suite : quand un fichier ne suffit plus
Le template complet du fichier de contexte, la structure de dossier à adopter quand une page devient trop courte, et la consigne qui fait écrire l’IA elle-même — 137 fiches chez moi, aucune déclenchée à la main. 14 pages, gratuit.
Après le fichier
Le jour où ton CLAUDE.md devient difficile à relire, ce n’est pas qu’il est mal écrit : c’est qu’un fichier unique ne suffit plus. L’étape suivante est un dossier que l’IA consulte elle-même, puis qu’elle entretient sans qu’on lui demande.
Mais n’y va pas trop tôt. Un fichier d’une page, tenu à jour, bat un dossier de cinquante fiches que personne ne relit.
Les autres guides sur l’outil, dont ses prix, sont réunis sur la page Claude Code en français.
Cette étape suivante, le vault puis l’IA qui écrit seule ses fiches, fait l’objet des modules 3 et 4 de la formation Mémoire IA.
Cette page fait partie du guide Mémoire IA, qui présente la méthode complète.