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 chargées dans la session avec /memory

Dans quel contexte utiliser cette fonctionnalité ?

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/`

Les deux mécanismes sont chargés en début de session, mais pas dans les mêmes conditions :

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`

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.

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 :
```
/memory
```
Les rules sans paths apparaissent tout de suite. Les rules avec paths n’apparaissent que quand Claude lit un fichier qui matche.

Vérifier ce qui est chargé

La commande /memory liste les fichiers d’instructions actifs dans la session en cours : CLAUDE.md, CLAUDE.local.md et rules. C’est le réflexe à avoir quand Claude semble ignorer une règle.

Quand garder dans `CLAUDE.md`, quand déplacer

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

Symptôme	Cause probable	Correction
La rule n’apparaît pas dans `/memory`	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	`/memory` pour voir les deux, trancher une bonne fois

Checklist de fin de guide

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 /memory 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
/memory est l’outil de vérification incontournable
Les procédures ne vont pas dans les rules : elles vont dans les skills

Prochaines étapes

Skills Claude Code Transformer les tâches répétitives en routines réutilisables invoquées par /nom

Hooks Claude Code Automatiser lint, tests et garde-fous autour des événements de session

Configurer CLAUDE.md Revoir les conventions qui restent dans le fichier principal