Un CLAUDE.md qui est suivi
Voici un piège qui attrape presque tout le monde : votre fichier CLAUDE.md ne cesse de grossir. Vous rencontrez un problème, vous ajoutez une règle. Vous en rencontrez un autre, vous ajoutez une autre règle. Avant longtemps, vous vous retrouvez avec un fichier gigantesque, et Claude commence à ignorer certaines parties. Ce n'est pas un bug chez Claude. C'est ainsi que le fichier fonctionne.
Ce qu'il faut comprendre, c'est que CLAUDE.md n'est pas une configuration imposée. C'est une orientation. Chaque ligne est en concurrence avec toutes les autres pour capter l'attention de Claude. Plus le fichier s'allonge, plus il entre en concurrence avec lui-même, et moins Claude suit de manière fiable une règle donnée. Donc l'objectif n'est pas de tout consigner. L'objectif est de garder le fichier compact. Plus le fichier est sobre, plus Claude en suit effectivement le contenu.
D'abord, demandez-vous si CLAUDE.md est même le bon outil
Avant d'écrire une règle, demandez-vous si elle a sa place dans CLAUDE.md. Certaines règles relèvent de l'orientation, et d'autres sont des lignes dures qui ne doivent jamais être franchies. Ce sont deux tâches différentes.
Prenez une règle comme « ne jamais pousser sur main ». Si vous la mettez dans CLAUDE.md, vous espérez que Claude la lit et la respecte. La plupart du temps, ce sera le cas. Mais « la plupart du temps » n'est pas suffisant pour quelque chose d'aussi risqué. Une règle dure de ce genre a plutôt sa place dans un hook pre-tool-use.
La différence compte. Un hook est du code qui s'exécute avant que Claude n'effectue une action, et il peut réellement bloquer cette action. Donc même si Claude tente de pousser sur main, le hook l'en empêche. C'est une véritable mise en application, pas une demande polie. Déplacez vos règles dures vers des hooks et laissez CLAUDE.md gérer les conventions plus souples.
Les quatre emplacements
CLAUDE.md n'est pas qu'un seul fichier posé dans votre projet. Il peut exister à quatre endroits, et Claude les charge tous ensemble au démarrage. Rien n'est écarté, et ils s'empilent.
Voici à quoi sert chacun d'eux :
- Politique gérée — le fichier au niveau de l'organisation que votre équipe plateforme contrôle. Vous ne pouvez pas l'exclure, donc la politique de l'organisation est toujours en jeu.
- Utilisateur — vos préférences personnelles qui vous suivent sur chaque projet, sur votre machine.
- Projet — le fichier partagé avec votre équipe, intégré dans le dépôt.
- Local — ignoré par git. Vos notes personnelles pour ce dépôt uniquement.
Ce dernier, le fichier local, est facile à négliger mais vraiment pratique. Supposons que vous soyez en train de refactoriser dans votre propre branche et que vous vouliez que Claude garde en tête certaines décisions d'architecture pendant que vous travaillez. Cela n'a pas sa place dans le fichier de projet partagé, où cela affecterait toute votre équipe. Cela va dans le fichier local, où c'est réservé à vous seul pour ce dépôt.
Découper un gros fichier grâce aux importations
Lorsque votre fichier de projet commence à s'allonger, vous pouvez le découper en plusieurs morceaux en utilisant la syntaxe d'importation par chemin de fichier. Au lieu d'un mur de texte unique, vous pointez vers d'autres fichiers :
@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.mdC'est excellent pour s'organiser. Mais sachez exactement ce que cela vous apporte, car il est facile de se méprendre. Au démarrage, Claude développe ces fichiers importés en ligne, exactement à l'endroit où vous les avez référencés. Les importations vous aident donc à garder les choses bien rangées, mais tout est quand même chargé d'emblée. Elles ne réduisent pas la quantité de contexte que Claude doit lire. Utilisez les importations pour organiser, pas pour alléger la charge.
La formulation, voilà ce qui fait tenir les règles
Une fois que vous avez décidé qu'une règle a sa place dans CLAUDE.md, le fait que Claude l'applique réellement ou non dépend de la façon dont vous la formulez. La plupart des règles échouent parce qu'elles sont vagues. Voici comment y remédier.
Soyez précis et vérifiable
N'écrivez pas « suivre les bonnes pratiques ». Savez-vous seulement exactement ce que cela signifie ? Si vous ne pouvez pas vérifier si c'est respecté, Claude non plus. Comparez ces deux formulations :
- Vague : « Suivre les bonnes pratiques pour les routes API. »
- Précis : « Placer les nouvelles routes API dans
src/api/handlers, une par fichier. »
La seconde est explicite. Vous pouvez regarder le résultat et dire immédiatement si c'est bien fait. C'est le niveau d'exigence que chaque règle devrait atteindre.
Nommez le remplacement, ne vous contentez pas d'interdire
Quand vous dites à Claude de ne pas faire quelque chose, dites-lui quoi faire à la place. Sinon, vous laissez la porte ouverte.
- Laisse la porte ouverte : « N'utilisez pas les exports par défaut. » D'accord, mais alors quoi ?
- La referme : « Utilisez des exports nommés, pas des exports par défaut. »
La seconde version nomme le remplacement, donc il ne reste rien à mal interpréter.
Formulez simplement plutôt que de crier
Des mots comme « IMPORTANT » et « TU DOIS » sauvent rarement une règle que Claude continue de manquer. Les modèles actuels suivent une ligne formulée simplement, et accumuler l'emphase a surtout pour effet de pousser Claude à sur-appliquer la règle. Si une règle ne peut souffrir aucune exception, transformez-la en hook. Si elle se perd, raccourcissez le fichier.
Gardez le fichier en révision constante
Votre fichier CLAUDE.md n'est jamais terminé. Traitez-le comme du code vivant qui continue d'être modifié.
Quand Claude fait une erreur, ne vous contentez pas de soupirer et de la corriger à la main. Traitez-la comme un rapport de bug contre votre fichier CLAUDE.md. Vous pouvez même le dire directement à Claude : « ajoute cela au fichier CLAUDE.md », et il rédigera la règle pour vous. Ainsi, le fichier s'améliore chaque fois que quelque chose tourne mal.
L'essentiel à retenir
Traitez votre CLAUDE.md comme du code de production. Si vous ne pouvez pas justifier une ligne, supprimez-la. Pour garder le fichier sobre et suivi :
- Déplacez les règles dures vers des hooks, là où elles sont réellement appliquées.
- Organisez les longs fichiers avec des importations (rappelez-vous simplement qu'elles ne réduisent pas le contexte).
- Rendez chaque règle précise et vérifiable, et nommez le remplacement.
- Formulez les règles simplement plutôt que d'ajouter de l'emphase.
- Continuez de réviser le fichier chaque fois que Claude se trompe.
L'idée générale est simple. Plus le fichier est sobre, plus Claude en suit le contenu.