Détail de Claude Code /checkup : nettoyer le contexte, corriger la configuration et améliorer la sécurité de l'agent

Introduction

Claude Code a désormais intégré un diagnostic de configuration plus performant. Dans la version 2.1.205, Anthropic a étendu le workflow existant /doctor afin qu'il puisse diagnostiquer les problèmes de configuration et aider à les résoudre. /checkup est disponible comme alias pour ce même workflow intégré.

Ce changement peut sembler mineur car il est déclenché par une simple commande oblique. En pratique, il répond à un problème courant pour les configurations Claude Code de longue durée : les compétences inutilisées, les serveurs Model Context Protocol obsolètes, les fichiers d'instructions trop volumineux, les hooks lents, les installations obsolètes et les invites d'autorisation répétées rendent progressivement l'environnement plus difficile à comprendre.

L'objectif n'est pas seulement de signaler qu'il y a un problème. Le diagnostic mis à jour peut inspecter la configuration, expliquer les modifications proposées et demander l'approbation avant de les appliquer.

/checkup

Vous pouvez également utiliser la commande canonique :

/doctor

Un diagnostic de configuration en une seule commande

Selon le journal des modifications de Claude Code 2.1.205, /doctor est désormais un diagnostic complet de configuration qui peut identifier et résoudre les problèmes, tandis que /checkup en est l'alias.

Ceci est différent de la commande terminal séparée :

claude doctor

La commande terminal affiche des diagnostics en lecture seule concernant l'installation et les paramètres, sans démarrer de session interactive. Le workflow intégré /doctor ou /checkup peut aller plus loin en proposant des correctifs et en laissant Claude coordonner le nettoyage via ses outils disponibles.

Le créateur de Claude Code, Boris Cherny, a décrit plusieurs tâches que le diagnostic est conçu pour prendre en charge :

1. Nettoyer les compétences inutilisées, les serveurs MCP et les plugins.
2. Dédupliquer les instructions locales CLAUDE.md par rapport aux instructions du projet validées.
3. Diviser un fichier CLAUDE.md racine trop volumineux en fichiers imbriqués et compétences réutilisables.
4. Identifier et désactiver les hooks lents.
5. Mettre à jour Claude Code vers la dernière version disponible.
6. Activer le mode automatique par défaut lorsque cela est approprié.
7. Pré-approuver les commandes en lecture seule fréquemment rejetées.
8. Détecter d'autres problèmes de configuration qui ralentissent ou rendent l'environnement moins fiable.

La commande demande une confirmation avant d'apporter des modifications.

Ce que le diagnostic examine réellement

1. Compétences, serveurs MCP et plugins inutilisés

Claude Code peut être étendu avec des compétences, des plugins, des hooks et des serveurs MCP. Ces intégrations sont utiles, mais une configuration mature accumule souvent des composants qui ne sont plus

pertinent.

Il est possible qu'un serveur MCP ait été ajouté pour un ancien système de suivi de tickets. Une compétence peut avoir été créée pour un flux de travail que l'équipe n'utilise plus. Un plugin peut encore être activé alors que ses commandes ont été remplacées.

Le diagnostic peut identifier ces composants inutilisés et proposer de les supprimer ou de les désactiver.

C'est important car les outils et les instructions peuvent occuper de l'attention et du contexte, même lorsqu'ils n'aident pas activement à la tâche en cours. Un nombre réduit d'intégrations non pertinentes rend également le modèle d'autorisation plus facile à auditer.

2. Instructions CLAUDE.md dupliquées ou trop volumineuses

Les fichiers CLAUDE.md fournissent des instructions persistantes pour Claude Code. Ils peuvent contenir des commandes de build, des conventions de codage, des notes architecturales, des exigences de test et des règles spécifiques au projet.

Ces fichiers sont chargés dans le contexte de la session. Anthropic recommande de garder chaque fichier concis et de vérifier régulièrement les fichiers d'instructions imbriqués pour détecter les règles obsolètes ou conflictuelles.

Avec le temps, un projet peut développer plusieurs problèmes courants :

