Les rules Claude Code scopées par chemin

💡 Sujet

Un CLAUDE.md est chargé en entier à chaque session : plus il grossit, plus il coûte en contexte et moins il est suivi. Le dossier .claude/rules/ permet de découper ces instructions en fichiers thématiques, et le champ paths en frontmatter ne charge une règle que lorsque Claude lit un fichier qui correspond au motif.

🏗️ Arborescence

Tous les .md du dossier sont découverts récursivement, les sous-dossiers servent juste à ranger.

mon-projet/
├── CLAUDE.md                 # Instructions générales, toujours chargées
└── .claude/
    └── rules/
        ├── code-style.md     # Sans paths → chargée au lancement
        ├── testing.md        # paths: tests/** → chargée à la demande
        ├── frontend/
        │   └── react.md
        └── backend/
            └── api.md

Deux niveaux existent :

Les règles utilisateur sont chargées avant celles du projet. Aucune n'écrase l'autre : en cas de contradiction, Claude peut suivre l'une ou l'autre, donc les garder cohérentes.

⚙️ Règle conditionnelle avec paths

Le frontmatter YAML entre --- porte un seul champ utile : paths, une liste de globs.

---
paths:
  - "src/api/**/*.ts"
---

# Règles de développement API

- Chaque endpoint valide ses entrées avec le schéma Zod correspondant.
- Les erreurs suivent le format `{ code, message, details }`.
- Documenter chaque route avec un commentaire OpenAPI.

• Sans paths : la règle est chargée au lancement, avec la même priorité que .claude/CLAUDE.md.
• Avec paths : elle est injectée quand Claude lit un fichier qui matche (outil Read), pas à chaque appel d'outil ni au démarrage.
• Le frontmatter est retiré avant l'injection : il ne consomme pas de contexte.
• Tout autre champ que paths est ignoré, sans erreur.

paths accepte aussi une chaîne séparée par des virgules :

---
paths: "src/**/*.ts, lib/**/*.ts"
---

🎯 Les motifs glob

Plusieurs motifs et l'expansion d'accolades se combinent :

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

Chaque groupe d'accolades multiplie les motifs : {a,b}/{c,d}/*.{ts,tsx} en donne huit. Le budget est de 1 000 motifs développés par règle ; au-delà, le motif est gardé tel quel et ses accolades littérales ne matchent rien.

Le [ ouvre une classe de caractères ([abc]). Pour un crochet littéral dans un nom de fichier, l'échapper :

---
paths:
  - "photos \\[2024/**"
---

Le double \\ vient des guillemets doubles YAML : le glob reçu est bien photos \[2024/**. Un motif invalide ne matche rien, sans casser les autres motifs de la règle.

🔍 Exemple concret : une règle par techno

Dans un projet Android, garder le CLAUDE.md pour le build et les conventions globales, et sortir le spécifique :

---
paths:
  - "**/*.gradle.kts"
  - "gradle/libs.versions.toml"
---

# Gradle

- Toute dépendance passe par le version catalog `libs.versions.toml`, jamais en dur.
- Ne pas monter de version d'AGP sans demander.

---
paths:
  - "**/src/test/**/*.kt"
  - "**/src/androidTest/**/*.kt"
---

# Tests

- JUnit 5 + MockK, pas de Mockito.
- Nommer les tests en phrase entre backticks : should do X when Y.

Claude ne voit la règle Gradle que lorsqu'il ouvre un script de build : le reste du temps, elle ne coûte rien.

🐞 Vérifier et déboguer

# Voir quels CLAUDE.md et rules sont chargés dans la session
/context

# Voir l'erreur si le YAML du frontmatter ne parse pas
claude --debug

• Un frontmatter invalide n'échoue pas : la règle est chargée comme si elle n'avait pas de paths, donc toujours. Piège classique.
• Après un /compact, les règles scopées disparaissent du contexte et reviennent à la prochaine lecture d'un fichier qui matche.
• Le hook InstructionsLoaded permet de logger quelles règles se chargent, quand et pourquoi.

🔗 Partager des règles entre projets

Le dossier suit les liens symboliques (les boucles sont détectées) :

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

Une cible hors du dossier de travail est traitée comme un import externe : elle ne se charge qu'après validation des imports externes du projet, et même alors seules les règles sans paths sont chargées. Pour des règles perso communes à tous les projets, ~/.claude/rules/ est plus simple.

🧩 Résumé

• .claude/rules/*.md découpe les instructions en fichiers thématiques, découverts récursivement.
• Sans frontmatter, une règle est chargée à chaque session comme un CLAUDE.md.
• Avec paths: (liste de globs ou chaîne à virgules), elle n'est chargée que quand Claude lit un fichier correspondant.
• Globs classiques : **, *, accolades {ts,tsx}, [ à échapper.
• YAML cassé = règle chargée tout le temps : vérifier avec /context et claude --debug.
• ~/.claude/rules/ pour les préférences perso, chargées avant celles du projet.
• Pour une procédure ponctuelle plutôt qu'une convention, préférer un skill.

🔗 Références

• Claude Code — Organize rules with .claude/rules/
• Claude Code — Path-specific rules
• Claude Code — Skills