Le répertoire de règles Claude Code

Problème : Un seul CLAUDE.md qui fait trop de choses. Il y a des notes React à côté des conventions API à côté de tes critères de test, et chaque session charge tout ça même quand tu modifies un fichier de migration.

Victoire rapide : Crée ton premier fichier de règle ciblé :

mkdir -p .claude/rules
echo "# Testing Rules
- Run tests before committing
- Mock external services in unit tests" > .claude/rules/testing.md

Claude récupère cette règle au démarrage de la session, juste à côté de CLAUDE.md, avec les deux préoccupations clairement séparées.

C'est quoi le répertoire de règles ?

Depuis Claude Code v2.0.64, tu as une autre option pour organiser tes instructions : le répertoire .claude/rules/. Au lieu d'un seul fichier mémoire surdimensionné, tu déposes plusieurs fichiers markdown à l'intérieur, et Claude les charge tous dans la mémoire du projet au démarrage de la session.

Détail crucial d'Anthropic : les fichiers dans .claude/rules/ se chargent avec la même priorité élevée que CLAUDE.md. C'est important, car la fenêtre de contexte de Claude n'est pas plate. Les différentes sources ont des poids différents lors de la génération.

Pas de configuration. Tout fichier .md sous .claude/rules/ devient automatiquement partie du contexte du projet.

.claude/rules/
├── code-style.md      # Formatting and conventions
├── testing.md         # Test requirements
├── security.md        # Security checklist
└── frontend/
    ├── react.md       # React-specific patterns
    └── styles.md      # CSS conventions

Séparation des préoccupations, mais au niveau de la couche d'instructions. Modifie tes règles de sécurité sans toucher au fichier de style, ou l'inverse.

Règles ciblées par chemin : la fonctionnalité clé

C'est là que le répertoire prouve sa valeur. Un fichier de règle peut cibler des patterns de fichiers spécifiques via le frontmatter YAML :

---
paths: src/api/**/*.ts
---
 
# API Development Rules
 
- All endpoints must validate input with Zod
- Return consistent error shapes: { error: string, code: number }
- Log all requests with correlation IDs

La règle se réveille uniquement quand Claude touche des fichiers correspondant à src/api/**/*.ts. Modifie un composant React et ces notes API restent silencieuses.

Plusieurs patterns de chemin

Un seul fichier peut surveiller plusieurs patterns à la fois :

---
paths:
  - src/components/**/*.tsx
  - src/hooks/**/*.ts
---
 
# React Development Rules
 
- Use functional components exclusively
- Extract logic into custom hooks
- Memoize expensive computations

Patterns de chemin courants

Pourquoi la priorité compte : le problème du CLAUDE.md monolithique

Tous les tokens dans le contexte de Claude n'ont pas le même poids. Les sources sont classées, et Anthropic est clair : CLAUDE.md et les fichiers de règles ont une priorité élevée. Claude traite les deux comme des instructions faisant autorité.

Ça créait un piège avec l'ancienne façon de travailler. Entasser chaque convention dans un CLAUDE.md massif signifiait que tout bénéficiait d'un traitement prioritaire. Les patterns API se disputaient l'attention avec les patterns React, même quand le boulot était une migration de base de données.

Priorité élevée partout = priorité nulle part.

Marque tout comme important et Claude ne peut plus distinguer ce qui s'applique vraiment maintenant. Les instructions perdent leur focus, le contexte devient bruyant, et le comportement devient imprévisible.

La hiérarchie de priorité du contexte

Un aperçu rapide de comment Claude pèse chaque source :

Le répertoire de règles corrige le monolithe en répartissant les instructions prioritaires sur des fichiers à portée limitée. Les règles API restent prioritaires, mais uniquement quand Claude est dans les fichiers API.

Ciblage par chemin = portée de la priorité

Une règle avec une entrée paths: se charge, et obtient une attention élevée, uniquement quand Claude travaille sur des fichiers qui correspondent :

---
paths: src/api/**/*.ts
---
 
# These instructions get high priority ONLY during API work

C'est là l'insight réel. Tu ne fais pas que classer les choses proprement. Tu choisis quand les instructions reçoivent un poids supplémentaire.

Règles vs CLAUDE.md vs Skills

Qui prend quel boulot ?

CLAUDE.md contient ce qui s'applique partout : logique de routage, critères de qualité, protocoles de coordination. Garde-le court. Chaque ligne ici se bat pour le même budget haute priorité.

Les règles contiennent ce qui s'applique à une zone : règles API pour les fichiers API, règles de test pour les fichiers de test. Le ciblage par chemin maintient cette priorité élevée dans le bon moment.

Les skills contiennent ce qui s'applique entre projets : playbooks de déploiement, checklists de review, guides de marque. Ils restent silencieux à priorité basse jusqu'à ce que quelque chose les déclenche.

Exemples pratiques

Règles de sécurité pour les répertoires sensibles

---
paths:
  - src/auth/**/*
  - src/payments/**/*
---
 
# Security-Critical Code Rules
 
- Never log sensitive data (passwords, tokens, card numbers)
- Validate all inputs at function boundaries
- Use parameterized queries exclusively
- Require explicit authorization checks before data access

Standards pour les fichiers de test

---
paths: **/*.test.ts
---
 
# Test Writing Standards
 
- Use descriptive test names: "should [action] when [condition]"
- One assertion per test when possible
- Mock external dependencies, never real APIs
- Include edge cases: empty inputs, null values, boundaries

Règles pour les migrations de base de données

---
paths: prisma/migrations/**/*
---
 
# Migration Safety Rules
 
- Always include rollback instructions
- Test migrations on a copy of production data first
- Never delete columns in the same migration that removes code using them
- Add columns as nullable first, populate, then add constraints