• La même règle apparaît à la fois dans les fichiers locaux et dans ceux suivis par le versionnement.
• D'anciennes instructions subsistent après des modifications du code source.
• Un fichier racine se transforme en une longue collection de procédures sans lien.
• Les règles à l'échelle de l'équipe et les règles spécifiques à un répertoire sont mélangées.
• Des workflows détaillés sont stockés dans CLAUDE.md alors qu'ils fonctionneraient mieux sous forme de compétences à la demande.

Le diagnostic peut comparer les instructions locales et celles du projet, identifier les doublons et suggérer une structure plus ciblée.

Une disposition pratique pourrait ressembler à ceci :

projet/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   │   ├── frontend.md
│   │   ├── backend.md
│   │   └── testing.md
│   └── skills/
│       └── release/
│           └── SKILL.md
└── packages/
    └── api/
        └── CLAUDE.md

Le fichier racine peut contenir uniquement les règles nécessaires à l'ensemble du dépôt. Des instructions plus spécifiques peuvent être chargées lorsque Claude travaille dans le répertoire concerné, tandis que les procédures réutilisables peuvent devenir des compétences qui se chargent lorsqu'elles sont invoquées.

3. Hooks lents ou redondants

Les hooks sont des actions déterministes qui s'exécutent à des moments précis du cycle de vie de Claude Code. Ils peuvent formater des fichiers, valider des commandes, appliquer des politiques, envoyer des notifications ou intégrer Claude Code à des systèmes internes.

Un hook n'est utile que si sa valeur justifie son coût. Un script qui ajoute deux ou trois secondes à chaque appel d'outil peut créer un retard important sur une session longue.

Le diagnostic peut aider à identifier les hooks qui sont :

• Constamment lents.
• Déclenchés plus souvent que prévu.
• En double avec une autre étape de validation.
• Référençant des scripts qui n'existent plus.
• Produisant des erreurs que l'utilisateur a appris à ignorer.
• N'étant plus liés à un flux de travail actif.

Désactiver un hook inutile n'améliore pas seulement la rapidité. Cela réduit également le bruit, ce qui permet de remarquer plus facilement les échecs importants.

4. Problèmes d'installation et de mise à jour

Un lanceur défectueux, une installation obsolète ou une mise à jour partielle peuvent créer un comportement confus. Le diagnostic de configuration peut vérifier l'état de l'installation et recommander la mise à jour de Claude Code.

Pour vérifier manuellement la version installée, utilisez :

claude --version

La méthode de mise à jour exacte dépend de la façon dont Claude Code a été installé.

Les déploiements d'entreprise gérés peuvent volontairement épingler une version, les utilisateurs ne doivent donc pas outrepasser la politique de l'organisation simplement parce qu'une version plus récente existe.

5. Invites répétées d'autorisation en lecture seule

Claude Code utilise un système d'autorisations qui sépare les inspections à faible risque des actions modifiant l'environnement.

La documentation de sécurité d'Anthropic indique qu'un ensemble intégré de commandes en lecture seule, incluant des commandes comme ls, cat et git status, peut s'exécuter sans invite. Les commandes qui modifient des fichiers, exécutent des opérations Bash potentiellement modificatrices ou accèdent à des systèmes supplémentaires peuvent nécessiter une approbation.

Si un utilisateur rejette ou approuve manuellement à plusieurs reprises une commande inoffensive en lecture seule, le diagnostic peut suggérer une règle d'autorisation plus claire. L'objectif est de réduire la fatigue liée aux invites sans accorder un accès en écriture étendu.

Une bonne règle d'autorisation doit être restreinte. Approuver un motif spécifique en lecture seule est plus sûr que d'autoriser une catégorie entière de shell ou d'outil.

Pourquoi la maintenance du contexte est importante

Un agent de codage IA doit intégrer plusieurs types d'informations dans un seul contexte de travail :

• La conversation en cours.
• Les fichiers source pertinents.
• Les résultats d'outils et les sorties de commandes.
• Les instructions CLAUDE.md.
• Les descriptions de compétences.
• Les définitions d'outils MCP.
• Les plans, l'état des tâches et les résultats intermédiaires.

La fenêtre de contexte est limitée. Une grande quantité d'informations de configuration non pertinentes peut laisser moins de place au problème réel.

