Où se trouvent les instructions Claude Code : CLAUDE.md, règles de chemin ou hooks

La plupart des équipes utilisant Claude Code conservent aujourd’hui un fichier CLAUDE.md, mais peu d’entre elles savent s’il est réellement utile. Un schéma courant consiste en un fichier qui a atteint plusieurs centaines de lignes, le modèle suivant certaines instructions tout en ignorant silencieusement d’autres. La solution n’est pas toujours un modèle amélioré ; il s’agit plutôt de comprendre ce que le fichier représente réellement et d’orienter chaque instruction vers le mécanisme capable de la traiter. Ce guide présente sept schémas pratiques, allant du raccourcissement du fichier à la définition de règles par chemin, en passant par le transfert des exigences essentielles vers des fonctions dédiées et la vérification de ce que Claude a réellement chargé.

Si vous commencez avec un fichier vierge, le guide pratique pour écrire un CLAUDED.md efficace aborde le contenu et la structure. L’approche ici est différente : il s’agit de déterminer quelles instructions doivent figurer dans le CLAUDED.md et où les autres devraient être placées.

CLAUDED.md, c’est du contexte, pas de la configuration

Tous les autres problèmes découlent de cette idée fausse. Claude Code insère le fichier dans la conversation sous forme de message ; il n’est pas intégré au prompt du système, et rien pendant l’exécution ne le force à être respecté. Le modèle le lit et tente de s’y conformer. Aucune garantie supplémentaire n’existe, et les chances diminuent encore lorsque la formulation est floue ou que deux instructions vont dans des directions opposées.

Gardez le fichier de base en dessous de 200 lignes

La recommandation actuelle est de rester autour de 200 lignes. Au-delà, le fichier occupe plus d’espace dans la fenêtre de contexte, ce qui rend son suivi plus difficile plutôt que meilleur.

C’est contre-intuitif : plus il y a d’instructions, moins celles-ci sont suivies. Chaque ligne concurrence pour attirer l’attention limitée, tout comme les autres lignes et la conversation elle-même. Prenons l’exemple d’une équipe dont le fichier comptait 340 lignes. En le réduisant à environ 120 lignes, Claude a pu le suivre de manière plus fiable. Aucune des lignes supprimées n’était erronée ; il s’agissait simplement de bruit superposé aux instructions importantes.

Il existe également un plafond strict, bien que vous ne vouliez pas concevoir en fonction de celui-ci : selon la documentation à l’époque de rédaction, les fichiers supérieurs à 4 Mo sont complètement ignorés. Le fonctionnement correct du système est déjà compromis bien avant que le fichier n’atteigne une telle taille.

Supprimer ce que Claude peut découvrir dans le dépôt

La règle d’édition la plus efficace est simple : supprimer tout ce que Claude peut déduire en lisant le code. Cela correspond au type de suppressions suggéré par la fonction /doctor intégrée à Claude Code, qui élimine les structures de dossiers, les listes de dépendances et les descriptions architecturales de haut niveau, tout en conservant les pièges potentiels, les raisons des choix et les conventions qui s’écartent des paramètres par défaut de l’outil. En d’autres termes, cela inverse le contenu habituel de ces fichiers.

À supprimer :

• La structure des dossiers, puisque Claude peut elle-même lister les répertoires.
• La liste des dépendances, déjà enregistrée dans package.json.
• Un aperçu narratif de l’architecture, que le code exprime plus précisément.

À conserver :

• Le code qui semble être une erreur mais qui est en réalité intentionnel.
• La raison pour laquelle l’approche évidente a été rejetée.

Toute convention qui contredit la documentation du framework.

Des commandes que personne ne trouverait par lui-même.

Un bon test : si un ingénieur compétent avec le répertoire ouvert peut l’apprendre en dix minutes, omettez-la. S’il ne peut le découvrir qu’en cassant quelque chose, notez-le.

Laissez des notes pour les humains sans aucun coût en tokens

