Comment écrire un bon CLAUDE.md : exemple et méthode

Un bon CLAUDE.md permet à un assistant de développement de comprendre les limites d’un dépôt sans dépendre d’un long prompt répété à chaque session. Il doit répondre à des questions simples : quel est le projet, quels fichiers sont sensibles, quelles commandes sont autorisées et comment vérifier une modification ? Un document utile n’essaie pas de raconter toute l’histoire de l’entreprise. Il rend les actions quotidiennes plus prévisibles.

Le principe le plus important est de décrire le réel. Si votre projet utilise pnpm, n’écrivez pas des commandes npm. Si les migrations demandent une validation, ne présentez pas leur exécution comme une étape automatique. Un CLAUDE.md inventé ou trop vague donne une fausse impression de contrôle.

Ce que vous allez apprendre

Vous allez définir le périmètre d’un CLAUDE.md, construire une version minimale, ajouter les consignes de sécurité qui comptent et la tester sur une tâche inoffensive. À la fin, vous saurez séparer les règles globales du dépôt, les instructions temporaires d’un ticket et les détails propres à une feature.

Prérequis

Vous avez besoin d’un dépôt Git, d’une liste des commandes réellement utilisées et de l’accord de la personne qui maintient les règles du projet. Lisez d’abord les éventuels fichiers existants (AGENTS.md, README, contribution guide ou politique de sécurité) afin de ne pas créer un second document contradictoire.

Avant toute édition, vérifiez l’état local :

git status --short

Vérification : vous devez pouvoir distinguer les changements de votre tâche de ceux qui existaient déjà. Si le dépôt est partagé, réservez aussi les fichiers que vous allez modifier.

1. Décrire l’architecture en quelques lignes

Commencez par le langage, le framework, les répertoires essentiels et la source des données. N’énumérez pas chaque fichier. Le but est d’aider à choisir le bon point d’entrée. Par exemple : « application Next.js ; routes dans app/ ; contenu MDX dans content/ ; accès base via Prisma ». Cette phrase guide une recherche sans transformer le document en index périssable.

Ajoutez les contraintes qui changent réellement la manière de travailler : loader MDX choisi, composants serveur par défaut, ou environnement sans base de données. Évitez de copier des secrets, URL internes ou données utilisateurs. Un fichier de consignes est versionné et doit rester publiable à un collaborateur autorisé.

Vérification : demandez à quelqu’un de localiser un composant et un contenu à partir du document. S’il doit deviner l’arborescence, améliorez la description.

2. Écrire les règles non négociables

Les règles les plus utiles sont courtes, observables et reliées à un risque. Par exemple : ne pas installer une dépendance sans décision, ne pas exposer de clé dans un exemple, ne pas lancer une migration contre une base inconnue et ne pas publier sans validation. Écrivez également ce qui doit être fait avant une modification : lire les règles locales, examiner le fichier visé et contrôler les doublons.

Ne confondez pas une préférence avec une interdiction. « Préférer les composants serveur » laisse une place aux exceptions justifiées. « Ne jamais modifier les fichiers de configuration » est une limite de propriété. Ce niveau de précision aide autant un nouveau collègue qu’un assistant.

Vérification : chaque règle doit répondre à « comment saurons-nous qu’elle a été respectée ? ». Remplacez « faire attention à la sécurité » par les actions concrètes attendues.

3. Ajouter les commandes et leur niveau de risque

Listez les commandes de lecture et de contrôle courantes, avec leur rôle :

pnpm lint
pnpm test
pnpm build
git diff --check

N’affirmez pas qu’elles sont inoffensives sans vérifier le projet. Certaines écrivent des caches ou dépendent d’un service local. Pour les actions à impact élevé — migration, seed, déploiement, publication de package — indiquez explicitement qu’elles demandent une autorisation et une cible connue.

Vérification : exécutez uniquement une commande autorisée par le propriétaire du dépôt et consignez tout effet de bord découvert. Le CLAUDE.md doit être corrigé si une commande annoncée comme disponible échoue systématiquement.

