Claude Code : CLAUDE.md, rules, settings, hooks, skills — quand utiliser quoi ?

Vous avez posé CLAUDE.md, ajouté un settings.json, écrit une rule, créé un hook, peut-être un skill. À chaque nouvelle règle, la même question revient : où la mettre ? Ce guide d’orientation vous donne une règle simple par brique, avec des exemples concrets sur lab-claude. Objectif : ne plus hésiter, et surtout ne pas dupliquer la même règle dans trois fichiers différents.

Ce que vous allez apprendre

• Distinguer fait, règle, procédure, automatisation et permission
• Choisir entre CLAUDE.md, CLAUDE.local.md, rules, settings.json, hooks, skills
• Placer une règle au bon niveau (projet, perso, zone de code)
• Reconnaître les mauvais mélanges fréquents

Dans quel contexte utiliser ce guide ?

• Vous ajoutez une nouvelle règle à votre projet et vous hésitez
• Votre CLAUDE.md commence à déborder de procédures et de permissions
• Vous retrouvez la même règle dans deux endroits différents
• Un contributeur demande “pourquoi cette règle est ici et pas là ?”

Les 6 briques en une ligne

Brique	Rôle	Exemple sur lab-claude
CLAUDE.md	Fait global du projet partagé à l’équipe	”On utilise FastAPI, uv, ruff, pytest”
CLAUDE.local.md	Préférence perso non partagée	”J’édite avec Helix, format imposé à ruff format”
.claude/rules/*.md	Règle ciblée par zone de code	”Les tests utilisent TestClient”
.claude/settings.json	Permission sur outils et commandes	allow: Bash(uv run pytest:*)
.claude/hooks	Automatisation autour des événements	Lancer ruff après chaque Edit
.claude/skills/<nom>/SKILL.md	Procédure invocable par /nom	/valider enchaîne ruff + pytest et résume
.mcp.json / serveurs MCP	Outils externes hors du dépôt	fetch pour la doc FastAPI, github pour les issues

Glissez pour voir

Retenez cette distinction en 5 mots : fait, règle, permission, automatisation, procédure. Chaque brique en couvre exactement une.

L’arbre de décision en 4 questions

1. Est-ce un fait vrai tout le temps pour ce projet ? → CLAUDE.md (ou CLAUDE.local.md si ça ne concerne que vous)

2. Est-ce une règle qui ne vaut que dans une zone (tests, API, infra) ? → .claude/rules/<zone>.md avec paths: dans le frontmatter

3. Est-ce une commande à autoriser, refuser ou soumettre à confirmation ? → .claude/settings.json via allow / deny / ask

4. Est-ce une action déclenchée par un événement ou invocable à la demande ?

   • Automatique (après Edit, avant Stop…) → hook
   • À la demande (/valider, /prep-pr…) → skill

Si la réponse est oui à plusieurs questions, c’est que vous mélangez deux choses. Découpez.

Brique par brique

CLAUDE.md — les faits stables du projet

À mettre :

• Stack, rôle du projet
• Commandes utiles (uv run ruff check ., uv run pytest -q)
• Conventions majeures (annotations de type, style de tests)
• Garde-fous simples (“ne pas modifier pyproject.toml sans confirmation”)

À ne pas mettre :

• Procédures numérotées (“étape 1, étape 2, étape 3”) → skill
• Règles qui ne concernent qu’un sous-dossier → rule
• Permissions shell → settings.json
• Préférences perso → CLAUDE.local.md

Règle de taille : moins de ~80 lignes actives. Détails dans configurer CLAUDE.md.

CLAUDE.local.md — vos préférences à vous

À mettre :

• Style de résumés préféré
• Rappels liés à votre machine ou à votre branche en cours
• Conventions en test avant promotion dans CLAUDE.md

À ne pas mettre :

• Règles d’équipe (→ CLAUDE.md)
• Secrets (→ variables d’environnement)

Ajoutez-le au .gitignore.

.claude/rules/*.md — règles par zone

À mettre :

• Une règle qui ne s’applique qu’à tests/**/*.py ou app/routes/**/*.py
• Un frontmatter paths: pour que la règle ne soit chargée que quand Claude touche la zone

Exemple sur lab-claude (.claude/rules/tests.md) :

---
paths:
  - tests/**/*.py
---

# Règles spécifiques aux tests

- Utiliser `fastapi.testclient.TestClient`
- Un test = une assertion principale
- Pas de mock sur les fonctions du projet

Détails dans rules ciblées.

.claude/settings.json — permissions et environnement

À mettre :

• allow, deny, ask sur les outils (Bash, Read, Edit, WebFetch)
• Variables d’environnement injectées (env)
• Attribution (includeCoAuthoredBy)

À ne pas mettre :

• Des règles de comportement (“toujours résumer en 5 points”) → CLAUDE.md
• Des procédures → skill

Règle : deny protège, allow accélère, ask garde la main. Détails dans settings.json avancé.

.claude/hooks — automatiser des événements

À mettre :

• Validation systématique après Edit|Write (ex : ruff check)
• Blocage de commandes destructives avant Bash
• Rappel de commande en Stop