Les commentaires HTML au niveau du bloc sont supprimés avant que le contenu du fichier n’atteigne le contexte de Claude. Cela vous permet d’annoter le fichier à l’intention des personnes qui le gèrent sans consommer de budget du modèle, par exemple pour indiquer pourquoi une section a été déplacée :

<!-- Deleted the API section — moved to .claude/rules/api.md, Sep 2026 -->

Vos collègues voient l’historique ; le modèle n’en paie jamais le prix.

@imports organise le fichier mais ne conserve pas de contexte

Lorsqu’un CLAUDE.md devient trop long, on a tendance à le diviser en plusieurs documents et à les importer :

@docs/architecture.md
@docs/api-conventions.md
@docs/testing.md

Cela ressemble au chargement différé, mais ce n’est pas le cas. Les fichiers importés sont décompressés et chargés dans le contexte au lancement, ainsi que le CLAUDE.md qui les référence. Même en divisant 340 lignes en quatre fichiers distincts, ce sont toujours les mêmes 340 lignes qui sont chargées.

Les imports ont effectivement des utilisations légitimes. Ils aident à l’organisation et permettent de partager un ensemble unique d’instructions entre les outils. Si un répertoire dispose déjà d’un AGENTS.md, une seule ligne @AGENTS.md dans CLAUDE.md évite de devoir gérer deux versions différentes. Ne vous attendez cependant pas à ce qu’ils réduisent l’utilisation de la mémoire contextuelle. Pour des instructions qui ne doivent être chargées que parfois, il vous faut des règles ciblées par chemin.

Appliquer des règles conditionnelles avec .claude/rules et les chemins

Les fichiers situés dans .claude/rules/ peuvent déclarer un champ paths dans leur frontmatter. C’est cette fonctionnalité qui permet d’obtenir ce que les utilisateurs attendent des imports : une règle à portée globale reste hors contexte jusqu’à ce que Claude lise ou modifie le fichier correspondant. Le frontmatter d’un fichier de règles API peut ressembler à ceci :

---
paths:
  - "src/api/**/*.ts"
---

En dessous du frontmatter, le corps de la règle contient les conventions qui s’appliquent uniquement à cette partie de l’arborescence, telles que la validation des entrées, le format commun des erreurs et les endroits où l’SQL est autorisé :

# API rules- Every endpoint validates input before touching the database
- Errors use the standard envelope in `src/api/errors.ts`
- No direct SQL outside `src/api/repositories/`

Le résultat est que le travail côté frontend n’est plus soumis aux coûts liés aux conventions API, et que le travail côté API n’est plus soumis aux coûts liés aux conventions de test.

Dans la pratique, c’est la solution pour un CLAUDE.md trop encombré. Divisez le contenu par thème, associez chaque thème aux dossiers qu’il concerne, et réservez le fichier racine pour les directives valables pour l’ensemble du projet. Un fichier de règles sans champ paths est chargé à chaque session ; considérez donc cela comme un choix délibéré et non comme la valeur par défaut.

Les expressions globales prennent en charge l’expansion avec des accolades, ce qui permet à une seule règle de couvrir plusieurs extensions ainsi qu’un motif de test distinct :

---
paths:
  - "src/**/*.{ts,tsx}"
  - "tests/**/*.test.ts"
---

Les étapes obligatoires doivent figurer dans les hooks

Des instructions telles que « lint avant chaque commit », « ne pas pousser directement sur main » ou « formater chaque fichier après modification » sont fréquentes dans CLAUDE.md. Elles sont généralement respectées, les exceptions attirent l’attention, et les équipes en concluent que le modèle n’est pas fiable.

C’est pourtant le comportement documenté : CLAUDE.md influence les actions de Claude sans pour autant les garantir. Pour une étape qui doit avoir lieu à un moment précis au cours du cycle de vie de la session, un hook exécute une commande shell à ce moment-là, indépendamment du jugement du modèle. Un hook PreToolUse peut même empêcher complètement l’appel à une outil, ce que rien de stylisé ou en majuscules dans le Markdown ne peut accomplir.

