Claude Code settings.json : le fichier qui configure ce que fait votre agent

settings.json n'est pas un fichier de préférences. C'est là que se configure le comportement de votre agent. Les thèmes et le choix du modèle s'y trouvent aussi, mais c'est la partie ennuyeuse. La partie qui mérite d'être comprise est le seul bloc qui change ce que l'agent fait, pas son apparence. Voici la version courte du fichier, celle qui compte vraiment.

Où se trouve le fichier settings.json de Claude Code

À trois endroits, et tout est une question de priorité. .claude/settings.local.json dans votre projet (ignoré par git, propre à votre machine) l'emporte en premier. Vient ensuite .claude/settings.json validé dans le dépôt, partagé par l'équipe. Enfin, ~/.claude/settings.json, votre configuration globale par défaut. Le fichier le plus spécifique surcharge les autres, clé par clé.

Cette séparation suit la même logique que pour un fichier CLAUDE.md. Ce qui est personnel reste local, ce qui est partagé est validé dans le dépôt, et les éléments spécifiques à la machine ne touchent jamais git. Maîtrisez cette priorité et vous arrêterez de vous battre avec votre propre configuration.

Le seul bloc qui change le comportement est hooks

Toutes les autres clés de settings.json ajustent l'apparence ou les accès : thème, modèle, permissions, ligne d'état. Le bloc hooks est différent. Il associe un événement du cycle de vie à une commande shell que Claude Code exécute automatiquement à ce moment-là. C'est la seule partie du fichier qui fait agir l'agent, c'est donc la seule qui mérite d'être étudiée. Consultez le fonctionnement des hooks pour comprendre tout le mécanisme.

Une entrée de hook a une structure bien précise. Notre installateur l'écrit ainsi, et vous devriez faire de même :

{ "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "node safety-guard.mjs" }] }

Le matcher détermine quels appels d'outils déclenchent le hook. Si vous l'omettez, l'événement se déclenche sans condition. La command est une simple chaîne de caractères shell, un hook peut donc être n'importe quel script dans n'importe quel langage. C'est tout ce qu'il y a à savoir.

Ce que kitstarter intègre dans settings.json, événement par événement

L'installateur de kitstarter génère tout le bloc hooks pour vous, à raison d'une entrée par événement du cycle de vie. Voici le véritable tableau de correspondance entre événements et scripts qu'il écrit, directement issu du code d'intégration. Rien n'est inventé, c'est exactement ce qui est livré.

Observez attentivement les matchers, car c'est là que réside toute la logique. Safety-guard écoute uniquement Bash, de sorte qu'il ne ralentit jamais une édition. Clarity écoute les quatre outils d'édition ainsi que la soumission de l'invite, car un build peut démarrer depuis n'importe lequel d'entre eux. Slop-check écoute Edit|Write, puisque c'est à ce moment-là qu'un fichier est modifié sur le disque.

Ce que fait concrètement un hook configuré

Chaque script est léger et conçu pour échouer de manière transparente (« fail open ») : en cas d'erreur, il reste silencieux plutôt que de bloquer votre travail. safety-guard.mjs lit la commande Bash en attente et la compare à une liste de motifs destructeurs : suppressions récursives de la racine ou du dossier personnel, force-push, hard reset, suppression de table. Il avertit, il ne bloque jamais. Un kit qui bloque systématiquement vos commandes finit par être désinstallé.

slop-check.mjs se déclenche après la modification d'un fichier d'interface utilisateur. Il lance le détecteur de code bâclé sur ce seul fichier et, s'il trouve des anomalies, les présente comme un contexte que l'agent doit corriger avant de continuer. Ces deux hooks sont déclenchés par une simple entrée dans le bloc hooks. C'est toute la puissance que ce fichier vous offre.

Configurer settings.json de cette manière est-il vraiment utile ?

Oui, sur les aspects essentiels, et nous l'avons mesuré en toute honnêteté. Lors de notre test comparatif en environnement isolé face à Claude Code standard, le kit a posé une question avant de construire sur 5 tâches sur 5 (contre 2 sur 5 pour la version standard), a livré environ 40 % de code en moins pour le même résultat, et a réduit les anomalies de code bâclé de 5 à 0 sur une tâche de débogage en boucle où la version standard en avait laissé cinq.

Les inconvénients sont réels et nous ne les cachons pas, c'est notre règle d'or. Sur une application de liste de tâches déjà simple, le kit s'est révélé environ deux fois plus lent et près de 75 % plus cher pour un résultat quasi identique. Sur l'ensemble des tests, le contexte des hooks ajoute un surcoût moyen d'environ 25 %, prélevé sur votre abonnement existant. Les hooks ne sont pas gratuits. Avec des invites vagues, ils sont rentabilisés en évitant de réécrire du code ; avec des invites déjà claires, ils représentent un surcoût inutile.

Écrivez les vôtres, ou partez d'une base qui fonctionne

Le mécanisme est simple : choisissez un événement, écrivez un script, ajoutez une entrée. Le plus difficile est de faire les bons choix : quels matchers écouter, quand avertir plutôt que bloquer, comment échouer de manière transparente pour que le hook ne bloque jamais une session. C'est précisément ce qu'est kitstarter : un fichier settings.json optimisé et les scripts associés, générés pour vous et prêts à l'emploi. Créez le vôtre à l'aide du tableau ci-dessus, ou installez-en un qui a déjà fait ses preuves.