SpyBara
Go Premium

debug-your-config.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 2 additions and 2 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Fri 25 23:58

Déboguer votre configuration

Diagnostiquez pourquoi CLAUDE.md, les paramètres, les hooks, les serveurs MCP ou les skills ne prennent pas effet. Utilisez /context, /doctor, /hooks et /mcp pour voir ce qui a réellement été chargé.

Quand Claude ignore une instruction ou qu'une fonctionnalité que vous avez configurée n'apparaît pas, la cause est généralement que le fichier n'a pas été chargé, qu'il a été chargé depuis un emplacement différent de celui que vous attendiez, ou qu'un autre fichier l'a remplacé. Ce guide montre comment inspecter ce que Claude Code a réellement chargé afin que vous puissiez déterminer lequel de ces cas s'applique.

Pour les problèmes d'installation, d'authentification et de connectivité, consultez plutôt Troubleshooting installation and login à la place.

Voir ce qui a été chargé dans le contexte

La commande /context affiche tout ce qui occupe la fenêtre de contexte pour la session actuelle, ventilé par catégorie : invite système, outils système, outils MCP, sous-agents personnalisés avec la source de chacun, fichiers de mémoire, skills et messages de conversation. Exécutez-la d'abord pour confirmer si vos fichiers CLAUDE.md, règles ou descriptions de skills sont présents. La section skills dans /context inclut également les skills groupés, que /skills ne liste pas.

Pour plus de détails sur une catégorie spécifique, suivez avec la commande dédiée :

Commande Affiche
/memory Emplacements des fichiers de mémoire dans les portées utilisateur et projet avec l'option d'ouvrir chacun dans votre éditeur, plus l'accès au dossier de mémoire automatique et le bouton bascule de mémoire automatique
/skills Les skills disponibles provenant des sources de projet, utilisateur et plugin
/hooks Les configurations de hooks actives
/mcp Les serveurs MCP connectés et leur statut
/permissions Les règles d'autorisation et de refus résolues actuellement en vigueur
/doctor Diagnostics de configuration : santé de l'installation, fichiers de paramètres invalides, extensions inutilisées, noms de sous-agents en doublon dans le même répertoire, et contenu CLAUDE.md enregistré que Claude peut dériver de la base de code, avec des corrections proposées
/debug [issue] Active la journalisation de débogage pour la session et invite Claude à diagnostiquer en utilisant la sortie du journal et les chemins de paramètres
/status Les sources de paramètres actives, y compris si les paramètres gérés sont en vigueur

Si un fichier de mémoire est absent de la ventilation /context, vérifiez son emplacement par rapport à comment les fichiers CLAUDE.md se chargent. Les fichiers CLAUDE.md des sous-répertoires se chargent à la demande quand Claude lit un fichier dans ce répertoire avec l'outil Read, pas au démarrage de la session.

Si /context confirme que le fichier a été chargé mais que Claude ne suit toujours pas une instruction particulière, le problème est probablement la façon dont l'instruction est écrite plutôt que si elle a été chargée. CLAUDE.md fonctionne bien pour le type de conseils que vous donneriez à un nouveau coéquipier, comme les conventions de projet, les commandes de compilation et l'emplacement des fichiers.

L'adhérence diminue quand une instruction est assez vague pour être interprétée de plusieurs façons, quand deux fichiers donnent des directives conflictuelles, ou quand le fichier est devenu assez long pour que les règles individuelles reçoivent moins d'attention. Écrire des instructions efficaces couvre les modèles de spécificité, de taille et de structure qui maintiennent l'adhérence élevée.

Vérifier les paramètres résolus

Les paramètres fusionnent entre les portées gérées, utilisateur, projet et locale. Les paramètres gérés s'appliquent d'abord quand ils sont présents. Parmi le reste, la portée plus proche remplace la plus large dans l'ordre local, puis projet, puis utilisateur. Certains paramètres peuvent également être définis par des drapeaux de ligne de commande ou des variables d'environnement, qui agissent comme une autre couche de remplacement. Quand un paramètre ne semble pas s'appliquer, la valeur que vous avez définie est généralement remplacée par une autre portée ou une variable d'environnement.

