settings.json : Configuration utilisateur et projet

📚 Navigation de la série : L'article précédent 30 Choisir ses fonctionnalités : CLAUDE.md vs Skill vs Hook vs MCP vs Subagent vous a appris à orienter vos besoins vers les bons points d'extension. Cet article descend d'un niveau : dans quel fichier ces interrupteurs cachés doivent-ils être saisis, et quelle est la priorité entre configuration utilisateur et projet ? Le fichier settings.json is le tableau électrique général de Claude Code. Mettons de l'ordre dans ses connexions dès aujourd'hui.

Voici un piège particulièrement facile à éviter, mais difficile à oublier une fois que l'on s'est fait avoir.

Lorsque j'ai commencé à utiliser Claude Code sérieusement, j'ai voulu ajouter la ligne defaultMode: "auto" dans le fichier .claude/settings.json d'un projet pour autoriser automatiquement les outils sans qu'il me le demande à chaque fois. Après modification, aucun effet. Ma première réaction a été de penser que j'avais mal orthographié le nom du champ ; j'ai comparé mot à mot avec la documentation officielle à trois reprises : pas une seule faute de frappe. J'ai ensuite suspecté le format JSON et validé le fichier en ligne : parfaitement valide. Après vingt minutes de tâtonnement, j'ai même commencé à me demander si cette version de Claude Code ne comportait pas un bug.

Ce n'est que plus tard que j'ai découvert cette phrase cachée dans un coin de la documentation : lorsque defaultMode est défini sur "auto", il est tout simplement ignoré s'il est saisi dans la configuration du projet. C'est une restriction délibérée de l'équipe officielle pour éviter qu'un dépôt malveillant n'active discrètement le mode automatique (ce point a également été évoqué au chapitre 20). La syntaxe de la ligne était correcte, le fichier était sain : je m'étais simplement trompé d'« étage ». Une fois déplacée dans le fichier utilisateur ~/.claude/settings.json, la configuration a fonctionné instantanément.

Si je vous partage cette anecdote, c'est pour graver une règle dans votre esprit : 90 % des erreurs avec settings.json ne concernent pas « la syntaxe », mais « le choix du bon niveau et les priorités d'écrasement ». Aujourd'hui, nous allons décortiquer ces « règles d'étage » pour que vous sachiez instantanément si une configuration doit être placée dans votre répertoire racine ou dans celui du projet.

À la fin de cet article, vous obtiendrez :

