Pourquoi les agents IA ignorent les règles .md : vérifier le chargement et les résultats avec Hooks et CI

Vous demandez à Claude Code s’il a lu CLAUDE.md. Il répond oui, mais omet les tests demandés. Dans ce cas, distinguez les consignes qui ne sont jamais parvenues au modèle de celles qu’il a reçues sans les respecter. La réponse « je l’ai lu » ne permet de trancher ni dans un sens ni dans l’autre.

Il en va de même pour .cursor/rules de Cursor, .github/copilot-instructions.md de GitHub Copilot et AGENTS.md de Codex CLI : l’emplacement de chargement et les conditions d’application varient selon l’outil. Le chargement d’un fichier et le respect de ses consignes par le modèle sont deux questions distinctes.

En bref, la démarche compte trois étapes. Vérifiez d’abord si les consignes sont chargées. Si une règle chargée n’est pas respectée, réécrivez-la en une phrase dont on peut vérifier le respect après coup. Enfin, confiez aux Hooks ou à la CI les traitements qui doivent s’exécuter à chaque fois sans exception. La documentation officielle de Claude Code indique elle aussi que CLAUDE.md est « du contexte, pas une configuration appliquée », et recommande un hook pour bloquer une action indépendamment de ce que décide Claude.

Cet article présente dans l’ordre cinq points à vérifier, dont le chargement, la réinjection après compression et les consignes contradictoires, puis la démarche de diagnostic et des exemples de réécriture des règles.

1. Pourquoi l’IA ignore les règles : cinq points à vérifier

1. Un fichier trop long noie les règles

La documentation de Claude Code recommande de limiter chaque fichier CLAUDE.md à moins de 200 lignes, en expliquant que les fichiers longs consomment davantage de contexte et réduisent le respect des consignes. Ces 200 lignes ne marquent pas la fin du chargement : un CLAUDE.md de 4 MiB au plus est chargé en entier (un fichier de plus de 4 MiB est ignoré). Dans un long fichier, le texte ne cesse pas d’être lu à partir d’un certain point : il est bien lu, mais chaque règle a moins de chances d’être respectée.

2. La compression automatique dans les sessions longues

La commande /compact de Claude Code compresse la conversation, mais le CLAUDE.md à la racine du projet est relu sur le disque et réinjecté dans le contexte après compression. En revanche, les CLAUDE.md des sous-répertoires et les règles propres à certains chemins sont rechargés lors de la lecture des fichiers concernés. Selon la documentation officielle, une consigne disparue après compression a été soit ① donnée uniquement dans la conversation, soit ② écrite dans un CLAUDE.md de sous-répertoire pas encore rechargé, soit ③ placée dans une règle liée à un chemin dont les fichiers cibles n’ont pas encore été touchés. Pour conserver une décision prise dans la conversation, ajoutez-la à CLAUDE.md.

3. Consignes contradictoires et portée

Si « tester avant de committer » et « sauter les tests cette fois » coexistent, le choix de la consigne applicable revient au modèle. La documentation de Claude Code explique qu’en cas de contradiction entre deux règles, Claude peut en choisir une arbitrairement. Comparez régulièrement les consignes générales du projet, personnelles et propres à un répertoire pour éliminer les contradictions et, si vous admettez une exception, précisez « qui peut l’autoriser, et par quelle instruction ». Pour bloquer l’opération elle-même, utilisez les permissions ou les Hooks plutôt que CLAUDE.md. Pour que Claude repère à votre place les consignes contradictoires ou obsolètes, lancez /doctor prompt-audit (fonctionnement et résultats sur ce site).

4. Règles vagues ou contradictoires

Face à des consignes subjectives ou abstraites comme « écris poliment » ou « gère cela correctement », l’IA apporte sa propre interprétation, qui peut différer de vos attentes. Formulez l’exigence de façon à pouvoir vérifier qu’elle a été respectée : « écris au maximum trois lignes » ou « pour utiliser l’API Slack, passe par chat.postMessage », par exemple (exemples de réécriture à la section 3).