Cela ne signifie pas que chaque compétence installée ou serveur MCP est automatiquement chargé en totalité. Claude Code utilise des mécanismes tels que les corps de compétences à la demande et la découverte d'outils pour contrôler l'utilisation du contexte. Malgré cela, une configuration inutile crée une complexité supplémentaire et augmente la probabilité que des instructions ou intégrations obsolètes influencent une session.

Une configuration saine nécessite donc le même type de maintenance qu'un projet logiciel :

1. Supprimez ce qui n'est plus utilisé.
2. Gardez les instructions globales courtes.
3. Déplacez les procédures spécialisées dans des fichiers ou compétences délimités.
4. Auditez les intégrations et les autorisations.
5. Mesurez le coût des hooks.
6. Revoyez la configuration après des changements majeurs du projet.

Du diagnostic au nettoyage assisté

Les outils de diagnostic antérieurs s'arrêtaient souvent après avoir listé les erreurs. L'utilisateur devait encore comprendre chaque avertissement, trouver le fichier pertinent, décider d'une correction et l'appliquer manuellement.

Le diagnostic actualisé en session suit un modèle plus agentique :

1. Inspectez l'environnement actuel.
2. Identifiez les problèmes spécifiques.
3. Estimez le bénéfice d'un nettoyage.
4. Présentez les modifications proposées.
5. Laissez l'utilisateur choisir un nettoyage complet, des corrections sélectionnées ou une option de simple rapport.
6. Appliquez uniquement les modifications approuvées.
7. Laissez les modifications de fichiers visibles pour révision.

Cela rend le flux de travail plus proche d'un assistant de maintenance interactif que d'un rapport d'erreur passif.

L'étape d'approbation est importante. Un outil ne devrait pas

supprimer silencieusement une compétence de projet, réécrire des fichiers d'instructions ou modifier le comportement des autorisations simplement parce qu'il juge la configuration inefficace.

Améliorations de sécurité autour des commandes autonomes

La même version inclut également des modifications visant à réduire les risques lorsque Claude Code agit de manière plus autonome.

Protection contre les approbations falsifiées dans les journaux de session

Les notifications de tâches en arrière-plan indiquent désormais explicitement lorsqu'aucune intervention humaine n'a eu lieu. Cela vise à empêcher qu'un texte dans un journal de session ne soit confondu avec une véritable approbation utilisateur.

Pour un agent, la différence entre « le journal contient un texte similaire à une approbation » et « l'utilisateur a réellement approuvé cette action via l'interface » est cruciale. Les décisions sensibles à la sécurité nécessitent un canal d'approbation de confiance.

Confirmation supplémentaire pour les commandes rm -rf risquées

Le journal des modifications note également une amélioration du mode automatique : Claude Code demande confirmation avant d'exécuter rm -rf lorsque le chemin contient une variable qu'il ne peut pas résoudre à partir du contexte.

Un exemple dangereux est :

rm -rf "$TARGET_DIR/"

Si TARGET_DIR est vide ou mal développé, le résultat peut être très différent de ce que l'auteur du script avait prévu.

La bonne leçon n'est pas qu'une simple demande de confirmation rend les commandes shell destructives sûres. Les utilisateurs doivent toujours inspecter le chemin résolu, utiliser un bac à sable ou un environnement jetable lorsque cela est possible, maintenir des sauvegardes et éviter les commandes de suppression larges dans les systèmes de production.

L'autonomie a besoin de limites

La version combine deux objectifs qui peuvent sembler en conflit :

• Réduire les interruptions inutiles pour les tâches courantes et en lecture seule.
• Ajouter une confirmation plus forte autour des actions incertaines ou destructrices.

Ces objectifs fonctionnent ensemble. Un agent utile doit se déplacer rapidement à l'intérieur d'une zone de sécurité bien définie et ralentir lorsqu'il s'approche d'une limite avec des conséquences irréversibles.

/doctor, /checkup, et claude doctor

Les noms similaires peuvent prêter à confusion.

Pour la plupart des utilisateurs qui souhaitent que Claude inspecte et aide à nettoyer la configuration active, /doctor ou /checkup est la commande appropriée.

