CLAUDE.md et AGENTS.md : les fichiers de contexte qui pilotent un agent de code

Un fichier CLAUDE.md ou AGENTS.md est un document court, à la racine du repo, que l’agent de code lit au début de chaque session. Il contient ce qu’un nouvel arrivant devrait savoir le premier jour et que le code ne dit pas : comment lancer les tests, où vont les choses, quelles conventions ne se devinent pas, où sont les pièges. Claude Code lit CLAUDE.md, d’autres outils ont adopté AGENTS.md pour le même objet, et une équipe qui utilise plusieurs outils maintient un seul fichier et fait pointer l’autre dessus.

C’est le document au meilleur rendement du repo, et celui que nous auditons en premier chez nos clients. La règle qui le résume : court, juste, utile. Chaque ligne doit changer ce que l’agent fait, être vraie, et mériter l’attention qu’elle consomme.

Ce qui va dans le fichier

Les commandes d’abord : tester, tester un seul fichier vite, linter, builder, lancer l’application en local. Un agent qui sait vérifier son travail converge seul, un agent qui devine tâtonne toute la session.

Ensuite une carte plutôt qu’une visite guidée : où vit la couche API, où va la logique partagée, par où passent les migrations. Une dizaine de lignes d’orientation épargnent des centaines de lectures et évitent le code neuf posé à un endroit plausible mais faux.

Puis les conventions qui s’écartent des défauts. L’agent arrive avec des habitudes génériques raisonnables, inutile de les lui redire. Notez là où votre équipe diverge : un type de résultat plutôt que des exceptions, des dates en UTC partout, ce service qui n’importe jamais celui-là.

Enfin les pièges connus, la rubrique qui paie à elle seule le fichier, une ligne franche chacun : le test instable qui demande un retry, le dossier généré qu’on n’édite pas à la main, le module en migration dont il ne faut pas imiter l’ancien pattern.

Ce qui n’y va pas

La documentation exhaustive : le wiki reste le wiki, le fichier y renvoie. Les évidences : "écrire du code propre et testé" ne change rien au comportement d’aucun agent et consomme de l’attention. Ce que le linter impose déjà, puisque le linter est l’application de la règle.

Les règles aspirationnelles sont plus dangereuses. Si le fichier décrit un pattern que le code ne suit pas, l’agent tient une contradiction et la résout au hasard, en copiant parfois le code voisin, parfois le fichier, souvent les deux dans un même diff. Décrivez le code que vous avez, plus la direction si elle est réelle.

Les procédures propres à une tâche n’y ont pas leur place non plus. Écrire une migration ou sortir une release relève d’une skill que l’agent charge quand la tâche se présente, et non du briefing permanent de chaque session. Tout ce qui se périme vite (la version du framework, le nom du responsable, l’état du sprint) va ailleurs.

Un fichier à la racine, un par module quand il le faut

Sur un petit repo, un seul fichier suffit. Sur un monorepo ou une base de code qui mélange plusieurs stacks, le fichier racine garde le général (commandes globales, carte, conventions transverses) et chaque module important reçoit le sien, avec ses commandes et ses pièges locaux. Les outils chargent le fichier racine, puis celui du dossier où l’agent travaille.

Les erreurs classiques, et l’entretien qui les évite

Le fichier de trois pages, assemblé en collant le guide de style, le document d’onboarding et deux README, où les douze lignes qui comptent sont enterrées sous trois cents qui ne comptent pas. Le fichier aux instructions contradictoires, parce que deux personnes l’ont complété sans se lire. Et le fichier écrit une fois, pendant la semaine de préparation de la base de code, puis oublié : six mois plus tard, la commande de test a changé de nom, l’agent conclut que la suite est cassée et contourne.

L’entretien tient en trois habitudes. Le fichier change dans la pull request qui change ce qu’il décrit, et le relecteur le vérifie. Chaque repo a un responsable nommé. Et chaque passage retire au moins une ligne devenue fausse ou inutile.

Comment savoir si le fichier sert

Le test est comportemental. Dans une session neuve, confiez à l’agent une tâche de routine : trouve-t-il le bon dossier, lance-t-il les bonnes commandes, respecte-t-il les conventions maison sans qu’on les lui répète ? Quand la réponse est non, la correction est presque toujours dans le fichier de contexte, et c’est le plus souvent une suppression.

La mesure qui tient dans la durée est le taux de diffs mergeables sans retouche sur des tickets ordinaires du backlog, suivi chaque semaine. C’est l’indicateur avec lequel nous pilotons le déploiement des agents dans une équipe, et le fichier de contexte est le premier levier quand il stagne. Il permet aussi de comparer Claude Code, Cursor et Copilot à armes égales, puisque tous lisent un fichier de ce type.

Écrire la première version franche prend un après-midi. Auditer et réécrire ces fichiers est souvent la première correction que nous livrons dans une mission d’ingénierie agentique, parce que c’est le delta le moins cher que nous connaissions : un fichier, une demi-journée, et toutes les sessions suivantes un peu meilleures.