4. Encadrer le travail à plusieurs agents

Dans un projet partagé, un fichier de tâches ou un registre d’ownership évite que deux personnes écrivent au même endroit. Le CLAUDE.md peut renvoyer vers cette source de vérité, sans tenter de maintenir une copie de chaque tâche active. Définissez le comportement en cas de collision : s’arrêter, rapporter le conflit et ne jamais écraser ou « nettoyer » les changements d’un autre contributeur.

Cette règle est particulièrement importante avec des assistants. Deux sessions peuvent produire un contenu similaire ou lancer deux builds qui se gênent, même si leurs intentions semblent compatibles. Un seul propriétaire par fichier et un verrou pour les commandes qui produisent des artefacts restent des protections simples.

5. Créer un exemple minimal

Voici une structure volontairement générique :

## Guide du dépôt

### Architecture
- Application : préciser framework et répertoires.
- Données : préciser source et limites locales.

### Règles
- Lire les consignes locales avant toute écriture.
- Ne jamais mettre de secret dans le dépôt ou le chat.
- Ne pas publier, migrer ou supprimer sans validation.

### Vérification
- Lancer uniquement les commandes autorisées pour le périmètre.
- Remettre fichiers modifiés, résultats et risques restants.

Adaptez les mots et chemins à votre projet. N’ajoutez pas une API imaginaire parce qu’elle paraît pratique dans l’exemple. Un CLAUDE.md doit refléter l’état observé, pas une architecture souhaitée.

Vérification : relisez le document à côté du README et des scripts package.json. Toute contradiction doit être résolue avec le propriétaire, pas tranchée par l’assistant.

Problèmes fréquents et solutions

Le document devient trop long

Gardez le tronc commun dans le CLAUDE.md et liez les détails à des guides spécialisés. Une personne doit pouvoir trouver les interdits et les commandes essentielles en moins d’une minute.

Les instructions sont contradictoires

Indiquez la hiérarchie : règles de sécurité et ownership d’abord, consignes locales ensuite, instructions de tâche enfin. Lorsque deux documents de même niveau divergent, stoppez le changement et faites valider la décision.

Les règles vieillissent

Mettez à jour le document après une modification d’outillage, une erreur répétée ou une décision d’architecture. Ajoutez le contrôle du CLAUDE.md à la revue des changements concernés, plutôt que de le réécrire globalement tous les mois.

FAQ

Où placer un CLAUDE.md ?

Placez-le à la racine du dépôt pour les règles générales. Des instructions locales peuvent exister dans un sous-dossier si le projet le prévoit ; elles ne doivent pas contredire les garde-fous globaux.

Peut-il contenir des identifiants de test ?

Non. Utilisez des variables d’environnement, exemples fictifs ou mécanismes protégés, même pour un environnement de démonstration.

Faut-il documenter toutes les commandes ?

Documentez surtout celles nécessaires au travail courant et celles qui sont risquées. Un lien vers la documentation officielle suffit pour les détails rares.

Un assistant peut-il modifier ce fichier ?

Seulement si la tâche l’autorise explicitement et si le fichier n’est pas réservé à une autre personne. Les règles partagées demandent généralement une revue humaine.

Comment savoir s’il améliore réellement le travail ?

Observez les erreurs évitées : moins de commandes inadaptées, de changements hors périmètre et de questions répétées. Ajustez le texte à partir de ces observations.

Conclusion

Un CLAUDE.md efficace est court, concret et vérifiable. Il donne un cadre à l’assistant sans prétendre remplacer la connaissance du projet. Commencez par l’architecture réelle, les interdits et les commandes utiles, puis faites-le évoluer avec les retours de revue.

Sources et limites

Anthropic — Manage Claude Code memory : emplacement et fonctionnement des instructions de projet à vérifier selon la version.
Anthropic — Best practices : principes généraux d’utilisation.

Les conventions de fichiers peuvent varier selon les outils d’agents. Cet article ne garantit pas qu’un même fichier soit découvert automatiquement partout.