5. Fichiers de règles surchargés ou dispersés

Un lien ordinaire de CLAUDE.md vers SPEC.md ne charge pas nécessairement l’intégralité du fichier lié au démarrage. Claude Code développe les imports @path au démarrage, mais leur contenu consomme lui aussi du contexte. Organiser des fichiers séparés et ne les charger qu’au besoin sont deux choses différentes. Si des règles dupliquées se contredisent, clarifiez leur source de référence et leur portée.

Le moment où les CLAUDE.md et AGENTS.md placés dans des sous-dossiers sont chargés (Claude Code et Codex diffèrent sur ce point) et la façon de faire respecter les règles à l’IA dans un monorepo grâce à des vérifications automatiques sont détaillés dans l’article sur les CLAUDE.md et AGENTS.md des sous-dossiers.

Les spécifications de Claude Code citées jusqu’ici proviennent de la documentation officielle de la mémoire de Claude Code (au 21 septembre 2026).

2. Comment vérifier le respect des règles

Commencez par vérifier la situation actuelle. Posez ces questions à l’IA et examinez ses réponses :

Les réponses « je l’ai lu » ou « j’ai compris » ne prouvent ni le chargement ni l’application des consignes. Les preuves sont l’affichage du chargement et les résultats d’exécution.

Quatre étapes pour isoler la cause

1. Vérifiez le point d’entrée. Dans Claude Code, regardez si le CLAUDE.md et les règles concernés figurent dans Memory files de /context. S’ils n’y sont pas, vérifiez l’emplacement des fichiers et les exclusions (claudeMdExcludes). Un AGENTS.md chargé directement n’apparaît pas dans cette liste. Avec les réglages par défaut, vérifiez que la ligne no CLAUDE.md found; AGENTS.md loaded: … s’affiche au démarrage (un AGENTS.md importé depuis CLAUDE.md, lui, figure dans la liste).
2. Déclenchez les conditions d’application. Pour une règle liée à un chemin, faites lire à l’agent un fichier correspondant. S’il n’a pas encore lu de tel fichier depuis la compression, cette règle n’a pas été rechargée. Pour garder une trace de ce qui a été chargé et quand, le hook InstructionsLoaded peut consigner dans un journal le chargement de CLAUDE.md et des règles (il ne se déclenche pas pour un AGENTS.md chargé directement).
3. Essayez une petite tâche sans danger. Faites modifier un échantillon jetable avec des règles comme « nommer le fichier cible avant de le modifier » et « communiquer ensuite la commande de test et son code de sortie ». Ne testez pas avec une suppression de données de production ou une publication. Si vous testez avec une phrase secrète, écrivez-la uniquement dans le fichier de consignes et ne l’incluez pas dans la question.
4. Vérifiez le résultat indépendamment. Cherchez les modifications inattendues dans le diff, confirmez l’exécution réelle des tests annoncés et vérifiez que le contrôle a couvert assez d’éléments. Notez les réglages, la version de l’outil et les fichiers cibles utilisés pour l’essai, et recommencez dès que l’un d’eux change.

Par exemple, si la consigne « tester avant de committer » a été chargée sans que les tests soient lancés, déplacer le fichier ne résoudra rien. Ce qu’il faut corriger, c’est la formulation de la règle (voir les exemples de réécriture de la section suivante) et le dispositif de contrôle. Exiger des contrôles CI avant fusion fournit en outre des éléments de décision indépendants du compte rendu de l’IA.

Si le CLAUDE.md pertinent manque dans l’affichage des fichiers chargés, corrigez le répertoire de démarrage et les réglages avant d’accentuer le texte. Si les manquements persistent malgré un chargement confirmé, revoyez la précision des consignes et la procédure de contrôle. Cette démarche évite d’attribuer chaque échec à « l’IA a oublié ».

