Vous avez écrit « ne modifie que le périmètre demandé » dans votre CLAUDE.md. Trois sessions plus tard, l'agent reformate un fichier voisin. La règle est là, en toutes lettres. Elle n'a pas tenu.

La raison figure dans la documentation d'Anthropic, et elle est plus intéressante qu'un problème de rédaction. CLAUDE.md n'est pas un fichier de configuration. Son contenu est injecté comme un message utilisateur au début de chaque session, et Claude le traite comme du contexte, pas comme une règle opposable. Un bon fichier tient donc en peu de lignes, formule des règles vérifiables, et confie à d'autres mécanismes tout ce qui doit tenir à coup sûr.

CLAUDE.md est du contexte, pas de la configuration

La documentation d'Anthropic le dit en une ligne : Claude traite ces fichiers « comme du contexte, pas comme une configuration appliquée ». Le contenu est délivré après le prompt système, sous forme de message utilisateur. Aucun mécanisme ne vérifie ensuite qu'une de vos lignes a été respectée.

La conséquence est inconfortable et très utile. Chaque ligne de votre fichier est une demande, pas un verrou. Et une demande est suivie d'autant plus fidèlement qu'elle est courte, précise et vérifiable.

Andrej Karpathy l'a documenté sans détour. Après être passé, entre novembre et décembre 2025, de 20 % à 80 % de code écrit par des agents, il publie le 26 janvier 2026 une note sur X qui détaille les erreurs qu'il observe. Puis cette phrase, que la plupart des articles consacrés au sujet oublient de citer : « All of this happens despite a few simple attempts to fix it via instructions in CLAUDE.md. »

Les instructions seules ne suffisent pas. C'est un membre fondateur d'OpenAI, ancien directeur de l'IA chez Tesla, qui l'écrit après plusieurs semaines à ne plus coder qu'en anglais. Ça ne veut pas dire qu'elles ne servent à rien. Ça veut dire qu'il faut savoir ce qu'on peut leur demander.

Les quatre comportements à cadrer en priorité

Karpathy ne publie pas quatre règles. Il décrit des comportements. Les « quatre règles de Karpathy » qui circulent depuis janvier sont une reconstruction de la communauté, utile mais mal attribuée. Les comportements, eux, sont cités mot pour mot dans sa note, et ce sont eux qui méritent une place en tête de votre fichier.

Les hypothèses silencieuses. Les modèles « font des hypothèses erronées à votre place et continuent sans vérifier ». Ils ne gèrent pas leur confusion, ne demandent pas de clarification et ne signalent pas les incohérences.

La sur-complication. Ils « aiment beaucoup sur-compliquer le code et les API, gonflent les abstractions, ne nettoient pas le code mort ». Karpathy décrit une construction de 1 000 lignes ramenée à 100 après une simple objection.

Les modifications hors périmètre. Ils « changent ou suppriment parfois des commentaires et du code qu'ils n'aiment pas ou ne comprennent pas assez, même si c'est orthogonal à la tâche ».

L'absence de critère de succès. À l'inverse, sa recommandation est nette : « Ne lui dites pas quoi faire, donnez-lui des critères de succès et regardez-le partir. » Faites écrire les tests d'abord, puis passez-les.

Ce qui donne, en tête de fichier :

## Comportement
- Si une spécification est ambiguë, pose une question avant d'agir.
- Ne choisis pas un format, une dépendance ou une architecture sans le signaler.
- Implémente la version la plus simple qui passe. Aucune abstraction non demandée.
- Ne modifie que les fichiers concernés par la tâche. Signale le reste, ne le touche pas.
- Au-delà de 3 étapes : décris le résultat attendu et le test qui le prouve, avant d'exécuter.

Cinq lignes. Le test de qualité tient en une question : est-ce que je peux vérifier, sur un diff, si la règle a été suivie ? « Écris du code propre » ne se vérifie pas. « Ne modifie que les fichiers concernés » se vérifie à chaque commit.

Sous 200 lignes, puis .claude/rules/

Anthropic donne un chiffre : viser moins de 200 lignes par fichier CLAUDE.md, parce qu'un fichier long consomme du contexte et fait baisser l'adhérence aux instructions. Vous trouverez ailleurs 80 lignes, parfois 50. Ces chiffres circulent sans source. Celui-là en a une.

Le réflexe naturel est d'ajouter une règle après chaque bêtise de l'agent. Au bout de trois mois, le fichier fait 300 lignes et fonctionne moins bien qu'au premier jour.

La sortie propre s'appelle .claude/rules/, ce qu'Anthropic nomme les project rules. Vous y déposez un fichier Markdown par sujet, et vous pouvez restreindre chacun à un périmètre de fichiers avec un simple en-tête YAML :

---
paths:
  - "src/api/**/*.ts"
---
- Tout point d'entrée valide ses entrées.
- Format d'erreur standard, sans exception.

Cette règle n'entre en contexte que lorsque Claude lit un fichier correspondant. Le reste du temps, elle ne coûte rien. Attention au piège symétrique : les imports @fichier dans un CLAUDE.md n'allègent pas le contexte, ils organisent seulement le texte. Les fichiers importés sont chargés au lancement, comme le reste.

