CLAUDE.md après Opus 5 : pourquoi les longues instructions gênent désormais Claude

Vous trouverez des informations sur l’utilisation d’Ailoot dans la documentation.

Qu’est-ce qui a changé dans Claude après la sortie d’Opus 5 ?#

Opus 5 est sorti le 24 juillet 2026 et est immédiatement devenu le modèle par défaut dans Claude Code. Le modèle lui-même — son prix, ses benchmarks et ses modes d’effort — est traité en détail dans un guide distinct, « Faut-il passer à Claude Opus 5 ? ». Cet article porte sur autre chose : la sortie du modèle a aussi changé la manière de lui parler efficacement.

Anthropic a publié une analyse sur le blog de Claude. Son idée principale est la suivante :

L’expression clé est « trop brider ». Quand les modèles étaient plus faibles, ils avaient besoin d’un cadre : fais ceci, ne fais pas cela, voici un exemple, répète-le encore une fois. Opus 5 n’a plus besoin de ce cadre et, pire encore, il peut commencer à le gêner. Anthropic énonce simplement le nouveau principe : laissez Claude faire preuve de discernement.

Qu’est-ce que cela signifie concrètement pour vous ?

• Votre CLAUDE.md est un prompt système du même type, mais pour votre projet. Si Anthropic a réduit le sien de 80 %, le vôtre est probablement trop chargé lui aussi.
• Les longues listes de règles ne garantissent plus leur respect. Au contraire, plus il y a de lignes, moins le modèle les suit attentivement (nous y reviendrons ci-dessous, avec des chiffres tirés de la documentation).
• De nouveaux mécanismes sont apparus — la mémoire automatique et les skills — qui prennent en charge une partie du travail que vous deviez auparavant détailler manuellement dans CLAUDE.md.

L’essentiel du travail se fait avant le prompt, dans ce que vous placez dans le contexte du modèle avant la première requête. La mise à jour d’Opus 5 est en quelque sorte la confirmation officielle par Anthropic de la même idée. Cette fois, toutefois, elle s’accompagne de chiffres concrets et de nouveaux outils. Je vais les examiner un à un.

Pourquoi une longue CLAUDE.md gêne-t-elle désormais Claude ?#

Voici comment cela fonctionne. CLAUDE.md est un fichier de règles que Claude lit au début de chaque session. Un guide distinct, « Comment configurer CLAUDE.md », explique comment en créer un à partir de zéro ; cet article aborde l’opération inverse : ce qu’il faut maintenant en supprimer. Tout ce que vous y écrivez entre dans le contexte avant votre première requête et y reste pendant toute la conversation. Le contexte n’est pas infini, et chaque ligne de règle supplémentaire occupe une place qui aurait pu être consacrée à votre tâche.

La documentation de Claude Code est catégorique :

Le deuxième point compte davantage que le premier : les fichiers longs réduisent le respect des instructions. Le modèle est moins attentif. C’est un piège dans lequel tombent presque tous les débutants. Le raisonnement semble imparable : je veux que Claude m’écoute, alors je vais écrire davantage de règles. En pratique, c’est l’inverse qui se produit. Plus la liste est longue, plus l’attention du modèle se disperse et plus souvent il ignore une règle.

Voici comment l’approche a évolué :

Il y a aussi un deuxième problème : les contradictions. À mesure qu’un fichier s’allonge, il finit presque inévitablement par accumuler des règles contradictoires. À un endroit, on lit « écris toujours des tests », à un autre, « ne touche pas au dossier des tests ». La documentation avertit que si deux règles se contredisent, Claude peut choisir l’une ou l’autre au hasard. Autrement dit, un fichier trop long rend le comportement du modèle moins prévisible.

Une règle simple : CLAUDE.md est une courte note sur ce que Claude ne peut pas déduire seul. Tout le reste ne fait que mobiliser son attention.

Que faut-il garder dans CLAUDE.md et que faut-il supprimer ?#

La documentation donne un critère clair pour décider si une règle mérite sa place dans CLAUDE.md. Ajoutez-la si :

1. Claude a commis la même erreur pour la deuxième fois.
2. Une vérification du code a révélé quelque chose que le modèle aurait dû savoir sur ce projet.
3. Vous saisissez la même correction dans le chat pour la deuxième fois.
4. Une nouvelle personne dans l’équipe aurait besoin du même contexte pour éviter de casser le projet.

Le principe général consiste à garder les pièges propres au projet et à supprimer les évidences. Claude Code possède même une vérification intégrée, claude doctor, qui suggère de nettoyer une CLAUDE.md trop longue. Elle supprime les détails que le modèle peut déduire de la base de code — structure des dossiers, liste des dépendances, aperçu de l’architecture — et conserve les pièges, les justifications et les conventions qui diffèrent des paramètres par défaut.

La deuxième règle importante est la précision. Les formulations vagues ne fonctionnent pas. Comparez :

