Claude Code /doctor : nettoyer sa config pour les modèles 5.x

Ouvre ton CLAUDE.md et cherche « NEVER », « YOU MUST », « CRITICAL ». Il y en a, et tu sais pourquoi. Un jour, un modèle a ignoré une règle de nommage, fait un commit sur la mauvaise branche ou un flush() dans une boucle. Tu as ajouté une ligne, en majuscules, répétée deux fois pour être tranquille. Ça a marché, donc tu l'as gardée. Les skills, les agents, les commandes et les hooks se sont empilés de la même façon, chacun écrit pour compenser un défaut précis d'un modèle précis.

Ces rustines ont un coût que personne ne mesure. Avec des modèles plus sensibles aux consignes et plus littéraux, une règle criée n'est plus une garantie : c'est un risque de sur-application, de rigidité et de contexte gaspillé à chaque session. Cet article traite ta configuration comme du code : elle a une dette technique, elle s'audite et elle se migre. Il ne reprend ni l'écriture d'un CLAUDE.md, couverte dans les fondamentaux de CLAUDE.md, ni les leviers d'économie de tokens. Il traite l'audit d'une configuration existante, livré en PR comme un refactoring.

Pourquoi ta config Claude Code vieillit-elle mal ?

Parce qu'un CLAUDE.md, une skill ou un agent est un prompt, calibré contre le comportement d'un modèle donné. Quand le modèle change, le défaut compensé disparaît, mais la compensation reste. Trois familles de règles périmées reviennent dans les configurations écrites pour Sonnet 4 ou Opus 4.x :

• Les rustines anti-paresse : « CRITICAL: you MUST use the Grep tool », « be thorough, never skip steps ». Le guide de prompting d'Anthropic l'explique pour Opus 4.5 et 4.6 : ces modèles étant plus réactifs au prompt système, un prompt conçu contre le sous-déclenchement peut désormais sur-déclencher. Le correctif recommandé est d'adoucir le langage : « CRITICAL: You MUST use this tool when… » devient « Use this tool when… ».
• Les béquilles de raisonnement : « think step by step », « écris tout ton raisonnement avant chaque modification ». Sur Opus 5.5, Sonnet 5.5 et Haiku 5.5, le raisonnement adaptatif est toujours actif et le levier est l'effort. Le guide Opus 5.5 recommande de retirer ces consignes.
• Les descriptions qui crient : « USE THIS SKILL ALWAYS ». Elles font déclencher la skill hors de propos, et la description coûte du contexte à chaque tour.

Le piège inverse existe. La page « Prompting Claude Sonnet 5 » décrit un modèle plus littéral, qui n'étend pas de lui-même une consigne d'un cas à un autre. Une règle vague comme « respecte nos conventions » a donc moins d'effet qu'avant. Le ménage ne consiste pas à tout adoucir, mais à supprimer le volume, expliquer le pourquoi et expliciter le périmètre. Les défauts ont aussi bougé : l'effort par défaut est medium sur les trois modèles 5.5. Un effort high posé à l'époque d'Opus 5 est devenu un choix coûteux, détaillé dans le choix du modèle et de l'effort.

Comment mesurer avant de couper ?

Ne supprime rien sans chiffres. Quatre commandes donnent l'état des lieux, et un instantané avant toute modification te servira de point de comparaison :

# Dans une session Claude Code
/context        # occupation du contexte : CLAUDE.md, skills, MCP, outils
/skill-doctor   # coût en contexte de chaque skill et fréquence d'usage
/usage          # attribution par skill, sous-agent, plugin, serveur MCP (24 h / 7 j)
/insights       # rapport HTML des sessions récentes

# Hors session, en texte
claude -p "/skill-doctor"