Pour trouver les fichiers de paramètres invalides, exécutez claude doctor depuis votre terminal. Il affiche les diagnostics d'installation et de paramètres en lecture seule sans démarrer une session. Pour une vérification complète qui propose également des corrections et demande avant de les appliquer, exécutez /doctor dans une session.

Exécutez /status pour voir quelles sources de paramètres sont actives, y compris si les paramètres gérés sont en vigueur. Pour comprendre quelle portée Claude Code utilise pour une clé donnée, consultez Précédence des paramètres.

Vérifier les serveurs MCP

Exécutez /mcp pour voir chaque serveur configuré, son statut de connexion et si vous l'avez approuvé pour le projet actuel. Un serveur peut être défini correctement mais ne pas fournir d'outils pour quelques raisons courantes :

  • Les serveurs à portée de projet dans .mcp.json nécessitent une approbation unique. Si l'invite a été rejetée, le serveur reste désactivé jusqu'à ce que vous l'approuviez depuis /mcp.
  • Un serveur qui échoue au démarrage s'affiche comme échoué dans /mcp. Les chemins de fichiers relatifs dans command ou args sont une cause fréquente, car ils se résolvent par rapport au répertoire à partir duquel vous avez lancé Claude Code plutôt qu'à l'emplacement de .mcp.json.
  • Un serveur qui s'affiche comme connecté mais qui liste zéro outils a démarré avec succès mais ne retourne pas de liste d'outils. Sélectionnez Reconnect depuis /mcp. Si le nombre reste à zéro, exécutez claude --debug=mcp et lisez la sortie stderr du serveur dans le journal de débogage à ~/.claude/debug/<session-id>.txt.

Pour les emplacements de configuration et les règles de portée, consultez MCP.

Vérifier les hooks

Exécutez /hooks pour lister chaque hook enregistré pour la session actuelle, groupé par événement. Si un hook que vous avez défini n'apparaît pas, il n'est pas en cours de lecture : les hooks vont sous la clé "hooks" dans un fichier de paramètres, pas dans un fichier autonome.

Si le hook apparaît mais ne se déclenche pas, le matcher est la cause habituelle. Vérifiez-le pour ces erreurs :

  • Le champ matcher est une chaîne unique qui utilise | pour correspondre à plusieurs noms d'outils, par exemple "Edit|Write". Un séparateur , est équivalent, donc "Edit,Write" correspond aux mêmes outils. Avant v2.1.191, une virgule passait à l'évaluation regex et le matcher ne correspondait jamais, donc utilisez | si vous n'êtes pas sur v2.1.191 encore.
  • Un nom d'outil mal orthographié produit un matcher qui ne correspond à rien, donc le hook échoue silencieusement.
  • Une valeur de tableau est une erreur de schéma : Claude Code affiche un avis d'erreur de paramètres et rejette l'intégralité du fichier de paramètres utilisateur, projet ou local, claude doctor signale l'échec de validation, et aucun hook de ce fichier n'apparaît dans /hooks. Dans les paramètres gérés, Claude Code supprime la clé hooks entière du fichier qui contient le tableau, donc aucun des hooks de ce fichier ne s'applique. Les autres paramètres du fichier s'appliquent toujours, et claude doctor liste la clé supprimée.

Lorsque vous modifiez settings.json, la modification prend effet dans la session en cours après un bref délai de stabilité du fichier, même si vous créez le fichier ou le dossier .claude/ du projet lui-même après le démarrage de la session. Vous n'avez pas besoin de redémarrer. Avant v2.1.257, Claude Code ne détectait pas les modifications dans un dossier .claude/ créé après le démarrage de la session.

Si /hooks affiche toujours l'ancienne définition quelques secondes après l'enregistrement, exécutez /hooks à nouveau pour actualiser la vue.

Si /hooks affiche le hook mais qu'il ne se déclenche toujours pas, l'étape suivante consiste à regarder l'évaluation du hook en direct. Démarrez une session avec claude --debug et déclenchez l'appel d'outil. Le journal de débogage enregistre chaque événement, quels matchers ont été vérifiés, et le code de sortie et la sortie du hook. Consultez Debug hooks pour le format du journal et hooks troubleshooting pour les modèles d'échec courants.