La différence est simple. Le modèle peut interpréter « formate-le correctement » comme il le souhaite. « Utilise une indentation de 2 espaces » se vérifie sans ambiguïté. Chaque règle de CLAUDE.md doit être quelque chose que vous pouvez contrôler et constater, qu’elle ait été suivie ou non.

Et troisièmement, supprimez les évidences. Si vous écrivez « écris du code propre » ou « suis les bonnes pratiques » dans CLAUDE.md, c’est du bruit. Le modèle le sait déjà, et cette ligne occupe de la place et disperse son attention. Anthropic déconseille explicitement de consacrer du contexte à des évidences.

Où déplacer les règles qui n’ont pas leur place dans CLAUDE.md ?#

C’est ici qu’intervient l’outil le plus sous-estimé. Si auparavant toutes les instructions devaient rester dans CLAUDE.md, les procédures longues ont désormais leur propre emplacement : les skills. Un guide distinct, « Comment choisir des skills pour Claude Code », explique comment choisir les bons sans en ajouter trop.

La différence est fondamentale. CLAUDE.md est chargée intégralement au début de chaque session. Ce n’est pas le cas d’un skill. La documentation l’explique ainsi :

C’est ce qu’on appelle la divulgation progressive : charger les informations au besoin. L’idée consiste à fournir le contexte au modèle par portions, au bon moment. Anthropic a déplacé dans des skills ses instructions détaillées — par exemple, les instructions de revue de code — et les a supprimées du prompt système.

Le critère pour déplacer quelque chose dans un skill est simple : une section de CLAUDE.md est passée d’un fait à une procédure. Une note d’une ligne, « les builds s’exécutent avec npm run build », est un fait et a sa place dans CLAUDE.md. Dix étapes expliquant « comment nous publions le projet » constituent une procédure et ont leur place dans un skill.

Un principe pratique : confiez à un skill tout ce que vous faites plus de deux ou trois fois. Expliquez une fois comment préparer, par exemple, le rapport hebdomadaire d’un client, transformez cette explication en skill et vous n’aurez pas à la répéter. Le skill reste disponible sans consommer de contexte et peut être appelé par son nom à l’aide d’une commande comme /otchet.

Voici ce qu’il est utile de déplacer dans des skills :

• Les procédures en plusieurs étapes (publication, compilation d’un rapport, vérifications avant une sortie).
• Les longues instructions dont on a rarement besoin, mais qui sont alors nécessaires dans leur intégralité.
• Tout ce que vous copiez d’une conversation à une autre pour la deuxième ou la troisième fois.

Il existe aussi une solution intermédiaire : les règles propres à un dossier. Si une instruction ne concerne qu’une partie du projet, vous pouvez la placer dans .claude/rules/ et la lier aux fichiers concernés. Elle ne sera alors chargée que lorsque Claude travaille sur ces fichiers, au lieu de rester en permanence dans le contexte.

Qu’est-ce que la mémoire automatique, et pourquoi l’utiliser en 2026 ?#

Le deuxième mécanisme qui allège CLAUDE.md est la mémoire automatique. L’idée est que Claude se souvient désormais non seulement de ce que vous avez écrit, mais aussi de ce qu’il a remarqué lui-même. Un guide distinct, « La mémoire de Claude ou CLAUDE.md », explique en quoi son fonctionnement diffère de celui de CLAUDE.md.

La différence entre les deux types de mémoire :

Voici comment cela fonctionne : pendant que Claude travaille sur votre tâche, il repère des détails utiles — la commande qui lance le build, le point où le débogage a rencontré un obstacle, ce que vous lui avez demandé de faire différemment — et les enregistre dans ses notes. Il les réutilise lors de la session suivante. Important : il sélectionne les éléments à enregistrer et ne garde que ce qu’il juge utile pour l’avenir.

Les notes se trouvent dans un dossier distinct pour chaque projet, avec un fichier d’index nommé MEMORY.md. Vous pouvez les consulter et les modifier avec la commande /memory. Ce sont des fichiers texte ordinaires que vous pouvez lire, modifier ou supprimer à tout moment.

Concrètement, cela signifie que Claude consigne désormais certains éléments que vous ajoutiez auparavant vous-même à CLAUDE.md après chaque erreur. Votre fichier de règles est donc encore plus court — et c’est une bonne chose.

Pourquoi Opus 5 conteste-t-il vos instructions ?#

Cette évolution a aussi un revers.

Un modèle autorisé à exercer son discernement contredira parfois, par définition, une commande rigide s’il repère une meilleure option dans le contexte.

Voici ce que cela signifie pour vous si vous êtes passé à Opus 5 et que quelque chose ne va pas :

1. Vérifiez à nouveau vos anciens skills et plugins. Les configurations conçues pour les modèles précédents peuvent entrer en conflit avec la nouvelle logique. Il vaut mieux retester ce qui fonctionnait autrefois à merveille.
2. Supprimez les formulations les plus rigides. Les modèles de cinquième génération gèrent moins bien les commandes comme « ne fais jamais X, fais toujours uniquement Y » que les formulations souples qui en expliquent la raison.
3. Surveillez les moments où le modèle s’arrête trop tôt. Cela peut indiquer qu’une instruction se contredit ou se heurte à une règle dans une CLAUDE.md trop longue.

