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

Un jour ou l’autre, Claude refuse une commande autorisée, le diff explose, ou settings.json ne semble plus pris en compte. Ce guide rassemble les diagnostics utiles et les corrections rapides pour les cas les plus fréquents, avec les commandes internes (/status, /doctor, /cost) qui font la différence. Tout est ancré sur lab-claude pour que vous puissiez rejouer les vérifications.

Ce que vous allez apprendre

Utiliser /status, /doctor, /cost et /stats pour diagnostiquer une session
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
/status montre une valeur que vous ne reconnaissez pas

Les 4 commandes de diagnostic à connaître

Commande	Ce qu’elle montre	Quand l’utiliser
`/status`	Scopes chargés, règles effectives, mode de permission	Toute incohérence entre config et comportement
`/doctor`	Installation, version, extensions, environnement	Problème global au démarrage
`/cost`	Coût estimé de la session	Avant une opération longue ou coûteuse
`/stats`	Durée, tokens, messages, outils utilisés	Bilan après une session longue

Réflexe : en cas de doute, lancez /status avant de modifier quoi que ce soit.

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 :

Dans la session, lancez /status et notez :
- d’où vient la règle (Managed, Local, Project, User)
- si un deny ou ask du même scope ou d’un scope supérieur la contredit
Vérifiez la syntaxe exacte du motif. Causes fréquentes :
- forme « espace » au lieu de « deux-points » : Bash(uv run pytest *) ne matche pas, la forme canonique est Bash(uv run pytest:*)
- oubli du :* terminal : Bash(uv run pytest) ne couvre pas les arguments
- casse incorrecte : bash(...) au lieu de Bash(...)
- espace superflu : Bash( uv run pytest:*)
Relancez la session. Les permissions sont relues au démarrage.

Causes fréquentes et corrections :

Cause	Correction
Motif trop strict	Ajouter `*` en suffixe
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

Problème 2 : `settings.json` semble ignoré

Symptôme : vous éditez .claude/settings.json, mais /status affiche l’ancien contenu ou aucune règle.

Diagnostic :

Valider la syntaxe JSON :
Fenêtre de terminal
```
python3 -c "import json; json.load(open('.claude/settings.json'))" && echo "JSON valide"
```
Une virgule finale ou un guillemet manquant casse silencieusement le chargement.
Vérifier le chemin exact :
Fenêtre de terminal
```
ls -la .claude/settings.json
```
Un fichier nommé setting.json (sans s) ou placé à la racine sans .claude/ ne sera jamais lu.
Relancer la session et lancer /status. Si la règle n’apparaît toujours pas, vérifier qu’aucun managed-settings.json système n’impose un override.

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 :

Lister les fichiers touchés :
Fenêtre de terminal
```
git diff --stat
```
Identifier les changements non demandés (fichiers que Claude a modifiés en dehors du périmètre).
Sélectionner ce qu’il faut garder avec git add -p (hunk par hunk), puis stasher le reste :
Fenêtre de terminal
```
git add -p
git stash --keep-index
```
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 :

Mode	Comportement	Quand l’utiliser
`default`	Confirmation à chaque action risquée	Par défaut, toujours
`acceptEdits`	Édits de fichiers auto-acceptés	Uniquement sur un périmètre verrouillé par `CLAUDE.md` + `rules` + `hooks`
`plan`	Aucune action, plan seul	Exploration, audit

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

Si une session a trop avancé en acceptEdits :

Vérifier l’étendue des changements :
Fenêtre de terminal
```
git status
git diff --stat
```
Revenir aux fichiers non voulus :
Fenêtre de terminal
```
git restore <fichier>
```
Attention : cette commande efface les modifications locales du fichier. Vérifiez d’abord avec git diff <fichier>.
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 :

/stats pour voir la longueur de la session (au-delà de ~60 messages, la densité de contexte baisse)
Relire le dernier plan validé : si Claude l’a perdu, ce n’est pas un bug, c’est un signal

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

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 :

Lister les hooks actifs :
Fenêtre de terminal
```
ls .claude/hooks/
```
Lancer à la main la commande du hook concerné. Exemple pour un hook PostToolUse qui fait uv run ruff check . :
Fenêtre de terminal
```
uv run ruff check .
```
Le message d’erreur complet s’affiche.
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

À 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

Prochaines étapes

Serveurs MCP Étendre Claude vers des ressources hors du dépôt (fetch, GitHub, bases locales)

Briques Claude Code : quand utiliser quoi Revoir l'orientation entre CLAUDE.md, rules, settings, hooks, skills

Erreurs courantes et recadrage Compléter avec le recadrage pendant la session