Le dossier .claude/ expliqué : la vraie carte d'un projet Claude Code en 2026

Vous avez probablement déjà un dossier .claude/ à la racine d'un projet, posé là par /init ou par un coéquipier, et vous n'êtes pas tout à fait sûr de ce qui s'y passe. Trois sous-dossiers, un fichier JSON, et une vague intuition que « c'est là où on configure Claude Code ». La réalité est plus précise, et la maîtriser change radicalement votre quotidien avec l'outil. Ce dossier n'est pas un détail de configuration : c'est le centre de contrôle que Claude lit en priorité, et chaque fichier qu'on y place a un rôle précis.

Cet article reprend la structure visualisée ci-dessous et l'explique fichier par fichier, avec les pièges classiques observés sur le terrain.

votre-projet/
├── CLAUDE.md            instructions du projet, relu à chaque session, < 200 lignes
├── .mcp.json            serveurs MCP partagés avec l'équipe
└── .claude/             le centre de contrôle (Claude Code lit tout ici en priorité)
    ├── skills/          Claude invoque automatiquement le bon SKILL.md selon la tâche
    ├── agents/          sous-agents avec fenêtre de contexte isolée, outils restreints, modèle dédié
    └── settings.json    permissions (allow/deny list), hooks registry, configuration du modèle

Le problème : pourquoi votre .claude/ ne sert à rien

Voilà ce qu'on observe sur la majorité des projets qui ont adopté Claude Code sans creuser : un CLAUDE.md de 300 lignes, un dossier .claude/ avec deux ou trois fichiers laissés par /init, et une équipe qui se demande pourquoi Claude oublie systématiquement de lancer les tests avant de proposer un commit. Le diagnostic est presque toujours le même : tout a été mis dans CLAUDE.md, rien n'a été déporté vers les bons fichiers spécialisés.

Or chaque type de configuration a son endroit. Les skills servent à enseigner des procédures spécialisées sans alourdir le contexte. Les agents servent à isoler des tâches lourdes dans une fenêtre séparée. Les settings servent au déterministe : permissions strictes, hooks qui s'exécutent quoi qu'il arrive, modèle imposé. Mélanger tout ça dans CLAUDE.md, c'est s'exposer aux trois maux classiques : adhérence qui chute parce que le fichier est trop long, comportements qui dérivent parce qu'on a confondu instruction et règle absolue, et coût en tokens qui explose à chaque tour.

Si vous n'avez pas encore lu mon guide complet sur CLAUDE.md, c'est le bon préalable. Cet article-ci complète l'ensemble en se concentrant sur ce qui se passe à côté du CLAUDE.md, dans le dossier .claude/ et ses voisins immédiats.

CLAUDE.md à la racine : le briefing court qui marche

Avant de plonger dans .claude/, un rappel rapide. CLAUDE.md vit à la racine du projet, pas dans le dossier .claude/. Cette distinction n'est pas anecdotique : Claude Code charge ce fichier automatiquement au début de chaque session et l'injecte dans le prompt système. Il est lu à chaque tour, chaque ligne paye un coût en tokens. La règle de bon sens est de viser moins de 200 lignes, idéalement entre 30 et 100.

On y met les commandes shell quotidiennes, les choix d'architecture qui orientent où poser quoi, les règles non négociables (sécurité, RGPD, déploiement), et les anti-patterns que vous avez payés cher. On n'y met pas la doc de l'API, l'historique du projet, ou les règles de formatage que Prettier et ESLint gèrent déjà. Pour les exemples concrets ligne par ligne sur Django, NestJS et Next.js, le guide dédié à CLAUDE.md les détaille.

.mcp.json : les serveurs MCP partagés avec l'équipe

Le fichier .mcp.json à la racine déclare les serveurs Model Context Protocol que Claude peut utiliser dans ce projet. Le but est simple : versionner la liste des outils MCP partagés, pour que tout le monde dans l'équipe ait accès aux mêmes intégrations sans configuration manuelle.

