Claude Code : rules ciblées par dossier pour sortir les règles spécifiques de CLAUDE.md

Votre CLAUDE.md a bien grossi : conventions API, règles de tests, scripts d'infra, le tout mélangé. Claude lit l'ensemble à chaque session, et certaines règles polluent les zones où elles ne s'appliquent pas. Les rules ciblées (.claude/rules/*.md) règlent ce problème : vous sortez les règles trop spécifiques de CLAUDE.md et les chargez uniquement quand Claude lit un fichier de la zone concernée, grâce au frontmatter paths.

Ce que vous allez apprendre

• Ce qui reste dans CLAUDE.md et ce qui part dans .claude/rules/
• La syntaxe du frontmatter paths avec globs
• Appliquer une rule ciblée sur lab-claude
• Vérifier les rules réellement chargées dans la session avec /context

Dans quel contexte utiliser cette fonctionnalité ?

Le déclencheur n'est pas la taille du fichier en soi, c'est le ratio de pertinence. Un CLAUDE.md de 300 lignes dont 280 s'appliquent partout reste sain ; un CLAUDE.md de 120 lignes dont la moitié ne concerne que tests/ mérite déjà un découpage. Chaque ligne inutile occupe du contexte à chaque session et dilue les règles qui comptent vraiment.

• Votre CLAUDE.md dépasse 150 lignes et mélange plusieurs zones
• Une règle ne s'applique qu'à un dossier (ex : tests/, app/api/)
• Plusieurs équipes contribuent et veulent des règles locales
• Vous voulez éviter que des règles de tests guident des changements côté API

Prérequis

• CLAUDE.md déjà posé (voir configurer CLAUDE.md)
• Projet fil rouge prêt : ~/Projets/lab-claude

CLAUDE.md vs .claude/rules/

La distinction tient en un mot : le moment du chargement. CLAUDE.md et les rules sans paths entrent en contexte au démarrage de la session, avec la même priorité. Une rule portant un paths ne s'y trouve pas : elle est injectée plus tard, quand Claude lit un fichier correspondant au motif. Ce n'est donc pas un filtre appliqué à chaque appel d'outil, mais un déclenchement à la lecture.

Mécanisme	Chargé quand	Usage recommandé
CLAUDE.md	À chaque session, en entier	Faits toujours vrais : stack, commandes, conventions globales
.claude/rules/<nom>.md sans paths	À chaque session, en entier	Règles transversales trop volumineuses pour CLAUDE.md
.claude/rules/<nom>.md avec paths	Quand Claude lit un fichier qui matche	Règles spécifiques à une zone (API, tests, migrations)
~/.claude/rules/<nom>.md	Même mécanique, sur tous vos projets	Vos préférences personnelles, indépendantes du dépôt

Glissez pour voir

La dernière ligne est celle qu'on oublie : les rules existent aussi au niveau utilisateur, dans ~/.claude/rules/. Elles suivent exactement les mêmes règles de chargement, paths compris, mais s'appliquent à tous vos dépôts. C'est l'endroit de vos conventions personnelles, celles que vous n'imposez pas à l'équipe en les commitant.

Règle simple :

• Si la règle vaut pour tout le projet et tient en quelques lignes, gardez-la dans CLAUDE.md
• Si elle ne vaut que pour un dossier précis, sortez-la dans .claude/rules/<zone>.md avec paths

Structure des rules

Les rules vivent dans .claude/rules/ et sont découvertes récursivement : un fichier rangé dans .claude/rules/frontend/react.md est trouvé sans rien déclarer. Chaque fichier Markdown couvre un sujet et peut être scopé avec un frontmatter YAML :

lab-claude/
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   └── rules/
│       ├── tests.md
│       └── api.md
└── ...

Exemple de rule ciblée sur les tests :

---
paths:
  - "tests/**/*.py"
---

# Règles pour les tests

- Utiliser `TestClient` de FastAPI pour les tests d'endpoint
- Chaque endpoint a au moins un test de cas nominal et un test d'erreur
- Les fixtures vivent dans `tests/conftest.py`
- Ne pas mocker la validation Pydantic : tester le comportement réel

Sans paths, la rule se charge à chaque session. Avec paths, elle n'arrive en contexte qu'au premier fichier lu qui correspond au glob.

Syntaxe du frontmatter paths

