Anatomie du dossier .claude : son rôle et pourquoi il déroute
Si vous avez cherché « anatomie du dossier .claude », vous essayez probablement de comprendre ce que fait ce dossier, pourquoi il embrouille les gens, et quelles parties méritent votre attention.
Un fil Reddit de mars 2026 l'a bien résumé. Un développeur ayant eu des problèmes à cause de conventions de placement peu claires a créé une fiche récapitulative couvrant l'arborescence .claude/, les événements de hooks, settings.json, la configuration MCP, la structure des skills et les seuils de gestion de contexte.
La confusion centrale : global vs. niveau projet
La plus grande source de confusion est la différence entre le répertoire global ~/.claude/ et le répertoire au niveau projet .claude/.
Le répertoire global se trouve dans votre dossier personnel et définit un comportement partagé. Le répertoire niveau projet se trouve dans un dépôt spécifique et remplit ou étend la configuration globale.
Conventions de placement
Les skills vont dans .claude/skills/. Chaque skill a son propre répertoire avec un fichier SKILL.md.
Les agents vont dans .claude/agents/, pas en fichiers épars à la racine.
Les paramètres se trouvent dans .claude/settings.json au niveau projet ou ~/.claude/settings.json globalement.
Les hooks sont opérationnels, pas passifs
L'erreur la plus courante est un matcher trop étroit. Un hook PostToolUse qui ne correspond qu'à « Write » rate les modifications faites via « Edit » ou « MultiEdit ».
Les quatre points essentiels
1. Portée — Global vs. niveau projet est la première décision.
2. Conventions de placement — Les skills ont besoin de SKILL.md, les agents vont dans agents/.
3. Contenu vs. orchestration — Skills, agents, paramètres, hooks et MCP ne sont pas des concepts équivalents.
4. Signes de dérive — La documentation évolue rapidement. Si votre configuration cesse de fonctionner, vérifiez si les conventions sous-jacentes ont changé.
Le dossier .claude combine portée, structure et comportement. Une fois ce modèle à trois couches intégré, le dossier cesse de ressembler à un encombrement caché et devient une carte opérationnelle.