Ce fichier AGENTS.md peut devenir le mode d’emploi commun de Codex, Claude, Cursor et Gemini

Un agent de développement peut comprendre la demande et tout de même casser le projet. Il modifie une ancienne migration déjà déployée, écrit dans un dossier généré, installe une dépendance inutile ou corrige le symptôme sans lancer les tests réellement utilisés par l’équipe.

Un fichier placé à la racine du dépôt peut réduire ce risque : AGENTS.md. Il décrit l’architecture, les commandes, les conventions et les limites que l’agent doit connaître avant de travailler. Codex et Cursor le lisent directement. Gemini CLI peut être configuré pour l’utiliser. Claude Code peut importer son contenu depuis CLAUDE.md.

Une étude de 2 853 dépôts montre la domination des fichiers de contexte

Des chercheurs des universités de Bamberg, Heidelberg et Singapore Management University ont étudié la configuration de Claude Code, GitHub Copilot, Cursor, Gemini et Codex dans 2 853 dépôts GitHub.

Ils ont identifié huit mécanismes allant du simple fichier de contexte aux intégrations et procédures exécutables. Leur principal constat est clair : les fichiers d’instructions dominent et constituent souvent l’unique configuration présente dans un projet. AGENTS.md apparaît comme un format interopérable entre plusieurs outils.

Les mécanismes plus sophistiqués restent beaucoup moins installés. La plupart des dépôts ne possèdent qu’un ou deux artefacts de configuration. Les skills s’appuient encore surtout sur du texte statique et les sous-agents sont faiblement adoptés. L’étude présente donc AGENTS.md comme un point de départ naturel, pas comme la preuve qu’il améliore automatiquement les performances de chaque agent.

À quoi sert exactement AGENTS.md ?

AGENTS.md est un fichier Markdown versionné avec le code. Il donne à l’agent les informations qu’un développeur expérimenté finirait par apprendre en travaillant sur le dépôt :

• où se trouve la logique métier ;
• quelles commandes installent, testent et construisent le projet ;
• quelles conventions sont réellement appliquées ;
• quels fichiers ne doivent jamais être modifiés ;
• comment gérer migrations, données et secrets ;
• quelles validations doivent réussir avant de terminer.

Le fichier évite de répéter ces règles dans chaque conversation. Surtout, il se déplace avec la branche et évolue dans le même historique Git que l’application. Une règle ajoutée pour une nouvelle architecture peut être relue, commentée et annulée comme n’importe quel changement de code.

Codex, Cursor, Gemini et Claude ne le chargent pas de la même manière

Le titre « mode d’emploi commun » désigne donc une source commune, pas quatre implémentations identiques. C’est précisément l’intérêt du petit relais : l’équipe maintient les règles essentielles dans un seul fichier au lieu de laisser diverger AGENTS.md, CLAUDE.md et GEMINI.md.

Comment Codex combine les instructions

La documentation officielle OpenAI précise que Codex lit les fichiers AGENTS.md avant de commencer. Il peut associer des règles globales dans le répertoire de configuration de l’utilisateur et des règles propres au dépôt.

Dans le projet, Codex part de la racine Git et descend jusqu’au dossier de travail. Un fichier plus proche du code concerné arrive plus tard dans la chaîne et peut remplacer une règle générale. Un service de paiement peut ainsi posséder des contraintes plus strictes que le reste de l’application.

Codex reconnaît également AGENTS.override.md. Ce fichier prend la priorité dans son dossier. La limite combinée documentée est de 32 Kio par défaut. Cette hiérarchie est utile pour un monorepo, mais elle crée aussi un risque : deux instructions opposées peuvent être chargées sans que l’équipe s’en rende compte.

AGENTS.md n’est pas un README destiné à une machine

Le README explique généralement ce qu’est le projet, comment l’installer et comment contribuer. Il s’adresse d’abord aux humains et peut contenir une présentation commerciale, des captures ou une documentation générale.

AGENTS.md doit être plus opérationnel. Il indique quelle commande exacte lancer, quelle couche modifier, quelle contrainte ne pas violer et comment vérifier le résultat. Il peut renvoyer vers le README au lieu de recopier toute son introduction.

CLAUDE.md joue un rôle comparable pour Claude Code. GEMINI.md constitue le contexte par défaut de Gemini CLI. Cursor dispose aussi de règles structurées dans .cursor/rules, et GitHub Copilot utilise ses propres fichiers d’instructions. AGENTS.md ne fait pas disparaître ces formats lorsque leurs fonctions spécifiques sont nécessaires.

Les informations réellement utiles à placer dans le fichier

1. Une carte courte de l’architecture

Écrire « projet PHP » est insuffisant. L’agent doit savoir où se trouvent contrôleurs, services, accès aux données, migrations, vues et tests. Il faut également préciser les frontières : « la logique métier reste dans les services » est plus utile qu’une description complète de chaque classe.

2. Les commandes qui fonctionnent réellement

