Claude Code CLI : settings.json avancé et permissions par projet

Après la série débutant, vos sessions sont cadrées mais chaque projet redemande les mêmes autorisations. Ce guide pose une configuration durable via settings.json : vous verrouillez les permissions sensibles, pré-autorisez les commandes répétitives et partagez un socle commun avec votre équipe. Tout est appliqué sur lab-claude et vérifié avec /status.

Ce que vous allez apprendre

Les 4 scopes de configuration et leur ordre de priorité
La structure d’un settings.json de projet avec $schema
La syntaxe des règles allow, deny et ask
La différence entre settings.json (partagé via git) et settings.local.json (personnel, ignoré)
Vérifier la configuration active avec /status

Prérequis

Claude Code CLI installé et fonctionnel
Projet fil rouge prêt : ~/Projets/lab-claude
Conventions posées dans CLAUDE.md (voir configurer CLAUDE.md)
À l’aise avec les modes d’exécution (voir mode plan, diff et validations)

Les 4 scopes de configuration

Claude Code lit la configuration depuis 4 emplacements, du plus spécifique au plus général :

Scope	Fichier	Usage	Suivi git
Managed	`managed-settings.json` (système)	Politique d’entreprise imposée	N/A
Local	`.claude/settings.local.json`	Préférences personnelles du projet	Ignoré
Project	`.claude/settings.json`	Règles partagées de l’équipe	Suivi
User	`~/.claude/settings.json`	Préférences globales utilisateur	N/A

Ordre de priorité : Managed > Local > Project > User. Les tableaux (allow, deny, ask) sont fusionnés entre scopes, pas écrasés.

La structure de base d’un settings.json

Commencez toujours avec $schema pour activer l’autocomplétion et la validation dans votre éditeur.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": []
  },
  "env": {},
  "includeCoAuthoredBy": false,
  "cleanupPeriodDays": 30
}

Les clés les plus utiles au quotidien :

Clé	Effet
`permissions.allow`	Commandes pré-autorisées, pas de prompt
`permissions.deny`	Commandes toujours refusées, non contournables
`permissions.ask`	Commandes qui demandent confirmation à chaque fois
`env`	Variables d’environnement injectées dans chaque session
`includeCoAuthoredBy`	Active ou coupe l’attribution `Co-Authored-By: Claude`
`cleanupPeriodDays`	Rétention des transcriptions de conversation
`defaultMode`	Mode de permission par défaut (`default`, `acceptEdits`, `plan`)

Syntaxe des règles de permissions

Les règles utilisent une syntaxe simple Outil(motif) :

Bash(uv run ruff check *)   -> commande shell préfixée par uv run ruff check
Bash(git status)            -> commande exacte, sans argument
Read(./.env)                -> lecture d'un fichier précis
Read(./secrets/**)          -> lecture récursive d'un dossier
Edit(src/**)                -> édition d'un chemin via motif
WebFetch(domain:github.com) -> accès réseau restreint à un domaine

Règles importantes :

Un * à la fin couvre tout suffixe (Bash(uv run *) autorise toutes les sous-commandes uv run)
Les motifs deny ont priorité sur allow au sein d’un même scope
deny au niveau Managed ne peut jamais être contourné

Application sur `lab-claude`

Placez-vous dans le projet
Fenêtre de terminal
```
cd ~/Projets/lab-claude
```

Créez .claude/settings.json partagé

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(uv run ruff check *)",
      "Bash(uv run ruff format *)",
      "Bash(uv run pytest *)",
      "Bash(uv add *)",
      "Bash(uv sync *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git commit *)"
    ]
  },
  "env": {
    "PYTHONDONTWRITEBYTECODE": "1"
  },
  "includeCoAuthoredBy": false,
  "cleanupPeriodDays": 30
}

Validez la syntaxe JSON

python3 -c "import json; json.load(open('.claude/settings.json'))" && echo "JSON valide"

Démarrez une session et vérifiez
Fenêtre de terminal
```
claude
```
Puis dans la session :
```
/status
```
Confirmez que .claude/settings.local.json est bien ignoré
Fenêtre de terminal
```
git check-ignore .claude/settings.local.json
```

settings.json vs settings.local.json

Deux fichiers, deux usages distincts :

Fichier	Contenu recommandé
`.claude/settings.json`	Règles stables, pertinentes pour toute l’équipe (allow de `uv run`, deny des secrets)
`.claude/settings.local.json`	Préférences personnelles temporaires (modèle préféré, allow spécifique à votre machine)

Règle simple : si un autre développeur rejoue votre configuration sans souci, c’est du settings.json. Si ça dépend de votre machine ou de votre compte, c’est du settings.local.json.

Vérifier la configuration active

La commande /status affiche d’où vient chaque valeur (Managed, Local, Project, User). C’est le réflexe à avoir quand une permission semble bloquée ou accordée sans raison apparente.

Dans une session Claude :

/status

Vous y trouvez :

Les scopes chargés et leur chemin sur disque
Les règles allow, deny, ask résultantes après fusion
Le mode de permission actif

Exemple commenté pour `lab-claude`

Pourquoi ces règles dans le settings.json partagé :

Bash(uv run ruff check *) et Bash(uv run pytest *) : validations répétées à chaque cycle, aucune raison de prompter
Bash(git status), Bash(git diff *), Bash(git log *) : lecture seule, sans risque
Bash(git push *) et Bash(git commit *) dans ask : action visible côté équipe, confirmation souhaitable
Read(./.env) et Read(./secrets/**) en deny : protection systématique des secrets
Bash(rm -rf *), Bash(curl *), Bash(wget *) en deny : opérations destructives ou exfiltration réseau
includeCoAuthoredBy: false : l’attribution par défaut peut gêner dans certains workflows de revue

Erreurs fréquentes

Symptôme	Cause probable	Correction
Claude redemande une autorisation pourtant dans `allow`	Motif trop restrictif ou syntaxe incorrecte	Ajouter `*` en suffixe ou vérifier la casse exacte
`deny` non respecté	Règle placée dans le mauvais scope	Vérifier avec `/status` d’où vient la règle
Éditeur ne complète pas le JSON	`$schema` absent ou incorrect	Ajouter la ligne `$schema` en tête du fichier
`settings.local.json` apparaît dans `git status`	Projet créé avant le fichier	Ajouter `.claude/settings.local.json` au `.gitignore` manuellement
Permissions perso poussées sur le dépôt	Règle mise dans `settings.json` au lieu de `.local.json`	Déplacer la règle vers le fichier local

Checklist de fin de guide

J’ai identifié les 4 scopes et leur ordre de priorité
J’ai créé .claude/settings.json avec $schema en tête
J’ai au moins une entrée dans allow, deny et ask
J’ai validé la syntaxe JSON du fichier
J’ai vérifié la configuration active avec /status
Je sais où mettre une règle perso (settings.local.json) vs équipe (settings.json)
.claude/settings.local.json est bien ignoré par git

À retenir

Le settings.json transforme les garde-fous en contrat durable du projet
deny protège, allow accélère, ask garde la main sur les actions visibles
settings.json se partage, settings.local.json reste local
/status est le seul juge de ce qui est vraiment actif
Plus les règles sont explicites, moins vous interrompez les sessions

Prochaines étapes

Rules ciblées Claude Code Sortir les règles spécifiques de CLAUDE.md vers .claude/rules/ avec frontmatter paths

Skills Claude Code Transformer les procédures répétitives en routines invocables par /nom

Hooks Claude Code Automatiser lint, tests et garde-fous autour des événements de session