Ce qui se trouve dans votre dossier .claude

Votre dossier .claude contient deux types d’éléments bien distincts : des instructions chargées dans le contexte de Claude au démarrage de chaque session (CLAUDE.md, rules/, skills/, agents/), et de la configuration qui régit le comportement de l’outil (settings.json, hooks, serveurs MCP). Ces deux catégories se répartissent entre un répertoire de projet que vous committez et un répertoire ~/.claude situé dans votre dossier personnel, que vous ne committez jamais.

Le dossier a aussi tendance à grossir tout seul. Approuver une demande de permission écrit un fichier que vous n’avez pas créé, /init dépose un CLAUDE.md, et une pull request peut finir par embarquer un .claude/settings.local.json rempli des règles d’autorisation d’un seul développeur.

Voici une visite fichier par fichier : ce que fait chaque chemin, quel fichier l’emporte lorsque deux d’entre eux définissent la même valeur, et un verdict pour chacun sur sa place — ou non — dans le dépôt.

Où se trouvent les deux emplacements .claude ?

Claude Code lit deux racines .claude. L’une se trouve dans le projet, voyage avec le dépôt et s’adresse à toute l’équipe ; l’autre, ~/.claude dans votre dossier personnel, n’appartient qu’à vous et vous suit dans chaque projet de la machine. Cette séparation est l’élément le plus utile à intégrer. La référence du répertoire Claude Code trace la même ligne : committez les fichiers du projet, laissez ceux du dossier personnel là où ils sont. Sous Windows, la racine personnelle se situe dans %USERPROFILE%\.claude, et pointer CLAUDE_CONFIG_DIR ailleurs déplace l’ensemble.

my-project/
├── CLAUDE.md                    # instructions loaded every session
├── CLAUDE.local.md              # private preferences, gitignored
├── .mcp.json                    # team-shared MCP servers
└── .claude/
    ├── settings.json            # permissions, hooks, env, model defaults
    ├── settings.local.json      # your personal overrides, gitignored
    ├── rules/*.md               # topic-scoped instructions, optionally path-gated
    ├── skills/<name>/SKILL.md   # reusable prompts invoked with /name
    ├── commands/*.md            # single-file prompts, same mechanism as skills
    ├── agents/*.md              # subagent definitions with their own prompt and tools
    ├── workflows/*.js           # workflow scripts saved from /workflows
    ├── output-styles/*.md       # instruction sets that adjust how Claude works
    └── agent-memory/<name>/     # persistent memory for subagents

~/.claude.json                   # app state, OAuth, personal MCP servers
~/.claude/
├── CLAUDE.md                    # your instructions, across every project
├── settings.json                # personal defaults
├── rules/*.md                   # user-level rules, applied to every project
├── keybindings.json             # custom keyboard shortcuts
├── themes/*.json                # custom colour themes
├── plugins/                     # cloned marketplaces and per-plugin data
├── projects/<project>/memory/   # auto memory Claude writes itself
└── .credentials.json            # login credentials

En pratique, deux fichiers concentrent la quasi-totalité des modifications : CLAUDE.md et settings.json. Tout le reste est facultatif.

CLAUDE.md, imports et règles conditionnées par chemin

CLAUDE.md est le fichier que Claude Code charge dans le contexte au début de chaque session, et il est lu depuis quatre emplacements : la politique managée, ~/.claude/CLAUDE.md, le projet (./CLAUDE.md ou ./.claude/CLAUDE.md), et ./CLAUDE.local.md pour les notes personnelles. La documentation sur la mémoire est claire : ces fichiers s’empilent au lieu de se concurrencer. Chaque fichier trouvé par Claude Code est ajouté au contexte dans l’ordre, en partant de la racine du système de fichiers jusqu’à votre répertoire de travail, et au sein d’un même répertoire le CLAUDE.local.md est ajouté après le CLAUDE.md. Un fichier situé dans un répertoire parent est chargé au lancement ; un fichier situé dans un sous-répertoire attend que Claude ouvre un fichier à cet endroit.

La syntaxe @path/to/file importe un autre fichier, résolu relativement au fichier importateur, jusqu’à quatre niveaux de profondeur. Découper un long fichier en imports permet de mettre de l’ordre sans récupérer le moindre contexte, puisque tout ce qu’il importe est également déployé au lancement. L’analyse des imports ignore tout ce qui se trouve entre backticks ou dans un bloc de code délimité : c’est ainsi que vous pouvez mentionner un chemin dans vos instructions sans importer le fichier.

Deux limites comptent. Le chiffre de 200 lignes est un objectif plutôt qu’un plafond : au-delà, un fichier consomme davantage de contexte et Claude le suit avec moins de fiabilité. Le vrai plafond est de 4 Mio. Claude Code charge intégralement un CLAUDE.md jusqu’à cette taille et ignore celui qui la dépasse.

.claude/rules/*.md constitue l’alternative modulaire. Les fichiers de règles sont découverts récursivement, un sujet par fichier. Une règle sans frontmatter est chargée au lancement, au même rang que .claude/CLAUDE.md ; ajoutez-lui un champ paths et elle reste hors contexte jusqu’à ce que Claude touche un fichier correspondant au glob.

---
paths:
  - "src/components/**/*.tsx"
