CLAUDE.md et AGENTS.md : à quoi ils servent, quoi y écrire et pourquoi l'agent ignore les règles

Ce que sont CLAUDE.md et AGENTS.md

Ce sont des fichiers Markdown ordinaires placés à la racine du dépôt, que l'agent charge automatiquement dans son contexte au début de chaque session. Ils vous permettent de transmettre à l'agent ce qu'il ne peut pas deviner à partir du code seul : comment préparer l'environnement, avec quelles commandes vérifier le travail, quelles règles du projet ne se discutent pas et où se trouve la documentation détaillée.

CLAUDE.md est le fichier lu par Claude Code. AGENTS.md est un format ouvert qui repose sur la même idée et que prennent en charge de nombreux agents de programmation. Si l'équipe utilise plusieurs agents, il est pratique de placer le contenu principal dans AGENTS.md et d'y faire référence depuis CLAUDE.md. Claude Code permet d'importer un autre fichier avec une ligne commençant par @ :

# CLAUDE.md
@AGENTS.md

Ainsi, les règles ne vivent qu'à un seul endroit et ne divergent pas entre deux fichiers.

Comment l'agent lit ces fichiers

Le contenu du fichier d'instructions entre dans la fenêtre de contexte du modèle avec le prompt système, et y reste pendant toute la session. Il en découle trois conséquences importantes.

• Chaque ligne occupe de la place dans le contexte. Le fichier est lu en entier à chaque démarrage, même si la tâche en cours n'en utilise qu'un dixième.
• Ce ne sont pas des règles exécutables, mais du texte. Le modèle en tient compte avec le reste du contexte, et rien ne garantit un respect à 100 %. Les interdictions strictes doivent être soutenues par des mécanismes : vérifications, hooks, droits d'accès.
• Les fichiers peuvent être imbriqués. Claude Code charge CLAUDE.md depuis la racine du projet et depuis le dossier utilisateur ~/.claude/, et les fichiers situés dans les sous-dossiers sont chargés lorsque l'agent travaille avec des fichiers de ces dossiers. Vous pouvez ainsi garder les règles d'un module à côté du module.

Que mettre dans CLAUDE.md et AGENTS.md

Un bon fichier d'instructions est une carte, pas un manuel. Il répond aux questions qu'un agent poserait à un collègue expérimenté le premier jour.

1. Comment construire et vérifier le projet

C'est la section la plus précieuse. Des commandes concrètes que l'agent doit exécuter avant de dire « terminé » : tests, linter, vérification de types, démarrage de l'environnement. Sans elles, l'agent vérifie son travail « à l'œil ».

2. Les contraintes strictes

Une courte liste de ce qui ne doit jamais être enfreint : les invariants de sécurité et de données. Formulez-les comme des invariants, non comme des consignes d'implémentation : « toutes les requêtes SQL sont paramétrées », et non « utilise telle fonction dans tel fichier ».

3. Une carte du projet

Où se trouve quoi : quelques lignes sur la structure des dossiers et sur l'endroit où chercher les détails. Pour chaque grand sujet, un lien vers un document séparé que l'agent n'ouvre que lorsqu'il aborde ce sujet.

4. Où est consigné l'état du travail

Où regarder pour reprendre là où la session précédente s'est arrêtée : fichier de plan, journal d'avancement, backlog. Cela soigne l'« amnésie » de l'agent entre les sessions.

Ce qu'il ne faut pas y écrire

• Ce que l'agent apprend du code. La liste des dépendances figure dans package.json ou pyproject.toml, la structure des classes dans le code lui-même.
• Des conseils généraux. « Écris du code propre » ou « sois attentif » ne changent pas le comportement et ne font que prendre de la place.
• L'historique du projet et des notes ponctuelles. « En mars, nous sommes passés de MySQL 5.7 » n'aide pas la tâche actuelle.
• Des instructions détaillées pour des tâches rares. Une procédure de déploiement ou de migration de données ne sert qu'une fois par semaine : placez-la dans un document séparé ou dans un skill.
• Des secrets. Le fichier est dans le dépôt et part entièrement vers le modèle. Jetons et mots de passe ne doivent figurer que dans les variables d'environnement.

Pourquoi l'agent ignore une règle écrite dans le fichier

Scénario typique : l'agent a commis une erreur, on ajoute une règle au fichier. Il commet une autre erreur, on ajoute encore une règle. Quelques mois plus tard, le fichier compte des centaines de lignes, et la règle de sécurité essentielle est violée comme si elle n'existait pas. Il y a généralement quatre causes, qui agissent simultanément.

Un fichier démesuré

Un fichier de 600 lignes représente environ 10 000 à 20 000 tokens. La fenêtre de contexte paraît immense, mais elle est partagée avec le code, les sorties de commandes et l'historique de la conversation. Plus les instructions occupent de place, moins chaque règle reçoit d'attention, et plus la tâche elle-même en manque.

La règle se trouve au milieu

Les modèles de langage exploitent beaucoup moins bien les informations situées au milieu d'un long texte que celles du début ou de la fin. Une règle à la ligne trois cents sur six cents se retrouve à l'endroit le plus faible.

Aucune hiérarchie

