AGENTS.md : le fichier d'instructions commun aux agents de code, et où chacun le cherche
AGENTS.md est un README pour les agents de code : un fichier Markdown que Codex, Copilot, Cursor et, à une condition, Claude Code lisent avant de toucher à votre code. Le format est simple. Les différences sont dans l'endroit où chaque outil le cherche.
Mis à jour le 14 novembre 2026. Chaque comportement décrit ici vient de la documentation officielle de l'outil, consultée ce jour-là. Les sources sont en lien dans chaque partie.
AGENTS.md est un simple fichier Markdown, en général à la racine du dépôt, qui explique aux agents de code comment travailler sur le projet : comment builder et tester, quelles conventions suivre, à quoi ne jamais toucher. Aucun champ n'est obligatoire. Le format est décrit sur agents.md, qui annonce plus de 60 000 projets open source utilisateurs et précise qu'il est désormais géré par l'Agentic AI Foundation, sous l'égide de la Linux Foundation.
Quels outils lisent AGENTS.md, et où
Le fichier est commun ; les règles de chargement, non. Voici ce que dit la documentation de chaque outil, vérifiée le 14 novembre 2026.
- OpenAI Codex : lit AGENTS.md avant tout travail. D'abord un fichier global dans ~/.codex (AGENTS.override.md s'il existe), puis un fichier par dossier, de la racine du projet jusqu'au dossier courant. Les fichiers les plus proches arrivent en dernier et l'emportent. La taille cumulée s'arrête à 32 Kio par défaut (project_doc_max_bytes).
- Claude Code : lit AGENTS.md comme instructions de projet depuis la version 2.1.277, mais par défaut seulement s'il n'y a aucun CLAUDE.md dans le dossier de travail ou au-dessus. Si les deux existent, il lit CLAUDE.md.
- GitHub Copilot : un ou plusieurs AGENTS.md n'importe où dans le dépôt ; le plus proche dans l'arborescence l'emporte. Un seul CLAUDE.md ou GEMINI.md à la racine fonctionne aussi. L'agent cloud, la revue de code, Copilot CLI et le chat de VS Code le prennent en charge ; les chats de Visual Studio, JetBrains et Xcode ne le mentionnent pas.
- Cursor : AGENTS.md à la racine du projet et dans les sous-dossiers. Les fichiers imbriqués se combinent avec ceux des dossiers parents et le plus précis l'emporte. C'est une alternative simple à .cursor/rules, sans métadonnées.
- VS Code : avec l'agent Copilot, AGENTS.md est trouvé à la racine du dépôt, dans le dossier de travail et dans les dossiers intermédiaires. L'ancien mode Local utilise les réglages chat.useAgentsMdFile (activé par défaut) et chat.useNestedAgentsMdFiles (désactivé par défaut).
Le site agents.md cite aussi Jules, Aider, Zed, Warp, Windsurf, Devin, Junie et Gemini CLI parmi les agents compatibles. Sources : Codex, Claude Code, GitHub Copilot, Cursor, VS Code.
AGENTS.md et CLAUDE.md dans le même dépôt
C'est là que la plupart des guides se contredisent. La documentation d'Anthropic est précise : par défaut, Claude Code lit AGENTS.md seulement s'il n'y a aucun CLAUDE.md dans le dossier de travail ou au-dessus. Dès qu'un CLAUDE.md s'y trouve, Claude lit ce fichier à la place.
Pour garder une seule source lue par tous les outils, Anthropic recommande un CLAUDE.md à côté, qui l'importe en une ligne, @AGENTS.md, suivie de ce qui ne concerne que Claude. Un lien symbolique (ln -s AGENTS.md CLAUDE.md) marche aussi si vous n'avez rien de propre à Claude, mais ses outils Edit et Write refusent d'écrire à travers un lien symbolique, et sous Windows la documentation renvoie vers l'import.
@AGENTS.md
## Claude Code
- Passer en mode plan pour toute modification de src/billing/.Deux précisions de la même page. Claude Code ne lit ni AGENTS.override.md (utilisé par Codex), ni AGENTS.local.md, ni le contenu d'un dossier .agents/. Et le réglage Project instructions de /config peut charger les deux fichiers à la fois (claude-md-and-agents-md) sans lire deux fois le même AGENTS.md.
Fichiers imbriqués : lequel l'emporte
Dans un monorepo, vous pouvez placer un AGENTS.md dans chaque paquet. La FAQ d'agents.md donne la règle générale : l'AGENTS.md le plus proche du fichier modifié l'emporte, et une consigne explicite dans le chat passe avant tout. Les outils diffèrent ensuite dans le détail. Codex assemble les fichiers de la racine jusqu'au dossier courant et ne lit rien en dessous. Cursor combine les fichiers imbriqués avec ceux des parents. Copilot donne la priorité au fichier le plus proche. Claude Code charge l'AGENTS.md d'un sous-dossier quand il y lit un fichier, si ce dossier n'a pas de CLAUDE.md.
Ce qu'il faut mettre dans AGENTS.md
- Les commandes qu'un agent ne peut pas deviner : installer, builder, linter, lancer tous les tests, lancer un seul test.
- Les conventions qui s'écartent des habitudes : « les montants sont des entiers en centimes », « un fichier par route d'API ».
- Ce qu'il ne faut jamais faire : « ne jamais modifier src/generated/ », « aucune dépendance ajoutée sans demander ».
- Où sont les choses : les quelques dossiers qui comptent et ce qu'ils contiennent.
- Comment rendre le travail : format des messages de commit, ce qu'il faut vérifier avant une pull request.
Écrivez des consignes vérifiables, « lance pnpm test avant chaque commit » plutôt que « assure-toi que ça marche », et gardez le fichier court. Chaque ligne est chargée au début de chaque session, par chaque agent qui le lit, et Codex cesse d'ajouter des fichiers d'instructions à 32 Kio par défaut.
# API de facturation
## Commandes
- Installer : `pnpm install`
- Tous les tests : `pnpm test` · un fichier : `pnpm test src/invoices/total.test.ts`
- Lint avant chaque commit : `pnpm lint`
## Conventions
- TypeScript strict, exports nommés uniquement
- Handlers d'API dans `src/api/handlers/`, un fichier par route
- Les montants sont des entiers en centimes, jamais des décimaux
## Jamais
- Modifier les fichiers de `src/generated/` (lancer `pnpm codegen` à la place)
- Ajouter une dépendance sans demander
## Avant une pull request
- `pnpm lint && pnpm test` passent
- Messages de commit : `zone: ce qui change`Ce qu'il faut laisser dehors
- Les secrets : clés d'API et mots de passe n'ont rien à faire dans un fichier versionné et chargé dans chaque session.
- Les réglages d'un seul outil : ils vont dans CLAUDE.md, .cursor/rules ou la configuration propre à cet outil.
- La documentation longue : mettez un lien plutôt que de la coller.
- L'historique des décisions : pourquoi vous avez choisi Postgres, ce que le client a demandé la semaine dernière, le bug déjà traqué pendant deux jours.
Ce dernier point est le piège. AGENTS.md est lu en entier à chaque démarrage, par chaque agent. C'est le bon endroit pour des règles qui changent rarement, et le mauvais pour un savoir qui grossit sans cesse. Ce savoir a sa place dans une mémoire que l'agent consulte seulement quand il en a besoin, et que tous vos agents peuvent lire.
Pryzm pour ordinateur en est une : une appli gratuite, sans compte, qui garde cette mémoire dans un fichier SQLite sur votre ordinateur et connecte Claude Code, Claude Desktop, Cursor et VS Code en un clic, pour qu'ils lisent tous les mêmes décisions. Une ligne dans AGENTS.md suffit pour que les agents s'en servent : « Avant de commencer, cherche dans la mémoire Pryzm les décisions passées sur ce projet, et enregistre-y les nouvelles. » Côté Claude, voir le guide CLAUDE.md.
Questions fréquentes
Qu'est-ce que AGENTS.md ?
Un simple fichier Markdown, en général à la racine du dépôt, qui contient les consignes destinées aux agents de code : commandes de build et de test, conventions, choses à éviter. Aucun champ n'est obligatoire. Le format est géré par l'Agentic AI Foundation, sous l'égide de la Linux Foundation.
Claude Code lit-il AGENTS.md ?
Oui, depuis la version 2.1.277, mais par défaut seulement s'il n'y a aucun CLAUDE.md dans le dossier de travail ou au-dessus. Pour utiliser les deux, placez à côté un CLAUDE.md qui contient la ligne @AGENTS.md.
Où Codex cherche-t-il AGENTS.md ?
Dans ~/.codex pour les consignes globales, puis dans chaque dossier de la racine du projet jusqu'au dossier courant, un fichier par dossier, AGENTS.override.md passant en premier. La taille cumulée est limitée à 32 Kio par défaut.
Faut-il utiliser AGENTS.md ou CLAUDE.md ?
Si vous utilisez plusieurs agents de code, écrivez les règles communes dans AGENTS.md et gardez un CLAUDE.md court qui l'importe et ajoute ce dont seul Claude a besoin. Si vous n'utilisez que Claude Code, CLAUDE.md suffit.
AGENTS.md peut-il remplacer une mémoire ?
Non. Il est chargé en entier à chaque session : il doit contenir des règles stables. Les décisions et le contexte qui grossissent sans cesse ont leur place dans un serveur de mémoire que l'agent consulte au besoin.