• Une explanation en une phrase de ce qu'est settings.json et de sa répartition des rôles avec CLAUDE.md
• L'emplacement, le périmètre d'action et le contenu recommandé pour les trois niveaux (utilisateur, projet, local)
• Un tableau de priorité d'écrasement, accompagné d'une exception à contre-courant (les tableaux se combinent au lieu de s'écraser)
• Les clés de configuration les plus courantes (model, permissions, env, hooks, statusLine), leurs rôles et leurs niveaux cibles
• Un cas pratique à suivre : éditer un paramètre → valider son application réelle avec /status

---

01 Comprendre d'abord : Qu'est-ce que settings.json et quelle est sa répartition des rôles avec CLAUDE.md

Commençons par la conclusion : settings.json est le « panneau d'interrupteurs comportementaux » de Claude Code. Il configure au format JSON les permissions, les variables d'environnement, le modèle par défaut, les Hooks et la barre d'état. Il se distingue de CLAUDE.md : l'un définit « comment travailler » et l'autre « ce qu'il faut mémoriser ».

De nombreux débutants confondent les deux. Vous avez rédigé des instructions dans CLAUDE.md (chapitre 18), configuré des règles de permission (chapitre 20) et allez bientôt définir des Hooks — tous ces éléments finissent par être traduits dans le fichier settings.json, mais sa nature diffère totalement de celle de CLAUDE.md.

Analogie : l'armoire à archives du projet vs le tableau électrique de votre bureau. CLAUDE.md s'apparente à la « notice du projet » rangée dans l'armoire : elle contient des instructions en langage naturel rédigées pour l'humain (et pour Claude) du type « nous utilisons pnpm et non npm » ou « exécuter les tests avant de soumettre », chargées au début de chaque session comme contexte. Le fichier settings.json est différent ; il s'apparente au tableau électrique fixé au mur : il contient des boutons configurés (cet outil est-il autorisé, quel modèle exécuter par défaut, quel script lancer automatiquement après modification). L'armoire contient « les conventions expliquées à l'agent », le tableau électrique contient « les comportements physiques imposés à la machine ».

La documentation officielle définit clairement son rôle :

Le fichier settings.json est le mécanisme officiel de configuration de Claude Code via des paramètres hiérarchisés.

Notez les termes « mécanisme officiel » et « hiérarchisés », qui constituent les deux fils conducteurs de cet article : il s'agit du point d'entrée formel de configuration de Claude Code (plutôt que de passer par des options de ligne de commande temporaires), et il est structuré sous forme de couches superposées (utilisateur, projet, local).

Dans la pratique, le fichier settings.json sert à gérer les aspects suivants :

• « Dans ce projet, bloquer impérativement les commandes du type rm -rf » → clé permissions.deny
• « Ce projet doit utiliser Sonnet par défaut pour éviter de consommer inutilement le quota d'Opus » → clé model
• « Lancer un formateur automatiquement après chaque modification de fichier » → clé hooks
• « Afficher la branche git actuelle dans la barre d'état en bas du terminal » → clé statusLine

Ces éléments ne sont pas des explications destinées à Claude, mais des commutateurs modifiant physiquement son comportement. C'est le fondement de la répartition des rôles entre settings.json et CLAUDE.md.

💡 Résumé en une phrase : CLAUDE.md contient les règles en langage naturel destinées à Claude ; settings.json is le tableau électrique programmant les comportements de l'outil. L'un gère la mémoire, l'autre régit l'exécution. Veillez à ne pas les confondre.

---

02 Trois niveaux : Répertoire utilisateur, racine du projet ou propre à votre machine

Avant de détailler la liste des champs de settings.json, il convient de comprendre ses trois niveaux : un même nom de fichier placé à trois endroits différents aura un périmètre d'action radicalement différent. L'anecdote du début provenait précisément d'une confusion entre ces niveaux.

Analogie : l'affichage des notes. Une note indiquant « éteindre la climatisation en partant » peut être apposée à l'entrée de l'entreprise (visible pour tous les projets), sur la porte d'un bureau spécifique (concerne uniquement les collaborateurs de ce projet et fait partie du règlement local), ou sous forme de post-it collé sur votre écran (concerne uniquement vous, les autres l'ignorant). Son périmètre varie. Les trois niveaux de settings.json correspondent à ces trois modes d'affichage.

Niveau	Emplacement du fichier	Périmètre	Validé dans git ?	Contenu recommandé
Utilisateur (User)	~/.claude/settings.json	Vous, sur tous vos projets	Non (répertoire racine personnel)	Préférences personnelles : modèle par défaut, thème, utilitaires globaux
Projet (Project)	.claude/settings.json	Tous les collaborateurs de ce dépôt	Oui (validé dans git)	Conventions d'équipe : permissions, Hooks, serveurs MCP partagés
Local (Local)	.claude/settings.local.json	Vous, uniquement sur ce dépôt	Non (exclu automatiquement)	Ajustements personnels, configurations de test avec jetons secrets

Pour choisir entre ces trois niveaux, retenez simplement ces trois règles :

• « Pour tous mes projets » → Niveau utilisateur (~/.claude/settings.json). Par exemple : « mon modèle par défaut is Sonnet » ou « le script de ma barre d'état ». Configurez-le une fois, il s'appliquera partout.
• « Pour tous les collaborateurs, lié au dépôt » → Niveau projet (.claude/settings.json). Ce fichier is validé dans git ; vos collaborateurs bénéficient des mêmes paramètres dès qu'ils récupèrent le dépôt. C'est l'approche « Configuration as Code ».
• « Uniquement pour moi, propre à ce projet, sans partage » → Niveau local (.claude/settings.local.json).

Un détail d'implémentation très appréciable est précisé officiellement : lors de la création de .claude/settings.local.json, Claude Code configure automatiquement git pour l'ignorer.

Claude Code configurera git pour ignorer .claude/settings.local.json lors de sa création.

Pourquoi ce choix ? Le niveau local est destiné aux « objets personnels » — vos tests de configuration individuels ou des données de connexion secrètes — qui ne doivent en aucun cas être partagés pour ne pas polluer l'espace de vos collaborateurs. Cette sécurité par défaut vous évite de commettre une erreur en exécutant maladroitement git add .. Cela rejoint la consigne de sécurité abordée au chapitre 21 : évitez à la source de laisser des éléments sensibles s'approcher de votre dépôt git.

Cas concret : Répartition sur les trois niveaux d'un projet réel

Pour mieux comprendre, analysons la répartition des paramètres d'un projet de production :

• Niveau utilisateur (~/.claude/settings.json) : scripts personnalisés de barre d'état, modèle par défaut. Ces éléments sont indépendants du projet et correspondent à des préférences globales qui vous suivent partout.
• Niveau projet (.claude/settings.json) : liste permissions.deny (interdiction de curl ou de lire .env), Hook déclenchant un lint avant validation. Ces paramètres définissent les exigences de sécurité minimales partagées par l'équipe et doivent être partagés via git.
• Niveau local (.claude/settings.local.json) : autorisations temporaires propres à votre poste de travail, Hook en cours d'expérimentation non stabilisé pour être partagé.

Pour déterminer le bon niveau d'une configuration, posez-vous cette suite de questions : « Cette consigne ne concerne-t-elle que moi ? → Niveau utilisateur ou local. Concerne-t-elle l'équipe ? → Niveau projet. » Puis affinez : « S'applique-t-elle à tous mes projets ? → Niveau utilisateur. S'applique-t-elle uniquement à ce dépôt sans devoir être partagée ? → Niveau local. »

Un pas-de-côté est vite arrivé : de nombreux débutants insèrent des règles de permission propres à un projet au niveau utilisateur : dès que vous changez de projet, ces règles continuent de s'appliquer, créant des exceptions inutiles sur des dépôts qui n'ont rien à voir. C'est pourquoi « cette configuration doit-elle me suivre ou suivre le projet ? » est la question fondamentale à se poser. Ce qui appartient au projet doit rester au niveau du projet.

💡 Résumé en une phrase : Pour distinguer les trois niveaux : global sur tous les projets → niveau utilisateur (~/.claude/settings.json), partagé avec l'équipe → niveau projet (.claude/settings.json, validé dans git), exception personnelle → niveau local (.claude/settings.local.json, ignoré automatiquement par git). La règle d'or : « Me suit-il ou suit-il le projet ? »

---

03 Les priorités d'écrasement, avec une exception à contre-courant

Chaque niveau peut définir la même clé de configuration. Si le niveau utilisateur indique Opus et le niveau projet indique Sonnet, qui l'emporte ? C'est le rôle des « priorités (precedence) », qui constituent l'aspect le plus technique de settings.json.

Voici l'ordre de priorité officiel, du plus élevé au plus faible (le niveau le plus haut écrase les niveaux inférieurs) :

Priorité	Niveau	Explication simple
1 (Maximale)	Managed (Gestion d'entreprise)	Règles verrouillées par l'entreprise, immuables
2	Ligne de commande (drapeau --settings, etc.)	Paramètre temporaire saisi au lancement, valable pour la session en cours uniquement
3	Local (.claude/settings.local.json)	Vos exceptions personnelles sur ce projet
4	Projet (.claude/settings.json)	Configuration partagée de l'équipe
5 (Minimale)	Utilisateur (~/.claude/settings.json)	Vos valeurs par défaut globales, appliquées si aucun niveau supérieur ne les surcharge

Cette relation d'écrasement peut être vue comme une pile de feuilles : les feuilles supérieures recouvrent les inférieures, masquant les valeurs définies pour une même clé :

Le schéma montre que les priorités diminuent du haut vers le bas : les couches supérieures surchargent les couches inférieures (pour les clés à valeur unique). En d'autres termes, plus on monte, plus le paramètre is « temporaire et spécifique », et plus on descend, plus il is « global et générique » — le niveau utilisateur tout en bas n'intervient que si aucune couche supérieure ne définit la clé.

Pour s'en souvenir : plus le niveau is proche du moment présent et spécifique, plus sa priorité is forte. La ligne de commande (pour cette session uniquement) écrase le niveau local (ce projet, uniquement pour vous), qui écrase le niveau projet (l'équipe), qui lui-même surcharge le niveau utilisateur (global). L'exemple officiel is parlant :

Par exemple, si vos paramètres utilisateur autorisent Bash(npm run *) mais que les paramètres partagés du projet le refusent, la configuration du projet l'emporte et la commande is bloquée.

En clair, les autorisations que vous vous accordez au niveau global peuvent être révoquées par la configuration d'un projet spécifique. C'est le sens de l'avertissement formulé à la fin du chapitre précédent : une même ligne de configuration écrite au niveau utilisateur ou projet peut produire des effets inverses. L'anecdote de départ sur defaultMode: "auto" provenait d'une mauvaise compréhension de ces priorités.

Le niveau Managed peut être résumé rapidement. Il s'agit des politiques distribuées de façon centralisée par les administrateurs informatiques (via MDM, clés de registre ou serveurs de stratégies). Ce niveau a une priorité absolue et ne peut être surchargé ni par l'utilisateur ni par le projet. Il sert à appliquer les règles de conformité et de sécurité de l'entreprise (par exemple, « désactiver curl au niveau global »). Dans le cadre d'un usage personnel ou d'une petite équipe, vous ne le rencontrerez pas — gardez simplement en tête qu'il existe un plafond absolu, et référez-vous à la documentation server-managed-settings si vous devez travailler dans un environnement d'entreprise réglementé.

L'exception à contre-courant : les tableaux se combinent au lieu de s'écraser

Les priorités d'écrasement décrites ci-dessus s'appliquent aux valeurs uniques (comme la clé model où la couche supérieure l'emporte). Il existe cependant une catégorie de paramètres qui fonctionne différemment : les clés stockant des tableaux (comme permissions.allow / deny) se combinent d'une couche à l'autre au lieu de s'écraser.

Qu'est-ce que cela signifie ? La documentation officielle l'explique :

Les paramètres de tableau se fusionnent entre les portées. Lorsque des valeurs de tableau identiques apparaissent dans plusieurs portées, les tableaux sont concaténés et dédoublés, au lieu d'être remplacés.

En clair : vos règles de permission globales ne sont pas écrasées par celles d'un projet, les deux listes s'additionnent pour s'appliquer conjointement.

Voyons un exemple concret :

Scénario	Intuition (erronée)	Réalité (exacte)
Niveau utilisateur allow: ["Bash(npm run *)"], niveau projet allow: ["Bash(git diff *)"]	Le niveau projet l'emporte, seul git diff est autorisé	Les deux s'appliquent : npm run * et git diff * sont tous deux autorisés

Il s'agit de deux logiques distinctes à mémoriser séparément :

• Valeurs uniques (comme model, defaultMode) : le niveau le plus prioritaire écrase intégralement les valeurs des niveaux inférieurs.
• Tableaux (comme permissions.allow / deny, variables d'environnement dans env) : les valeurs se cumulent et s'épurent des doublons d'un niveau à l'autre.

C'est un piège classique : penser qu'en définissant des règles deny restrictives au niveau projet, on neutralise des règles allow trop permissives du niveau utilisateur. Ces dernières continuent pourtant de s'appliquer car les listes se fusionnent au lieu de s'exclure. Comprendre cette nuance évite de laisser des accès ouverts par mégarde.

💡 Résumé en une phrase : La priorité d'écrasement suit la règle : « plus on se rapproche du cas spécifique, plus la priorité is forte » (Ligne de commande > Local > Projet > Utilisateur, avec Managed en sommet) ; mais les paramètres sous forme de tableaux (comme les permissions) fusionnent d'un niveau à l'autre au lieu de s'écraser — c'est le piège le plus fréquent.

---

04 Les clés de configuration les plus courantes : Rôles et niveaux recommandés

Une fois la structure et les priorités posées, concentrons-nous sur les clés que vous modifierez le plus souvent. Bien que le fichier settings.json supporte officiellement des dizaines de clés, l'usage quotidien se limite à une poignée d'entre elles. Détaillons-les.

Voici un exemple minimaliste mais complet pour illustrer la structure globale du fichier :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Bash(npm run test *)"],
    "deny": ["Bash(curl *)", "Read(./.env)"]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

Il est vivement conseillé d'inclure la clé $schema. Elle référence le schéma JSON officiel, ce qui active l'autocomplétion et la validation en temps réel dans vos éditeurs de code (VS Code, Cursor, etc.). Si vous faites une faute de frappe ou saisissez un type incorrect, l'éditeur vous le signale immédiatement. Les vingt minutes passées à comparer ma saisie avec la documentation officielle auraient pu être évitées instantanément en déclarant cette clé $schema. L'équipe officielle le confirme :

L'ajouter à votre settings.json active l'autocomplétion et la validation intégrée dans VS Code, Cursor et tout autre éditeur supportant la validation de schéma JSON.

Détaillons ces champs essentiels :

model : le modèle exécuté par défaut

La clé model définit le modèle exécuté par défaut à ce niveau. La valeur correspond à l'identifiant du modèle (par exemple, "claude-sonnet-4-6").

• Niveau recommandé : selon votre besoin. « Préférer un modèle pour mes usages personnels » → niveau utilisateur ; « Imposer l'usage de Sonnet sur ce projet pour maîtriser la consommation » → niveau projet.
• Remarque importante : contrairement à d'autres clés, la clé model n'est lue qu'une fois au lancement de la session. Toute modification nécessite de relancer la session ou d'utiliser la commande /model pour basculer à la volée. L'option --model de la ligne de commande ou la variable d'environnement ANTHROPIC_MODEL l'emportent de façon temporaire (voir chapitre 5).

Cette clé offre un cas d'usage très pratique : définir des modèles différents selon les projets. Par exemple, pour un dépôt contenant de la documentation simple, forcez le modèle à une version plus légère dans le fichier projet settings.json. Pour un dépôt contenant du code complexe, laissez le modèle global plus performant défini au niveau utilisateur s'appliquer. Ainsi, le modèle s'adapte automatiquement selon le projet ouvert sans nécessiter de basculement manuel via /model — cela évite de consommer du quota de calcul performant pour des tâches simples, tout en garantissant la puissance nécessaire là où elle s'impose. C'est tout l'intérêt de la priorité « le projet écrase l'utilisateur » : le projet applique des surcharges locales et l'utilisateur sert de filet de sécurité global.

permissions : autoriser ou interdire des outils/commandes

Ce point a été détaillé au chapitre 20 — il s'agit d'appliquer les règles allow (autoriser), ask (interroger) et deny (bloquer) pour affiner les privilèges par outil et par commande.

• Niveau recommandé : les exigences de sécurité minimales partagées (comme « interdire curl » ou « interdire la lecture de .env ») doivent figurer au niveau projet et être validées dans git. Vos facilités de travail personnelles peuvent être définies au niveau local ou utilisateur.
• Rappel important (section 03) : la clé permissions contenant des tableaux, ses valeurs fusionnent d'une couche à l'autre — définir une interdiction deny à un niveau ne permet pas d'annuler une autorisation allow définie par ailleurs.

env : injecter des variables d'environnement dans la session

Les couples clé-valeur définis dans env sont chargés comme variables d'environnement dans chaque session et dans les sous-processus lancés par Claude Code.

Analogie : le badge et l'équipement distribués à l'entrée d'un atelier. Quelle que soit la personne de garde, l'accès à l'atelier (session) s'accompagne de ce paquetage — env est cette « configuration d'accès standard », et toute variable déclarée ici is transmise aux commandes et aux processus enfants exécutés dans la session.

• Cas d'usage classique : activer la télémétrie (CLAUDE_CODE_ENABLE_TELEMETRY), définir une variable fixe pour une chaîne d'outils.
• Niveau recommandé : variables propres à un dépôt (comme l'adresse d'un service local) → niveau projet ; préférences globales → niveau utilisateur.

hooks : exécuter automatiquement des scripts à des moments clés

La clé hooks permet de déclarer des Hooks (les actions automatiques déclenchées par des événements abordées au chapitre précédent et détaillées au chapitre 33). Par exemple : « formater le code après modification de fichier », « afficher un message d'accueil au lancement ».

• Niveau recommandé : les règles d'équipe (comme « vérifier le code avant validation ») → niveau projet ; vos préférences personnelles → niveau utilisateur.
• La syntaxe et la liste des événements associés seront traitées au chapitre 33. Retenez pour l'instant que les Hooks se déclarent dans settings.json.

statusLine : personnaliser la barre d'état en bas

La barre d'état au bas de la console a été abordée au chapitre 14. La clé statusLine vous permet de personnaliser son affichage — par exemple, y brancher un script pour afficher la branche git active, le modèle en cours ou la consommation de tokens.

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

• Niveau recommandé : l'aspect visuel de la barre d'état étant propre à vos goûts personnels, privilégiez le niveau utilisateur (~/.claude/settings.json) pour l'appliquer à l'ensemble de vos projets.

Paramètre	Rôle	Niveau recommandé par défaut
model	Modèle par défaut	Préférence personnelle → utilisateur ; exigence d'équipe → projet
permissions	Privilèges des outils/commandes	Cadre de sécurité → niveau projet (validé dans git)
env	Variables d'environnement	Propre au dépôt → projet ; globale → utilisateur
hooks	Actions automatiques sur événement	Conventions d'équipe → projet ; habitudes personnelles → utilisateur
statusLine	Barre d'état personnalisée	Préférence esthétique → niveau utilisateur

Une confusion fréquente : tous les paramètres ne résident pas dans settings.json

C'est un point méconnu qui se manifeste généralement par un message d'erreur. Claude Code exploite un second fichier de configuration nommé ~/.claude.json (notez sa position à la racine du répertoire utilisateur, distinct de ~/.claude/settings.json). Ce fichier stocke données de nature différente : vos jetons de session active, les configurations globales et locales des serveurs MCP (abordées au chapitre 22), l'état de confiance de chaque projet et divers fichiers de cache.

Le piège principal réside dans le fait que certaines clés de configuration doivent impérativement être déclarées dans ~/.claude.json. Les renseigner dans settings.json déclenchera une erreur de validation de schéma. C'est le cas pour des clés comme autoConnectIde (connexion automatique de la console vers l'IDE) ou teammateDefaultModel (modèle par défaut des coéquipiers d'équipe).

Le cas d'école consiste à vouloir configurer la connexion automatique vers VS Code en ajoutant la clé correspondante dans settings.json : la validation du schéma via $schema vire immédiatement au rouge et la commande /status renvoie une erreur. Il faut alors chercher dans la documentation pour comprendre que cette option doit être déclarée dans ~/.claude.json. Retenez cette règle : settings.json configure « les règles comportementales », tandis que ~/.claude.json stocke « les données système, serveurs MCP et sessions ». Vous éditerez le premier dans la grande majorité des cas, mais si un paramètre refuse d'être écrit dans settings.json, vérifiez s'il ne relève pas de ~/.claude.json.

---

05 Mode d'édition, prise en compte des changements et validation

Savoir écrire les champs is un bon début, mais trois questions concrètes se posent : où éditer les fichiers, les modifications nécessitent-elles un redémarrage, et comment s'assurer qu'elles sont appliquées ? Les tâtonnements du début provenaient en partie de cette incertitude.

Mode d'édition : modification directe ou via la commande /config

Deux options s'offrent à vous :

1. Modifier directement le fichier JSON dans votre éditeur — repérez l'emplacement correspondant au niveau souhaité (section 02) et éditez-le. Comme pour CLAUDE.md, il is recommandé de modifier les fichiers directement pour garder un historique propre et contrôlé.
2. Saisir la commande /config dans la session — elle ouvre une interface interactive permettant de consulter l'état et d'éditer certaines options courantes (comme le thème ou le niveau de verbosité).

Une confusion fréquente is levée officiellement dans la documentation : l'onglet Config accessible via /config ne représente pas une vue complète du contenu de votre fichier settings.json. Il s'agit uniquement d'un éditeur simplifié pour quelques options courantes (thème, verbosité). Ne vous attendez pas à y retrouver l'intégralité de vos clés configurées — l'état réel se vérifie dans les fichiers de configuration.

Prise en compte des changements : rechargement dynamique, avec deux exceptions

Bonne nouvelle — Claude Code surveille vos fichiers de paramètres et applique la plupart des modifications de clés en temps réel dans la session active, sans nécessiter de redémarrage. La documentation officielle l'indique :

Claude Code surveille vos fichiers de paramètres et les recharge lorsqu'ils changent... Cela inclut les permissions, les hooks et les assistants d'identification.

Il existe cependant deux exceptions qui ne sont lues qu'au lancement de la session. Modifier ces clés nécessite de relancer la session (ou d'utiliser une commande dédiée) :

Clé	Prise en compte après modification
model	Redémarrage de la session, ou basculement via la commande /model
outputStyle (style de sortie, voir chapitre suivant)	Redémarrage de la session, ou réinitialisation via la commande /clear

En pratique, si vous modifiez des règles dans permissions ou hooks, la sauvegarde du fichier suffit à les appliquer instantanément. En revanche, si vous modifiez la clé model et ne constatez aucun changement, ne suspectez pas une erreur de syntaxe — la session doit être relancée pour l'appliquer. Si l'anecdote de départ avait concerné des permissions, j'aurais constaté l'application dès la sauvegarde du fichier, mais le fait de buter sur une option ignorée localement a compliqué les choses.

Valider l'application réelle : inspecter « Setting sources » via la commande /status

C'est l'outil indispensable pour lever le doute sur le chargement effectif d'un fichier. Saisissez la commande /status dans la console : la ligne Setting sources détaille les sources de configuration effectivement chargées par la session active — comme User settings ou Project local settings (les étiquettes exactes dépendent de la version installée).

La documentation officielle le précise clairement :

La ligne Setting sources confirme quelles sources sont lues... Une couche n'apparaît dans la liste que si elle définit au moins une clé ; une liste vide signifie qu'aucune source n'a été détectée.

Cette précision is cruciale :

• La présence du niveau dans la liste indique que le fichier a été localisé et lu avec succès.
• L'absence du niveau indique que Claude Code n'a pas localisé le fichier (généralement en raison d'un mauvais chemin d'accès, comme placer le fichier à la racine settings.json au lieu de .claude/settings.json).
• En cas d'erreur de syntaxe (JSON mal formé, valeur invalide), la commande /status renvoie explicitement une erreur, ce qui évite de chercher au hasard.

Par conséquent, après toute modification de settings.json, le premier réflexe doit être d'exécuter la commande /status pour vérifier la liste des sources — connaître cette astuce m'aurait évité de perdre vingt minutes au départ.

Guide de dépannage en cas d'échec de configuration

Voici une grille de dépannage regroupant les pièges classiques. Si vos modifications ne s'appliquent pas, évitez de suspecter la syntaxe immédiatement et suivez cet ordre de vérification :

Symptôme	❌ Ne suspectez pas en premier	✅ Vérifiez en priorité
Aucun effet constaté après modification	Erreur de nom de clé	Exécuter /status pour vérifier la liste Setting sources — si le niveau is absent, le chemin d'accès au fichier is erroné
La modification de model n'est pas prise en compte	Fichier corrompu	La clé model requiert un redémarrage (ou la commande /model), la simple sauvegarde ne suffit pas
L'option defaultMode: "auto" reste inactive	Faute de frappe	La valeur auto is ignorée aux niveaux projet et local, elle doit figurer au niveau utilisateur (section 03)
Une commande s'exécute malgré une règle deny	Règle mal rédigée	Les permissions fusionnent entre les couches, vérifiez qu'une règle allow ne subsiste pas à un autre niveau (section 03)
Un paramètre refuse d'être écrit dans settings.json	JSON invalide	Cette clé doit peut-être déclarée dans ~/.claude.json (comme autoConnectIde, section 04)

Comme l'illustre ce tableau, les erreurs de syntaxe pure sont très rares. La grande majorité des dysfonctionnements provient d'une mauvaise appréciation du niveau, du moment d'application ou de la logique de fusion des tableaux. C'est le sens du message d'avertissement : la difficulté avec settings.json ne réside pas dans sa rédaction, mais dans la compréhension de ses règles hiérarchiques.

---

06 En pratique : Écrire une configuration projet et locale et valider son application via /status

Rien ne vaut la pratique. Voici comment déclarer des paramètres sur deux niveaux différents et s'assurer de leur bonne lecture avec la commande /status — une démonstration simple pour assimiler le flux complet « édition → hiérarchie → validation » sans dépendre de projets préexistants.

Étape 1 : Créer un répertoire de test (dans la console)

mkdir settings-demo && cd settings-demo

Étape 2 : Écrire une configuration au niveau projet

Créez le fichier settings-demo/.claude/settings.json et insérez le contenu ci-dessous (autoriser la commande de test, interdire curl). La première ligne $schema active le contrôle de cohérence dans votre éditeur :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run test *)"],
    "deny": ["Bash(curl *)"]
  }
}