Une interdiction non négociable et une remarque anodine sur le style sont écrites de la même façon, en une ligne dans une liste. L'agent n'a aucun moyen de savoir ce qui compte davantage. Et si le fichier contient trois règles de style contradictoires, le comportement devient aléatoire d'une exécution à l'autre.

La dégradation

Ajouter une règle ne coûte rien, mais en supprimer une fait peur : « et si quelque chose en dépendait ? ». Le fichier grossit donc sans cesse pendant que la part des lignes utiles diminue. Il est utile de mesurer cela par un rapport signal/bruit : combien de lignes une tâche typique utilise réellement, et combien sont inutiles ?

Comment corriger : un routeur plutôt qu'un mur de texte

Corriger une seule cause ne sert à rien : si vous raccourcissez le fichier sans le structurer, les règles restent mélangées. Un ensemble de mesures est efficace.

1. Faites du fichier d'entrée un routeur. 50 à 150 lignes : commandes de vérification, contraintes strictes, carte du projet et liens vers les documents thématiques.
2. Sortez les sujets dans des fichiers séparés. Par exemple docs/agents/deploy.md ou docs/agents/database.md. L'agent les ouvre au besoin. Dans Claude Code, les skills conviennent bien aux procédures répétitives : ils ne se chargent que lorsqu'on en a besoin.
3. Placez l'essentiel en haut. Les contraintes strictes vont au début du fichier, dans un bloc court et explicitement marqué MUST.
4. Supprimez les contradictions. Une règle par sujet. S'il existe une exception, écrivez-la juste à côté de la règle.
5. Appuyez la règle par un mécanisme. Si la transgression est inacceptable, le texte ne suffit pas. Il faut une vérification qui la détecte : linter, test, hook de pré-commit ou hook de l'agent, ou une restriction au niveau des droits d'accès.
6. Révisez régulièrement. Fixez une limite de lignes et, à chaque ajout, demandez-vous ce qui peut être retiré ou déplacé.

Règle ou vérification ?

Exemple d'AGENTS.md compact

# AGENTS.md — backend de paiement (FastAPI, PostgreSQL)

## MUST — à ne pas enfreindre
- Les montants sont des int en centimes, jamais des float
- SQL uniquement paramétré, pas de f-strings
- Ne pas modifier les migrations appliquées, uniquement en ajouter de nouvelles
- Secrets uniquement depuis les variables d'environnement

## Vérification avant d'écrire « terminé »
docker compose up -d     # environnement
make lint                # ruff + mypy
make test                # pytest
make e2e                 # scénario de commande
Des tests unitaires verts sans E2E ne valent pas « terminé ».

## Carte
- app/payments/   — calcul des montants, remises, webhooks du fournisseur
- app/api/        — gestionnaires HTTP
- tests/e2e/      — scénarios utilisateur
Détails : docs/agents/architecture.md, docs/agents/database.md

## État du travail
- PLAN.md      — objectif courant, critères d'achèvement, prochaine étape
- PROGRESS.md  — ce qui a été fait et comment c'est vérifié, impasses
- BACKLOG.md   — ce qui est repéré « au passage » : le noter ici, ne pas le corriger maintenant

À la fin de la session, mettez à jour PROGRESS.md et la prochaine étape dans PLAN.md.

Remarquez ce qui est absent : pas de liste de bibliothèques, pas de conseils de style, pas d'historique du projet. Tout cela est soit visible dans le code, soit garanti par des vérifications, soit consigné dans des documents thématiques.

L'amnésie entre les sessions : un fichier d'instructions plus un fichier de plan

Le fichier d'instructions décrit comment travailler dans le projet, mais pas ce qui se passe en ce moment. Il faut pour cela un fichier d'état distinct, que l'agent lit au début et met à jour à la fin de la session. Il contient l'objectif, ce qui a été fait avec l'indication de la façon dont cela a été vérifié, les décisions avec leurs raisons, les options écartées et une formulation de la prochaine étape. Test de qualité simple : ouvrez une nouvelle session, écrivez « continue » et voyez si l'agent se met utilement au travail sans poser de questions.

Ne confondez pas les deux fichiers. Les instructions changent rarement et concernent toutes les tâches. Le plan change à chaque session et concerne la tâche en cours. Si vous mélangez les deux, le fichier d'instructions se remplit vite de notes périmées.

Comment vérifier que le fichier fonctionne

Le fichier d'instructions doit lui aussi être testé. Prenez quelques tâches types — une correction de bug, une petite fonctionnalité, un refactoring — et observez ce que fait l'agent sans indication : lance-t-il les bonnes commandes, ouvre-t-il le bon document thématique, respecte-t-il les contraintes strictes. Si une règle est transgressée, demandez-vous d'abord si elle est visible, si elle contredit une autre règle et si elle peut être remplacée par une vérification automatique. Ajouter une nouvelle ligne est le dernier recours.

Synthèse

CLAUDE.md et AGENTS.md constituent le point d'entrée de l'agent dans le projet. Ils fonctionnent lorsqu'ils restent une courte carte : commandes de vérification, contraintes strictes en haut, liens vers les détails et vers le fichier de plan. Si une règle est ignorée, la cause est presque toujours un fichier démesuré et non structuré ; les règles réellement critiques doivent être soutenues par des vérifications et des hooks. La conception des instructions et de l'état de l'agent est traitée en pratique dans le cours sur le harness engineering.