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 touche 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 touche un fichier matché	Règles spécifiques à une zone (API, tests, migrations)

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. 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 que quand Claude lit un fichier qui matche le 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/`

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.

Créez le dossier des rules

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

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

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

Allégez votre CLAUDE.md

Retirez les sections "Tests" et "API" qui sont maintenant dans les rules. Gardez dans CLAUDE.md uniquement ce qui vaut pour tout le projet (stack, commandes de validation, conventions globales).
Démarrez une session et vérifiez
Fenêtre de terminal
```
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.

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 une procédure (pas un fait)	à déplacer en skill

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

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

À 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.