Les motifs suivent la syntaxe glob habituelle, avec une distinction qui piège souvent : * ne traverse pas les répertoires, ** si. Écrire app/*.py ne couvrira donc que les fichiers posés directement dans app/, pas ceux de app/routers/. C'est la cause numéro un des rules qui semblent ne jamais se déclencher.

Attention aussi au crochet [ : glob le lit comme le début d'une classe de caractères ([abc]). Un motif contenant un [ non refermé correctement ne correspond à rien, silencieusement, sans casser les autres motifs de la même rule. Pour un crochet littéral dans un nom de fichier, échappez-le : \[.

Quelques motifs utiles :

Motif	Correspond à
**/*.py	Tous les fichiers Python du projet
app/**/*	Tous les fichiers sous app/
tests/**/*.py	Tous les tests Python
app/api/**/*.py	API uniquement
migrations/*.sql	Fichiers SQL de migration à la racine de migrations/

Glissez pour voir

Vous pouvez combiner plusieurs motifs et utiliser l'expansion accolade :

---
paths:
  - "app/**/*.{py,pyi}"
  - "tests/**/*.py"
---

Application sur lab-claude

Objectif : sortir les règles tests et les règles endpoints API de CLAUDE.md vers deux rules dédiées.

L'étape 4 est celle qu'on oublie, et c'est la seule qui produise le bénéfice recherché. Créer les fichiers dans .claude/rules/ sans retirer les sections correspondantes de CLAUDE.md ne fait qu'ajouter du contexte : les règles sont désormais présentes deux fois, avec le risque qu'elles divergent à la première modification. Le déplacement doit être un déplacement, pas une copie.

1. Créez le dossier des rules

   cd ~/Projets/lab-claude
   mkdir -p .claude/rules

2. Créez .claude/rules/tests.md

   ---
   paths:
     - "tests/**/*.py"
   ---
   
   # Règles pour les tests
   
   - Chaque endpoint a au moins un test de cas nominal et un test d'erreur
   - Utiliser `TestClient` de FastAPI pour les tests d'endpoint
   - Nom des fonctions de test : `test_<endpoint>_<cas>`
   - Pas de mock sur la validation Pydantic

3. Créez .claude/rules/api.md

   ---
   paths:
     - "app/**/*.py"
   ---
   
   # Règles pour l'API
   
   - Chaque endpoint déclare son type de retour (`-> dict[str, str]`)
   - Statut HTTP explicite via `status_code=` si différent de 200
   - Documenter l'endpoint en une ligne (docstring)
   - Ne pas dupliquer la logique de `/health` : factoriser si besoin

4. Allégez votre CLAUDE.md

   Retirez les sections Tests et API qui vivent maintenant dans les rules. Gardez dans CLAUDE.md uniquement ce qui vaut pour tout le projet : stack, commandes de validation, conventions globales.

5. Démarrez une session et vérifiez

   claude

   Puis dans la session :

   /context

   Les rules sans paths apparaissent tout de suite sous Memory files. Les rules avec paths n'apparaissent que quand Claude lit un fichier qui matche.

Vérifier ce qui est chargé

Deux commandes, deux usages distincts, et les confondre fait perdre du temps. /context affiche ce qui est réellement chargé dans la session en cours, sous la rubrique Memory files : c'est la commande de diagnostic quand Claude semble ignorer une règle. /memory liste et ouvre les emplacements des fichiers d'instructions (CLAUDE.md, CLAUDE.local.md, mémoire automatique), y compris ceux qui n'existent pas encore : c'est la commande d'édition, pas de vérification.

Déboguer le chargement des rules

Si une rule paths n'apparaît pas dans /context, demandez à Claude de lire un fichier qui matche le motif : la rule se charge à la première lecture, pas au démarrage. Pour un diagnostic plus fin, le hook InstructionsLoaded journalise quels fichiers d'instructions sont chargés, à quel moment et pourquoi.

Le test en deux temps, positif puis négatif

Une rule absente de /context ne prouve rien tant que vous n'avez pas provoqué son chargement. Le contrôle se fait donc avec deux fichiers de chemins différents, et il demande deux sessions.

1. Le cas positif. Demandez à Claude de lire un fichier qui matche le motif, par exemple tests/test_sante.py pour un paths valant "tests/**/*.py". Relancez /context : la rule doit maintenant figurer sous Memory files. Si elle n'y est pas, le problème est dans le fichier de rule, pas dans le glob.