Tester avec une configuration propre

Commencez par claude --safe-mode, qui lance une session avec toutes les personnalisations désactivées, y compris CLAUDE.md, les skills, les plugins, les hooks, les serveurs MCP, et les commandes et agents personnalisés. L'authentification, la sélection du modèle, les outils intégrés et les permissions fonctionnent normalement. Si le problème disparaît en mode sécurisé, l'une de ces surfaces en est la cause ; utilisez les vérifications ciblées ci-dessus pour trouver laquelle. Le mode sécurisé applique toujours les hooks gérés et la politique de paramètres de votre organisation. Les plugins gérés, les skills, CLAUDE.md et les serveurs MCP sont désactivés.

Si le problème persiste en mode sécurisé, ou si vos paramètres eux-mêmes sont suspects, comparez avec une session qui ne charge rien de votre configuration habituelle. Pointez CLAUDE_CONFIG_DIR vers un répertoire vide pour contourner tout ce qui se trouve sous ~/.claude, et lancez depuis un répertoire qui n'a pas de dossier .claude, .mcp.json ou CLAUDE.md afin que la configuration du projet soit également ignorée.

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

La session propre n'a aucun paramètre utilisateur ou projet, hooks, serveurs MCP, plugins ou mémoire. Au premier lancement, attendez-vous aux écrans de configuration initiale, en commençant par la sélection du thème. Si vous les voyez, le répertoire de configuration propre est en vigueur. Les lancements ultérieurs avec le même répertoire ignorent ces écrans car Claude Code y enregistre l'état de l'intégration.

  • Les paramètres gérés s'appliquent toujours si votre organisation les déploie. Claude Code lit les profils MDM, la politique de registre et managed-settings.json à partir d'emplacements en dehors du répertoire de configuration, et récupère les paramètres gérés par le serveur à nouveau pour la session propre une fois qu'elle dispose des identifiants
  • Vous serez invité à vous connecter à nouveau

Si le problème disparaît ici, la cause se trouve quelque part dans vos fichiers réels ~/.claude ou .claude du projet. Réintroduisez-les un à la fois, en copiant les fichiers dans le répertoire temporaire ou en lançant depuis votre projet, pour trouver lequel. S'il persiste dans la session propre, la cause se trouve en dehors de votre configuration utilisateur et projet. Exécutez /status pour vérifier si les paramètres gérés sont en vigueur, recherchez les variables d'environnement qui affectent Claude Code, puis consultez Troubleshooting.

Vérifier les causes courantes

La plupart des surprises de configuration remontent à un petit ensemble de règles d'emplacement et de syntaxe. Vérifiez-les avant de supposer un bogue :