---

Prefer function components with explicitly typed props.
Co-locate the test file beside the component it covers.

Les instructions contradictoires entre fichiers sont arbitrées de façon arbitraire : il n’y a donc aucune règle à mémoriser sur ce point. Lancez /context ou /memory pour voir ce qui a réellement été chargé, et si une instruction doit impérativement s’exécuter à un moment précis, écrivez-la plutôt sous forme de hook PreToolUse. Un hook s’exécute comme une commande shell à un point fixe de la session, que Claude l’ait choisi ou non.

Quelle est la place d’AGENTS.md ?

Un dépôt qui contient déjà un AGENTS.md pour d’autres agents de codage n’a besoin de rien de plus : Claude Code lit ces fichiers lui-même, seuls ou aux côtés de CLAUDE.md. Lorsque le répertoire de travail et ses parents ne contiennent aucun CLAUDE.md, c’est AGENTS.md qui est chargé. Les fichiers chargés sont déterminés par l’option « Project instructions » de /config, et ce paramètre n’apparaît que dans les sessions capables de récupérer les feature flags d’Anthropic : il est donc absent sur Bedrock, Vertex et Foundry.

Pour une session incapable de charger AGENTS.md, ou lorsque vous souhaitez conserver un CLAUDE.md existant, ajoutez un CLAUDE.md à côté d’AGENTS.md qui l’importe :

@AGENTS.md

## Claude Code

Run `pnpm typecheck` before proposing any change under `packages/api/`.

Un lien symbolique fonctionne également lorsque vous n’avez besoin d’aucun contenu propre à Claude : ln -s AGENTS.md CLAUDE.md. Windows n’en crée pas sans privilèges administrateur ou sans le mode développeur : l’import est donc la voie la plus sûre dans ce cas. Un AGENTS.md lu directement n’apparaît pas sous Memory files dans /context ou /memory. La session affiche à la place une ligne « AGENTS.md loaded ».

Ne confondez pas AGENTS.md et CLAUDE.local.md. Ce dernier est le pendant personnel et gitignoré de CLAUDE.md, et n’a rien à voir avec l’interopérabilité entre outils.

Quelle est la différence entre skills/, commands/ et agents/ ?

