La plupart des gens utilisent Claude Code avec un CLAUDE.md trop vague, trop long ou trop abstrait.
Résultat: l'agent oublie les règles importantes, improvise sur l'environnement, ou fait perdre du temps avec des choix peu adaptés.
Si tu veux un CLAUDE.md exemple qui sert vraiment, voici la logique:
- rester court
- décrire l'environnement réel
- préciser ce qu'il faut éviter
- cadrer la manière de travailler
À quoi sert un fichier CLAUDE.md ?
Le fichier CLAUDE.md sert à donner à Claude Code un contexte stable sur:
- ton projet
- ton environnement
- tes contraintes
- ta manière de travailler
Pense-le comme un contrat de collaboration, pas comme un roman.
Structure minimale qui marche
Voici une base simple:
# Projet
Application SaaS Node.js avec frontend React et backend Fastify.
# Environnement
- OS: Windows 11 + WSL 2
- Shell principal: bash dans Ubuntu
- Node: 22
- Package manager: npm
# Priorités
- Toujours lire avant de modifier
- Expliquer les changements à risque
- Préférer des patchs ciblés
- Ne jamais supprimer des données sans confirmation explicite
# Vérification
- Lancer les tests ciblés après modification
- Signaler clairement ce qui n'a pas pu être vérifié
1. Exemple CLAUDE.md pour SaaS web classique
# Contexte
Produit SaaS web pour PME.
# Stack
- Frontend: React
- Backend: Node.js / Fastify
- Base: SQLite en local, Postgres en prod
# Règles
- Comprendre le flux existant avant de refactorer
- Préserver les comportements de prod
- Préférer les changements incrémentaux
# Style
- Réponses courtes
- Pas de refactor large sans bénéfice clair
- Ajouter des commentaires seulement quand c'est utile
2. Exemple pour repo legacy
# Contexte
Codebase legacy avec dette technique élevée.
# Priorités
- Limiter le rayon d'impact
- Ne pas renommer massivement
- Ne pas déplacer de fichiers sans raison forte
- Identifier les risques avant toute modification
# Vérification
- Tester uniquement la zone touchée
- Signaler les hypothèses non confirmées
3. Exemple pour Windows natif
# Environnement
Projet exécuté sur Windows natif avec PowerShell 7.
# Contraintes
- Utiliser des commandes PowerShell quand possible
- Ne pas supposer un environnement bash
- Éviter les chemins Unix si l'environnement courant est Windows
# Sécurité
- Demander confirmation avant commande potentiellement destructive
4. Exemple pour sécurité renforcée
# Priorités sécurité
- Ne jamais exposer de secrets
- Ne jamais modifier la config prod sans validation explicite
- Signaler toute commande destructive avant exécution
- Préférer la lecture et l'analyse avant l'action
5. Exemple pour code review sévère
# Mode review
Quand on te demande une review:
- chercher d'abord les bugs et régressions
- prioriser les risques de prod
- signaler les tests manquants
- citer fichier et ligne quand c'est possible
6. Exemple pour équipe produit rapide
# Objectif
Aller vite sans casser la qualité.
# Règles
- Commencer par une solution simple
- Reporter les idées optionnelles à la fin
- Livrer ce qui débloque le plus vite
- Garder une communication directe
7. Exemple pour repo avec agents, hooks et automatisation
# Contexte
Projet agentique avec hooks, scripts et intégrations externes.
# Règles
- Décrire l'impact attendu avant ajout d'un hook
- Préférer les mécanismes déterministes pour les garde-fous
- Isoler les scripts critiques
- Documenter toute nouvelle automatisation
Les erreurs qui rendent CLAUDE.md inutile
Trop long
Un fichier de 400 lignes ne vaut pas forcément mieux qu'un fichier de 40 lignes.
Trop vague
Sois intelligent, code proprement, fais au mieux ne servent presque à rien.
Pas mis à jour
Si ton environnement change et que le fichier raconte encore une ancienne réalité, tu nourris l'agent avec de fausses hypothèses.
CLAUDE.md vs hooks
Le bon modèle est simple:
- CLAUDE.md pour les règles, le contexte, le mode de travail
- hooks pour les garde-fous et automatismes qui doivent vraiment se déclencher
Pour aller plus loin, vois aussi Maîtriser les Hooks Claude Code.
Mon conseil
Commence par un CLAUDE.md court, concret et relis-le après chaque semaine d'usage réel.
S'il ne change rien au comportement de l'agent, ce n'est pas un manifeste: c'est juste du bruit.