Claude Code /doctor prompt-audit : auditer CLAUDE.md et les skills pour repérer les consignes obsolètes, et ce qu'il a trouvé chez nous

Dans Claude Code, /doctor prompt-audit est une commande qui fait lire à Claude vos fichiers d'instructions (CLAUDE.md, AGENTS.md, skills, commandes, etc.), y cherche les consignes devenues obsolètes ou contradictoires, puis propose des corrections. Vous ne recevez qu'un rapport et des propositions de diffs : pas un seul caractère de vos fichiers ne change tant que vous ne demandez pas à Claude d'appliquer quelque chose. Taper /checkup prompt-audit lance exactement le même audit.

Cet article explique ce que vérifie l'audit des prompts, comment le lancer et que faire des résultats. Il s'appuie sur le texte original de la documentation officielle de Claude Code (la section « Audit your instruction files » de How Claude remembers your project, ainsi que Commands et Skills), sur le CHANGELOG et sur le guide d'audit livré avec Claude Code. Tout ce qui concerne la spécification a été vérifié dans ces originaux au 3 octobre 2026. Les sections 7 et 8 racontent aussi ce qui s'est passé quand nous l'avons lancé sur les fichiers d'instructions de ce site (9 constats, 7 appliqués) et les limites que nous avons rencontrées.

1. Qu'est-ce que /doctor prompt-audit ? Un audit des consignes obsolètes et contradictoires

Claude Code charge CLAUDE.md et vos autres fichiers d'instructions à chaque démarrage. Ces fichiers grossissent à l'usage et accumulent des formulations appuyées écrites pour d'anciens modèles, des noms de fichiers et de commandes qui n'existent plus et des règles qui contredisent un autre fichier. /doctor prompt-audit est la commande qui charge Claude d'aller chercher précisément cela.

En résumé, d'après la documentation officielle :

• Ce qu'il cherche : les consignes écrites pour d'anciens modèles, les références à des fichiers ou des commandes inexistants et les fichiers qui se contredisent.
• Ce qu'il renvoie : un rapport des problèmes trouvés et des corrections proposées sous forme de diffs. Rien ne change dans vos fichiers tant que vous ne demandez pas à Claude de les appliquer.
• Fonctionnement : il passe par la skill /claude-api livrée avec Claude Code. Si vous avez désactivé cette skill dans vos paramètres (via skillOverrides, ou en activant disableBundledSkills), l'audit n'est pas disponible.
• Version : Claude Code v2.1.283 ou ultérieure. /checkup prompt-audit est la même commande.

L'entrée v2.1.283 du CHANGELOG ajoute /doctor prompt-audit (et /checkup prompt-audit) pour auditer CLAUDE.md, les skills, les agents et les commandes à la recherche de façons de rédiger les prompts pensées pour d'anciens modèles. La même version a aussi modifié l'audit pour placer en tête du rapport les chemins obsolètes, les commandes obsolètes et les fichiers d'instructions contradictoires, et pour conserver les mots-clés de profondeur de réflexion comme « think », que Claude Code prend officiellement en charge.

Pourquoi les consignes obsolètes posent-elles problème ? Le guide d'audit livré avec l'outil l'explique ainsi : les modèles actuels suivent les instructions de plus près et plus littéralement que les anciens. Les « CRITICAL » et « MUST » empilés pour qu'un ancien modèle ne laisse pas passer une règle frappent désormais trop fort : la règle est appliquée là où elle n'a pas lieu d'être et le modèle devient rigide. Le guide précise que le but n'est pas de raccourcir les instructions, mais de trouver celles qui ne correspondent plus au modèle actuel, au projet actuel ou à vos autres instructions.

2. Utilisation : il suffit de le taper, et un chemin réduit le périmètre

Dans une session Claude Code, tapez simplement :

/doctor prompt-audit

Sans argument, la documentation officielle indique que l'audit porte sur les fichiers suivants :

Pour n'auditer qu'un fichier ou un dossier, passez un chemin. L'exemple de la documentation officielle :

/doctor prompt-audit .claude/skills/deploy

D'après le guide livré avec l'outil, l'audit est conçu pour aller jusqu'au bout sans s'arrêter pour poser des questions. Il déduit de votre demande et des fichiers eux-mêmes le périmètre et le modèle de référence, puis énonce ces hypothèses en tête du rapport. Si une hypothèse est fausse, relancez-le avec un chemin plus précis. Pour les fichiers d'instructions, la référence est en général le modèle qui exécute l'audit (ou, si une skill ou un sous-agent impose son propre modèle, celui-ci).