2. Le cas négatif. Ouvrez une nouvelle session, indispensable puisqu'une rule déjà chargée le reste, et faites lire un fichier hors périmètre, par exemple app/main.py. La rule doit rester absente.

Le second temps est celui qu'on saute, et c'est le seul qui attrape un glob trop large. Une rule qui se charge partout n'est plus ciblée : elle pèse sur chaque session sans que rien ne le signale, ce qui est exactement le problème que vous cherchiez à résoudre en la sortant de CLAUDE.md.

Quand garder dans CLAUDE.md, quand déplacer

La dernière ligne du tableau tranche une confusion fréquente. Une règle est un fait toujours vrai que Claude doit avoir en tête ; une procédure est une suite d'étapes à dérouler dans un cas particulier. Les procédures n'ont rien à faire dans les rules : elles occuperaient du contexte en permanence pour servir une fois. Elles vont dans les skills, qui ne se chargent qu'à l'invocation.

La règle…	Où la mettre
s'applique au projet entier et tient en 2 lignes	CLAUDE.md
s'applique au projet entier mais fait 20+ lignes	.claude/rules/<sujet>.md sans paths
ne concerne qu'un dossier	.claude/rules/<zone>.md avec paths
est personnelle et ne doit pas être partagée	CLAUDE.local.md
est personnelle et vaut pour tous vos projets	~/.claude/rules/<sujet>.md
est une procédure (pas un fait)	à déplacer en skill

Glissez pour voir

Une limite mérite enfin d'être posée avant d'écrire votre première rule : comme CLAUDE.md, une rule est une consigne que Claude lit, pas une configuration que Claude Code applique. Elle oriente, elle n'empêche pas. Pour un comportement garanti, quoi qu'il arrive, ce sont les hooks et les permissions qu'il faut, pas une règle mieux formulée. Écrire « ne jamais lancer telle commande » dans une rule réduit la probabilité ; un hook la ramène à zéro.

Erreurs fréquentes

Les deux premières lignes se ressemblent mais ne se diagnostiquent pas pareil. Une rule absente de /context n'a pas été lue du tout : le problème est dans le fichier lui-même, frontmatter mal fermé ou emplacement incorrect. Une rule présente mais sans effet sur certains fichiers a bien été lue : c'est le glob qui ne couvre pas la zone attendue. Vérifiez toujours la présence avant de retoucher le motif.

Symptôme	Cause probable	Correction
La rule n'apparaît pas dans /context	Frontmatter mal fermé ou paths incorrect	Vérifier les trois tirets et la syntaxe YAML
Règle ignorée sur les nouveaux fichiers	Glob trop restrictif	Passer de app/*.py à app/**/*.py
CLAUDE.md toujours aussi long	Règles transversales laissées dedans	Ne déplacer que les règles réellement ciblées
Rules contradictoires entre scopes	Rule utilisateur qui entre en conflit avec projet	Les rules projet passent après celles de ~/.claude/rules/ et l'emportent ; trancher une bonne fois

Glissez pour voir

Checklist de fin de guide

Reprenez ces cinq points sur un projet réel, pas sur le lab. Le troisième est celui qui décide du résultat : tant que CLAUDE.md n'a pas maigri, le contexte consommé à chaque session n'a pas bougé et l'exercice n'a rien apporté.

• J'ai créé le dossier .claude/rules/
• J'ai au moins une rule avec paths fonctionnelle
• J'ai allégé CLAUDE.md en retirant les règles déplacées
• J'ai vérifié avec /context que les rules sont chargées
• Je sais quand garder une règle dans CLAUDE.md et quand la sortir

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• CLAUDE.md = faits globaux, .claude/rules/ = règles ciblées
• Le frontmatter paths évite de polluer le contexte avec des règles non pertinentes
• Chaque rule couvre un sujet, pour rester lisible et maintenable
• /context est l'outil de vérification : il montre ce qui est chargé dans la session, là où /memory ne fait que lister et ouvrir les fichiers
• Les procédures ne vont pas dans les rules : elles vont dans les skills

Pour aller plus loin

• Hooks pour automatiser lint et tests : Une règle qui doit s'appliquer sans dépendre du bon vouloir du modèle devient un hook.
• Skills : routines réutilisables : L'étage au-dessus des rules : une procédure complète invoquée à la demande.
• Quelle brique utiliser quand ? : La frontière exacte entre rules, CLAUDE.md, settings, hooks et skills, sans doublon.

×

📖 Voir la documentation →