CLAUDE.md : le fichier qui donne de la mémoire à votre IA

Vous utilisez Claude Code et, à chaque nouvelle session, vous devez tout réexpliquer ? Votre stack, vos conventions, vos règles… Claude repart de zéro à chaque fois. C'est frustrant, et c'est exactement le problème que résout le fichier CLAUDE.md. Un simple fichier texte, placé à la racine de votre projet, qui transforme Claude en assistant qui connaît déjà vos règles avant même que vous ne parliez.

Qu'est-ce que le fichier CLAUDE.md ?

CLAUDE.md est un fichier Markdown que vous placez à la racine de votre projet. Claude Code le lit automatiquement au début de chaque session. Vous n'avez rien à attacher, rien à coller, rien à référencer manuellement. Il se charge tout seul, à chaque fois.

Pensez-y comme un manuel d'accueil pour un nouveau prestataire. Au lieu de réexpliquer vos préférences à chaque conversation, vous les écrivez une fois. Claude les lit à chaque session.

Concrètement, votre CLAUDE.md peut contenir :

• Votre stack technique et les versions spécifiques utilisées
• Les conventions de code propres à ce projet
• Les règles critiques que Claude doit suivre sans exception
• Les commandes nécessaires pour lancer, tester ou déployer le projet
• Les erreurs connues que vous avez déjà corrigées et que vous ne voulez plus revoir

Quand créer un CLAUDE.md ?

Vous n'avez pas besoin d'attendre qu'un problème survienne. Il y a trois moments clés pour créer ce fichier :

1. Au début de chaque nouveau projet

Créez-le avant même d'écrire la première ligne de code. Cinq minutes d'installation au départ vous évitent des heures de corrections répétées par la suite. Documentez votre stack, votre structure de dossiers, et les contraintes que vous connaissez déjà.

2. Dès que Claude fait deux fois la même erreur

Si vous avez corrigé Claude dans une session et qu'il répète la même erreur dans la suivante, cette correction appartient définitivement au CLAUDE.md. Une erreur qui apparaît deux fois apparaîtra une troisième fois. Écrivez-la.

3. Quand votre projet a des contraintes non évidentes

Si vous utilisez une version spécifique d'un package, une structure de dossiers non standard, un identifiant de modèle particulier ou une convention de nommage qui diffère des standards courants, documentez-le avant que Claude n'ait l'occasion de deviner. Car Claude choisira toujours ce qu'il considère comme standard. Si votre projet ne l'est pas, dites-le-lui.

Comment créer un CLAUDE.md ?

Étape 1 — La commande /init

Ouvrez Claude Code dans votre terminal, à la racine de votre projet. Tapez /init et appuyez sur Entrée. Claude Code va analyser vos fichiers existants et générer automatiquement un premier brouillon de CLAUDE.md.

claude
> /init

Étape 2 — Nettoyer le brouillon

Relisez ce qui a été généré et supprimez tout ce qui est générique. Claude connaît déjà les bonnes pratiques générales pour écrire du code propre ou structurer un projet. Ne gardez que ce qui est unique à votre projet spécifique.

Étape 3 — Ajouter vos contraintes manuellement

C'est la partie la plus précieuse. Ajoutez :

• Les identifiants de modèles spécifiques
• Les versions de packages imposées
• Les commandes de build/run/test
• Les erreurs déjà rencontrées que Claude doit éviter

Exemple concret d'un CLAUDE.md efficace

Voici un exemple réel d'un CLAUDE.md concis et efficace :

# Mon Projet - CLAUDE.md

## Stack technique
- Astro v4 (SSG) + TypeScript strict
- CSS vanilla avec design tokens (pas de Tailwind)
- Notion API comme CMS headless
- Vercel pour le deploiement

## Regles critiques
- Ne JAMAIS utiliser de framework CSS (Tailwind, Bootstrap...)
- Toujours utiliser les design tokens definis dans tokens.css
- Les images sont sur Cloudinary (cloud: dh0gkbugm)
- Ne pas modifier astro.config.mjs sans demander

## Commandes
- Dev : npm run dev (port 4321)
- Build : npm run build
- Pas de suite de tests configuree

## Erreurs connues
- Le sitemap Astro crash au build -> desactive pour l'instant
- Notion: le filtre Status est un 'select', pas un 'checkbox'

Remarquez ce que ce fichier ne contient pas : il n'explique pas comment écrire du JavaScript, il ne liste pas des principes généraux de programmation. Chaque ligne décrit quelque chose que Claude ne peut pas deviner tout seul : un choix spécifique, une contrainte de ce projet, une commande de ce codebase.

Les 4 règles d'or d'un bon CLAUDE.md

1. Restez sous 200 lignes

Le fichier entier est chargé dans la fenêtre de contexte de Claude à chaque session. Un fichier trop long gaspille des tokens et noie les instructions importantes. Si votre fichier grossit trop, taillez-le. La longueur n'est pas un signe de rigueur — c'est un signe que du contenu générique s'est glissé dedans.

2. N'écrivez que des règles spécifiques au projet

Claude sait déjà coder, structurer un projet et utiliser les librairies courantes. Ne répétez pas les bonnes pratiques générales. Le CLAUDE.md est réservé à ce que Claude ne peut pas savoir tout seul : vos choix, vos contraintes, votre historique avec ce codebase.

Si la règle s'appliquerait à n'importe quel projet par n'importe quel développeur, elle n'a pas sa place ici.

3. Traitez-le comme un document vivant

À chaque fois que Claude fait une erreur que vous avez déjà vue, ajoutez une ligne. À chaque fois qu'une règle devient obsolète, supprimez-la. Le CLAUDE.md doit refléter votre projet tel qu'il existe aujourd'hui, pas une photo du premier jour.

4. Utilisez la stratégie du fichier index pour les gros projets

Si votre projet devient suffisamment grand pour qu'un seul CLAUDE.md devienne énorme, utilisez-le comme un index. Écrivez des résumés courts au niveau racine et renvoyez vers des fichiers Markdown séparés pour chaque domaine :

## API
Voir /docs/api-conventions.md pour toutes les regles API.

## Frontend
Voir /docs/frontend-rules.md pour les conventions UI.

Cela garde le fichier racine court tout en préservant le détail là où vous en avez besoin.

Ce qu'il faut retenir

Le CLAUDE.md est une petite habitude avec un retour disproportionnément grand. Cinq minutes au début d'un projet évitent des heures de corrections répétées par la suite.

En résumé :

• Créez-le dès le début du projet avec /init
• Ne gardez que les règles spécifiques à votre projet
• Mettez-le à jour régulièrement (ajouts + suppressions)
• Restez concis : moins de 200 lignes

Plus vous lancez de sessions avec Claude Code, plus votre CLAUDE.md prend de la valeur. Chaque correction que vous y inscrivez est une correction que vous n'aurez plus jamais à refaire.