Pour les scripts, les vérifications de support ou les diagnostics d'installation rapide en dehors d'une session, claude doctor est plus approprié.

Une façon sûre d'exécuter /checkup

Étape 1 : Vérifier l'état actuel du dépôt

Avant d'autoriser un outil à modifier des fichiers de configuration, assurez-vous que le travail important est validé ou sauvegardé.

git status

Examinez les fichiers non validés et évitez de mélanger des modifications de code sans rapport avec le nettoyage de la configuration.

Étape 2 : Démarrer Claude Code dans le projet concerné

cd /chemin/vers/projet
claude

L'exécution de la vérification depuis le bon dépôt est importante car les instructions du projet, les hooks, les plugins et les paramètres MCP peuvent être limités à ce contexte.

Étape 3 : Exécuter la vérification

/checkup

Lisez le rapport avant d'accepter les modifications.

Étape 4 : Choisir la portée

Selon ce que Claude

découvre que l’interface peut proposer des options telles que :

• Appliquer le nettoyage recommandé.
• Sélectionner des catégories individuelles.
• Conserver la configuration actuelle et générer un rapport.
• Discuter d’une recommandation avant de décider.

Privilégie un nettoyage sélectif lorsque le dépôt contient des outils internes personnalisés ou une configuration d’équipe partagée.

Étape 5 : Examiner le diff

Après la modification des fichiers de configuration, inspecte-les :

git diff

Porte une attention particulière à :

• CLAUDE.md et CLAUDE.local.md.
• Les fichiers sous .claude/.
• Les définitions de hooks.
• Les paramètres des plugins.
• La configuration MCP.
• Les règles d’autorisation.
• Toute compétence générée.

Étape 6 : Tester un workflow normal

Exécute une tâche représentative d’une utilisation quotidienne. Confirme que les outils requis fonctionnent toujours, que les instructions pertinentes sont toujours chargées, que les hooks continuent d’appliquer les règles importantes et que les invites de permission se comportent comme prévu.

Étape 7 : Commiter le nettoyage séparément

Lorsque la configuration partagée du projet change, utilise un commit ciblé afin que les collègues puissent le réviser et le révoquer indépendamment.

git add CLAUDE.md .claude/
git commit -m "chore: nettoyage de la configuration Claude Code"

Ajuste les chemins en fonction des fichiers réellement modifiés.

Quand ne pas accepter immédiatement un nettoyage automatique

N’approuve pas chaque recommandation sans révision lorsque :

• Le dépôt utilise des paramètres gérés par l’organisation.
• Les serveurs MCP fournissent des intégrations critiques pour l’activité.
• Les hooks appliquent des politiques de sécurité ou de conformité.
• CLAUDE.md contient une duplication intentionnelle pour la portabilité.
• Le projet épingle Claude Code à une version testée.
• Plusieurs équipes dépendent du même plugin ou de la même hiérarchie d’instructions.
• Le nettoyage propose de modifier le comportement des autorisations.
• L’arbre de travail contient des modifications non commitées non liées.

Dans ces cas, utilise d’abord le checkup comme un rapport d’audit. Discute ou applique les changements via le processus de révision normal de l’équipe.

FAQ

Qu’est-ce que la commande /checkup de Claude Code ?

/checkup est un alias pour le workflow /doctor étendu en session introduit dans Claude Code 2.1.205. Il audite les problèmes de configuration et peut proposer des correctifs pour la configuration, le contexte, les intégrations, les hooks, la santé de l’installation et les problèmes connexes.

/checkup est-il différent de /doctor ?

Dans les versions actuelles de Claude Code, /checkup est un alias pour /doctor. Ils invoquent le même checkup complet de configuration dans une session interactive Claude Code.

claude doctor est-il identique à /doctor ?

Non. claude doctor s’exécute depuis le terminal et imprime des diagnostics en lecture seule de l’installation et des paramètres sans ouvrir de session. La commande slash peut coordonner des correctifs après avoir demandé une approbation.

/checkup peut-il supprimer automatiquement des compétences ou des serveurs MCP ?