Le guide indique aussi que l'audit ne lit ni les fichiers de paramètres de Claude Code (.claude/settings*.json) ni la configuration MCP (.mcp.json), parce qu'ils peuvent contenir des secrets. Les problèmes de permissions ou de hooks sortent donc du cadre de cet audit : c'est le rôle de /doctor tout court (voir la section 6).

3. Ce que l'audit considère comme « obsolète »

Le contenu de l'audit est décrit dans le guide livré avec Claude Code (les instructions de prompt-audit à l'intérieur de la skill /claude-api). En lisant les fichiers fournis avec la v2.1.286, nous avons constaté que les vérifications se répartissent en quatre groupes. Pour des fichiers d'instructions, ce sont les deux premiers qui font l'essentiel du travail.

Dans le groupe 2, les « chemins et commandes inexistants » sont traités avec une fermeté particulière par le guide. L'audit vérifie si chaque chemin cité dans vos fichiers d'instructions existe réellement dans le projet, et si les commandes et options sont définies dans vos scripts ou votre configuration, en lisant les fichiers plutôt qu'en exécutant la moindre commande. Tout ce qui contredit le contenu réel du projet devient un constat de confiance élevée.

Quand deux fichiers se contredisent, l'audit s'appuie sur git blame (l'historique qui indique qui a écrit chaque ligne et quand) pour déterminer lequel est le plus récent, et propose d'aligner l'ancien sur le nouveau. Mais si l'un des deux est une interdiction ou une règle de sécurité que la correction affaiblirait, ou si l'historique ne permet pas de savoir lequel est le plus récent, le guide demande de ne proposer aucune correction et de se contenter de le signaler comme une décision qui revient à l'utilisateur.

4. Ce qu'il ne supprime pas : ce n'est pas un audit pour « raccourcir »

Ce que nous avons le plus apprécié dans cet audit, c'est que le guide énonce clairement ce qui ne doit pas être supprimé. Il prévient qu'un audit qui coupe tout pénalise justement ceux qui ont rédigé des instructions soignées, et il demande de conserver ce qui suit, même si la formulation correspond à un motif repéré :

• Le contexte que seul l'auteur connaît : les faits sur le public, le produit et l'environnement, les exigences de qualité, les contraintes, et les raisons qui les motivent. Le guide affirme sans détour que le contexte n'est jamais du gaspillage.
• La longueur en soi : rien n'est coupé au seul motif d'être long. Ce qui fait des dégâts, ce sont les consignes obsolètes, pas le volume.
• Les étapes exactes des opérations délicates : un travail qui n'a qu'une seule procédure sûre, comme des commandes de suppression ou un flux d'authentification, peut rester entièrement détaillé.
• Les interdictions visant des erreurs qui se produisent encore : si l'erreur se reproduit avec les modèles actuels, la règle reste.
• Les doublons qui fonctionnent : un même contenu à deux endroits relève d'une préférence d'organisation, pas de l'audit, tant que les deux copies ne se contredisent pas.

Cela marche aussi dans l'autre sens. Si les modèles actuels gagneraient à recevoir une consigne supplémentaire, l'audit le propose. Et le guide précise que, lorsque rien n'apparaît, ne rien changer est le bon résultat.

5. Lire les résultats : le rapport et les diffs proposés

Vous recevez deux choses : un rapport d'audit et des corrections proposées sous forme de diffs. Chaque constat du rapport comporte six champs :

Seuls les constats de confiance élevée et moyenne entrent dans les diffs proposés. Ceux de confiance faible n'apparaissent que dans le rapport. Les diffs sont découpés en un bloc par constat, ce qui permet de ne retenir que ceux que vous voulez.

Pour les appliquer, demandez par exemple à Claude « applique les points 1, 3 et 4 ». Le guide précise aussi que les conflits entre fichiers et les réécritures d'un texte qui ne correspond pas au projet ne sont pas appliqués sur une demande globale du type « nettoie tout ». N'importe qui ayant accès en écriture au dépôt a pu modifier le texte le plus récent comme le projet lui-même : la conception part donc du principe qu'un humain vérifie chacun de ces points.

6. Différences avec /doctor, /claude-api prompt-audit et claude doctor

Quatre commandes portent des noms proches. Voici ce qu'en disent la documentation officielle (Commands et Skills) et le CHANGELOG :

Ce qui prête à confusion, c'est que /doctor lui-même s'occupe aussi de CLAUDE.md. La différence tient à l'objectif. /doctor cherche à réduire ce qui est chargé en permanence (supprimer les doublons, couper ce que le code apprend déjà à Claude, déplacer certains contenus là où ils ne se chargent qu'en cas de besoin). /doctor prompt-audit vérifie si le contenu est devenu obsolète ou se contredit. Quant à claude doctor dans le terminal, il ne lance pas d'audit des prompts.

