Accueil / Étendre : compétences, MCP, sous-agents, hooks, plugins

settings.json en profondeur

Cinq niveaux de settings.json se succèdent du plus fort au plus faible, une clé scalaire commune aux deux fichiers se décide par le niveau le plus prioritaire, mais la plupart des listes, dont permissions.allow et permissions.deny, se fusionnent entre les niveaux au lieu de s'écraser.

Un settings.json de projet remplace celui de l'utilisateur sur une clé scalaire que les deux fichiers définissent, et cinq niveaux se succèdent avant d'atteindre ce résultat (source code.claude.com/docs/en/settings, consultée le 2026-09-02).

Cinq niveaux, un seul qui gagne par défaut

Du plus fort au plus faible : les réglages gérés, posés par un MDM ou par la console claude.ai ; l'option --settings passée sur la ligne de commande, valable pour une seule session ; .claude/settings.local.json, privé au poste, jamais partagé par git ; .claude/settings.json, partagé par git avec le reste de l'équipe sur ce projet ; enfin ~/.claude/settings.json, posé une fois pour tous les projets ouverts sur ce poste. Sur une clé simple présente à deux niveaux à la fois, celui de rang le plus fort l'emporte entièrement, le niveau plus faible n'est pas lu. Les réglages gérés restent hors de portée d'édition depuis le poste de travail, posés par une organisation, tandis que les quatre autres niveaux sont de simples fichiers texte que chacun peut ouvrir et modifier directement.

Les listes fusionnent, sauf quatre clés

La règle change dès qu'une clé porte une liste. permissions.allow et permissions.deny, entre autres, se fusionnent entre les niveaux : une entrée posée au niveau utilisateur reste active même quand le projet en ajoute une autre à côté. Quatre clés échappent à cette fusion, chacune selon sa propre règle plutôt qu'une règle unique. fallbackModel prend la valeur entière du niveau le plus prioritaire qui la définit. modelPicker prend la valeur entière du plus prioritaire parmi les réglages gérés, --settings et les settings utilisateur, et ignore purement et simplement la clé si elle n'est posée qu'au niveau projet ou local. availableModels, quand les réglages gérés la définissent, s'applique telle quelle et ignore ce qu'ajoutent l'utilisateur, le projet ou le local, et ne se fusionne pas non plus entre plusieurs sources gérées elles mêmes. modelSettings se résout modèle par modèle, avec effortLevel, chaque entrée précisant elle même quel fichier s'applique à quel modèle.

{
  "permissions": {
    "allow": ["Bash(npm test)"],
    "deny": []
  },
  "env": {
    "NODE_ENV": "development"
  }
}

Le bloc env suit la même règle

Le bloc env inséré dans un fichier de réglages est une clé ordinaire qui suit les cinq mêmes niveaux que le reste du fichier, mais la plupart de ses valeurs, comme les règles permissions.allow, n'entrent en vigueur qu'après que chaque coéquipier a fait confiance au dossier du projet. Une variable d'environnement du shell n'est pas un niveau de cette pile : quand un comportement dispose à la fois d'une variable et d'une clé de réglage, lequel des deux s'applique se décide paire par paire, pas par niveau, ANTHROPIC_MODEL exporté dans le shell l'emportant par exemple sur la clé model de n'importe quel fichier, tandis qu'ANTHROPIC_DEFAULT_MODEL ne s'applique que si aucun fichier ne pose model.

Cette hiérarchie prend tout son sens dès qu'un hook entre en jeu : la déclaration d'un événement, comme celle décrite dans les événements de hook, du déclenchement au message, vit elle aussi dans ce même fichier, et suit exactement le même ordre de priorité entre projet et poste personnel.