Un CLAUDE.md que Claude suit

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 vers 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 dangereux. Une règle dure de ce type 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'entreprenne une action, et il peut réellement bloquer cette action. Ainsi, même si Claude tente de pousser vers main, le hook l'arrête. C'est une application réelle, 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 existe quatre endroits où il peut résider, et Claude les charge tous ensemble au lancement. Rien n'est abandonné, et ils s'empilent.

Voici à quoi chacun sert :

• Politique gérée — le fichier au niveau de l'organisation que votre équipe de plateforme contrôle. Vous ne pouvez pas l'exclure, donc la politique de l'organisation est toujours en vigueur.
• Utilisateur — vos préférences personnelles qui vous suivent dans tous les projets sur votre machine.
• Projet — le fichier partagé avec votre équipe, intégré au dépôt.
• Local — ignoré par git. Vos notes personnelles pour ce seul dépôt.

Ce dernier, local, est facile à négliger mais vraiment pratique. Disons que vous refactorisez dans votre propre branche et que vous voulez 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 local, où c'est uniquement le vôtre pour ce dépôt.

Découpez un gros fichier avec des imports

Lorsque votre fichier de projet commence à s'allonger, vous pouvez le découper en morceaux en utilisant la syntaxe d'import 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.md

C'est excellent pour organiser. Mais sachez exactement ce que cela vous apporte, car il est facile de se faire une fausse idée. Lorsque Claude se lance, il développe ces fichiers importés en ligne, exactement à l'endroit où vous les avez référencés. Les imports vous aident donc à garder les choses ordonnées, mais tout est quand même chargé dès le départ. Ils ne réduisent pas la quantité de contexte que Claude doit lire. Utilisez les imports pour organiser, pas pour réduire la charge.

La formulation est 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'obéisse réellement dépend de la façon dont vous la formulez. La plupart des règles échouent parce qu'elles sont vagues. Voici comment corriger cela.

Soyez précis et vérifiable

N'écrivez pas « suivre les bonnes pratiques ». Savez-vous même exactement ce que cela signifie ? Si vous ne pouvez pas vérifier si elle a été suivie, Claude ne le peut pas non plus. Comparez ces deux exemples :

• Vague : « Suivre les bonnes pratiques pour les routes API. »
• Précis : « Placer les nouvelles routes API dans src/api/handlers, une par fichier. »

Le second est explicite. Vous pouvez regarder le résultat et dire immédiatement si c'a été fait correctement. C'est la barre que chaque règle devrait atteindre.

Nommez le remplacement, ne vous contentez pas d'interdire

Lorsque vous dites à Claude de ne pas faire quelque chose, dites ce qu'il faut 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 ferme : « Utilisez des exports nommés, pas des exports par défaut. »

La seconde version nomme le remplacement, il ne reste donc rien à mal interpréter.

L'emphase est un budget

Des mots comme « IMPORTANT » et « VOUS DEVEZ » augmentent effectivement la priorité d'une règle. Mais seulement par rapport à tout ce qui est plus discret autour. Si chaque règle crie, alors rien ne se démarque et l'emphase ne signifie plus rien. Traitez donc l'emphase comme un budget. Dépensez-la sur les deux ou trois règles qui font vraiment mal lorsqu'elles sont enfreintes, et laissez le reste à un volume normal.

Gardez le fichier en révision permanente

Votre fichier CLAUDE.md n'est jamais terminé. Traitez-le comme du code vivant qui continue d'être modifié.

Lorsque Claude fait la mauvaise chose, ne vous contentez pas de soupirer et de corriger à la main. Traitez cela comme un rapport de bug contre votre fichier CLAUDE.md. Vous pouvez même le dire directement à Claude : « ajoute ça au fichier CLAUDE.md », et il écrira la règle pour vous. Ainsi, le fichier s'améliore chaque fois que quelque chose se passe 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 épuré et suivi :

1. Déplacez les règles dures vers des hooks, où elles sont réellement appliquées.
2. Organisez les longs fichiers avec des imports (rappelez-vous simplement qu'ils ne réduisent pas le contexte).
3. Rendez chaque règle précise et vérifiable, et nommez le remplacement.
4. Dépensez votre budget d'emphase sur les quelques règles qui comptent le plus.
5. Continuez à réviser le fichier chaque fois que Claude se trompe.

L'idée générale est simple. Plus le fichier est épuré, plus Claude en suit le contenu.