Si Claude ne suit pas vos instructions parce qu'elles ne sont tout simplement pas chargées, cet audit n'y changera rien. Nous expliquons comment vérifier ce qui est chargé dans « Pourquoi les agents IA ignorent les règles .md : vérifier le chargement et les résultats avec Hooks et CI », et comment mesurer la part de votre contexte occupée par les fichiers d'instructions dans « Claude Code : qu'est-ce qui dévore vraiment votre contexte ? ».

7. Notre essai : l'audit du CLAUDE.md et de l'AGENTS.md de ce site

Le 3 octobre 2026, nous avons lancé /doctor prompt-audit sur les fichiers d'instructions qui servent au développement de ce site, depuis l'application de bureau Claude Code (Claude Code 2.1.286 intégré, avec Opus 5.5 comme modèle). Nos fichiers d'instructions sont AGENTS.md (les règles principales, partagées entre Claude Code et Codex) et CLAUDE.md (qui l'importe et ajoute des notes propres à Claude Code), soit environ 10 700 caractères au total. Nous ne gardons ni règles, ni skills, ni commandes sous .claude/.

Première surprise : l'audit n'a trouvé presque aucune formulation écrite pour d'anciens modèles. Pas un seul « think step by step », ni le moindre script d'étapes. La plupart des constats relevaient du groupe 2 de la section 3 (fichiers de configuration fragiles).

L'unique constat de confiance élevée était une vraie dérive. En ajoutant les outils d'audit, nous avions inscrit leurs noms dans la liste, mais oublié de réécrire l'explication juste à côté. À chaque chargement du fichier, Claude risquait de mal interpréter ce que désignait « les deux », et cela nous avait échappé à la relecture.

Le rapport indiquait aussi avoir confirmé que tous les chemins, noms d'outils et mémos référencés dans les fichiers d'instructions existent bel et bien. Il a même recoupé la version de PHP (conforme à la configuration Docker) et le nombre d'étapes d'une procédure (conforme à une liste dans un autre fichier).

Nous n'avons pas accepté tels quels les diffs proposés par Claude : nous ne les avons appliqués qu'après avoir vérifié chacun dans les fichiers d'origine. Ce sont les cinq constats de confiance moyenne qui ont demandé le plus de jugement. La proposition était de supprimer les comptes rendus d'incidents, mais ces comptes rendus sont précisément ce qui empêche de refaire les mêmes erreurs : nous les avons donc déplacés au lieu de les supprimer. Quand les dates et les nombres figuraient déjà dans un autre fichier, nous les avons simplement retirés des fichiers d'instructions ; les deux qui n'étaient consignés nulle part ailleurs ont été recopiés dans le fichier de suivi. Au final, les fichiers d'instructions sont passés d'environ 10 700 caractères à environ 40 caractères de moins seulement. La taille a à peine bougé ; seules les contradictions ont disparu.

Gardez à l'esprit qu'il s'agit d'une seule exécution sur un seul projet. C'est le modèle qui rédige l'audit : le relancer sur les mêmes fichiers peut donner un nombre de constats ou une formulation différents. Un projet qui a beaucoup de skills et de commandes sous .claude/ obtiendra sans doute des constats assez différents.

8. Inconvénients et points de vigilance

À l'usage et à la lecture de la documentation officielle et du guide, voici cinq points à garder en tête :

• Il consomme votre quota d'utilisation : Claude lit et audite vos fichiers d'instructions dans la session, ce qui est décompté de votre utilisation comme n'importe quel autre travail. La documentation officielle ne mentionne aucune tarification à part.
• N'appliquez pas les constats à l'aveugle : Claude ne sait pas forcément pourquoi une règle a été écrite. Dans notre cas, accepter tel quel « supprimer les comptes rendus d'incidents » aurait fait disparaître ce qui empêche de refaire les mêmes erreurs.
• Les résultats varient d'une exécution à l'autre : c'est un modèle qui rédige l'audit, donc le nombre et la formulation peuvent changer à chaque fois. Ne prenez pas une exécution sans constat pour la preuve qu'un fichier n'a aucun problème.
• Il ne regarde pas les fichiers de paramètres : il ne lit ni settings.json ni .mcp.json, donc les problèmes de permissions, de hooks et de MCP n'apparaîtront pas. Utilisez /doctor pour ceux-là.
• Il ne garantit pas que votre contenu est juste : il repère les chemins manquants et les contradictions, mais il ne juge pas si votre politique est la bonne. Cette décision vous appartient.

Le guide lui-même traite les suppressions comme des hypothèses, pas comme des conclusions. Une fois une instruction retirée, il faut vérifier en conditions réelles que le comportement qu'elle imposait ne s'est pas dégradé.