Voici à quoi ressemble un fichier minimal pour un projet Django avec Stripe en test et un Postgres en lecture seule pour l'analyse :

{
  "mcpServers": {
    "stripe-test": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp", "--tools=all", "--api-key=${STRIPE_TEST_KEY}"]
    },
    "postgres-readonly": {
      "command": "uvx",
      "args": ["postgres-mcp", "--read-only"],
      "env": { "DATABASE_URL": "${READONLY_DATABASE_URL}" }
    }
  }
}

Trois choses à retenir. D'abord, ce fichier est versionné dans Git, mais les secrets viennent par variables d'environnement. On ne met jamais de clé API en clair dedans. Ensuite, à la première session, Claude Code demande votre approbation explicite pour activer chaque serveur déclaré. C'est une protection contre l'exécution arbitraire de code venu d'un fork malveillant. Enfin, vous avez aussi un .mcp.json au niveau utilisateur, dans ~/.claude/, pour vos serveurs personnels qui vous suivent partout.

.claude/skills/ : les procédures spécialisées

C'est probablement la partie qui change le plus la vie quand on l'adopte vraiment. Un skill est un dossier qui contient un fichier SKILL.md et, optionnellement, des scripts d'aide ou des fichiers de référence. Le frontmatter YAML en tête de SKILL.md décrit quand le skill doit s'activer, et le contenu n'est chargé dans le contexte que lorsque Claude l'invoque. C'est exactement ce qu'on cherche : avoir une bibliothèque de procédures sans payer le coût en tokens à chaque tour.

Concrètement, le dossier .claude/skills/ ressemble à ça sur un projet réel :

.claude/skills/
├── release-checklist/
│   └── SKILL.md
├── debug-celery/
│   ├── SKILL.md
│   └── scripts/
│       └── inspect-queue.sh
└── audit-rgpd/
    ├── SKILL.md
    └── reference/
        └── checklist-cnil.md

Chaque SKILL.md commence par un frontmatter qui détermine le mode d'invocation :

---
name: release-checklist
description: Procédure de release : tag git, build Docker, déploiement staging puis prod, smoke tests
trigger: model
---

## Étapes

1. Vérifier que `make test` est vert sur la branche main
2. Mettre à jour CHANGELOG.md avec la version cible
3. Créer le tag git `vX.Y.Z` et le pousser
4. Lancer le pipeline release sur GitHub Actions
5. Smoke tests sur staging avant promotion en prod
...

Le champ trigger est essentiel. Avec model, Claude décide d'invoquer le skill quand il juge que la description colle à votre demande. Avec manual, vous l'appelez vous-même via une slash command. Avec both, les deux modes coexistent. La description doit être précise, parce que c'est elle que Claude lit pour décider s'il invoque ce skill ou pas.