Symptôme Cause Correction
Le hook ne se déclenche jamais matcher est un tableau JSON au lieu d'une chaîne Utilisez une chaîne unique avec | pour correspondre à plusieurs outils, par exemple "Edit|Write". Consultez matcher patterns.
Le hook ne se déclenche jamais matcher utilise , comme séparateur sur une version antérieure à v2.1.191 Claude Code v2.1.191 ou version ultérieure traite , comme un séparateur de liste comme |. Les versions antérieures évaluent une virgule comme un caractère littéral, donc "Edit,Write" ne correspond à rien. Utilisez | à la place, ou mettez à jour Claude Code.
Le hook ne se déclenche jamais La valeur matcher est en minuscules, par exemple "bash" La correspondance est sensible à la casse. Les noms d'outils sont en majuscules : Bash, Edit, Write, Read.
Le hook ne se déclenche jamais Les hooks sont définis dans un fichier autonome au lieu de settings.json Il n'y a pas de fichier hooks autonome pour la configuration du projet ou de l'utilisateur. Définissez les hooks sous la clé "hooks" dans settings.json. Seuls les plugins chargent un fichier hooks/hooks.json séparé. Consultez hook configuration.
Les permissions, hooks ou env définis globalement sont ignorés La configuration a été ajoutée à ~/.claude.json ~/.claude.json contient l'état de l'application et les bascules d'interface utilisateur. permissions, hooks et env appartiennent à ~/.claude/settings.json. Ce sont deux fichiers différents.
Une valeur settings.json semble ignorée La même clé est définie dans settings.local.json settings.local.json remplace settings.json, et les deux remplacent ~/.claude/settings.json. Consultez settings precedence.
Le skill n'apparaît pas dans /skills Le fichier skill est à .claude/skills/name.md au lieu d'être dans un dossier Utilisez un dossier avec SKILL.md à l'intérieur : .claude/skills/name/SKILL.md.
Le skill apparaît dans /skills mais Claude ne l'invoque jamais Le skill a disable-model-invocation: true dans son frontmatter, ou sa description ne correspond pas à la façon dont vous formulez la demande Vérifiez le badge dans /skills : un label « user-only » signifie que Claude ne le déclenchera pas de lui-même. Consultez skill invocation.
Les instructions du sous-répertoire CLAUDE.md semblent ignorées Les fichiers du sous-répertoire se chargent à la demande, pas au démarrage de la session Ils se chargent quand Claude lit un fichier dans ce répertoire avec l'outil Read, pas au lancement et pas lors de l'écriture ou de la création de fichiers là-bas. Consultez how CLAUDE.md files load.
Le sous-agent ignore les instructions CLAUDE.md Les agents Explore et Plan intégrés ignorent CLAUDE.md. Un sous-agent personnalisé le charge de la même manière que la conversation principale, sauf si sa définition définit omitClaudeMd Pour Explore ou Plan, reformulez l'instruction dans votre invite de délégation. Pour un sous-agent qui définit omitClaudeMd, supprimez le champ. Pour tout autre sous-agent personnalisé, mettez les instructions critiques dans le corps du fichier agent, qui devient l'invite système du sous-agent. Consultez what loads at startup.
La logique de nettoyage ne s'exécute jamais à la fin de la session Aucun hook SessionEnd configuré Ajoutez un hook SessionEnd dans settings.json. Consultez la hook events list.
Les serveurs MCP dans .mcp.json ne se chargent jamais Le fichier est sous .claude/, ou ses serveurs se trouvent sous une clé servers de haut niveau, comme dans le mcp.json de VS Code, au lieu de mcpServers La configuration MCP du projet va à la racine du référentiel sous .mcp.json, pas à l'intérieur de .claude/, avec les serveurs sous la clé mcpServers. Consultez MCP configuration.
Les serveurs MCP ajoutés sous mcpServers dans settings.json n'apparaissent jamais settings.json ne lit pas une clé mcpServers Définissez les serveurs du projet dans .mcp.json à la racine du référentiel, ou exécutez claude mcp add --scope user pour les serveurs à portée utilisateur. Consultez MCP configuration.
Le serveur MCP du projet ajouté n'apparaît pas L'invite d'approbation unique a été rejetée Les serveurs à portée de projet nécessitent une approbation. Exécutez /mcp pour voir le statut et approuver.
Le serveur MCP échoue au démarrage depuis certains répertoires command ou args utilise un chemin de fichier relatif Utilisez des chemins absolus pour les scripts locaux. Les exécutables sur votre PATH comme npx ou uvx fonctionnent tels quels.
Le serveur MCP démarre sans les variables d'environnement attendues L'entrée de configuration du serveur ne les définit pas, et elles ne se trouvent pas dans l'environnement que Claude Code transmet aux serveurs stdio : son propre environnement, moins les variables qu'il supprime des sous-processus Définissez env par serveur à l'intérieur de l'entrée .mcp.json du serveur, ce qui ne dépend pas de l'environnement de lancement ou de la confiance de l'espace de travail.
La règle de refus Bash(rm *) ne bloque pas /bin/rm ou find -delete Les règles Bash correspondent à la chaîne de commande littérale, pas à l'exécutable sous-jacent ; consultez what a Bash rule doesn't match Utilisez un PreToolUse hook ou le sandbox pour une garantie difficile.

Pour la référence complète sur chaque surface de configuration, consultez la page dédiée :