Explication · mis à jour Oct 10, 2026

Qu'est-ce qu'AGENTS.md et comment les agents de code l'utilisent

AGENTS.md est un fichier Markdown simple placé dans un dépôt, qui donne aux agents de code les étapes de build, les tests et les conventions. Il n'a aucun champ obligatoire, et les agents lisent le fichier le plus proche dans l'arborescence.

AGENTS.md →

Ce qu'est AGENTS.md

AGENTS.md est un fichier Markdown simple que vous placez dans un dépôt pour donner aux agents de code les instructions de projet dont ils ont besoin, comme les étapes de build, les tests et les conventions. Le site AGENTS.md le décrit comme un README pour agents. Les humains continuent de lire le README habituel, tandis que les agents disposent d'un emplacement prévisible pour le détail qui l'encombrerait. Selon le site, le format est piloté par l'Agentic AI Foundation, au sein de la Linux Foundation. Parmi les agents qui le lisent figurent Claude Code, OpenAI Codex, Gemini CLI, Cursor et GitHub Copilot.

Il n'y a ni champ obligatoire ni schéma. C'est du Markdown standard : vous pouvez utiliser les titres de votre choix. La façon dont un agent traite le contenu dépend de cet agent, et c'est le point essentiel à connaître avant de s'y fier. Comme le format n'impose aucune règle sur le contenu, deux agents peuvent lire le même fichier et agir différemment ; il vaut donc la peine de vérifier comment chaque outil que vous utilisez le gère.

Un README pour les humains, un AGENTS.md pour les agents : étapes de build, tests et conventions

Comment fonctionne AGENTS.md

Un agent lit l'AGENTS.md le plus proche du fichier qu'il modifie. Dans un monorepo, vous pouvez donc garder un fichier à la racine du dépôt et en ajouter un dans chaque package, de sorte que chaque sous-projet ait ses propres instructions. En cas de conflit entre deux fichiers, le plus proche l'emporte. Les prompts explicites de l'utilisateur dans le chat priment sur tout, fichier compris. AGENTS.md est donc une consigne pour l'agent, pas une règle stricte. Des couches propres à chaque outil viennent s'y ajouter : règles Cursor, skills Claude Code et serveurs MCP pour les outils externes.

Fichiers AGENTS.md imbriqués : le plus proche l'emporte, et votre prompt dans le chat prime sur tous

Donne aux agents un emplacement prévisible pour les instructions de configuration, de test et de style de code
Garde le détail destiné aux agents hors du README des humains
Prend en charge des fichiers AGENTS.md imbriqués ; le plus proche du fichier modifié l'emporte
Fonctionne avec de nombreux agents grâce à un seul fichier, au lieu d'un format par outil

Ce que coûte AGENTS.md

AGENTS.md est un format de fichier et non un produit payant : il n'y a ni plans ni prix à comparer. Notre fiche n'indique ni licence ni date de sortie, et le dépôt source public n'a pas été vérifié ; nous ne les mentionnons donc pas. La seule condition est un agent qui lit AGENTS.md. Tout le reste se résume au temps nécessaire pour écrire et maintenir le fichier. Si vous hésitez encore sur l'agent, commencez par Codex vs Claude Code, Cursor vs GitHub Copilot ou la liste des meilleurs agents IA ; le guide des outils IA de code couvre un champ plus large, et le prompt engineering explique comment formuler le fichier.

À qui s'adresse AGENTS.md, et à qui il ne convient pas

Il convient aux équipes qui utilisent plusieurs agents de code sur le même dépôt, car un seul fichier remplace un format distinct pour chaque outil. Il convient aussi aux monorepos qui ont besoin d'instructions par package, et à quiconque veut que les agents lancent les commandes de test indiquées avant de terminer. Garder ce détail hors du README des humains raccourcit les deux documents et les rend plus lisibles.

Ce n'est pas un moyen d'imposer une politique. Le fichier est un texte de consigne, et les prompts explicites de l'utilisateur dans le chat le supplantent. Si une règle doit toujours s'appliquer, il faut un mécanisme extérieur au fichier, puisque le format n'oblige aucun agent à suivre un contenu particulier. Considérez-le comme un jeu d'instructions partagé que de nombreux agents lisent, et vérifiez vous-même le comportement de chacun.

Quels agents lisent AGENTS.md

Le site cite Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf et d'autres. Notre catalogue relie les fiches associées pour OpenAI Codex, Cursor, Gemini CLI et Windsurf Editor. Certains outils demandent un réglage : Gemini CLI lit le fichier une fois context.fileName défini sur AGENTS.md dans .gemini/settings.json, et Aider a besoin de read: AGENTS.md dans .aider.conf.yml.

Les agents cités par le site, et les deux réglages dont Gemini CLI et Aider ont besoin

Premiers pas avec AGENTS.md

Créez un AGENTS.md à la racine du dépôt et ajoutez des sections comme l'aperçu du projet, les commandes de build et de test, le style de code, les tests et les consignes de PR. Pour un monorepo, ajoutez un autre fichier dans chaque package. Si vous avez déjà un fichier AGENT.md, la commande de migration figure aussi ci-dessous. Configurez ensuite tout agent qui ne prend pas le fichier en compte par défaut.

Créez le fichier à la racine, ajoutez des sections, puis un fichier par package

Créez un fichier AGENTS.md à la racine du dépôt
Ajoutez des sections comme l'aperçu du projet, les commandes de build et de test, le style de code, les tests et les consignes de PR
Pour les monorepos, ajoutez un autre AGENTS.md dans chaque package
Pour migrer : mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
Gemini CLI : définissez context.fileName sur AGENTS.md dans .gemini/settings.json ; Aider : ajoutez read: AGENTS.md à .aider.conf.yml

Questions fréquentes

Qu'est-ce qu'AGENTS.md??

AGENTS.md est un fichier Markdown simple placé dans un dépôt pour donner aux agents de code les étapes de build, les tests et les conventions. Le site le qualifie de README pour agents.

Que mettre dans AGENTS.md??

Mettez ce dont un agent a besoin pour travailler dans votre dépôt : un aperçu du projet, les commandes de build et de test, le style de code, les règles de test et les consignes de PR. Gardez le détail destiné aux humains dans le README, et ajoutez un AGENTS.md imbriqué par package dans un monorepo.

Que se passe-t-il quand des fichiers AGENTS.md sont en conflit??

L'AGENTS.md le plus proche du fichier modifié l'emporte, et les prompts explicites de l'utilisateur dans le chat priment sur tout.

Quels agents prennent en charge AGENTS.md??

Le site cite Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf et d'autres.

Comment faire lire AGENTS.md à Gemini CLI??

Définissez context.fileName sur AGENTS.md dans .gemini/settings.json.