9. Quand lancer un audit des prompts

Le guide décrit les prompts comme des artefacts propres à un modèle donné, où les lignes nécessaires à une génération deviennent un poids mort à la suivante, et il recommande de refaire l'audit à chaque sortie d'un nouveau modèle. À notre avis, ces trois situations s'y prêtent bien :

• Quand vous passez à une nouvelle génération de modèles : repérer les formulations fortes et les contournements hérités des anciens modèles
• Après une refonte importante de vos fichiers d'instructions : comme dans notre essai, les nouvelles règles et les anciennes explications ont tendance à diverger
• Quand vous partagez vos fichiers d'instructions entre plusieurs outils, comme Claude Code et Codex : les contradictions entre AGENTS.md et CLAUDE.md deviennent plus faciles à repérer

En revanche, si vos fichiers d'instructions sont courts et changent rarement, rien ne presse. Le guide rappelle d'ailleurs que ne rien trouver est un résultat correct.

Conclusion

/doctor prompt-audit est une commande qui cherche dans vos fichiers d'instructions (CLAUDE.md, AGENTS.md, skills, etc.) les formulations écrites pour d'anciens modèles, les chemins et commandes inexistants et les règles contradictoires, puis renvoie un rapport et des propositions de diffs. Elle est disponible dans Claude Code v2.1.283 et versions ultérieures, et rien ne change tant que vous ne le demandez pas.

Le guide d'audit protège le contexte, les raisons et les interdictions visant des erreurs qui se produisent encore, afin que l'exercice ne se transforme pas en audit pour « raccourcir ». Sur les fichiers d'instructions de ce site, il n'a trouvé presque aucune formulation dépassée, mais il a mis au jour une explication que nous avions oublié de réécrire après l'ajout d'une règle, une vraie dérive.

La démarche sûre consiste à vérifier chaque constat dans le fichier d'origine et à déplacer plutôt que supprimer le texte qui a une raison d'être. Le lancer une fois après un changement de modèle ou une refonte de vos fichiers d'instructions permet de repérer des contradictions passées inaperçues à la relecture.

FAQ

Q. /doctor prompt-audit va-t-il réécrire mon CLAUDE.md tout seul ?

R. Non. La documentation officielle indique qu'il renvoie un rapport et des corrections proposées, et que rien ne change dans vos fichiers tant que vous ne demandez pas à Claude de les appliquer. Même alors, vous pouvez choisir proposition par proposition.

Q. Quelle différence entre /doctor prompt-audit et /checkup prompt-audit ?

R. Aucune. /checkup est un alias de /doctor, et l'entrée v2.1.283 du CHANGELOG mentionne /doctor prompt-audit avec /checkup prompt-audit.

Q. Audite-t-il aussi l'AGENTS.md destiné à Codex ?

R. Oui. La documentation officielle cite AGENTS.md à côté de CLAUDE.md et CLAUDE.local.md parmi les fichiers audités quand vous ne passez aucun argument. Si vous partagez ces deux fichiers, il est aussi efficace pour repérer leurs contradictions.

Q. Je l'ai tapé, mais l'audit ne démarre pas.

R. Vérifiez d'abord votre version : /doctor prompt-audit nécessite la v2.1.283 ou ultérieure. Si votre version est assez récente et que cela ne fonctionne toujours pas, vérifiez si vous avez désactivé la skill intégrée /claude-api dans vos paramètres (skillOverrides ou disableBundledSkills). Notez aussi que claude doctor tapé dans le terminal ne fait que diagnostiquer votre installation et ne lance pas cet audit.

Q. Peut-il auditer le prompt système d'une application construite sur l'API ?

R. Oui, mais utilisez pour cela /claude-api prompt-audit (v2.1.221 ou ultérieure). Il audite vos prompts, vos descriptions d'outils et votre code d'appel à l'API à la recherche de façons de rédiger pensées pour d'anciens modèles, et propose des diffs.

Sources

• Documentation de Claude Code : How Claude remembers your project (section « Audit your instruction files »)
• Documentation de Claude Code : Commands (lignes /doctor et /claude-api)
• Documentation de Claude Code : Skills (sous-commandes de la skill intégrée /claude-api et versions requises)
• Claude Code : CHANGELOG (v2.1.283)
• Le guide de prompt-audit de la skill /claude-api livrée avec Claude Code v2.1.286 (vérifié sur notre propre machine)

Toutes les sources ont été vérifiées dans leur version originale le 3 octobre 2026. Le guide intégré est mis à jour à chaque version de Claude Code : le contenu de l'audit peut donc changer d'une version à l'autre.