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.

Pour .cursor/rules de Cursor, .github/copilot-instructions.md de GitHub Copilot et AGENTS.md de Codex CLI, vérifiez aussi d’où les fichiers sont chargés et quand ils s’appliquent. Le chargement des consignes par l’outil et leur respect par le modèle sont deux questions distinctes.

Cet article présente cinq points à vérifier, dont le chargement, la réinjection après compression et les consignes contradictoires, avec une démarche de diagnostic et des améliorations concrètes. Raccourcir le texte ne garantit pas son respect. Confiez les conditions vérifiables mécaniquement aux Hooks ou à la CI, et gardez en revue les questions qui exigent un jugement humain.

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

1. Confondre longueur conseillée et limite de chargement

Des consignes longues consomment du contexte et rendent les conditions importantes plus difficiles à repérer. La documentation de Claude Code recommande de limiter chaque fichier CLAUDE.md à moins de 200 lignes, sans dire que le chargement s’arrête à la ligne 200. Une limite de chargement ne se confond pas avec le respect des consignes chargées. La documentation ne définit pas de seuils tels que « 150 lignes garantissent le respect des règles » ou « au-delà de 200 lignes, le milieu disparaît ».

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. Distinguez les décisions prises uniquement dans le chat, les consignes locales pas encore rechargées et les consignes chargées mais non respectées.

3. Consignes contradictoires et portée

Si « tester avant de committer » et « sauter les tests cette fois » coexistent, l’agent doit déterminer quelle consigne s’applique. La chronologie seule n’explique pas la priorité : plus récent ne signifie pas simplement plus prioritaire. Comparez les consignes générales du projet, personnelles et propres à un répertoire, et précisez qui peut autoriser une exception. Une interdiction écrite dans CLAUDE.md ne retire pas, à elle seule, la permission d’exécuter l’opération.

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. Rendez l’exigence vérifiable : « écris au maximum trois lignes » ou « pour utiliser l’API Slack, passe par chat.postMessage », par exemple.

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.

Ces distinctions suivent la documentation officielle de la mémoire de Claude Code, vérifiée dans le texte original le 21 septembre 2026. Distinguez les recommandations de longueur de l’explication des éléments réinjectés après compression pour éviter un mauvais diagnostic.

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 :

Même si l’IA dit « je l’ai lu » ou « j’ai compris », l’application des consignes reste une question distincte. Vérifiez à la fois les éléments attestant le 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, consultez Memory files dans /context pour contrôler le chargement de CLAUDE.md et des règles. Vérifiez aussi que le fichier se trouve dans le répertoire pertinent et n’est pas exclu par les réglages. Le chargement direct d’AGENTS.md constitue une exception qui peut ne pas figurer dans cette liste : son absence ne prouve donc pas, à elle seule, qu’il n’a pas été lu.
2. Déclenchez les conditions d’application. Pour une règle liée à un chemin, faites lire à l’agent un fichier correspondant. S’il ne l’a pas lu depuis la compression, les règles peuvent ne pas avoir été rechargées. Notez séparément les consignes du démarrage et celles chargées pour un travail particulier.
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 incluez une phrase secrète de contrôle dans la question elle-même, l’agent peut répondre sans lire le fichier de consignes : cela ne teste donc pas le chargement.
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. Un essai réussi ne garantit pas toutes les opérations futures. Notez les réglages modifiés, la version de l’outil et les fichiers cibles, puis refaites le contrôle lorsque les conditions changent.

Par exemple, si l’agent a chargé « tester avant de committer » sans lancer les tests, déplacer le fichier ne résoudra pas à lui seul le problème. Précisez les tests requis et ne considérez pas l’étape de commit comme terminée sans leurs résultats. Exiger des contrôles CI avant fusion fournit aussi des preuves indépendantes 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. 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.

3. 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. » Cela permet de vérifier la compréhension, sans garantir l’exécution des tests. Contrôlez aussi les résultats ensuite.

4. Inclure les conditions de vérification 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é ». Une case cochée sans preuve laisse le travail non vérifié.

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 pertinentes, le diff et les preuves attendues. Un prompt court ne garantit pas un taux élevé de reconnaissance des règles. Confrontez chaque constat aux fichiers ou aux résultats de tests, et signalez 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.

Consultez la documentation officielle des skills pour leur emplacement et leur invocation. Inscrivez dans le skill la procédure et les conditions de vérification, 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 : vérifiez leur prise en charge pour chaque fonctionnalité. 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.

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é après compression : n’attribuez donc pas le problème à la seule compression. La concision, l’emphase et la revue par l’IA apportent une aide. Confiez les conditions vérifiables de façon fiable aux 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 couvrant le périmètre requis, 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. Ce n’est ni un seuil de chargement ni une garantie de respect des règles. Gardez les consignes nécessaires à chaque fois et séparez les détails avec des conditions de lecture explicites. Tout réimporter ne réduit pas le contexte initial.

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. Ajouter des conditions ou des exemples nécessaires peut aider, mais évitez les doublons et les contradictions. Vérifiez ce qui est chargé et les conditions réellement contrôlables.

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

Gardez une source de référence commune, avec des points d’entrée et des réglages propres à chaque outil. Codex et Cursor prennent en charge AGENTS.md. Dans Claude Code, vous pouvez aussi importer @AGENTS.md depuis un CLAUDE.md effectivement chargé. Toutefois, la portée de recherche des fichiers et les exclusions diffèrent. Placer un fichier commun dans le projet ne prouve pas que tous les outils l’ont reçu.

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

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