Indiquez les commandes d’installation, de développement, de lint, d’analyse statique, de tests et de build. Une commande obsolète détériore davantage le travail qu’une commande absente. Elle doit donc être exécutée avant d’être inscrite.

3. Les conventions qui ne sont pas déjà automatisées

Le formatage simple appartient au linter. AGENTS.md doit surtout décrire les choix que la machine ne peut pas facilement déduire : nommage des routes publiques, compatibilité minimale, services à réutiliser ou stratégie de gestion des erreurs.

4. Les zones interdites et les actions soumises à validation

Listez les dossiers générés, fichiers tiers, secrets, migrations anciennes et configurations de production. Distinguez ce que l’agent ne doit jamais faire de ce qu’il peut faire après confirmation : ajouter une dépendance, modifier un contrat d’API ou lancer une migration destructive.

5. Une définition vérifiable du travail terminé

« Fais au mieux » ne permet aucune validation. Demandez un changement minimal, les tests concernés, une relecture du diff et un résumé des limites. Interdisez explicitement d’affirmer qu’un test passe lorsqu’il n’a pas été exécuté.

Exemple avant/après : corriger un webhook de paiement

Prenons une demande réaliste : « Empêche la création de deux abonnements lorsqu’un webhook Stripe est rejoué. » Sans contexte, un agent peut modifier le contrôleur, ajouter une condition locale et considérer le problème résolu. Il peut ignorer que le projet possède déjà un service d’idempotence et que les événements sont traités par une file d’attente.

Un AGENTS.md adapté pourrait préciser :

## Paiements
- Le fournisseur de paiement est la source de vérité.
- Les webhooks vérifient leur signature avant tout traitement.
- Réutiliser PaymentEventService pour l'idempotence.
- Ne jamais modifier une migration déjà déployée.
- Tester un événement valide, invalide et rejoué.

Avec ces règles, l’agent dispose d’une trajectoire plus sûre : localiser le service existant, appliquer le changement à la bonne couche et ajouter le test de rejeu. Le fichier ne garantit pas le résultat, mais il réduit les décisions prises à l’aveugle.

Les instructions trop longues peuvent produire l’effet inverse

Transformer AGENTS.md en manuel de cent pages noie les règles critiques. Une instruction répétée sous plusieurs formulations peut aussi être interprétée comme plusieurs contraintes différentes.

Les recommandations officielles pour les modèles récents vont dans le même sens : des prompts plus légers, sans répétitions inutiles, peuvent améliorer l’efficacité. Il faut conserver les contraintes qui protègent réellement le produit et déplacer la documentation détaillée vers des fichiers spécialisés.

Les contradictions sont encore plus dangereuses. « Ne jamais modifier les migrations » et « adapter la dernière migration si nécessaire » ne peuvent pas cohabiter sans préciser la différence entre une migration locale non déployée et une migration déjà utilisée en production.

Télécharger trois modèles AGENTS.md prêts à adapter

Le pack Okibata contient trois modèles distincts pour éviter un fichier générique inutilisable :

• PHP : architecture, SQL préparé, migrations, CSRF, tests et versions compatibles ;
• WordPress : cœur et extensions tierces interdits, hooks, capacités, nonces, REST et échappement ;
• SaaS : isolation des tenants, permissions, paiements, webhooks, API, secrets et déploiement.

Pourquoi ces règles doivent être versionnées avec le code

Une convention stockée dans une discussion disparaît de la prochaine session. Une règle conservée uniquement dans les paramètres personnels ne bénéficie pas à l’équipe. Dans Git, chaque changement apporté à AGENTS.md possède un auteur, une date et une justification dans la pull request.

Le fichier doit évoluer avec le projet. Lorsqu’une commande change, mettez-la à jour dans le même commit. Lorsqu’un incident révèle une zone dangereuse, ajoutez une règle courte accompagnée du chemin sûr. Supprimez les consignes devenues fausses.

Cette discipline devient particulièrement utile lorsque plusieurs agents travaillent sur le même dépôt. Les fonctions de GPT-5.6 destinées aux workflows agentiques et les constructeurs comme Figma Make, Lovable ou Replit Agent accélèrent la production, mais augmentent aussi le nombre de décisions confiées au modèle.

Le bon fichier ne bloque pas l’agent, il lui donne un chemin sûr

AGENTS.md ne doit pas être une succession de « ne fais jamais ». Un bon guide associe chaque interdiction à une méthode correcte : ne pas modifier le cœur WordPress, utiliser un thème enfant ; ne pas changer une migration déployée, créer une nouvelle migration réversible ; ne pas ajouter une dépendance sans validation, chercher d’abord une fonction existante.

Le gain attendu n’est pas qu’une IA devienne infaillible. C’est qu’elle cesse de redécouvrir l’architecture et les précautions du projet à chaque tâche. Le fichier devient alors une mémoire technique partagée entre les développeurs et leurs outils.

La meilleure première version tient en quelques écrans, contient des commandes vérifiées et nomme les vrais risques du dépôt. Si une règle ne change aucune décision de l’agent, elle n’a probablement pas besoin d’être dans AGENTS.md.