3. Correctifs rapides à essayer en cinq minutes

1. Séparer les règles permanentes des détails lus au besoin

Partez de la recommandation officielle de Claude Code, moins de 200 lignes, mais réduisez les doublons et les explications inutiles plutôt que de poursuivre un nombre de lignes. Par exemple :

• Règles essentielles (10 à 20 lignes) → en tête de CLAUDE.md
• Spécifications détaillées par service → fichiers SPEC-xxx.md séparés
• Historique et contexte → répertoire docs/

Après avoir déplacé le détail, précisez dans le fichier d’entrée quoi lire avant chaque type de tâche. Si vous importez tout ce qui est nécessaire à chaque session, séparer les fichiers ne réduit pas le contexte initial. Utilisez des règles liées aux chemins ou des skills pour charger les consignes conditionnelles uniquement au besoin.

2. Réécrire la règle en « phrase dont on peut vérifier le respect »

Pour une règle chargée mais non respectée, vérifiez d’abord qu’elle précise « ce qu’il faut faire pour la respecter ». La documentation de Claude Code recommande elle aussi des consignes assez spécifiques pour être vérifiables, par exemple « exécuter npm test avant de valider » plutôt que « testez vos modifications ». En allant un peu plus loin, et en précisant aussi le comportement en cas d’échec et les conditions d’exception, on obtient ceci :

Avec la version réécrite, le respect de la règle se vérifie dans le diff, l’historique des commandes et les codes de sortie. Une règle vérifiable devient aussi, telle quelle, une condition de contrôle lorsque vous la confiez ensuite aux Hooks ou à la CI (section 4).

3. Ajouter des marqueurs de priorité

Les marqueurs d’importance aident les humains et l’IA à comprendre l’intention. Ils n’imposent pas, à eux seuls, l’exécution. Vous pouvez par exemple les définir ainsi :

• CRITICAL : une violation peut provoquer un incident en production
• MUST : toujours requis
• SHOULD : normalement attendu
• NICE TO HAVE : facultatif si le temps le permet

« CRITICAL : les requêtes destructives sur la base de production exigent une approbation préalable » précise l’opération et la condition d’approbation. Bloquer réellement les opérations non autorisées nécessite aussi des permissions ou des contrôles avant exécution.

4. Rappeler les règles dans le chat

Au début d’une session, ajoutez « Énonce les trois règles les plus importantes avant de commencer. » Cette déclaration rappelle les règles ; leur respect se vérifie ensuite dans les résultats du travail.

5. Inclure des conditions d’achèvement dans le plan

Inscrivez « vérifier les règles » dans le suivi des tâches de votre agent IA et rendez visibles les conditions d’achèvement de chaque étape. Demandez la commande, le code de sortie et le périmètre non testé, plutôt qu’un simple « testé ». Si une étape est cochée alors que le champ des preuves est vide, ne la considérez pas comme terminée.

4. Protections durables : Hooks, revues et skills

Transformez les conditions évaluables en scripts et contrôlez les permissions par les réglages. Hooks, CI, revue par l’IA et skills remplissent des rôles distincts. Les regrouper sous « application automatique des règles » masque les aspects qu’ils ne vérifient pas.

1. Imposer des contrôles avec les Hooks de Claude Code

La fonctionnalité Hooks de Claude Code peut exécuter des scripts avant ou après certains appels d’outils. Elle permet de construire un dispositif où le système arrête une opération même si l’IA oublie la règle.

Un hook PreToolUse peut, par exemple :

• Détecter les commandes dangereuses (rm -rf, git push --force) avant l’exécution de l’outil Bash, puis les refuser
• Vérifier les permissions ou le verrouillage du fichier cible avant l’exécution de l’outil Edit
• Lancer les tests du projet avant un commit et le bloquer en cas d’échec

