Aller au contenu principal

AGENTS.md & interopérabilité entre outils

Intermédiaire

Vous connaissez déjà CLAUDE.md — le briefing de projet de Claude Code. Mais votre dépôt est probablement manipulé par plus d'un agent : un collègue lance Codex, la CI utilise un bot de code, quelqu'un ouvre le dépôt dans Cursor. AGENTS.md est le standard ouvert que ces outils s'accordent à lire, pour que vous écriviez les instructions de votre projet une seule fois au lieu de maintenir un fichier différent par outil.

What you'll learn
  • Ce qu'est AGENTS.md et qui en assure la gouvernance
  • Pourquoi Claude Code lit CLAUDE.md et non AGENTS.md
  • Trois moyens fiables de garder une seule source de vérité entre les outils
  • Comment les fichiers AGENTS.md imbriqués et globaux fusionnent
  • Ce qui a sa place dans le fichier — et ce qu'il faut en exclure

Ce qu'est AGENTS.md​

AGENTS.md est un simple fichier Markdown à la racine de votre dépôt — voyez-le comme un README écrit pour les agents plutôt que pour les humains. Il indique à un agent de code comment construire, tester et contribuer au projet. Le format n'impose aucun champ : les agents lisent simplement le texte.

C'est un standard ouvert dont la gouvernance est assurée par l'Agentic AI Foundation (AAIF) sous l'égide de la Linux Foundation, et à la mi-2026 il est utilisé par plus de 60 000 projets open source et lu par plus de 30 outils — dont OpenAI Codex, Jules et Gemini CLI de Google, Cursor, Windsurf, Devin, Zed, Warp, Aider, goose, Amp et l'agent de code de GitHub Copilot.

What you'll learn
  • AGENTS.md est une convention, pas un runtime : chaque outil décide comment il découvre, fusionne et injecte le fichier.
  • Aucun schéma n'est imposé — un texte clair vaut mieux qu'une structure rigide.
  • Il complète votre README ; il ne le remplace pas.

Le piège de Claude Code​

Voici le point sur lequel les gens trébuchent : Claude Code lit CLAUDE.md, pas AGENTS.md. Si votre dépôt ne contient qu'un AGENTS.md, Claude Code l'ignore par défaut. Ce n'est pas un bug — il précède le standard — mais cela signifie qu'un dépôt multi-outils a besoin d'une stratégie de synchronisation délibérée, sinon vos instructions divergent silencieusement.

Watch out
  • Ne supposez pas que Claude Code se rabat sur AGENTS.md — il ne le lit pas automatiquement.
  • Deux fichiers maintenus à la main (CLAUDE.md et AGENTS.md) finiront par diverger. Choisissez une seule source de vérité.
  • Vérifiez le comportement actuel dans la documentation mémoire officielle avant de vous fier à toute promesse de repli.

Gardez une seule source de vérité​

Trois approches gardent CLAUDE.md et AGENTS.md synchronisés sans dupliquer le contenu. Choisissez selon la plateforme de votre équipe.

Guided walkthrough1 of 3
  1. Faites de CLAUDE.md un lien symbolique vers AGENTS.md. Claude Code suit les liens symboliques et lit la cible octet pour octet — un seul vrai fichier, aucune logique de fusion. Bémol : sous Windows, créer un lien symbolique nécessite le mode développeur ou des droits administrateur, donc les équipes multi-plateformes peuvent préférer la méthode par import.

Lier CLAUDE.md au standard partagé par symlink (macOS / Linux)

ln -s AGENTS.md CLAUDE.md

Ou garder un CLAUDE.md d'une seule ligne qui l'importe

@AGENTS.md
Pro tip
  • Utilisez le symlink quand toute votre équipe est sous macOS/Linux — c'est le moins de maintenance.
  • Utilisez @import quand des contributeurs sous Windows sont impliqués.
  • Versionnez l'option que vous choisissez pour que toute l'équipe obtienne le même comportement.

Comment les fichiers imbriqués et globaux fusionnent​

Les agents les plus aboutis traitent AGENTS.md de façon hiérarchique — le même modèle mental que la hiérarchie mémoire de CLAUDE.md. Codex, par exemple, part d'un fichier global dans votre répertoire personnel, descend jusqu'à la racine Git puis jusqu'à votre dossier courant, en concaténant au fur et à mesure :

Les fichiers les plus proches du travail l'emportent, parce qu'ils sont concaténés en dernier et surchargent les directives antérieures. Ainsi, un services/payments/AGENTS.md hérite des instructions de la racine du dépôt et ajoute des règles qui ne s'appliquent qu'à l'intérieur de ce service — placez les directives spécialisées aussi près que possible du code spécialisé.

L'interopérabilité en un coup d'œil
Appuyez sur Entrée ou Espace pour retourner la carte. Utilisez les flèches gauche et droite pour naviguer entre les cartes.Terme affiché.
1 / 5

Ce qu'il faut y mettre​

La même discipline qu'un bon CLAUDE.md — le standard suggère simplement quelques sections courantes :

  • Présentation du projet — ce que c'est, en deux phrases.
  • Commandes de build et de test — comment exécuter, tester et linter.
  • Style de code — les conventions qu'un agent ne peut pas deviner.
  • Instructions de test — ce que « terminé » signifie.
  • Considérations de sécurité — ce qu'il ne faut jamais toucher ni committer.
  • Directives de commit / PR — format des messages, règles de branches.
Watch out
  • Les agents suivent le fichier à la lettre — des instructions périmées ou idéalisées nuisent activement, exactement comme pour CLAUDE.md.
  • Gardez-le court et vrai ; décrivez comment le projet fonctionne aujourd'hui.
  • Ne committez jamais de secrets ; référencez les gros documents au lieu de les coller.

Vérifiez vos acquis​

Vérifiez vos acquis

0/3
  1. Claude Code lit-il AGENTS.md automatiquement ?
  2. Votre équipe est entièrement sous macOS et Linux. Quel est le moyen le moins coûteux en maintenance pour partager un seul fichier d'instructions entre Claude Code et Codex ?
  3. Quand des agents fusionnent un AGENTS.md global, un à la racine du dépôt et un dans un sous-répertoire, lequel l'emporte en cas de conflit ?
Key takeaways
  • AGENTS.md est le standard ouvert, sous gouvernance de la Linux Foundation, que lisent plus de 30 agents de code — un README pour les agents.
  • Claude Code lit CLAUDE.md, pas AGENTS.md, donc les dépôts multi-outils doivent les garder synchronisés.
  • Liez CLAUDE.md → AGENTS.md par symlink sous Mac/Linux, ou utilisez un import @AGENTS.md d'une seule ligne pour les équipes multi-plateformes.
  • Les fichiers imbriqués fusionnent global → racine → sous-répertoire, le fichier le plus proche l'emportant.
  • Remplissez-le comme un excellent CLAUDE.md : présentation, commandes de build/test, conventions, sécurité et garde-fous — court et vrai.

Pour aller plus loin​

Sources & lectures complémentaires​