AGENTS.md : un seul fichier de contexte pour tous tes agents de code (Codex, Gemini, Claude)

Tu as passé un après-midi à écrire un CLAUDE.md propre. Ton agent a enfin arrêté de deviner ta stack et s'est mis à lancer la bonne commande de test. Et puis un collègue ouvre le même repo avec Codex, tu testes Gemini CLI sur une branche, et tout ce contexte si durement gagné ne suit pas. Chaque outil veut son propre fichier, à son propre endroit.

AGENTS.md, c'est la réponse à ce bazar : un seul fichier Markdown, à la racine de ton repo, que n'importe quel agent de code lit avant de toucher à ton code.

AGENTS.md, c'est quoi au juste

Aucune magie. C'est un fichier Markdown nommé AGENTS.md, en général à la racine du dépôt, qu'un agent charge comme consignes permanentes avant de commencer à travailler. Vois-le comme le README que tu écris pour tes coéquipiers IA plutôt que pour tes coéquipiers humains : ce qu'est le projet, comment le builder et le tester, les conventions à respecter, et les pièges à éviter.

C'est une convention ouverte, déjà lue par Codex et une liste grandissante d'outils d'agents, pensée pour être portable de l'un à l'autre. Un fichier, plein d'agents, au lieu d'un fichier sur mesure par outil.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Pour l'instant le paysage est découpé par outil :

• CLAUDE.md, c'est ce que cherche Claude Code.
• GEMINI.md, c'est la convention de Gemini CLI.
• AGENTS.md, c'est le standard inter-outils, lu par Codex et d'autres, conçu pour être le fichier neutre.

Le contenu est quasi identique dans les trois : contexte du projet, commandes, conventions. La seule vraie différence, c'est le nom de fichier que chaque outil lit par défaut. C'est exactement pour ça que dupliquer les mêmes règles à la main dans trois fichiers est une bataille perdue d'avance (on revient plus bas sur comment les garder synchros).

Si tu bosses surtout dans Claude Code, notre guide CLAUDE.md creuse la structure spécifique à Claude. AGENTS.md, c'est le cousin neutre, indépendant du provider, de ce fichier.

Ce qu'il faut y mettre

Garde-le court et à fort signal. Un agent le lit à chaque tâche, donc chaque ligne se bat pour capter l'attention. L'essentiel :

• La stack, en une phrase. "Next.js 16, TypeScript, Prisma, MariaDB." Pas d'historique, pas de marketing.
• Les commandes qui comptent. Comment installer, lancer, builder, tester et linter. Des commandes exactes : npm test, pas "lance les tests."
• Les conventions. Nommage, organisation des fichiers, gestion d'erreurs, les patterns que tu fais vraiment respecter en review.
• Une carte des dossiers. Deux lignes sur où vivent les choses, pour que l'agent arrête de grepper à l'aveugle.
• Des règles "lire avant de toucher". "Lis docs/payments.md avant de modifier quoi que ce soit sous billing/." Cette seule habitude évite beaucoup de dégâts.
• Les interdits fermes. "Ne jamais créer de branche sans qu'on le demande." "Pas de chemins absolus liés à la machine dans les fichiers commités."

Les erreurs qui font ignorer le fichier par les agents

Un fichier de contexte échoue en silence. L'agent ne plante pas, il dérive, c'est tout. Les causes classiques :

1. Trop long. Un fichier de 600 lignes enterre les cinq règles qui comptent. Coupe tout ce que l'agent peut déduire du code lui-même.
2. Des contradictions. "Toujours écrire des tests" dans une section, "sauter les tests pour les prototypes" dans une autre. L'agent en choisit une au hasard.
3. Des chemins liés à la machine. /Users/toi/projet/... dans un fichier commité casse pour tous tes collègues, et pour tout agent sur n'importe quelle autre machine. Garde des chemins relatifs.
4. Des commandes périmées. La commande de test a changé il y a six mois, pas le fichier. Maintenant l'agent lance le mauvais truc avec une confiance totale.
5. Aucune priorité. Tout est "important," donc rien ne l'est. Mets les non-négociables en premier et étiquette-les.
6. Du déversement de doc. Ce sont des instructions, pas un wiki. Mets des liens vers ta doc, ne la colle pas dedans.

Garder un seul contexte entre les providers

Voilà la partie pratique que la plupart des guides zappent. Si toi, ou ton équipe, lancez plus d'un agent CLI, tu ne veux pas trois copies divergentes des mêmes règles.

Deux approches propres :

• Un fichier canonique, des pointeurs minces. Mets tout dans AGENTS.md et fais de CLAUDE.md et GEMINI.md des fichiers d'une ligne qui disent "voir AGENTS.md," ou crée des liens symboliques. Une seule source de vérité, tous les outils nourris.
• Un fichier, partagé par convention. Si tes outils peuvent pointer vers un chemin personnalisé, vise-les tous vers AGENTS.md et supprime le reste.

Dans les deux cas la règle est la même : écris le contexte une fois, pas une fois par provider. C'est aussi la seule façon qu'il reste correct, parce qu'un fichier unique est le seul fichier que les gens maintiennent vraiment.

Quand tu lances plusieurs agents en même temps

Un AGENTS.md au niveau du repo répond à "c'est quoi ce projet." Il ne répond pas à "c'est qui cet agent." Quand tu lances un agent Backend, un agent Frontend et un agent QA en parallèle sur le même code, chacun a besoin du contexte projet partagé plus de son propre rôle.

C'est la couche qu'AgentsRoom ajoute par-dessus ton AGENTS.md. Chaque agent reçoit un rôle dédié avec son propre system prompt (DevOps, Frontend, Sécurité et d'autres), pour que le fichier partagé reste léger pendant que chaque agent sait quand même quel est son job. C'est agnostique au provider par conception, donc le même setup fait tourner Claude, Codex ou Gemini côte à côte, et tes instructions réutilisables vivent dans une bibliothèque de prompts au lieu d'être retapées dans chaque session.

Arrivé là, la méthode pour faire tourner plusieurs agents en parallèle sans perdre le fil est la lecture qui suit naturellement.

À retenir

Écris un seul AGENTS.md. Garde-le court, garde-le à jour, garde-le portable. Pointe chaque outil dessus au lieu de maintenir un fichier par agent. Ton contexte arrête d'être lié au CLI par lequel tu as commencé, et tes agents, quels qu'ils soient, partent tous de la même page.

Tu veux tous tes agents sur un seul écran, chacun avec son rôle et ton contexte partagé ? Télécharge AgentsRoom, connecte ton provider, et mets ta flotte au travail.