Rules Claude Code : la feature que tout le monde a oubliée
Tout le monde parle de skills et d’agents, mais les rules de Claude Code sont passées sous le radar
TLDR;
Le dossier
.claude/rules/permet de découper vos instructions en fichiers thématiques au lieu de tout entasser dans un seul CLAUDE.mdAvec le frontmatter
paths:, vous ciblez des règles uniquement quand Claude travaille sur certains fichiersLes rules ne représentent pas seulement une meilleure organisation, c’est également du ciblage de priorité (vos règles d’API ne “polluent” plus le contexte quand vous éditez du CSS)
Résultat : un CLAUDE.md léger, des instructions qui ne se perdent plus et un agent qui suit enfin vos conventions
Question à un million : combien de lignes fait votre CLAUDE.md ?
Si vous êtes comme l’un de mes récents clients, la réponse est sûrement beaucoup trop. Le sien faisait plusieurs milliers de lignes et Claude Code affichait un warning à chaque ouverture : conventions de naming, commandes de build, instructions de tests, patterns d’API, règles de sécurité... Tout au même endroit. Et bien entendu, Claude ignorait la moitié de ce que les développeurs de l’entreprise écrivaient.
Et disons-le tout de suite, le problème, ce n’était pas Claude. Même pour une IA, un fichier de 300+ lignes, c’est beaucoup de bruit. La solution existe depuis un moment. Des vidéos et des articles ont été publiés à leur sortie… puis plus rien. Plus personne n’en parle. Tout le monde s’est jeté sur les skills et les agents. Les rules, elles, sont restées dans l’ombre malgré leur importance.
Quand tout est prioritaire, plus rien ne l’est
Pour comprendre pourquoi les rules changent la donne, il faut savoir quelque chose de fondamental sur le fonctionnement interne de Claude Code : toutes les informations dans le contexte n’ont pas le même poids. Le CLAUDE.md et les fichiers de rules reçoivent une priorité élevée. Claude traite ces instructions comme faisant autorité.
Le problème du CLAUDE.md monolithique, c’est que TOUT son contenu reçoit cette priorité élevée. Vos patterns React entrent en compétition avec vos règles d’API, qui entrent en compétition avec vos conventions de tests. Même quand vous travaillez sur une migration de base de données et que ces informations ne servent à rien.
Et trop de priorité tue la priorité.
Vous connaissez la suite. Claude “oublie” certaines règles. Pas parce qu’il est mauvais, mais parce que vos instructions sur la sécurité des endpoints se noient au milieu de vos préférences ESLint. Et côté maintenance, quand 3 développeurs ajoutent leurs règles dans le même fichier, c’est la pagaille (et c’est ce qui se passait chez ce client dont je vous parlais en début d’article).
La documentation officielle le dit clairement : visez moins de 200 lignes dans votre CLAUDE.md. Au-delà, les instructions commencent à se perdre. Et encore, certains se limitent à 150, voire 60. Vous l’aurez compris, ce fichier doit être succint mais suffisamment documenté.
Les rules : vos instructions, mais modulaires
Au lieu d’un fichier unique, vous découpez vos instructions en fichiers thématiques. Chacun couvre un sujet, chacun est court et chacun se charge automatiquement au démarrage de la session, avec la même priorité élevée que le CLAUDE.md.
mon-projet/
├── .claude/
│ ├── CLAUDE.md # Le minimum vital
│ └── rules/
│ ├── code-style.md # Conventions de code
│ ├── testing.md # Règles de tests
│ ├── frontend/
│ │ ├── react.md # Patterns React
│ │ └── styles.md # Conventions CSS
│ └── backend/
│ ├── api-design.md # Patterns d'API
│ └── security.md # Règles de sécuritéTous les fichiers .md sont découverts récursivement, y compris dans les sous-dossiers. Pas besoin de les référencer quelque part. Vous les créez, Claude les lit.
Un exemple concret. Votre fichier testing.md (c’est mieux de l’écrire en anglais, mais rédigeons en français pour l’exemple) :
# Conventions de tests
- Utiliser Vitest, pas Jest
- Nommer les fichiers de test avec le suffixe .test.ts
- Un fichier de test par composant ou module
- Privilégier les tests d'intégration pour les pages, les tests unitaires pour les utilitaires
- Lancer les tests avec `pnpm test` avant chaque commit
- Ne pas mocker les modules internes sauf en dernier recoursVous voyez ? C’est court, précis et difficilement ignorable pour Claude.
Le vrai pouvoir : les rules ciblées par chemin
Là où les rules deviennent redoutables, c’est avec le frontmatter et l’élément paths:. Ce mécanisme charge une règle uniquement quand Claude travaille sur des fichiers qui correspondent à un pattern donné.
Du coup, vous ne faites pas une simple organisation, mais vous décidez quand une instruction reçoit la priorité élevée.
Vos règles d’API ne se chargent que quand Claude touche aux fichiers d’API ou encore vos patterns React ne s’activent que dans le dossier des composants. Le reste du temps, zéro bruit dans le contexte.
Prenons un cas concret : les règles de sécurité pour les fichiers sensibles.
---
paths:
- "src/auth/**/*"
- "src/payments/**/*"
---
# Code critique (sécurité)
- Ne jamais logger de données sensibles (mots de passe, tokens, numéros de carte)
- Valider tous les inputs en entrée de fonction
- Utiliser exclusivement des requêtes paramétrées
- Vérifier les autorisations avant tout accès aux donnéesCes règles ne se chargent que quand Claude travaille dans src/auth/ ou src/payments/. Le reste du temps, elles n’existent pas dans son contexte.
Autre exemple, pour les fichiers de test :
---
paths: "**/*.test.ts"
---
# Standards de tests
- Noms descriptifs : "should [action] when [condition]"
- Une assertion par test quand c'est possible
- Mocker les dépendances externes, jamais les vrais endpoints
- Inclure les cas limites : inputs vides, null, valeurs aux bornesLe frontmatter paths: accepte les globs classiques et les brace expansions. src/**/*.{ts,tsx} cible les fichiers TypeScript et TSX en une seule ligne. {src,lib}/**/*.ts couvre deux dossiers à la fois.
Rules vs CLAUDE.md vs skills : comment choisir
Avec tous ces outils, c’est la question que vous vous posez sûrement. Trois endroits pour mettre des instructions, lequel utiliser ? La réponse :
CLAUDE.md, c’est pour ce qui s’applique à chaque session, peu importe le contexte. Les commandes de build, l’architecture du projet, les interdictions universelles. Gardez-le sous 200 lignes maximum, le moins étant le mieux.
les rules (
.claude/rules/), c’est pour ce qui s’applique à un domaine. Conventions de tests, patterns d’API, règles de sécurité pour les fichiers sensibles. Sans frontmatter, elles se chargent à chaque session. Avecpaths:, uniquement quand Claude travaille sur les fichiers ciblés.les skills concernent ce que Claude n’a pas besoin de connaître en permanence : une procédure de déploiement que vous déclenchez avec
/deploy, un guide de review que vous invoquez à la demande. Les skills ne consomment presque rien en contexte tant qu’elles ne sont pas appelées.
En pratique, sur mes projets, cela donne un CLAUDE.md de 40 lignes, 5 fichiers de rules ciblés par chemins, 4 ou 5 skills pour les workflows manuels et quelques agents.
La migration en pratique
Pour que ce soit concret, voici ce que donnerait le passage d’un CLAUDE.md (volontairement simplifié) monolithique à une architecture modulaire :
Avant (un CLAUDE.md de 400 lignes) :
# Mon Projet
## Commandes
- Build : pnpm build
- Tests : pnpm test
## Conventions API
- Valider les inputs avec Zod
- Retourner des erreurs consistantes
...
## Patterns React
- Composants fonctionnels uniquement
- Extraire la logique dans des hooks custom
...
## Règles de tests
- Mocker les services externes
...Après (un CLAUDE.md de 30 lignes + des rules ciblées) :
# CLAUDE.md (ce qui reste)
## Commandes
- Build : pnpm build
- Tests : pnpm test
- Lint : pnpm lint
## Architecture
- Monorepo pnpm workspaces
- Frontend dans apps/web, API dans apps/apiEt la structure de tout ceci :
.claude/rules/
├── api-guidelines.md # avec paths: src/api/**/*
├── react-patterns.md # avec paths: src/components/**/*
├── testing-rules.md # avec paths: **/*.test.*
└── security.md # avec paths: src/auth/**/* + src/payments/**/*Le CLAUDE.md ne garde que ce qui est universel. Les instructions techniques vivent dans des rules ciblées qui ne reçoivent la priorité élevée que quand c’est pertinent.
Deux astuces bonus
Les rules supportent les liens symboliques. Si vous avez des conventions partagées entre plusieurs projets (TypeScript, sécurité), stockez-les dans un dossier commun et linkez-les :
ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.mdEt vous pouvez créer des rules personnelles dans ~/.claude/rules/. Elles s’appliquent à tous vos projets, sur votre machine uniquement. Vos préférences de formatage, vos raccourcis de workflow… Les rules utilisateur (globales) se chargent avant les rules projet, donc le projet a toujours le dernier mot en cas de conflit.
Que faire à partir de maintenant ?
Ouvrez votre CLAUDE.md. Repérez le bloc d’instructions le plus long, celui qui concerne un domaine précis. Coupez-le, collez-le dans .claude/rules/nom-du-domaine.md. Ajoutez un frontmatter paths: si ces règles ne concernent que certains fichiers. Relancez Claude Code.
Si cette édition vous a été utile, transférez-la à un collègue qui a un CLAUDE.md de 400 lignes, il vous remerciera et moi aussi !