Étape 3 : Écrire une configuration au niveau local

Créez le fichier settings-demo/.claude/settings.local.json et ajoutez-y une règle d'exception personnelle qui ne doit pas être partagée sur git :

{
  "permissions": {
    "allow": ["Bash(git status *)"]
  }
}

Résultat attendu : une fois les deux fichiers créés, le répertoire dispose de deux niveaux de configuration distincts. Le fichier settings.local.json doit être automatiquement exclu par git (à vérifier à l'étape suivante).

Étape 4 : Confirmer l'exclusion du fichier local par git

git init -q && git status --short

Résultat attendu : la sortie de git liste le fichier .claude/settings.json (destiné à être partagé avec l'équipe), mais le fichier .claude/settings.local.json n'apparaît pas car il a été exclu automatiquement par le système. Cela valide le comportement par défaut abordé à la section 02.

Étape 5 : Lancer une session et vérifier le chargement via /status

claude

Une fois la session ouverte, saisissez :

/status

Résultat attendu : la ligne Setting sources de la sortie d'état doit lister l'étiquette Project local settings (et éventuellement User settings si vous l'avez configuré globalement). La présence des lignes indique que vos fichiers ont été localisés et chargés par Claude Code. Si un niveau is manquant, vérifiez les chemins de fichiers décrits à la section 02.

Étape 6 : Valider la fusion des permissions via la commande /permissions

/permissions

Résultat attendu : les règles déclarées s'affichent — npm run test * et git status * figurent parmi les règles d'autorisation, tandis que curl * is listé dans les interdictions. Remarquez que bien que git status * provienne du fichier local et les autres du fichier projet, les trois règles s'appliquent simultanément — c'est la démonstration concrète de la fusion des tableaux étudiée à la section 03.

En déroulant ces six étapes, vous avez manipulé concrètement les piliers de settings.json : l'édition par niveaux, l'exclusion automatique des paramètres locaux, la validation du chargement avec /status et la fusion avec /permissions. Toute édition future de clé reposera sur ce même principe.

💡 Résumé en une phrase : L'exercice pratique consiste à : créer deux fichiers projet et local → vérifier l'exclusion du fichier local avec git status → valider le chargement des sources avec /status → constater la fusion avec /permissions. Ce test simple dissipe toutes les incertitudes sur les concepts de priorité et de fusion.

---

07 Conclusion

Dans ce chapitre, nous avons exploré en détail le tableau électrique de configuration settings.json de Claude Code — depuis son rôle initial jusqu'aux mécanismes de priorité, de fusion et de diagnostic.

Récapitulons les points essentiels :

Sujet d'intérêt	Réponse	Point clé en une phrase
Différence avec CLAUDE.md	Deux natures distinctes	CLAUDE.md définit les règles de mémoire, settings.json programme les comportements
Niveaux et emplacements	Trois couches	Utilisateur (~/.claude/), projet (.claude/, git), local (.claude/settings.local.json, ignoré)
Règles de priorité	Le niveau spécifique l'emporte	Ligne de commande > Local > Projet > Utilisateur, avec Managed en sommet
Comportement à contre-courant	Fusion des tableaux	Les tableaux comme les permissions se cumulent et s'épurent, sans s'écraser
Clés les plus courantes	Cings clés	model / permissions / env / hooks / statusLine
Validation post-modification	Commande /status	Inspecter la ligne « Setting sources » pour confirmer la bonne lecture du niveau

Vous devriez maintenant être capable de : distinguer la nature de settings.json de celle de CLAUDE.md, choisir le bon niveau d'une option de configuration (utilisateur ou projet), comprendre les priorités d'écrasement et la fusion de tableaux, identifier les clés d'usage courant (model, permissions, env, hooks, statusLine), et valider leur chargement effectif à l'aide de la commande /status. Cette maîtrise de la hiérarchie de configuration is l'outil indispensable pour adapter Claude Code à vos méthodes de travail et à celles de votre équipe.

Ma perte de temps de vingt minutes au départ provenait uniquement d'une chose — m'être trompé de niveau de configuration. Fort de cette lecture, vous éviterez ce détour : si une option reste inactive, ne suspectez pas la syntaxe, posez-vous la question « suis-je au bon étage ? » et vérifiez avec la commande /status.

---

Le prochain article 32 « Styles de sortie (Output Styles) » — vous venez de repérer la clé spécifique outputStyle dans le fichier de paramètres. Rappelez-vous qu'elle fait partie des deux exceptions nécessitant de relancer la session pour s'appliquer. Le prochain chapitre y is entièrement consacré : comment configurer le ton et le prompt système de Claude pour le faire passer de son rôle d'assistant technique à celui d'instructeur pédagogique ou à d'autres usages. Un même agent Claude configuré avec des styles de sortie différents peut formuler ses réponses de manières radicalement opposées.

---

Lectures recommandées

• Système de mémoire (memory) : se faire mémoriser d'une session à l'autre
• Plugins : regrouper et empaqueter vos configurations en un clic
• Introduction à Claude Code