AGENTS.md : un seul fichier de contexte pour tous tes agents de code (Codex, Antigravity, 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 Antigravity 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

Quand ce guide a été écrit, chaque outil cherchait son propre fichier. La plupart ont depuis convergé vers AGENTS.md :

• Codex lit AGENTS.md, comme GitHub Copilot CLI, Cursor, Amp et la plupart des CLI d'agent récents.
• Claude Code lit CLAUDE.md, et depuis la version 2.1.277 il lit aussi AGENTS.md tout seul quand ton dossier de travail et les dossiers au-dessus n'ont ni CLAUDE.md ni CLAUDE.local.md. Quand un CLAUDE.md existe, Claude ne lit que lui, sauf si tu changes le réglage Project instructions dans /config.
• Antigravity CLI lit AGENTS.md ou GEMINI.md, à la racine du dépôt ou dans n'importe quel sous-dossier, plus un dossier .agents/rules/ et des règles globales sous ~/.gemini/.

Le contenu est quasi identique dans les trois : contexte du projet, commandes, conventions. Ce qui diffère encore, c'est le fichier qu'un outil choisit quand il en trouve plusieurs. 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). On a vérifié ces comportements le 10 octobre 2026 dans la documentation mémoire de Claude Code et dans la documentation des règles d'Antigravity.

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 seul AGENTS.md, rien d'autre. Si personne n'a besoin de règles propres à Claude, garde un seul AGENTS.md : Codex, Antigravity CLI et Claude Code 2.1.277 ou plus récent le lisent tous. Le piège est silencieux : un CLAUDE.md, ou un CLAUDE.local.md personnel, ajouté plus tard fait que Claude Code arrête de lire AGENTS.md.
• Un fichier canonique, un import. Mets tout dans AGENTS.md et commence CLAUDE.md par la ligne @AGENTS.md, puis écris en dessous les règles propres à Claude. Claude lit d'abord le fichier importé. Notre propre dépôt fonctionne comme ça : son CLAUDE.md tient en cette seule ligne. Un lien symbolique (ln -s AGENTS.md CLAUDE.md) marche aussi, mais mal sous Windows, où en créer un demande les droits Administrateur ou le mode développeur, et où un clone sans core.symlinks récupère un fichier texte d'une ligne à la place de tes consignes.

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 Antigravity 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.

Questions fréquentes

AGENTS.md, c'est quoi ?

Un fichier Markdown, en général à la racine d'un dépôt, que les agents de code chargent comme consignes permanentes avant de travailler : ce qu'est le projet, comment le compiler et le tester, les conventions à respecter et les pièges à éviter. C'est une convention ouverte partagée entre outils plutôt que le fichier d'un seul outil, lue par Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp et, depuis la version 2.1.277, Claude Code.

Claude Code lit-il AGENTS.md ?

Oui, depuis Claude Code 2.1.277, mais seulement quand il n'y a ni CLAUDE.md, ni .claude/CLAUDE.md, ni CLAUDE.local.md dans ton dossier de travail ou au-dessus. Il charge alors chaque AGENTS.md du dossier de travail en remontant, et l'AGENTS.md d'un sous-dossier quand il y ouvre un fichier. Si un CLAUDE.md existe, Claude ne lit que lui, sauf si tu passes Project instructions sur claude-md-and-agents-md dans /config. Sur les versions plus anciennes, mets la ligne @AGENTS.md en tête d'un CLAUDE.md.

Antigravity utilise-t-il AGENTS.md ou GEMINI.md ?

Les deux. Antigravity lit un AGENTS.md, un GEMINI.md ou un dossier .agents/rules/ à la racine du dépôt ou dans n'importe quel sous-dossier, et des règles globales dans ~/.gemini/. Les règles s'additionnent au lieu de se remplacer, et quand deux d'entre elles se contredisent, c'est la règle du dossier le plus précis qui l'emporte.

Faut-il garder AGENTS.md ou CLAUDE.md ?

Garde AGENTS.md comme le seul fichier que tu maintiens. Si tu as aussi besoin de règles pour Claude seul, ajoute un CLAUDE.md dont la première ligne est @AGENTS.md et écris ces règles en dessous : Claude lit d'abord le fichier importé. Si tu n'en as pas besoin, AGENTS.md suffit pour Claude Code 2.1.277 ou plus récent. Évite deux copies complètes des mêmes règles : celle que personne ne modifie devient fausse.

Où mettre AGENTS.md ?

À la racine du dépôt pour les règles qui valent partout. Claude Code et Antigravity lisent aussi les fichiers AGENTS.md des sous-dossiers, donc un package ou un service avec ses propres commandes peut porter son propre fichier, lu quand l'agent travaille dans ce dossier.