Claude Code : dépannage avancé, permissions, config, diff et sessions qui dérivent

Un jour ou l'autre, Claude refuse une commande pourtant autorisée, le diff explose, ou settings.json ne semble plus pris en compte. Ce guide rassemble les diagnostics et les corrections des six situations les plus fréquentes, avec les commandes internes qui tranchent : /permissions pour savoir de quel fichier vient une règle, /context quand la session dérive, /doctor quand rien d'autre n'explique le symptôme. Tout est ancré sur lab-claude pour que vous puissiez rejouer chaque vérification.

Ce que vous allez apprendre

• Choisir la bonne commande de diagnostic parmi /permissions, /status, /context, /doctor
• Identifier pourquoi une permission est refusée malgré un allow
• Valider un settings.json invalide et retrouver un état propre
• Réduire un diff trop large avant de le valider
• Reconnaître une mauvaise utilisation de acceptEdits
• Redresser une session qui dérive sans tout relancer

Dans quel contexte utiliser ce guide ?

• Claude redemande une confirmation sur une commande pourtant dans allow
• settings.json modifié n'a aucun effet visible
• Le diff dépasse 300 lignes et devient impossible à relire
• La session a exécuté plusieurs étapes non voulues en mode acceptEdits
• Une règle s'applique et vous ne savez pas de quel fichier elle vient

Quelle commande de diagnostic pour quel symptôme ?

Le réflexe le plus rentable est de choisir la bonne commande, pas de les lancer toutes. Chacune répond à une question précise, et les confondre fait chercher au mauvais endroit.

Commande	Ce qu'elle répond	Quand l'utiliser
/permissions	quelles règles existent, et de quel fichier chacune vient	une commande est refusée, ou autorisée sans que vous sachiez pourquoi
/status	quelles sources de configuration sont chargées	vérifier qu'un fichier est bien pris en compte
/context	ce qui occupe la fenêtre de contexte	la session dérive, oublie le périmètre, rallonge
/hooks	quels hooks sont actifs et d'où ils viennent	un comportement automatique inattendu
/mcp	quels serveurs MCP sont connectés, et leur état	un outil MCP absent ou en erreur
/doctor	un diagnostic d'installation	rien de ce qui précède n'explique le symptôme
/cost	le coût estimé de la session	avant une opération longue
/stats	durée, tokens, messages, outils	bilan après une session longue

Glissez pour voir

Réflexe : en cas de doute sur une permission, lancez /permissions avant de modifier quoi que ce soit. C'est la seule commande qui nomme le fichier d'origine de chaque règle, information décisive puisque les permissions fusionnent entre scopes au lieu de s'écraser.

Problème 1 : une permission est refusée malgré un allow

Symptôme typique : vous avez ajouté Bash(uv run pytest *) dans allow, et Claude demande quand même confirmation.

Diagnostic en 3 étapes :

1. Dans la session, lancez /permissions et notez :

   • de quel fichier vient la règle, l'information que cette commande est seule à donner
   • si un deny ou un ask la contredit : l'ordre d'évaluation est deny, puis ask, puis allow, et la spécificité ne change rien

2. Vérifiez la syntaxe exacte du motif. Causes fréquentes, par ordre de fréquence :

   • astérisque absent : Bash(uv run pytest) n'autorise que la commande exacte, sans aucun argument
   • espace manquant avant l'astérisque : Bash(uv run pytest*) déborde sur tout ce qui commence pareil, ce qui n'est en général pas voulu
   • espace superflu au début : Bash( uv run pytest *) ne correspond à rien
   • casse incorrecte : bash(...) au lieu de Bash(...)

   La forme Bash(uv run pytest:*) avec deux-points est équivalente à la forme avec espace, et reste valide : ce n'est jamais elle la cause du problème. En revanche le deux-points n'est reconnu qu'en fin de motif.

3. Relancez la session. Les permissions sont relues au démarrage.

Causes fréquentes et corrections :

Cause	Correction
Motif trop strict	Ajouter un espace puis un astérisque, qui couvre aussi la commande nue
Règle deny prioritaire	Retirer ou scoper le deny
Règle au mauvais scope	Déplacer vers settings.json (projet) ou settings.local.json (perso)
Clé tapée dans ask au lieu de allow	Déplacer dans le bon tableau

Glissez pour voir

Problème 2 : settings.json semble ignoré

Symptôme : vous éditez .claude/settings.json, mais /permissions n'affiche pas vos règles, ou /status ne montre pas le fichier.

Diagnostic :

1. Valider la syntaxe JSON :

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

   Une virgule finale ou un guillemet manquant casse silencieusement le chargement.

2. Vérifier le chemin exact :

   ls -la .claude/settings.json

   Un fichier nommé setting.json (sans s) ou placé à la racine sans .claude/ ne sera jamais lu.

3. Relancer la session, puis /permissions. Si la règle n'apparaît toujours pas, vérifier qu'aucun managed-settings.json système ne l'écrase : le niveau Managed ne peut être contourné par aucun autre.

Le JSON invalide est silencieux

Claude Code n'affiche pas toujours d'erreur quand settings.json est invalide : il retombe simplement sur la configuration précédente. Le réflexe : toujours valider le JSON après modification.

Problème 3 : le diff est trop large pour être relu

Symptôme : git diff affiche plusieurs centaines de lignes, impossible à valider sereinement.

Règle : un diff relisible tient en moins de 200 lignes avec un périmètre clair. Au-delà, coupez avant de valider.

Corrections dans l'ordre :

1. Lister les fichiers touchés :

   git diff --stat

2. Identifier les changements non demandés (fichiers que Claude a modifiés en dehors du périmètre).

