Maîtriser le dossier .claude : le guide complet pour configurer Claude Code comme un pro
Ce qu'on va obtenir
À la fin de ce tutoriel, vous saurez structurer le dossier .claude de Claude Code pour que l'outil adopte des comportements cohérents et reproductibles dans votre projet — que vous travailliez seul ou en équipe. On couvre CLAUDE.md, les règles modulaires, les préférences personnelles, et les Hooks. Plus de "Claude qui ignore vos conventions de code" après ça.
Prérequis
- Claude Code installé et fonctionnel (
claudedisponible en ligne de commande) - Un projet existant avec un répertoire racine clair
- Accès en écriture au répertoire du projet et à votre home directory (
~) - Notions de base en YAML (pour le path-scoping des règles)
Étape 1 : Comprendre les deux répertoires .claude
Avant de toucher quoi que ce soit, il faut lever une ambiguïté que la documentation officielle ne rend pas assez visible : il existe deux répertoires .claude distincts, avec des rôles différents.
~/.claude/ ← global, personnel, jamais commité
CLAUDE.md ← préférences qui s'appliquent à tous vos projets
settings.json ← configuration machine-locale
monprojet/
.claude/ ← projet, partagé via git avec l'équipe
CLAUDE.md ← règles du projet
rules/ ← règles modulaires par domaine
commands/ ← commandes personnalisées
Pourquoi cette distinction compte : le dossier au niveau projet se commite en git. Toute l'équipe hérite des mêmes règles, des mêmes commandes, des mêmes politiques de permissions. Le dossier global ~/.claude/ contient vos préférences personnelles et l'historique de session — ça ne sort jamais de votre machine.
Pour vérifier que Claude Code reconnaît bien votre configuration :
# Depuis la racine de votre projet
ls -la .claude/
ls -la ~/.claude/
Étape 2 : Créer un CLAUDE.md efficace
CLAUDE.md est le fichier le plus important du système. À chaque démarrage de session, Claude Code le charge directement dans le system prompt et le conserve pour toute la conversation. Ce n'est pas une suggestion — c'est une instruction permanente.
Règle d'or : restez sous 200 lignes. Au-delà, l'adhérence aux instructions de Claude diminue mesuralement. Le contexte se dilue, les règles en bas de fichier sont moins bien suivies.
Ce qui appartient dans CLAUDE.md :
## Build & Test
- `npm run test` — Jest, coverage minimum 80%
- `npm run lint` — ESLint strict, zéro warning toléré
- `npm run build` — TypeScript strict mode activé
## Architecture
- Monorepo avec Turborepo, packages dans /packages
- Chaque package a son propre tsconfig.json
## Conventions critiques
- Jamais de `console.log` pour les erreurs : utiliser `logger` de @monorepo/logger
- Les variables d'environnement passent exclusivement par `src/config/env.ts`
- Nommage des fichiers : kebab-case pour les modules, PascalCase pour les composants React
## Gotchas TypeScript
- `strict: true` dans tsconfig — les variables non utilisées sont des erreurs de compilation
- Les types externes vont dans `src/types/`, jamais inline dans les composants
Ce qui n'appartient pas dans CLAUDE.md :
- La documentation complète de votre API (linkez-la, ne la copiez pas)
- Les longs paragraphes théoriques sur votre architecture
- Ce qui est déjà enforced par ESLint ou Prettier
Pour vérifier que Claude lit bien votre fichier, démarrez une session et demandez-lui : "Quelle commande dois-je utiliser pour lancer les tests ?". Il doit répondre sans hésitation avec ce que vous avez écrit.
Étape 3 : Ajouter CLAUDE.local.md pour vos préférences personnelles
Vous préférez un test runner différent de celui de l'équipe ? Vous voulez que Claude ouvre toujours les fichiers dans un ordre particulier ? Ces préférences ne doivent pas polluer la config partagée.
# À la racine du projet
touch CLAUDE.local.md
# Préférences personnelles — ne pas commiter
- Quand tu génères des tests, utilise `describe/it` plutôt que `test()`
- Toujours afficher le chemin complet des fichiers dans tes réponses
- Je préfère les arrow functions aux function declarations
Claude Code gitignore automatiquement CLAUDE.local.md. Vous n'avez rien à configurer. Le fichier est lu en parallèle de CLAUDE.md et les deux sets d'instructions sont combinés.
Pour confirmer :
cat .gitignore | grep local
# Vous devriez voir CLAUDE.local.md ou *.local.md
Étape 4 : Modulariser avec .claude/rules/
Quand une équipe grandit, CLAUDE.md devient vite un fourre-tout de 300 lignes que personne ne maintient. La solution : le dossier .claude/rules/.
mkdir -p .claude/rules
Chaque fichier Markdown dans ce dossier est chargé automatiquement aux côtés de CLAUDE.md. Vous découpez les instructions par domaine :
.claude/rules/
api-conventions.md ← conventions REST, format des réponses JSON
testing-standards.md ← couverture, mocking, naming des tests
security-rules.md ← ce que Claude ne doit jamais faire (exec shell, etc.)
frontend-patterns.md ← composants React, gestion du state
Le path-scoping via frontmatter YAML est la fonctionnalité la plus puissante ici. Une règle peut ne se charger que lorsque Claude travaille sur des fichiers correspondant à un pattern :
---
paths:
- "src/api/**"
- "src/routes/**"
---
## Conventions API
- Toutes les routes retournent `{ data, error, meta }`
- Les codes HTTP suivent strictement RFC 7231
- Jamais de 200 avec un body d'erreur
Cette règle ne consomme du contexte que quand Claude édite des fichiers dans src/api/ ou src/routes/. Pour les fichiers frontend, elle n'est pas chargée. C'est crucial pour préserver le contexte disponible.
Étape 5 : Comprendre la différence entre instructions et Hooks
C'est la distinction la plus importante pour les équipes en production.
Les instructions dans CLAUDE.md sont probabilistes. Claude les suit en général, mais ce sont des suggestions dans un système de génération de texte. Dans 95% des cas, ça marche. Mais pas à 100%.
Les Hooks sont des event handlers shell qui s'exécutent de façon déterministe à des points précis du workflow. Quand Claude termine d'écrire un fichier, avant qu'il exécute une commande shell, après qu'il génère du code — vous pouvez brancher des scripts à ces moments-là.
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npm run lint -- --fix ${file}"
}
]
}
]
}
}
Avec cette configuration, chaque fois que Claude écrit un fichier, ESLint s'exécute automatiquement. Pas "si Claude pense à le faire" — systématiquement.
Les Hooks sont la réponse à la question "comment s'assurer que Claude respecte toujours X ?" quand X est non-négociable.
Le piège classique
Écrire CLAUDE.md comme une documentation, pas comme des instructions.
La plupart des gens rédigent des paragraphes explicatifs : "Notre projet utilise une architecture microservices parce que nous avons besoin de scalabilité indépendante par domaine métier..."
Claude n'a pas besoin du contexte historique. Il a besoin de savoir quoi faire.
Mauvais :
Nous avons choisi TypeScript strict mode après plusieurs incidents de production
liés à des types implicites. Cette décision a été prise en Q3 2023 et s'applique
à l'ensemble du monorepo depuis la migration de janvier 2024.
Bon :
- TypeScript strict mode activé — les `any` implicites sont des erreurs de build
Même règle pour la longueur : si vous dépassez 200 lignes, coupez. Déplacez les règles dans .claude/rules/ avec du path-scoping. Le contexte de Claude est une ressource limitée — ne la gaspillez pas.
Pour aller plus loin
Configuration globale pour vos standards perso : créez ~/.claude/CLAUDE.md avec vos préférences qui s'appliquent à tous vos projets (langue de réponse préférée, style de commentaires, etc.).
Commandes personnalisées dans .claude/commands/ : Claude Code supporte des commandes slash personnalisées définies en Markdown. Utile pour des workflows répétitifs comme "génère un composant avec ses tests et son story Storybook".
Versionner la config dès le début : committez .claude/ dès le premier jour du projet. C'est aussi important que votre .eslintrc ou votre tsconfig.json — c'est la configuration de votre assistant de développement.
Tester vos règles : après chaque modification de CLAUDE.md, démarrez une nouvelle session (les instructions sont chargées au démarrage) et demandez explicitement à Claude de vous expliquer les règles du projet. C'est le moyen le plus rapide de vérifier qu'il a bien tout lu.
Sources
- Guide original d'Akshay Pachaar sur X — anatomie complète du dossier
.claude - Documentation officielle Claude Code — Anthropic — référence sur les Hooks, permissions et commandes
- Claude Code sur GitHub — code source et issues pour les cas edge