L'erreur fréquente, c'est de transformer chaque petite préférence en skill. Un skill se justifie quand vous avez une procédure de plusieurs étapes, qui se répète, et dont vous ne voulez pas refaire le briefing à chaque fois. Pour une simple convention de style, restez dans CLAUDE.md ou dans .claude/rules/. Pour des routines complexes (release, audit, migration de données, debug d'un module particulier), les skills sont taillés pour ça.

.claude/agents/ : les sous-agents qui sauvent votre contexte

Le dossier .claude/agents/ contient les définitions de vos sous-agents personnalisés. Un sous-agent est un Claude isolé, lancé depuis votre session principale, avec sa propre fenêtre de contexte, son propre prompt système, ses propres outils autorisés, et même son propre modèle si vous le souhaitez. C'est le mécanisme qui permet de déléguer une tâche lourde sans polluer le contexte principal.

Le cas d'usage typique : vous travaillez sur une feature, et il faut auditer 80 fichiers d'un module legacy pour repérer les usages d'une API dépréciée. Si Claude fait ça dans la session principale, vous récupérez 80 lectures de fichiers dans votre fenêtre de contexte, et tous les tours suivants en paient le prix. Avec un sous-agent dédié, vous lancez la mission, le sous-agent fait son boulot dans son propre espace, et il vous renvoie juste un résumé. Votre contexte principal reste propre.

Voici une définition d'agent type, dans .claude/agents/code-auditor.md :

---
name: code-auditor
description: Audite des fichiers en lecture seule pour repérer dette technique, usages dépréciés, violations de conventions. Renvoie un rapport synthétique.
tools: Read, Grep, Glob
model: sonnet
---

Tu es un auditeur de code. Tu lis des fichiers, tu repères des problèmes,
tu produis un rapport structuré. Tu ne modifies jamais rien. Tu ne fais
pas de suggestions de refactoring détaillées : ton job est le diagnostic,
pas le traitement.

Format de sortie attendu :
- Liste des fichiers analysés
- Problèmes critiques (sécurité, données)
- Dette technique notable
- Score global sur 10

Trois éléments structurent un agent. Le champ tools liste les outils auxquels l'agent a accès, et restreindre cette liste est très utile. Un agent d'audit n'a pas besoin de Write ni de Bash. Le champ model permet de choisir un modèle plus léger pour les tâches simples ou plus puissant pour les tâches lourdes. Un agent de revue de PR sur Opus 4.7 et un agent de génération de docstrings sur Haiku 4.5, c'est cohérent et économique. Le corps du fichier est le prompt système qui définit le comportement.

L'usage en pratique : Claude principal détecte qu'une tâche colle à un agent (par la description) et propose de la déléguer. Vous pouvez aussi forcer l'invocation explicitement. Et plusieurs agents peuvent tourner en parallèle, ce qui transforme certaines analyses qui prenaient une heure en quelques minutes. Cette mécanique de délégation est évoquée plus largement dans le guide pratique Claude Code 2026.

.claude/settings.json : permissions, hooks, configuration

Le fichier settings.json est l'endroit où vous passez du déclaratif souple (CLAUDE.md, skills) au contractuel strict. C'est lui qui contient ce qui doit être appliqué quoi qu'il arrive : les permissions, les hooks, le modèle imposé, certains paramètres d'environnement.

Une version réelle ressemble à ça :

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Bash(make test:*)",
      "Bash(make lint:*)",
      "Bash(pnpm test:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)",
      "Read(.env*)",
      "WebFetch(domain:internal.example.com)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "make lint --quiet || true" }
        ]
      }
    ]
  },
  "model": "claude-sonnet-4-6",
  "env": {
    "PYTHONDONTWRITEBYTECODE": "1"
  }
}

La partie permissions est la plus rentable au quotidien. La allow liste ce qui est auto-approuvé, sans demander à chaque fois. La deny liste ce qui est bloqué, avec une priorité absolue sur l'allow. Approuver chaque commande à la main est insupportable, mais tout auto-approuver est dangereux. La bonne configuration est un allow restrictif sur les commandes que vous avez vraiment besoin de voir tourner souvent (tests, lint, status git), et un deny strict sur tout ce qui peut faire mal (rm récursif, push force, accès aux fichiers .env).

La partie hooks apporte le déterminisme. Un hook est un bout de code qui s'exécute autour d'événements du cycle de vie de Claude Code. Avant un commit, lancer le linter. Après chaque écriture de fichier, vérifier la conformité au guide de style. Refuser tout fetch d'une URL interdite. Les hooks ne demandent pas l'avis du modèle, ils s'exécutent. Les événements disponibles incluent PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, et plusieurs autres.

Le champ model permet de figer le modèle pour ce projet. Pratique quand vous voulez que toute l'équipe travaille sur la même base, ou pour rester sur Sonnet 4.6 sur un projet routinier afin d'économiser le quota Opus.