Les commandes et les skills reposent sur le même mécanisme et répondent toutes deux à /name. La référence du répertoire oriente les nouveaux développements vers skills/<name>/SKILL.md, car un répertoire de skill peut regrouper des fichiers annexes aux côtés des instructions, alors qu’une commande est un unique fichier markdown. Un répertoire commands/*.md existant continue de fonctionner. Pour savoir comment structurer un skill dédié au travail frontend, consultez notre guide sur les skills Claude Code pour les workflows frontend.

agents/*.md contient les définitions de sous-agents, chacune avec son propre prompt et sa propre liste d’outils. Ces deux répertoires existent à la portée du projet et sous ~/.claude, et tous deux sont détectés par leur emplacement plutôt que par un enregistrement dans un fichier de paramètres.

Précédence de configuration dans Claude Code : settings.json face à settings.local.json

settings.json est le fichier partagé du projet et settings.local.json votre surcharge personnelle propre au projet ; lorsque les deux définissent la même clé, c’est le fichier local qui l’emporte. La référence des paramètres énonce cinq niveaux de précédence, du plus prioritaire au moins prioritaire : les managed settings, les arguments en ligne de commande, .claude/settings.local.json, .claude/settings.json et ~/.claude/settings.json. Le JSON que vous passez à --settings s’insère juste en dessous des managed settings et au-dessus de vos trois fichiers.

Ce qui prend les gens au dépourvu, c’est que toutes les clés ne suivent pas cette pile. Les clés de type liste telles que permissions.allow, permissions.ask et permissions.deny se combinent entre portées au lieu de se remplacer : une règle deny présente dans le settings.json partagé d’un collègue continue donc de mordre même si votre fichier local autorise le même outil. Quatre clés liées aux modèles font exception à cette fusion. fallbackModel est une chaîne ordonnée : le fichier de plus haute précédence qui la définit fournit donc l’intégralité de la valeur. modelPicker fonctionne de la même manière, à ceci près qu’elle ne lit que les managed settings, --settings et les paramètres utilisateur, et ignore la clé dans les fichiers de projet et locaux (Claude Code v2.1.242 et versions ultérieures). Une liste availableModels managée s’applique telle quelle et vos propres ajouts sont écartés, même si, entre les fichiers utilisateur, projet et local, ces tableaux fusionnent bel et bien. modelSettings est résolu modèle par modèle.

Fichier partagé :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "cleanupPeriodDays": 30,
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}

Fichier local :

{
  "cleanupPeriodDays": 7,
  "permissions": {
    "allow": ["Bash(npm run lint)"]
  }
}

La session résolue utilise cleanupPeriodDays: 7, car le fichier local prime sur le fichier partagé pour une clé scalaire. Les deux règles de permission restent actives : npm run lint s’exécute sans demande d’autorisation et la lecture de .env reste bloquée. Les fichiers de paramètres sont du JSON strict : ajoutez un commentaire // ou une virgule finale et le fichier échoue à l’analyse. La ligne $schema vous offre l’autocomplétion dans l’éditeur, et comme le schéma publié accuse parfois un retard sur les dernières versions de la CLI, un avertissement sur une clé documentée la semaine dernière en dit plus long sur le schéma que sur votre fichier. Lancez /status pour confirmer quels fichiers de paramètres ont été chargés.

Où vivent les hooks et les serveurs MCP ?

Les hooks ne sont pas des fichiers distincts. Ils résident sous la clé hooks de settings.json, à la portée de votre choix, et une modification prend effet sans redémarrer la session. Les serveurs MCP se répartissent selon leur public : .mcp.json se trouve à la racine du projet, est livré avec le dépôt et constitue la liste partagée par l’équipe. Les serveurs MCP personnels résident dans ~/.claude.json, qui stocke également l’état de l’application, les données OAuth et les serveurs de portée locale indexés par chemin de projet : traitez-le donc comme un état machine plutôt que comme un fichier de configuration à éditer à la main.

Que committer et que mettre dans le gitignore

La première fois que Claude Code écrit ce fichier local dans un dépôt qui ne l’ignore pas déjà, il ajoute **/.claude/settings.local.json à vos exclusions git globales. Cette écriture se produit lorsque vous répondez « Yes, and don’t ask again » à une demande de permission. Créez le fichier à la main et rien n’est ajouté pour vous : rendez donc l’entrée explicite.

# Claude Code personal config
# settings.local.json is usually auto-excluded already; this covers hand-created files
.claude/settings.local.json
CLAUDE.local.md