• /skill-doctor (bloc v2.1.261 du changelog, septembre 2026) liste les skills jamais invoquées et leur coût en contexte, ainsi que les plugins inutilisés récemment. Il exclut les skills intégrées. C'est le meilleur indicateur d'élagage, parce qu'il repose sur l'usage réel et pas sur ton souvenir.
• /usage répartit l'usage récent par skill, sous-agent, plugin et serveur MCP sur les plans Pro, Max, Team et Enterprise. Les chiffres sont calculés localement, donc approximatifs. Un serveur MCP à 0 % sur sept jours est candidat à la suppression.
• /context montre le poids réel de chaque bloc au démarrage. Note les pourcentages des fichiers mémoire et des skills : ce sont eux que tu vas faire baisser.

Que font /doctor et /doctor prompt-audit ?

Ce sont deux modes distincts, et c'est la confusion la plus fréquente. /doctor (alias /checkup) est le bilan de l'installation : settings illisibles, skills, serveurs MCP et plugins inutilisés rapportés à leur coût, hooks lents, permissions. Depuis juillet 2026, il propose aussi des coupes dans un CLAUDE.md versionné : contenu que Claude peut déduire du code (arborescences, listes de dépendances, vues d'architecture), en gardant les pièges, les justifications et les conventions qui s'écartent des défauts. Il présente ses conclusions et demande confirmation avant toute modification.

/doctor prompt-audit, ajouté en v2.1.283 le 25 septembre 2026, audite tes instructions, pas ton installation. D'après la doc mémoire, son périmètre par défaut couvre CLAUDE.md, CLAUDE.local.md, AGENTS.md, ainsi que les rules, skills, commandes, sous-agents et output styles de .claude/ et ~/.claude/. Il cherche les consignes écrites pour d'anciens modèles, les références à des fichiers ou commandes disparus, et les fichiers qui se contredisent. Il propose des éditions, et rien n'est modifié tant que tu ne demandes pas l'application.

/doctor prompt-audit                          # tout le périmètre par défaut
/doctor prompt-audit .claude/skills/deploy    # un fichier ou un dossier précis
/doctor prompt-audit .claude/commands         # les commandes custom

Deux précisions. L'audit passe par la skill intégrée /claude-api : il est indisponible si ton équipe l'a coupée via skillOverrides ou disableBundledSkills. Et il ne faut pas le confondre avec /claude-api prompt-audit, qui audite les prompts de ton code applicatif appelant l'API Anthropic. Surtout, l'outil ne connaît pas ton métier : il ne peut pas savoir qu'un « NEVER use findAll() » est un garde-fou voulu contre une dette Doctrine précise. Traite sa sortie comme une revue de code, règle par règle, jamais en « appliquer tout ».

Comment réécrire les règles NEVER et MUST pour un modèle 5.x ?

Remplace chaque règle criée par une règle qui donne la raison et le périmètre. Le guide d'Anthropic le formule ainsi : donner le contexte ou la motivation derrière une consigne aide Claude à mieux cerner ton objectif. Quatre patrons reviennent dans les configurations PHP et Symfony.

<!-- 1. AVANT : l'interdiction criée -->
- NEVER use $em->flush() inside a loop. THIS IS CRITICAL.
- YOU MUST ALWAYS use QueryBuilder for ANY query with joins!!!

<!-- APRÈS : règle, raison, périmètre -->
- Un seul flush() par unité de travail (fin de handler Messenger ou de
  contrôleur). Un flush dans une boucle émet un UPDATE par itération et
  casse la cohérence transactionnelle.
- Les requêtes avec jointure passent par un repository dédié
  (src/Repository/), jamais par du DQL dans un contrôleur ou un service,
  y compris dans les commandes console.

<!-- 2. AVANT : la rustine anti-paresse -->
- ALWAYS run ALL the tests before answering. Be EXTREMELY thorough.

<!-- APRÈS : on ne garde que ce qui est propre au projet -->
- Après une modification de src/, lance la suite unitaire et PHPStan :
  docker compose exec php vendor/bin/phpunit --testsuite unit
  docker compose exec php vendor/bin/phpstan analyse
  La suite fonctionnelle prend plusieurs minutes : ne la lance qu'avant le commit.

<!-- 3. AVANT : la béquille de raisonnement -->
- Think step by step. List 5 approaches and justify your choice before any edit.

<!-- APRÈS : supprimé. Le levier est /effort, le raisonnement est toujours actif en 5.5 -->

<!-- 4. AVANT : la règle vague -->
- Respecte nos conventions de nommage.

<!-- APRÈS : le périmètre est dit, un modèle littéral ne généralise pas seul -->
- Handlers Messenger : suffixe Handler, un handler par message, dans
  src/<Contexte>/Application/. Vaut pour tous les contextes, pas seulement Billing.

Pour chaque ligne restante, applique une grille de tri en quatre questions. Claude peut-il le déduire du code ? Supprime. Est-ce un piège propre au projet ou une convention hors défaut ? Garde, avec le pourquoi. N'est-ce vrai que pour une partie de l'arborescence ? Déplace vers .claude/rules/ avec un champ paths. La règle doit-elle tenir à chaque fois, sans exception ? C'est un hook ou une règle de permission, pas une phrase : un hook bloque, une phrase suggère. Vise moins de 200 lignes par CLAUDE.md, sachant que les @imports ne réduisent pas le contexte. La méthode de découpage est dans l'optimisation avancée de CLAUDE.md.

Comment nettoyer les skills inutilisées et leurs descriptions ?

Chaque description de skill figure dans le listing à chaque tour, utilisée ou non. D'après la doc des skills, ce listing a un budget de 1 % de la fenêtre de contexte, avec un plafond de 1 536 caractères par entrée ; quand il déborde, les descriptions des skills les moins invoquées sautent en premier. Trois actions, par ordre d'efficacité :

• disable-model-invocation: true pour les skills manuelles (déploiement, release, migrations) : la description sort entièrement du contexte. Attention, une telle skill ne peut plus être préchargée dans un sous-agent via skills:.
• skillOverrides dans les settings, pour les skills partagées que tu ne veux pas éditer : états on, name-only, user-invocable-only ou off. La commande /skills les écrit pour toi.
• Réécrire la description : le cas d'usage d'abord, sans majuscules, avec when_to_use et paths pour cibler le déclenchement.

# AVANT
---
name: symfony-migration
description: ALWAYS USE THIS SKILL WHENEVER THE USER MENTIONS MIGRATIONS, DATABASE, DOCTRINE OR SCHEMA!!!
---

# APRÈS
---
name: symfony-migration
description: Génère et vérifie une migration Doctrine (diff, revue du SQL, rollback). À utiliser quand une entité change de schéma.
when_to_use: Demandes du type « ajoute une colonne », « renomme ce champ », « crée la migration ».
paths:
  - "src/Entity/**/*.php"
  - "migrations/**/*.php"
---

Les commandes custom de .claude/commands/ sont désormais fusionnées dans le système de skills : applique-leur la même grille. Une commande obsolète est typiquement un mode d'emploi d'outils que Claude maîtrise déjà. Après modification, /reload-skills rescanne sans redémarrer.

Que vérifier dans les agents, les settings et les hooks ?

Les sous-agents de .claude/agents/ héritent souvent d'un modèle et d'un effort choisis il y a des mois. Rends-les explicites, d'après la doc des sous-agents :

---
name: symfony-reviewer
description: Revue de code Symfony/Doctrine en lecture seule.
tools: Read, Grep, Glob
model: sonnet
effort: medium
maxTurns: 30
autoCompactWindow: 200000   # entier brut, de 100000 à 1000000 (v2.1.296+)
omitClaudeMd: true          # n'embarque pas CLAUDE.md dans la délégation (v2.1.271+)
---
Tu relis un diff Symfony. Signale uniquement les régressions de sécurité
et les requêtes N+1, sous forme fichier:ligne et raison.

Piège : autoCompactWindow: 200k est lu comme 200 et sort de la plage. Plus généralement, Claude Code ignore en silence les champs de frontmatter inconnus : après réécriture, lance claude --debug et cherche « does not recognize or apply » dans le fichier de debug de la session (v2.1.296+).

Côté settings, plusieurs réglages n'ont plus d'effet sur la génération 5.5. Ils restent valides sur Opus 4.6 et Sonnet 4.6 : si ton équipe est mixte, documente la raison de chaque variable conservée.

• MAX_THINKING_TOKENS : une valeur positive est ignorée par les modèles à raisonnement adaptatif, et 0 n'éteint rien en 5.5. À supprimer, l'effort est le levier.
• alwaysThinkingEnabled: false et CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING : sans effet sur Sonnet 5+, Haiku 5.5, Opus 4.7+ et Fable. À supprimer.
• effortLevel: "high" : plus un défaut, et la clé de premier niveau ne s'applique pas à Opus 5.5. Remesure, puis fixe l'effort par modèle avec /effort.
• /ultraplan : supprimé en v2.1.222 (août 2026). Retire-le des commandes, scripts et documentations d'équipe ; /plan le remplace.

Une variable récente mérite d'être connue : CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 (v2.1.299, 14 octobre 2026) fait recevoir à Claude le chemin des fichiers cités avec @ au lieu de leur contenu. Elle est ignorée dans les settings de projet : à poser au niveau utilisateur ou managé. Pour les hooks et les serveurs MCP, /hooks liste les hooks configurés (cherche les scripts disparus, qui échouent à chaque événement) et /mcp permet de désactiver un serveur pour tester avant de le retirer du .mcp.json versionné.

Comment livrer le ménage et vérifier que rien n’a cassé ?

Une configuration est du code : elle suit le circuit du code. Sur une branche dédiée, et dans cet ordre :

• Prendre l'instantané : /context, /skill-doctor, /usage sur 24 heures et 7 jours.
• Lancer /doctor et n'accepter que les coupes de contenu déductible du code.
• Lancer /doctor prompt-audit et valider chaque proposition, fichier par fichier.
• Réécrire les règles criées avec raison et périmètre ; passer en hook ce qui doit tenir à chaque fois.
• Déplacer le conditionnel vers .claude/rules/ avec paths.
• Passer les skills manuelles en disable-model-invocation, couper les inutilisées.
• Rendre explicites modèle, effort et compaction des agents, puis vérifier avec claude --debug.
• Supprimer les réglages sans effet et les références à ultraplan.
• Rejouer deux ou trois tâches représentatives et comparer /context avant et après.

git switch -c chore/claude-config-5x
git add CLAUDE.md .claude/ .mcp.json
git commit -m "chore(claude): migrer la config vers les modèles 5.x"

Dans la description de la PR, mets les chiffres avant et après, la liste des règles supprimées avec leur justification, et ce que tu as choisi de garder malgré l'audit. Le relecteur doit pouvoir contester chaque suppression : ce sont souvent les collègues qui se souviennent de l'incident derrière une règle. Si une règle manque, un git revert la ramène. Je n'ai pas de chiffre universel de gain à te donner : il dépend de ta configuration et se mesure chez toi. Le contexte allégé se traduit en tokens économisés, selon les mécanismes décrits dans l'article sur les leviers natifs.

Faut-il auditer sa config à chaque nouveau modèle ?

Oui. La dette revient : la prochaine rustine sera écrite pour le prochain défaut. Planifie une revue de configuration à chaque changement de modèle par défaut et à chaque montée de version importante de Claude Code, au même titre qu'une montée de version de framework. Les outils d'audit proposent, ils ne tranchent pas : la décision reste humaine, et c'est précisément pour cela qu'elle doit passer en revue de code. Ce qui marche sur un poste doit devenir une convention du dépôt, relue par l'équipe sur son code réel.

Concrètement, cette semaine : une demi-journée, une branche chore/claude-config-5x, /skill-doctor et le prompt-audit de /doctor, trois règles en majuscules réécrites avec leur raison, un invariant critique déplacé dans un hook, et une PR que l'équipe a le droit de contester. Si ton contexte reste lourd malgré le ménage, le prochain article passe au crible les outils tiers d'économie de tokens, avec leurs limites.

Écrit par

Flavien Métivier

Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.

Mon parcours