À côté du settings.json, vous avez aussi un settings.local.json qui n'est pas versionné (ajoutez-le au .gitignore) et qui contient vos préférences personnelles. C'est l'endroit pour les permissions plus larges que vous vous accordez à titre individuel sans les imposer à l'équipe.

La hiérarchie globale et locale

Une question revient sans arrêt : est-ce qu'on a un .claude/ uniquement par projet, ou aussi au niveau utilisateur ? La réponse est : les deux, et ils se complètent.

Au niveau utilisateur, le dossier ~/.claude/ dans votre home contient vos skills personnels (ceux qui vous suivent partout, comme un skill de génération de docstrings ou un audit de sécurité générique), vos agents personnels, vos settings globaux. Au niveau projet, le .claude/ à la racine contient ce qui est partagé avec l'équipe, versionné dans Git.

La règle de précédence est simple : les paramètres locaux et projet l'emportent sur les paramètres utilisateur. Les permissions du projet s'ajoutent aux permissions utilisateur, mais une règle deny au niveau enterprise (politique imposée par l'organisation) écrase toutes les autres. C'est ce qui permet à une boîte de garantir qu'aucun dev ne pourra activer une commande dangereuse, même s'il bidouille son settings.local.json.

Le piège classique : tout mettre dans CLAUDE.md

Maintenant que les rôles sont clairs, voici le test mental qui aide à décider où va une nouvelle règle. Si c'est une convention que Claude doit avoir en tête à chaque tour de chaque session, c'est CLAUDE.md, et il faut que la formulation tienne en deux ou trois lignes. Si c'est une procédure qui ne sert que de temps en temps, c'est un skill. Si c'est une tâche qui doit tourner dans son propre espace de contexte, c'est un agent. Si c'est une règle qui doit être appliquée de force, sans dépendre de la décision du modèle, c'est un hook ou une permission dans settings.json.

Le piège, c'est de tout mettre dans CLAUDE.md parce que c'est le fichier qu'on connaît. On finit avec un fichier de 400 lignes qui n'est plus respecté, et un dossier .claude/ presque vide qui ne sert à rien. Le bon réflexe est de partir d'un CLAUDE.md court et d'ajouter des fichiers spécialisés au fur et à mesure que les besoins apparaissent.

Comment construire son .claude/ progressivement

Plutôt que d'essayer de tout structurer dès le premier jour, voici la progression qui marche en pratique. Première étape, vous lancez /init et vous obtenez un CLAUDE.md de départ. Vous l'élaguez agressivement pour ne garder que ce qui est vraiment spécifique à votre projet. Vous ajoutez à la racine un .mcp.json avec un ou deux serveurs utiles (Postgres en lecture, Stripe en test).

Deuxième étape, vous créez un .claude/settings.json minimal avec une allowlist sur les trois ou quatre commandes que vous validez tout le temps (tests, lint, git status), et une denylist solide sur les commandes destructrices. Cela seul change la qualité de vie sur les sessions longues.

Troisième étape, après quelques semaines, vous identifiez les deux ou trois procédures que vous expliquez en boucle à Claude. Vous les transformez en skills dans .claude/skills/, avec un trigger model et une description précise.

Quatrième étape, quand une tâche commence à polluer systématiquement votre contexte (audits, explorations, recherches longues), vous la déplacez dans un agent dédié dans .claude/agents/ avec des outils restreints et le bon modèle.

Cinquième étape, à ce stade, votre .claude/ est devenu une vraie carte du projet. C'est aussi le moment où packager le tout en plugin pour distribution interne devient pertinent, surtout si l'équipe a plusieurs dépôts qui partagent les mêmes conventions. Mais ça, c'est un autre sujet.

FAQ

Faut-il versionner tout le dossier .claude/ dans Git ?

Oui pour ce qui est partagé avec l'équipe : .claude/skills/, .claude/agents/, et .claude/settings.json. Non pour .claude/settings.local.json qui contient vos préférences personnelles et doit aller dans le .gitignore. La logique : ce qui est règle d'équipe se versionne, ce qui est confort individuel reste local.

Comment Claude choisit-il quel skill activer ?

Claude lit la description du frontmatter de chaque SKILL.md dont le trigger est model ou both. Quand votre demande matche cette description, Claude charge le contenu du skill dans son contexte avant de répondre. La qualité de cette description est donc cruciale : trop vague, elle se déclenche trop souvent ; trop spécifique, elle est ignorée. Visez une phrase claire qui décrit la tâche cible et ses conditions d'application.

Quelle différence concrète entre un skill et un agent ?

Un skill est une procédure que Claude exécute dans la session principale, en chargeant juste le contenu du SKILL.md dans son contexte. Un agent est un Claude séparé, lancé dans son propre espace, avec son propre contexte, ses propres outils et son propre modèle. Si la tâche tient en quelques étapes et n'a pas besoin d'isoler le contexte, c'est un skill. Si la tâche est lourde (lire 50 fichiers, faire des recherches longues), c'est un agent. Et un skill peut très bien déléguer son exécution à un agent, ce qui combine les deux mécanismes.

Les hooks remplacent-ils les permissions ?

Non, les deux mécanismes sont complémentaires. Les permissions filtrent en amont les outils que Claude peut invoquer (allow, ask, deny). Les hooks s'exécutent autour d'événements du cycle de vie : avant un appel d'outil, après une écriture de fichier, à la soumission d'un prompt. Une permission deny bloque l'action ; un hook PreToolUse peut bloquer aussi, mais peut surtout transformer, logger, ou déclencher autre chose en parallèle. Pour interdire rm -rf, une permission deny suffit. Pour lancer un linter à chaque écriture, c'est un hook PostToolUse.

Mon CLAUDE.md fait 400 lignes, par où commencer ?

Repérez d'abord les sections qui décrivent des procédures (release, debug d'un module, audit RGPD) et déplacez-les en skills dans .claude/skills/. Repérez ensuite les règles dures (pas de push force, pas de lecture des .env) et déplacez-les en permissions dans settings.json. Supprimez tout ce qui est règle de formatage gérée par Prettier ou ESLint. Ce qui reste devrait tenir sous 100 lignes.