Les paramètres partagés sont aussi ce que voient les sessions cloud, puisque celles-ci s’exécutent sur un clone neuf. Les fichiers utilisateur et locaux restent sur votre machine et ne les atteignent jamais.

Tout ce qui se trouve sous ~/.claude est en clair

Les transcriptions de session, les sorties d’outils, le texte collé et le journal de prompts history.jsonl atterrissent tous sur le disque en texte brut, avec pour seule protection les permissions de fichiers. Si une commande a affiché un token pendant une session, ce token repose dans une transcription. .credentials.json contient vos identifiants de connexion et survit au nettoyage de rétention, qui efface par ailleurs les fichiers éligibles une fois dépassé le cleanupPeriodDays : 30 jours par défaut, 1 au minimum, et 0 refusé comme valeur invalide.

Le dossier est plus petit qu’il n’y paraît une fois trié : les instructions se concatènent, les paramètres suivent une précédence, les permissions fusionnent, et le répertoire personnel n’entre jamais dans le contrôle de version. Confrontez votre propre .claude/ à l’arborescence ci-dessus, supprimez les fichiers que personne n’a écrits volontairement, et ajoutez le bloc .gitignore de deux lignes avant que la prochaine pull request ne le fasse à votre place.

FAQ

Dois-je approuver les serveurs MCP qui arrivent dans le .mcp.json committé par un collègue ?

Oui. Dans une session interactive, Claude Code demande confirmation avant d'utiliser tout serveur de portée projet déclaré par un .mcp.json, et chaque développeur répond pour lui-même plutôt qu'une fois pour tout le dépôt. Lancez claude mcp reset-project-choices pour effacer ces réponses. Les contextes non interactifs ne peuvent pas afficher la demande : les exécutions claude -p, les sessions Agent SDK et les sessions cloud chargent les serveurs de portée projet sans demander ; utilisez donc disabledMcpjsonServers pour bloquer un serveur dans tous les modes de permission.

Comment surcharger un paramètre de Claude Code pour une seule session sans éditer de fichier ?

Passez --settings avec soit un chemin vers un fichier JSON, soit une chaîne JSON en ligne. Il se place en dessous des managed settings et au-dessus de vos fichiers utilisateur, projet et local. Certaines clés disposent aussi de leur propre flag ou variable d'environnement, et l'arbitrage se fait clé par clé : --model et /model l'emportent sur ANTHROPIC_MODEL, tandis que CLAUDE_CODE_EFFORT_LEVEL l'emporte sur /effort.

La modification de settings.json en cours de session prend-elle effet immédiatement ?

Certaines clés sont rechargées à la volée et d'autres ne sont lues qu'au démarrage de la session : une modification peut donc sembler ignorée jusqu'au prochain lancement. Les permissions et les hooks se rechargent sans redémarrage, tandis que model, effortLevel et modelSettings ne sont lus qu'au démarrage. Un changement d'outputStyle s'applique dès votre message suivant depuis la v2.1.251, même si, dans le terminal, un fichier de style créé ou modifié en cours de session n'est pris en compte qu'après un redémarrage. Si une valeur semble toujours erronée après redémarrage, lancez /status et vérifiez la précédence : un fichier de portée supérieure tel que .claude/settings.local.json définit peut-être la même clé.

Que perds-je si je supprime le dossier projects sous ~/.claude ?

Supprimer projects/ efface les transcriptions conservées et peut vous empêcher de reprendre des sessions passées, même si les nouvelles sessions ne sont pas affectées. La commande claude project purge constitue l'alternative ciblée : elle supprime les transcriptions, la mémoire automatique, les tâches et les entrées d'historique de fichiers d'un seul projet, les lignes de prompt correspondantes dans history.jsonl, ainsi que l'entrée de ce projet dans ~/.claude.json. Les dossiers shell-snapshots/ et backups/ restent en place. Passez -i pour parcourir le plan de suppression étape par étape.