3. Sélectionner ce qu'il faut garder avec git add -p (hunk par hunk), puis stasher le reste :

   git add -p
   git stash --keep-index

4. Valider uniquement le stage, relancer ruff et pytest, puis décider pour le reste.

Pour éviter le problème à la source :

• Demander un plan en 3 étapes avant toute exécution
• Donner un périmètre explicite (app/main.py uniquement)
• Exécuter une étape à la fois

Rappel : la boucle Explorer → Planifier → Exécuter → Valider est détaillée dans premier workflow réel CLI.

Problème 4 : acceptEdits a été mal utilisé

Symptôme : plusieurs fichiers ont été modifiés sans que vous ayez confirmé à chaque étape.

Rappel des modes de permission les plus employés au quotidien. Claude Code en compte six au total, détaillés dans la leçon mode plan.

Mode	Comportement	Quand l'utiliser
default	confirmation à la première utilisation de chaque outil	par défaut, et point de retour après un incident
acceptEdits	modifications de fichiers auto-acceptées, plus les commandes courantes du système de fichiers	uniquement sur un périmètre verrouillé par CLAUDE.md, rules et hooks
plan	Claude lit et explore avec des commandes en lecture seule, sans modifier vos sources	exploration, audit, reprise après dérive

Glissez pour voir

Attention à une confusion répandue sur plan : il n'empêche pas toute exécution, il empêche la modification des sources. Si votre besoin est de n'exécuter strictement rien, la réponse est un sandbox, pas un mode.

Règle : acceptEdits ne se mérite que sur un projet où les garde-fous, deny strict, hook de lint et tests rapides, rattrapent les dérives.

Si une session a trop avancé en acceptEdits :

1. Vérifier l'étendue des changements :

   git status
   git diff --stat

2. Revenir aux fichiers non voulus :

   git restore <fichier>

   Attention : cette commande efface les modifications locales du fichier. Vérifiez d'abord avec git diff <fichier>.

3. Repasser en mode default pour la suite de la session.

Détails sur les modes dans mode plan, diff et validations.

Problème 5 : une validation a été oubliée

Symptôme : un commit est parti sans que ruff ou pytest aient été lancés.

Corrections immédiates :

cd ~/Projets/lab-claude
uv run ruff check .
uv run pytest -q

Si une erreur remonte, corrigez et committez à nouveau avec un message explicite (fix: ruff warning after previous commit).

Prévention durable : poser un hook PostToolUse sur Edit|Write qui lance uv run ruff check . automatiquement. Voir hooks Claude Code.

Problème 6 : la session dérive lentement

Symptôme : chaque échange rallonge, Claude oublie le périmètre, les changements débordent.

Diagnostic rapide :

• /context pour voir ce qui occupe réellement la fenêtre de contexte : c'est la commande faite pour ce symptôme
• /stats pour la longueur de la session, en messages et en tokens
• Relire le dernier plan validé : si Claude l'a perdu, ce n'est pas un défaut, c'est un signal que le contexte est saturé

Corrections graduelles :

Niveau de dérive	Action
Faible	Reformuler le périmètre en 2 lignes et reposer le plan
Moyenne	Lancer /clear et redémarrer avec le résumé du dernier plan
Forte	Quitter la session, committer l'état stable, redémarrer à froid

Glissez pour voir

Rappel : le recadrage détaillé pendant la session est traité dans erreurs courantes et recadrage. Ce guide-ci se concentre sur les causes techniques (config, permissions, diff).

Problème 7 : un hook bloque sans message clair

Symptôme : Claude s'arrête après un Edit avec un message générique, aucun détail.

Diagnostic :

1. Lister les hooks actifs :

   ls .claude/hooks/

2. Lancer à la main la commande du hook concerné. Exemple pour un hook PostToolUse qui fait uv run ruff check . :

   uv run ruff check .

   Le message d'erreur complet s'affiche.

3. Corriger la cause (erreur de lint, fichier manquant) ou ajuster le hook pour remonter le message (exit 2 avec texte explicite).

Un hook qui retourne exit 2 bloque l'action Claude et remonte le stdout comme feedback. Exploitez cette remontée pour rendre les blocages lisibles.

Commandes de diagnostic : exemples concrets

Sur lab-claude, voici ce que vous tapez quand quelque chose cloche :

/status         # d'où viennent mes règles effectives
/doctor         # la CLI et l'environnement sont-ils OK
/cost           # où en est le coût de cette session
/stats          # bilan des messages et outils utilisés
/clear          # repartir d'un contexte propre

Gardez ces 5 commandes en mémoire. Elles couvrent 90 % des diagnostics.

Checklist de dépannage

• J'ai lancé /status avant de modifier la config
• J'ai validé la syntaxe JSON de settings.json
• J'ai vérifié que les motifs allow ont bien un * terminal quand nécessaire
• Je garde mes diffs sous ~200 lignes relisibles
• Je n'active acceptEdits que sur un projet avec garde-fous solides
• Je sais reconnaître une dérive et quand /clear plutôt que continuer

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• /status est votre premier réflexe : il montre ce qui est vraiment chargé
• Un JSON invalide casse settings.json en silence, validez toujours
• Un gros diff est un signal de périmètre mal tenu, pas une fatalité
• acceptEdits se mérite, default est toujours sûr
• Un hook bien écrit remonte son erreur lisiblement, pas un blocage opaque

Pour aller plus loin

• Sandbox d'exécution pour agents IA : Isoler le code produit par un agent, avec le comparatif conteneur durci, gVisor et micro-VM.
• Sous le capot de Docker : namespaces et seccomp : Les mécanismes Linux sur lesquels repose le confinement que vous venez d'employer.

×

📖 Voir la documentation →