Comment réécrire CLAUDE.md pour Opus 5 : étape par étape#

Voici la marche à suivre pour une CLAUDE.md héritée de modèles précédents.

1. Lancer la vérification intégrée

   Saisissez claude doctor dans le projet. L’outil vous suggérera quoi supprimer du fichier trop long et quoi garder.

2. Supprimer les évidences

   Supprimez chaque ligne dont Claude peut déduire le contenu à partir du code lui-même : structure des dossiers, liste des bibliothèques et formules générales comme « écris du code propre ».

3. Supprimer les contradictions

   Parcourez le fichier de haut en bas et repérez les règles contradictoires. Gardez-en une et supprimez celle qui la contredit.

4. Déplacer les procédures dans des skills

   Déplacez dans un skill distinct tout ce qui est passé d’un fait à une instruction étape par étape. Laissez dans CLAUDE.md un lien d’une ligne.

5. Rendre les règles restantes précises

   Reformulez chaque règle pour qu’elle soit vérifiable : « formate-le correctement » devient « utilise une indentation de 2 espaces ».

6. Activer la mémoire automatique et vérifier la longueur

   Assurez-vous que la mémoire automatique fonctionne (/memory) et que le fichier contient moins de 200 lignes. Si ce n’est pas le cas, il reste quelque chose à déplacer.

Pour éviter de faire le premier passage à la main, demandez à Claude de s’en charger. Voici un prompt à utiliser comme point de départ : copiez-le et collez-le dans une session ouverte dans votre projet :

Lis mon fichier CLAUDE.md et mon code. Ta tâche consiste à rendre CLAUDE.md plus court et plus utile pour un modèle de cinquième génération.

Parcours le fichier et répartis toutes les règles en trois groupes :

CONSERVER - les pièges propres au projet et les conventions que tu ne peux pas déduire du code par toi-même.

SUPPRIMER - les évidences que tu connais déjà, ainsi que tout ce qui peut être déduit du code.

DÉPLACER VERS UN SKILL - les procédures en plusieurs étapes qui figurent actuellement dans CLAUDE.md sous forme de texte.

Pour le groupe 1, reformule les règles vagues pour les rendre concrètes et vérifiables.
Repère les règles qui se contredisent et présente-les séparément.
Renvoie une nouvelle version de CLAUDE.md de moins de 200 lignes, ainsi qu’une liste des éléments que tu proposes de déplacer vers des skills.
Ne modifie aucun fichier avant que je confirme.

Remarquez la dernière ligne : « Ne modifie rien avant que je confirme. » Avec un modèle qui fait désormais preuve de discernement, c’est important : demandez-lui d’abord de vous présenter un plan, puis gardez la décision pour vous.

Pourquoi le contexte est-il plus important que le prompt ?#

Si l’on met de côté les détails propres à Opus 5 pour prendre du recul, toute cette analyse porte sur une idée : le contexte est plus important que le prompt. L’essentiel du travail se fait avant la demande, au moment où l’on assemble l’environnement dans lequel le modèle va travailler.

CLAUDE.md, les skills et la mémoire automatique sont autant d’éléments d’un même ensemble : ce que Claude voit avant votre premier message. Vous pouvez modifier sans fin la formulation de votre demande, mais si le contexte est mal assemblé — CLAUDE.md trop longue, règles contradictoires, absence de structure — les résultats resteront incohérents.

Voici une vérification simple : sans premier cerveau, un second cerveau ne sert à rien. Par « second cerveau », cet article désigne la structure des connaissances d’un projet que le modèle consulte à chaque requête. Mais cela ne fonctionne que si cette structure s’appuie sur votre compréhension claire de la tâche. Un outil amplifie votre réflexion ; son rôle s’arrête là.

La mise à jour d’Opus 5 a renforcé cette logique. Anthropic a montré, avec son propre travail, que lorsque le modèle est assez intelligent, les règles supplémentaires nuisent et que l’avantage revient à ceux qui ont soigneusement assemblé le contexte. Cette compétence vous accompagnera avec tous les prochains modèles, qu’il s’agisse d’Opus 6 ou d’un autre.

Par où commencer dès maintenant ?#

Ne remettez pas cela à « un jour ». Le plus simple est d’ouvrir CLAUDE.md dès maintenant et de vous poser honnêtement la question pour chaque ligne : s’agit-il d’un piège que Claude ne peut pas déduire, ou d’une évidence que j’ai ajoutée par précaution ? Tout ce qui relève du deuxième groupe peut être supprimé.

Ensuite, faites examiner le fichier à l’aide du prompt de la section ci-dessus, déplacez les procédures longues dans des skills et vérifiez que la mémoire automatique est activée. Une soirée de travail, et votre contexte deviendra une base concise et précise pour le modèle.

Vous pouvez appliquer cela à l’un de vos vrais projets : CLAUDE.md, un second cerveau et des skills pour vos tâches.

Découvrez Ailoot.