Depuis la version 2.1.206, la commande /doctor propose des coupes dans un CLAUDE.md versionné. Elle retire ce que Claude peut déduire seul de la base de code, comme l'arborescence ou la liste des dépendances, et garde les pièges et les conventions qui s'écartent des valeurs par défaut. C'est exactement le bon critère de tri.

Ce qu'une instruction ne garantira jamais

Il existe des règles qu'on ne peut pas se permettre de voir ignorées une fois sur dix. Ne jamais pousser sur main. Ne jamais toucher aux migrations. Celles-là n'ont rien à faire dans un CLAUDE.md, et la documentation d'Anthropic est claire sur ce point : pour bloquer une action quelle que soit la décision de Claude, il faut un hook PreToolUse ou une règle permissions.deny.

La ligne de partage est simple. Les paramètres sont appliqués par le client, quoi que le modèle décide. CLAUDE.md oriente un comportement, il ne l'impose pas. Style de code, conventions, rappels de conformité : le fichier. Blocage d'un outil, d'une commande ou d'un chemin, isolation en bac à sable : les paramètres.

À l'échelle d'une organisation, la même logique se retrouve dans un CLAUDE.md déployé en politique gérée, à un emplacement système, ou directement via la clé claudeMd d'un fichier managed-settings.json. Il se charge avant les fichiers utilisateur et projet, et aucun réglage individuel ne peut l'exclure. Ce qui en fait un bon véhicule pour des consignes, et un mauvais véhicule pour des interdits.

Vérifier ce qui est réellement chargé

Avant de conclure qu'une règle est mal écrite, vérifiez qu'elle est arrivée. Trois commandes suffisent, et elles répondent à trois questions différentes.

/context affiche ce qui a réellement été chargé dans la session en cours. Si votre fichier n'apparaît pas dans la répartition, Claude ne l'a jamais vu, et aucune reformulation n'y changera quoi que ce soit (on a tous passé une demi-heure à peaufiner une règle qui n'était pas chargée). /memory liste les emplacements de vos CLAUDE.md et CLAUDE.local.md, et ouvre la mémoire automatique de Claude Code : ces notes que Claude écrit lui-même au fil de vos corrections. Elle est distincte de vos instructions, elle est en Markdown, et elle se relit.

Deux causes fréquentes de règle fantôme. Un CLAUDE.md de sous-répertoire n'est chargé qu'au moment où Claude lit un fichier de ce répertoire, et il n'est pas réinjecté après un /compact, contrairement au fichier racine. Et dans un monorepo, un fichier d'une autre équipe peut remonter par héritage et contredire le vôtre. Quand deux règles se contredisent, Claude en choisit une, arbitrairement. Le réglage claudeMdExcludes sert précisément à faire le ménage.

Questions fréquentes

Qu'est-ce que le fichier CLAUDE.md, exactement ? C'est un fichier Markdown que vous écrivez et que Claude Code lit au début de chaque session. Il contient vos instructions permanentes : conventions, commandes, architecture, règles de comportement. Ce n'est pas un fichier de configuration au sens technique : son contenu est ajouté au contexte de la conversation, sans mécanisme de contrôle d'application.

Où placer le fichier CLAUDE.md dans un projet ? Quatre portées existent, de la plus large à la plus étroite : une politique gérée à l'échelle de la machine, vos préférences personnelles dans ~/.claude/CLAUDE.md, les instructions d'équipe dans ./CLAUDE.md ou ./.claude/CLAUDE.md, et vos préférences locales dans ./CLAUDE.local.md, à mettre au .gitignore. Tous sont concaténés, du plus général au plus spécifique.

Combien de lignes maximum pour un CLAUDE.md efficace ? Anthropic recommande de rester sous 200 lignes par fichier. Au-delà, la consommation de contexte augmente et l'adhérence aux instructions baisse. Déportez le surplus dans .claude/rules/ avec une portée par chemin plutôt que d'allonger le fichier principal.

Comment démarrer sans partir d'une page blanche ? La commande /init analyse votre base de code et génère un premier fichier avec les commandes de build, les tests et les conventions détectées. Si un CLAUDE.md existe déjà, elle propose des améliorations au lieu de l'écraser. Ajoutez ensuite vos règles de comportement en tête.

Et si mon dépôt utilise déjà AGENTS.md ? Claude Code lit CLAUDE.md, pas AGENTS.md. Créez un CLAUDE.md qui importe l'autre avec @AGENTS.md, puis ajoutez dessous ce qui est propre à Claude. Les deux outils lisent alors les mêmes instructions, sans duplication.

Karpathy termine sa note en disant qu'il ne reviendrait pas au code manuel, et nous non plus. Mais son constat mérite d'être pris au sérieux : cinq lignes de comportement bien écrites valent mieux que deux cents lignes de spécifications, et une règle qui doit absolument tenir se met ailleurs que dans un fichier Markdown. C'est le même arbitrage que sur Claude Tag dans Slack, et il revient dès qu'un agent travaille en production. Le reste de nos tutoriels techniques creuse ce terrain.

Le vrai livrable n'est donc pas un fichier, c'est une frontière : ce qui reste une consigne, ce qui devient un hook, ce qui se verrouille dans les permissions. Sur les outils sur mesure que nous construisons, cette frontière est versionnée et relue comme le reste du code. Si vous voulez en parler, réservez un premier échange de 30 minutes.

ClaudeAgentsPrompting