Pour bloquer une opération avec PreToolUse, faites renvoyer au hook le code de sortie 2 ou le JSON de refus approprié. Un test échoué qui renvoie 1 avec une simple sortie textuelle produit une erreur non bloquante : l’opération continue. PostToolUse intervient ensuite et ne permet donc pas d’annuler une opération déjà terminée.

Un hook ne bloque que ce que son script évalue lors de l’événement configuré. Surveiller uniquement Edit ne couvre pas les écritures par le shell. La simple recherche de chaînes dangereuses n’est pas exhaustive non plus. Combinez hooks, permissions, bac à sable et CI, puis testez les entrées qui doivent passer comme celles qui doivent être refusées.

2. Répartir les responsabilités entre sous-agents

Utilisez les sous-agents du Claude Agent SDK ou de Cursor pour créer un agent dédié à l’audit des règles. Faire relire le code de l’agent principal par un agent d’audit peut révéler des omissions sous un autre angle. Les deux agents peuvent néanmoins commettre la même erreur ou manquer le même problème.

Transmettez au relecteur les règles à examiner, le diff et les preuves attendues (noms des tests, codes de sortie). Confrontez les constats reçus aux fichiers ou aux résultats de tests, et traitez comme non vérifiés les aspects extérieurs à sa mission.

3. Appeler des procédures répétables avec les skills

Dans Claude Code, placez une procédure répétable dans .claude/skills/precommit/SKILL.md pour l’appeler avec votre propre /precommit. Il s’agit d’un exemple à créer, pas d’une commande intégrée. Les fichiers de l’ancien répertoire .claude/commands/ fonctionnent encore, mais la documentation actuelle les intègre aux skills. Appeler une procédure ne signifie pas réussir tous ses contrôles : examinez les résultats à la fin.

L’emplacement et l’invocation des skills sont décrits dans la documentation officielle des skills. Inscrivez dans le skill la procédure et les critères de réussite, et demandez des preuves de l’exécution des étapes.

4. Détecter les violations par des scripts

Utilisez grep dans la CI ou un hook de pré-commit pour détecter les motifs interdits. Exemples :

• console.log oublié dans le code de production
• Clés d’API codées en dur
• Commentaires de copyright manquants en tête de fichier

Un script ne vérifie ni les règles qu’il n’implémente pas, ni les fichiers hors de son périmètre. Testez les cas valides, les violations et les échecs de récupération, et affichez le nombre d’éléments contrôlés ou ignorés. Si deux fichiers sur dix sont illisibles, la réussite des huit autres ne signifie pas « tous les fichiers ont passé le contrôle ».

5. Bonnes pratiques par outil

Consultez la documentation des règles Cursor, les instructions personnalisées de GitHub Copilot et le guide AGENTS.md d’OpenAI pour les conditions propres à chaque outil. Les instructions de Copilot liées à des chemins utilisent *.instructions.md, et les fonctionnalités qui les lisent varient. Les 32 KiB de Codex constituent une limite totale par défaut en octets, pas en caractères ou en lignes.

Le principe commun est « concis, précis et clairement hiérarchisé ». Les noms et emplacements des fichiers varient, mais les principes de rédaction restent les mêmes.

6. Trois erreurs de conception des règles

1. « Suis les bonnes pratiques »

Cette demande ne définit pas à elle seule les « bonnes pratiques ». Précisez les méthodes du projet et la façon de les vérifier. Pour « tester correctement », indiquez les commandes de test requises et l’étape du travail qui doit s’arrêter en cas d’échec (voir les exemples de réécriture de la section 3).

2. Dupliquer la même règle dans plusieurs fichiers

Si les mêmes conventions de commit figurent dans CLAUDE.md, SPEC.md et README.md, les mises à jour peuvent rendre ces trois copies incohérentes. Choisissez une seule source de référence et créez des liens vers elle dans les autres fichiers.

3. Écrire « absolument obligatoire » partout

Donner la même emphase à chaque condition brouille les priorités. Réservez « CRITICAL » aux conséquences vraiment graves et utilisez un langage ordinaire pour le reste. Gardez à l’esprit que l’emphase perd sa valeur quand elle est omniprésente.