Une manière pratique de gérer chaque type d’instruction :

• Les conventions que Claude doit généralement suivre sont indiquées dans CLAUDE.md.
• Les règles relatives à une partie du codebase se trouvent dans .claude/rules/ avec des paths.
• Les exigences ne tolérant aucune exception deviennent des hooks.
• Les procédures répétibles en plusieurs étapes deviennent des compétences.

Déplacer un petit nombre de règles « toujours » vers des hooks présente un double avantage : les exigences sont désormais réellement appliquées, et le fichier se voit débarrassé de lignes qui ne pourraient jamais fonctionner, ce qui permet d’accorder plus d’attention aux instructions qui le peuvent.

Vérifier ce qui a vraiment été chargé

Exécutez /context et examinez sa section des fichiers de mémoire, qui reflète exactement ce que la session en cours a chargé. /memory complète cette information en listant les fichiers au niveau de l’utilisateur et au niveau du projet, tout en vous permettant de les ouvrir. Ensemble, ils transforment la question « Claude ignore-t-il cela ? » en quelque chose que l’on peut vérifier. Il est étonnamment facile de passer du temps à affiner la rédaction d’un fichier qui n’est même pas chargé.

Contradictions entre fichiers concaténés

Rien n’est surchargé ; tout est concaténéné. Partant du répertoire de travail, Claude Code remonte vers la racine du système de fichiers et collecte chaque fichier CLAUDE.md en chemin, puis les ordonne de la racine vers le bas. À tout niveau où se trouve également un fichier CLAUDE.local.md, ce dernier suit son frère CLAUDE.md. Dans un monorepo, deux fichiers peuvent facilement donner des indications opposées. Lorsque cela se produit, Claude peut simplement en choisir un, sans que rien ne vous avertisse du conflit.

Fichiers ancestraux que vous n’avez pas demandés

Si un fichier CLAUDE.md situé dans un répertoire parent s’infiltre dans vos sessions, la valeur claudeMdExcludes de vos paramètres locaux permet d’exclure des fichiers via des expressions globales.

Ce qui survit à la compression

Le fichier CLAUDE.md situé dans la racine du projet est relu depuis le disque et réinséré après l’exécution de /compact, ce qui permet à ses instructions de persister. Tout ce que vous dites uniquement au cours de la conversation est perdu. Si vous continuez à répéter la même correction après chaque compression, c’est un signe fort qu’elle doit figurer dans le fichier.

Un modèle de départ

Si vous deviez créer la configuration depuis zéro, un objectif raisonnable serait le suivant :

• Un fichier CLAUDE.md de racine comptant environ 120 lignes, ne contenant que des informations valables partout.
• Des directives conditionnelles stockées dans .claude/rules/, avec des patterns de chemins.
• Chaque exigence impérative « toujours » mise en œuvre sous forme de hook.
• Rien que quelqu’un ne pourrait pas apprendre en lisant le répertoire en dix minutes.
• Vérification rapide avec /context après chaque modification.

La référence complète, y compris des fonctionnalités telles que la mémoire automatique qui méritent un traitement distinct, se trouve dans la documentation sur la mémoire de Claude Code. Le comportement et les limites évoluent, il convient donc de la consulter lorsque quelque chose ne correspond pas à ce que vous attendez.

Points clés

• Rédigez des fichiers CLAUDE.md pour un collègue qui les lit, et non pour une machine qui les exécute : qu’ils soient courts, précis et sans contradictions.
• Les fichiers plus courts sont suivis de manière plus fiable ; supprimez tout ce que la base de code indique déjà à Claude.
• Les imports réorganisent le contenu mais chargent tout ; ce sont les règles ciblées par chemin qui diffèrent réellement le chargement.
• Tout ce qui doit se produire à chaque fois nécessite un hook, car le contexte ne peut influencer que le comportement.
• Tenez /context pour votre source de vérité avant d’ajuster le texte.