La plupart des utilisateurs de Claude Code savent
.claude/
qu’il existe, mais ne l’ont jamais vraiment ouvert. L’ingénieur en IA Akshay a récemment préparé un guide complet, expliquant la fonction de chaque fichier dans ce dossier, ainsi que comment configurer Claude pour qu’il fonctionne exactement selon vos préférences.
Deux dossiers, pas un
Il faut d’abord clarifier une idée reçue courante :
Le dossier .claude/
n’est pas unique, il en existe deux.
Au niveau du projet (votre projet/.claude/) : stocke les réglages partagés par l’équipe, soumis à Git, pour que tout le monde suive les mêmes règles et commandes.
Au niveau global (~/.claude/) : préférences personnelles et réglages inter-projets, affectant uniquement votre machine.
CLAUDE.md : un fichier crucial
À chaque démarrage d’une session Claude Code, Claude lit en premier lieu
CLAUDE.md
, et l’intègre dans le prompt système (system prompt), en respectant en permanence ses instructions tout au long de la dialogue.
Ce qu’il faut y écrire :
Les commandes de build, test, lint (ex : npm run test)
Les décisions architecturales importantes
Les précautions non évidentes (par exemple, « Mode strict TypeScript activé, variables non utilisées généreront une erreur »)
Les conventions de nommage, le style de gestion des erreurs
Ce qu’il ne faut pas y mettre : règles de linter, documents complets, explications théoriques longues.
Akshay recommande de limiter CLAUDE.md à 200 lignes — au-delà, la conformité de Claude aux instructions diminue en réalité, car cela consomme trop de contexte.
Dossier rules/ : commandes modulaires, idéal pour l’expansion en équipe
Lorsque CLAUDE.md devient trop volumineux,
.claude/rules/
constitue la solution. Chaque fichier Markdown représente un point d’attention, par exemple code-style.md, testing.md, api-conventions.md. Claude lira automatiquement tous ces fichiers.
Ce qui est encore plus puissant, c’est la « règle de portée par chemin » : en ajoutant des métadonnées YAML en tête de fichier de règle, vous pouvez faire en sorte que ces règles ne s’appliquent qu’aux fichiers dans certains chemins, évitant ainsi que des règles non pertinentes encombrent le contexte.
Dossier commands/ : commandes slash personnalisées
Chaque fichier Markdown placé dans
.claude/commands/
devient une commande slash. review.md correspond à /project:review, fix-issue.md à /project:fix-issue.
La fonctionnalité la plus pratique consiste à utiliser
!
dans le fichier de commande pour exécuter une commande shell et injecter sa sortie — par exemple, récupérer automatiquement un git diff pour l’injecter dans le prompt, permettant à Claude de « voir » réellement vos changements de code. Les commandes personnelles dans ~/.claude/commands/ sont accessibles dans tous les projets.
skills/ et agents/ : déclencheurs actifs vs. sous-agents dédiés
La différence principale entre Skills et agents réside dans leur déclenchement :
Skills : Claude décide automatiquement, en fonction de la conversation, s’il doit appeler une compétence, sans que vous ayez besoin de taper une commande. Chaque skill possède son propre dossier et un SKILL.md, avec éventuellement des fichiers de support.
Agents : définissent des sous-personnalités spécialisées, avec leur propre prompt système, permissions d’outils et réglages de modèle. En cas de tâches complexes, Claude peut lancer un contexte isolé pour que l’agent exécute, évitant de saturer la fenêtre principale avec trop de tokens.
Dans les agents,
tools
permet de limiter leur champ d’action — par exemple, un agent de sécurité n’a besoin que de permissions en lecture, pas d’écriture. Le champ model permet de choisir un modèle plus léger pour des tâches ciblées, réduisant les coûts.
settings.json : listes blanches et noires de permissions
Le fichier
.claude/settings.json
contrôle ce que Claude est autorisé ou interdit à faire :
allow : liste blanche — actions autorisées sans confirmation (ex : npm run *, git *)
deny : liste noire — actions totalement bloquées (ex : rm -rf *, lecture de .env)
Les opérations non listées seront demandées à l’utilisateur pour confirmation.
Les réglages personnels peuvent être dans
.claude/settings.local.json
, qui est automatiquement ignoré par git et ne sera pas soumis au dépôt.
Par où commencer ?
Selon Akshay, la démarche pratique recommandée est : d’abord exécuter
/init
pour générer un initial CLAUDE.md, ajouter un fichier settings.json avec les permissions de base, puis créer une ou deux commandes personnalisées les plus utilisées — le reste pouvant être ajouté progressivement selon votre usage.
L’idée clé est :
Le dossier .claude/
est votre protocole pour dire à Claude « qui vous êtes, quel est le projet, quelles règles suivre ». Plus c’est clair, moins vous passerez de temps à corriger Claude.
Cet article explique en détail : Comprendre le dossier .claude/ : le centre de contrôle de Claude Code, avec une analyse complète de CLAUDE.md, des commandes, compétences et permissions, publié initialement sur ABMedia.