Résumé

Quand une règle n’est pas respectée, examinez dans cet ordre : conditions de chargement → portée → consignes contradictoires → résultats d’exécution. Le CLAUDE.md racine est réinjecté même après compression : une consigne disparue après compression a donc été donnée uniquement dans la conversation, ou figure dans un CLAUDE.md imbriqué ou une règle liée à un chemin pas encore rechargés.

• Consigne non chargée : corrigez l’emplacement, les exclusions ou les conditions de chargement d’AGENTS.md
• Consigne chargée mais non respectée : réécrivez la règle en une phrase dont on peut vérifier le respect après coup
• Traitement à exécuter à chaque fois sans exception : contrôlez-le avec les Hooks ou la CI, et définissez les opérations autorisées dans les permissions

La preuve d’achèvement vient des résultats d’exécution et des livrables, pas de la réponse « je l’ai lu ».

FAQ

Q1. Quelle est la longueur idéale de CLAUDE.md ?

La recommandation officielle est moins de 200 lignes par fichier : la documentation explique que plus un fichier est long, plus il consomme de contexte et moins ses règles sont respectées. Au-delà de 200 lignes, le chargement ne s’interrompt pas pour autant (jusqu’à 4 MiB, le fichier est chargé en entier). Ne gardez que les règles nécessaires à chaque session, et déplacez celles qui ne concernent que certains fichiers dans des règles liées à des chemins. Les fichiers séparés par des imports @path sont eux aussi chargés au démarrage : le contexte ne diminue donc pas.

Q2. Faut-il utiliser .cursorrules ou .cursor/rules/*.mdc dans Cursor ?

Pour une nouvelle configuration, utilisez .cursor/rules/*.mdc. Gardez une règle par fichier et délimitez sa portée avec des motifs glob. L’ancien .cursorrules regroupe tout dans un fichier qui peut devenir difficile à gérer.

Q3. Des règles plus longues sont-elles appliquées plus strictement ?

La longueur seule ne rend pas les règles plus strictes. La documentation officielle explique même que les fichiers longs réduisent le respect des consignes. Si vous ajoutez du texte, ajoutez des conditions vérifiables et des exemples concrets, et supprimez les doublons et les contradictions.

Q4. Et si j’utilise plusieurs outils IA, comme Claude Code et Cursor, sur un projet ?

Réunissez les règles communes dans AGENTS.md comme source de référence, et placez les réglages propres à chaque outil dans son point d’entrée. Codex et Cursor prennent en charge AGENTS.md. Depuis la v2.1.277, Claude Code charge lui aussi directement AGENTS.md si aucun CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md ne se trouve dans le répertoire de travail ou ses répertoires parents. Si l’un d’eux existe, c’est par défaut lui seul qui est lu : même un simple CLAUDE.local.md personnel empêche la lecture d’AGENTS.md. Dans un projet qui utilise aussi CLAUDE.md, écrivez dans CLAUDE.md la ligne @AGENTS.md pour l’importer (vous pouvez aussi régler Project instructions sur claude-md-and-agents-md dans /config pour faire lire les deux). Le chargement direct ne fonctionne pas dans les sessions passant par un fournisseur externe comme Amazon Bedrock ou avec la télémétrie désactivée, lors de la première session après une installation ou une mise à jour, ni dans les environnements où les hooks sont désactivés, par exemple avec disableAllHooks : utilisez alors l’import. L’étape 1 de la section 2 permet de savoir par quelle voie le fichier est lu.

Q5. Si l’IA dit « je l’ai lu », le fichier peut-il ne pas avoir été lu ?

La réponse ne prouve ni que le fichier a été lu, ni qu’il ne l’a pas été. Suivez les étapes de diagnostic de la section 2 pour vérifier l’affichage du chargement, puis comparez-le aux diffs, aux tests et à l’historique d’exécution.