Bonnes pratiques des fichiers de règles Claude Code

Pourquoi les fichiers de règles existent

Dès que votre CLAUDE.md dépasse un écran ou deux, tout y entasser cesse de fonctionner. Les règles de sécurité se confondent avec les règles CSS, le modèle survole, et rien n'est bien suivi. Claude Code permet de découper les conventions en fichiers de règles distincts sous .claude/rules/ — un fichier par domaine — pour que chacun reste ciblé et facile à maintenir.

Voyez le CLAUDE.md racine comme la table des matières et les fichiers de règles comme les chapitres.

Un domaine par fichier

Le bon modèle, c'est un fichier par sujet :

.claude/rules/
  testing.md
  security.md
  typescript.md
  databases.md
  nextjs.md
  app_layout_ui.md

Quand vous modifiez les règles de sécurité, vous ne défilez pas devant les conventions de composants. Quand l'agent travaille sur une Server Action, ce sont les règles de sécurité et de TypeScript qui comptent — et elles se lisent clairement parce qu'elles ne sont pas mêlées au reste.

Rendez chaque règle actionnable

Une règle que l'agent ne peut pas appliquer, c'est du bruit. Ancrez chacune à un comportement concret, idéalement avec un exemple de code montrant la mauvaise et la bonne manière :

Flou : « Écrire du code de base de données sécuritaire. »
Actionnable : « Activer RLS sur chaque table. Ne jamais préfixer la clé de rôle de service par NEXT_PUBLIC_. »

Les meilleurs fichiers de règles se lisent comme une liste de vérification, pas comme un essai philosophique.

Utilisez « toujours » et « jamais » pour les non-négociables

Réservez le langage impératif net aux règles qui ne doivent jamais être enfreintes. Ce sont celles qui causent de vrais dégâts quand on les ignore :

Jamais lancer supabase db reset sur une instance contenant des données de pipeline.
Toujours valider les entrées des Server Actions avec Zod avant de les utiliser.
Jamais importer un type réservé au serveur dans un composant client.

Les formulations molles comme « préférer » ou « essayer de » passent au second plan quand la tâche devient difficile. Gardez « jamais » pour ce qui n'est vraiment jamais acceptable.

Montrez le modèle, ne le décrivez pas seulement

Les règles avec un exemple avant/après sont bien mieux suivies que la prose. Un extrait de trois lignes de la bonne forme enseigne la convention plus vite qu'un paragraphe qui l'explique :

// Mauvais — desktop d'abord, interdit
<div className="w-1/3 lg:w-full">

// Bon — mobile d'abord
<div className="w-full md:w-1/2 lg:w-1/3">

L'agent apprend par correspondance de motifs. Donnez-lui le motif.

Gardez-les à jour

Les fichiers de règles dérivent. Une règle qui pointe vers un fichier, un indicateur ou une commande qui n'existe plus est pire que pas de règle — elle envoie l'agent dans une impasse avec assurance. Quand vous renommez un module ou changez un flux de travail, mettez à jour la règle concernée dans le même commit. Traitez le dossier des règles comme du code, pas comme de la documentation qui pourrit dans un coin.

Merci de votre lecture — à bientôt.