Migration depuis un CLAUDE.md monolithique

Un CLAUDE.md surchargé est généralement le symptôme d'une saturation de priorité. Tout est marqué important, donc rien ne l'est. La solution consiste à extraire les sections spécifiques à un domaine et à placer chacune dans une règle ciblée par chemin :

Avant (un seul CLAUDE.md de 400 lignes) :

# Project Context
 
...
 
## API Guidelines
 
- Validate inputs with Zod
- Return consistent errors
  ...
 
## React Patterns
 
- Use functional components
- Extract hooks
  ...
 
## Testing Rules
 
- Mock external services
  ...

Après (CLAUDE.md épuré + règles modulaires) :

# CLAUDE.md - Operational Core Only
 
## Routing Logic
 
- Simple tasks: execute directly
- Complex tasks: delegate to sub-agents
 
## Quality Standards
 
- Correctness > Maintainability > Performance

.claude/rules/
├── api-guidelines.md      # API section with paths: src/api/**/*
├── react-patterns.md      # React section with paths: src/components/**/*
└── testing-rules.md       # Testing section with paths: **/*.test.*

CLAUDE.md garde son focus sur comment tu opères. La connaissance du domaine va dans des règles ciblées qui n'ont une priorité élevée que quand les fichiers actifs correspondent.

La saturation de priorité, c'est ce que tu résous vraiment. Les instructions opérationnelles de base sont toujours actives. Les règles de domaine élèvent leur voix uniquement quand Claude édite des fichiers dans leur couloir. Partout ailleurs, le silence.

Règles au niveau utilisateur : tes défauts personnels dans tous les projets

Les règles de projet ne sont pas la seule couche. Les règles personnelles qui te suivent dans chaque projet vivent dans ~/.claude/rules/ :

~/.claude/rules/
├── preferences.md     # Your personal coding preferences
├── workflows.md       # Your preferred workflows
└── shortcuts.md       # Custom patterns you always want

Les règles utilisateur se chargent en premier, puis les règles de projet s'ajoutent par-dessus. Tes défauts personnels voyagent avec toi, mais n'importe quel projet peut les remplacer quand il le doit.

Utile pour tout ce qui reflète comment toi tu travailles : style d'indentation, forme des messages de commit, patterns de test préférés, petites habitudes que tu veux toujours en place peu importe la codebase.

Expansion d'accolades dans les patterns de chemin

Les patterns de chemin gèrent l'expansion d'accolades, donc une seule entrée peut couvrir plusieurs extensions ou répertoires à la fois :

---
paths:
  - "src/**/*.{ts,tsx}"
  - "{src,lib}/**/*.ts"
---
 
# TypeScript/React Rules
 
- Use strict TypeScript
- Prefer interfaces over type aliases for public APIs

{ts,tsx} capture à la fois .ts et .tsx. {src,lib} couvre à la fois src/ et lib/. Ton frontmatter reste compact quand une règle couvre des types de fichiers ou des dossiers connexes.

Symlinks : partager des règles entre projets

Les symlinks fonctionnent dans .claude/rules/, ce qui te permet de garder une source de règles canonique et de la partager entre dépôts :

# Symlink a shared rules directory
ln -s ~/shared-claude-rules .claude/rules/shared
 
# Symlink individual rule files
ln -s ~/company-standards/security.md .claude/rules/security.md

Les fichiers liés se résolvent et se chargent exactement comme des fichiers locaux. Les symlinks circulaires sont détectés et gérés, donc une boucle infinie n'est pas quelque chose contre quoi tu dois te protéger.

Parfait pour les équipes qui partagent des standards de code entre projets. Garde le dépôt de règles canonique à un seul endroit. Fais un symlink vers chaque projet qui en a besoin.

Découverte récursive dans les sous-répertoires

Les sous-répertoires sont pris en compte. Chaque fichier .md dans l'arborescence est récupéré :

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── general.md

Imbriqué ou plat, le chargeur parcourt tout le répertoire. Groupe les fichiers connexes comme tu veux sans perdre la lisibilité.

Bonnes pratiques

Garde les règles focalisées : une préoccupation par fichier. Sécurité à un endroit, style ailleurs.

Utilise des noms de fichiers descriptifs : api-validation.md vaut mieux que rules1.md.

Mise sur le ciblage par chemin : les règles sans paths: se chargent partout. Ajoute un pattern dès qu'une règle commence à s'infiltrer dans un travail sans rapport.

Mets tout sous contrôle de version : les règles sont du code. Review-les dans les PRs, suis leur historique, reviens en arrière sur celles qui n'ont pas marché.

Documente l'objectif de la règle : ouvre chaque fichier avec une ligne expliquant quand elle doit s'appliquer.

Prochaines étapes

1. Audite ton CLAUDE.md : repère les sections qui ne s'appliquent vraiment qu'à certains types de fichiers
2. Extrais une règle : sors ton bloc le plus spécifique à un domaine dans .claude/rules/
3. Ajoute le ciblage par chemin : pointe cette règle vers les fichiers qu'elle sert vraiment
4. Itère : quand Claude charge un contexte dont tu n'as pas besoin, extrais une autre règle

Pour l'architecture mémoire plus large et pourquoi un seul gros fichier pose problème, consulte le guide CLAUDE.md Mastery. Pour comprendre comment la priorité s'intègre dans une stratégie de contexte plus large, lis les guides sur la gestion du contexte et l'optimisation de la mémoire.

Souviens-toi : l'objectif est de donner à Claude exactement les instructions haute priorité qui correspondent aux fichiers à l'écran. Rien de plus. L'attention là où ça compte, le silence partout ailleurs. Combine ça avec une architecture de skills qui charge la connaissance du domaine à la demande, et ta fenêtre de contexte reste légère pendant que tes instructions gardent leur poids.