Exemple typique : lancer uv run ruff check . après chaque modification de fichier Python.

À ne pas mettre :

• Des actions que vous devez pouvoir déclencher à la demande → skill
• Des permissions → settings.json (avec ask ou deny)

Détails dans hooks Claude Code.

.claude/skills/<nom>/SKILL.md — procédures invocables

À mettre :

• Une procédure que vous tapez souvent à la main (validation, préparation de PR, revue)
• Un SKILL.md avec des étapes en impératif
• disable-model-invocation: true si le skill change l’état du projet

À ne pas mettre :

• Une règle générale (→ CLAUDE.md ou rule)
• Une action qui doit se déclencher seule à un événement (→ hook)

Détails dans skills Claude Code.

La même intention, rangée dans la bonne case

Pour ancrer le réflexe, voici 7 intentions courantes sur lab-claude, chacune dans sa bonne case :

Intention	Bonne brique
”On utilise FastAPI, pytest, ruff”	CLAUDE.md
”Les tests utilisent TestClient”	.claude/rules/tests.md (paths: tests/**/*.py)
“Je préfère des résumés en 3 points”	CLAUDE.local.md
”Autoriser uv run pytest * sans prompt”	.claude/settings.json (allow)
“Refuser rm -rf * toujours”	.claude/settings.json (deny)
“Lancer ruff après chaque Edit”	hook PostToolUse sur `Edit
“Commande /valider qui enchaîne ruff + pytest”	skill .claude/skills/valider/SKILL.md

Glissez pour voir

Retenez surtout la distinction la plus piégeuse : hook vs skill. Un hook se déclenche tout seul sur un événement. Un skill attend que vous tapiez /nom.

Ce qu’il ne faut pas mélanger

Les erreurs fréquentes viennent toutes du même schéma : une brique prend le rôle d’une autre.

Mélange à éviter	Symptôme	Correction
Procédure dans CLAUDE.md	Le fichier gonfle, Claude survole	Extraire vers un skill (/valider, /prep-pr)
Règle par zone dans CLAUDE.md	Règles contradictoires selon le dossier	Déplacer vers .claude/rules/<zone>.md avec paths:
Permissions en langage naturel dans CLAUDE.md	Claude redemande à chaque fois	Transformer en allow/deny dans settings.json
Automatisation dans un skill	Claude oublie de le lancer	Passer en hook (PostToolUse)
Préférence perso dans CLAUDE.md partagé	Les autres contributeurs la subissent	Déplacer dans CLAUDE.local.md (gitignore)
Skill déclenché en auto sur action risquée	Déploiement ou commit inattendu	Ajouter disable-model-invocation: true

Glissez pour voir

Exemple de bon découpage sur lab-claude

Voici à quoi ressemble un projet bien rangé :

lab-claude/
├── CLAUDE.md                              # Stack, commandes, conventions globales
├── CLAUDE.local.md                        # Préférences perso (gitignore)
├── .claude/
│   ├── settings.json                      # Permissions d'équipe (allow, deny, ask)
│   ├── settings.local.json                # Permissions perso (gitignore)
│   ├── rules/
│   │   ├── tests.md                       # Règles pour tests/**
│   │   └── routes.md                      # Règles pour app/routes/**
│   ├── hooks/
│   │   └── post-edit-ruff.json            # Lint auto après Edit|Write
│   └── skills/
│       ├── valider/SKILL.md               # /valider : ruff + pytest + résumé
│       └── prep-pr/SKILL.md               # /prep-pr : diff, commits, titre PR

Chaque fichier a un seul rôle. Aucune règle n’est dupliquée. Si demain vous ajoutez une règle, vous savez exactement où la poser.

Le bon test

Avant d’ajouter une règle, posez-vous la question : “si je la supprime de cet endroit, est-ce qu’elle doit aller ailleurs ?” Si oui, vous êtes dans la bonne case. Si non, c’est probablement une redondance à retirer.

Checklist d’orientation

• Je sais distinguer fait, règle, permission, automatisation, procédure
• Aucune procédure numérotée ne traîne dans mon CLAUDE.md
• Les règles spécifiques à une zone sont dans .claude/rules/ avec paths:
• Les permissions sont dans settings.json, pas en langage naturel ailleurs
• Les automatisations sont dans hooks, pas dans les skills
• Les procédures à invoquer sont dans skills, pas dans CLAUDE.md
• Mes préférences perso sont dans CLAUDE.local.md (gitignore)

À retenir

• Une brique = un rôle. Dès que vous avez un doute, découpez.
• CLAUDE.md pour les faits, rules pour les règles ciblées, skills pour les procédures, hooks pour les automatisations, settings.json pour les permissions.
• CLAUDE.local.md et settings.local.json absorbent tout ce qui est perso.
• Un projet bien rangé rend chaque nouvelle règle triviale à placer.

Prochaines étapes

Dépannage avancé Claude Code Diagnostiquer permissions, config, diff trop large et sessions qui dérivent

Workflows concrets Voir les briques combinées sur debug, refactor, test, doc, PR

Claude Code dans VS Code Transposer la même méthode dans l'éditeur

×

📖 Voir la documentation →