Peut-on partager skills et agents entre projets sans tout dupliquer ?

Oui, plusieurs options. La plus simple : mettre les skills et agents transversaux dans ~/.claude/, ils seront disponibles sur tous vos projets sans dépendre du repo. La plus structurée : packager le tout en plugin, le publier sur une marketplace privée (ou Git), et que chaque projet l'installe explicitement. Pour une équipe sur plusieurs dépôts qui partagent les mêmes conventions, cette deuxième approche évite la dérive de copies divergentes.

Les serveurs MCP de .mcp.json marchent-ils sur n'importe quelle session ?

Oui, dès que vous lancez Claude Code à la racine du projet ou dans un sous-dossier. À la première session, l'outil détecte le fichier et vous demande votre approbation pour chaque serveur déclaré. Cette validation reste en mémoire pour les sessions suivantes. Si quelqu'un modifie le fichier en ajoutant un nouveau serveur, l'approbation sera redemandée. C'est une protection contre l'ajout discret d'un serveur malveillant via une PR.

Comment debugger un .claude/ qui se comporte bizarrement ?

La commande /memory liste tous les fichiers de contexte chargés dans la session courante avec leur précédence. /permissions affiche les règles d'autorisation actives. Pour les hooks, /hooks liste ceux qui sont enregistrés. Et Ctrl-R en mode interactif affiche l'intégralité du contexte tel que Claude le voit, ce qui permet de repérer immédiatement un fichier qui n'est pas chargé comme prévu, ou au contraire un skill qui s'invite alors qu'il ne devrait pas.