Le workflow peut identifier des composants inutilisés et proposer un nettoyage, mais il est conçu pour demander avant d’apporter des modifications. Les utilisateurs doivent examiner chaque suppression proposée, en particulier dans les projets partagés ou gérés.

Pourquoi un grand CLAUDE.md affecte-t-il Claude Code ?

Les instructions de CLAUDE.md entrent dans le contexte de la session, donc des fichiers longs ou dupliqués consomment de l’espace qui pourrait autrement être utilisé pour la tâche active. Anthropic recommande des instructions concises et des fichiers délimités pour les grands projets.

Chaque procédure doit-elle être déplacée hors de CLAUDE.md ?

Non. Les procédures stables

Les faits du projet, les règles de codage et les commandes requises appartiennent à CLAUDE.md. Les longues procédures réutilisables sont souvent mieux adaptées aux compétences, car leur contenu complet ne se charge que lorsque cela est nécessaire.

Est-ce que /checkup rend le mode automatique totalement sûr ?

Non. Il peut améliorer les paramètres par défaut et ajouter des protections, mais les utilisateurs restent responsables de la vérification des commandes et des autorisations. Les opérations destructrices, les écritures externes, l'accès à la production et la gestion des informations d'identification nécessitent toujours des contrôles rigoureux.

À quelle fréquence dois-je exécuter le bilan de configuration ?

Il n'y a pas de calendrier obligatoire. Il est utile après des modifications majeures de configuration, lorsque Claude Code semble plus lent ou moins cohérent, après l'ajout de plusieurs intégrations, ou dans le cadre d'une révision périodique de la maintenance du projet.

Outils connexes

• Claude Code : L'outil de codage agentique d'Anthropic pour les terminaux, IDE, bureau et le web.
• Claude Code Skills : Créez des procédures réutilisables et à la demande qui étendent Claude Code.
• Protocole de contexte de modèle dans Claude Code : Connectez Claude Code à des outils externes, API, bases de données et services.
• Claude Code Hooks : Exécutez une automatisation déterministe à des points définis du cycle de vie de l'agent.
• Claude Code Plugins : Empaquetez et distribuez des compétences, agents, hooks et intégrations MCP.
• Claude Agent SDK : Construisez des agents programmables avec les mêmes outils de base et la même boucle d'agent qu'utilise Claude Code.

Liens connexes

• Journal des modifications de Claude Code : Historique officiel des versions, y compris les modifications de configuration et de vérification de la version 2.1.205.
• Référence des commandes Claude Code : Référence pour les commandes slash intégrées et les compétences groupées.
• Référence CLI de Claude Code : Référence officielle pour les commandes de terminal et les indicateurs CLI.
• Comment Claude se souvient d'un projet : Guide pour structurer et maintenir les fichiers CLAUDE.md.
• Sécurité de Claude Code : Comportement des autorisations, sandboxing, contrôles d'approbation et conseils de sécurité.
• Paramètres de Claude Code : Étendues de configuration, paramètres gérés, plugins, politiques MCP et contrôles du système de fichiers.
• Dépannage de Claude Code : Guide officiel de diagnostic et de rétablissement.
• Automatiser les actions avec des hooks : Guide pratique pour créer et auditer les hooks de cycle de vie.

Résumé

Claude Code 2.1.205 transforme /doctor en un flux de travail plus large de maintenance de configuration et ajoute /checkup comme alias. La commande peut inspecter les extensions inutilisées, les instructions dupliquées, les fichiers CLAUDE.md surdimensionnés, les hooks lents, les problèmes d'installation,

et comportement de permission répétitif.

La partie la plus utile de cette mise à jour n'est pas qu'elle cache la maintenance derrière une seule commande, mais plutôt qu'elle permet au workflow d'expliquer les changements proposés et de maintenir l'utilisateur impliqué avant de modifier l'environnement.

Cette version renforce également un modèle important pour les outils agentiques : les opérations de lecture courantes devraient nécessiter moins de friction, tandis que les opérations incertaines ou destructrices devraient bénéficier de protections renforcées.

Une configuration Claude Code plus saine n'est pas celle qui possède le plus de compétences, de hooks et d'intégrations — c'est celle où chaque composant chargé a un objectif clair et où chaque action puissante a une limite appropriée.