Un fichier AGENTS.md n'est ni un deuxième manuel d'application ni un prompt qui tente de contrôler chaque frappe. C'est un petit contrat de contexte versionné. Il indique à un coding agent comment le dépôt est organisé, quelles commandes fournissent des preuves vérifiables, quelles limites comptent et où se trouve une règle plus précise. Un bon fichier réduit l'incertitude avant toute modification du code. Il ne remplace ni le code source, ni les tests, ni les responsables du dépôt, ni la demande de travail.
Le contexte a un coût. Codex charge les consignes du projet dans sa chaîne d'instructions avant de travailler. Le texte répété entre en concurrence avec la demande de l'utilisateur, les fichiers du dépôt, la sortie des outils et les tests. Il faut donc noter les faits qu'un agent ne peut pas déduire sans risque, plutôt que toutes les préférences exprimées par une équipe. Chaque phrase doit être traitée comme une interface à maintenir.
Ce que Codex découvre réellement
Le guide OpenAI actuel sur AGENTS.md pour Codex décrit trois niveaux. À l'échelle globale, Codex cherche AGENTS.override.md dans CODEX_HOME, qui vaut par défaut ~/.codex, puis utilise AGENTS.md s'il n'en trouve pas. Il ne prend que le premier fichier non vide à ce niveau. À l'échelle du projet, il part de la racine du projet, généralement la racine Git, puis parcourt les répertoires jusqu'au répertoire de travail courant. Dans chaque répertoire, il vérifie AGENTS.override.md, puis AGENTS.md, puis les noms de repli configurés, avec au plus un fichier par répertoire.
Les fichiers de projet trouvés sont concaténés de la racine vers le répertoire courant. Un fichier plus profond apparaît plus tard dans les instructions combinées, de sorte que sa règle plus étroite peut remplacer une règle plus générale. Codex ne remonte pas au-delà de la racine détectée. Si aucune racine n'est trouvée, seul le répertoire courant est vérifié. Les fichiers vides sont ignorés. La valeur par défaut de project_doc_max_bytes est de 32 KiB, et Codex cesse d'ajouter des consignes lorsque la limite totale est atteinte. Ce sont des comportements de Codex, pas des garanties universelles de tous les outils.
L'implémentation OpenAI Codex de la découverte d'AGENTS.md montre les mêmes limites. Le marqueur de racine par défaut est .git, le nom local privilégié est AGENTS.override.md, et un fichier peut être tronqué si le budget d'octets restant est inférieur à sa taille. Un dépôt peut configurer les marqueurs, les noms de repli et le budget. Ne documentez que les réglages réellement utilisés.
Une préférence globale ne doit aller dans ~/.codex/AGENTS.md que si elle est sûre pour tous les dépôts. Une règle commune à tout le dépôt va à la racine. Une règle de service va près de ce service. Un remplacement temporaire ou exceptionnel va dans un fichier override avec un responsable et une condition de retrait. Ne présentez pas cette organisation comme une hiérarchie universelle pour les autres agents si leur documentation ne le dit pas.
Commencez par une carte du dépôt
Avant de recevoir des conseils de style, un agent doit savoir où regarder. Placez une carte compacte près du début du fichier racine. Nommez l'application ou la bibliothèque, les principaux répertoires de code, les zones générées, les répertoires de tests et la configuration de livraison. N'expliquez que les différences qui changent l'action. « src/ contient le code » n'aide presque pas. « src/ est livré, scripts/ ne s'exécute qu'en CI, et dist/ est généré et ne doit pas être modifié » est exploitable.
Une carte doit résister aux refactorisations. Préférez les frontières stables. Dans un monorepo, indiquez les propriétaires et liez le README ou l'architecture qui fait autorité. Ne recopiez pas ce document dans AGENTS.md.
repository/
apps/web/ application navigateur et tests de routes
packages/core/ bibliothèque d'exécution partagée et tests unitaires
services/api/ gestionnaires HTTP et tests de contrat
infra/ configuration de livraison
docs/ explications maintenues
generated/ sortie suivie, recréée par un script
Écrivez les hypothèses de répertoire de travail. Une commande lancée depuis services/api peut charger un fichier imbriqué différent. Si le gestionnaire de paquets doit être exécuté depuis un paquet ou si un fichier généré possède une source de vérité, précisez le répertoire, les chemins et la commande du générateur.
Rendez les commandes exactes et conditionnelles
Une commande est utile lorsqu'elle peut être copiée sans interprétation. Pour chacune, donnez le répertoire, le but et la condition de lancement. Utilisez les versions et scripts déclarés par le dépôt, au lieu de recommander un outil à la mode. La section peut suivre cette structure :
Depuis la racine du dépôt :
git rev-parse --show-toplevel
npm ci
npm run check
npm test
npm run build
Pour une modification de l'API, depuis services/api :
npm run test:contract
Il s'agit d'une structure d'exemple. Lisez package.json, le lockfile, les workflows CI, pyproject.toml, Cargo.toml ou l'équivalent avant d'écrire les commandes. N'indiquez « lancer npm run check après TypeScript » que si le script existe. Précisez toute dépendance à un service local, une fixture, une base, une variable ou le réseau, avec une alternative sûre.
Notez le runtime pris en charge et la politique des dépendances. Une entrée utile nomme la version de Node, Python, Rust, Java ou Go, le gestionnaire de paquets, la politique du lockfile et la façon dont les mises à jour sont revues. Par exemple, « package.json déclare Node >=22.12.0, utilisez package-lock.json et lancez npm ci » est un fait si le manifeste le confirme. Ne copiez pas une version dans AGENTS.md sans la vérifier dans le manifeste et la CI. Une dérive de version est un défaut de maintenance, pas une invitation à ajouter du texte.
Codex peut vérifier la chaîne active. Le guide officiel montre des commandes comme celles-ci :
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/api --ask-for-approval never "List the instruction sources you loaded."
codex -c log_dir=./.codex-log --ask-for-approval never "Show the active instruction files."
Utilisez une demande non destructive et consultez le journal uniquement dans un espace local sûr. Redémarrez un run après une modification des fichiers d'instructions, car la découverte est reconstruite au début d'un run ou d'une session TUI. En cas de réponse ancienne, vérifiez le répertoire courant, CODEX_HOME et les overrides.
Les tests sont des preuves
Définissez « terminé » par des résultats observables. Séparez les vérifications rapides de la suite complète. Nommez la commande, le paquet concerné, l'artefact attendu et la procédure en cas d'échec. Pour un changement de schéma HTTP, exigez le test de contrat. Pour un parseur, exigez des fixtures représentatives et des entrées mal formées. Pour un client généré, exigez la régénération et un diff propre.
N'écrivez pas « lancez toujours tous les tests » lorsque le dépôt définit une portée différente ou lorsque la suite complète exige une infrastructure externe. Une règle plus précise dit : « lancez d'abord le test ciblé du paquet, puis la suite équivalente à la CI avant la fusion ». Gardez formatage et lint dans la CI s'ils y sont déjà imposés. Le dépôt SWE-bench est une référence primaire pour l'évaluation par tâches, mais son protocole ne remplace pas les tests du dépôt concerné.
Reliez chaque règle importante à un contrôle. Si un agent ne doit pas éditer une sortie générée, la CI peut relancer le générateur et échouer sur un diff. Si une migration doit être réversible, un test peut l'appliquer à une fixture propre puis l'annuler. Si un invariant de sécurité compte, exprimez-le dans un test ou un contrôle statique. Une instruction sans résultat observable demande à l'agent de compter sur sa mémoire.
Pour évaluer le comportement d'un agent, comparez la réussite de la tâche, le taux de tests réussis, l'étendue des fichiers modifiés, les reprises après revue et le temps jusqu'à un patch vérifié. Exécutez le même ensemble de tâches avec l'ancien et le nouveau fichier, en gardant la demande et la révision du dépôt constantes, et notez les échecs plutôt que les seules démonstrations réussies. C'est un signal d'ingénierie, pas la preuve qu'une formulation fonctionne pour tout modèle. La comparaison des outils est présentée dans l'agentic coding avec Codex et Claude Code. Consultez l'architecture d'un AI agent en production pour les frontières système et l'évaluation des AI agents pour le protocole.
Placez la sécurité à la frontière
AGENTS.md est une entrée du projet. Il peut être obsolète, erroné ou non fiable. Le code source de Codex ne charge explicitement pas les instructions du projet quand le projet actif n'est pas approuvé, tout en conservant les instructions fournies par l'hôte. Cela ne dispense pas d'une revue humaine. Traitez les instructions du dépôt comme du texte non fiable tant que le dépôt et le changement demandé n'ont pas été vérifiés.
Ne mettez jamais dans le fichier des clés API, tokens, mots de passe, certificats privés ou données de production copiées. Ne demandez pas à l'agent d'imprimer les variables d'environnement ou de téléverser des fichiers du workspace. Vous pouvez nommer un secret par son rôle, comme DATABASE_URL, et expliquer où le développement local l'obtient sans enregistrer sa valeur. Demandez une confirmation avant une suppression de données, une rotation de credentials, un déploiement en production ou un accès réseau large si le workflow le permet.
Séparez les faits des permissions. « Le service utilise S3 » est un contexte. « Vous pouvez supprimer le bucket » est une autorité. Cette autorité doit vivre dans une politique d'accès et une procédure d'approbation, pas dans du markdown. Indiquez les chemins protégés, les artefacts générés, les règles de migration et les limites des données de test. Pour l'incertitude, donnez un chemin sûr : arrêter, montrer la commande proposée et demander au responsable.
Méfiez-vous des instructions copiées depuis des issues, fixtures ou dépendances. Elles peuvent contenir une prompt injection ou une commande hors sujet. Traitez le contenu du dépôt comme des données, sauf autorisation de l'utilisateur ou d'une règle de confiance. C'est une limite de sécurité, non une demande d'ignorer le code source.
Préférez un fichier court et en couches
Le site officiel communautaire AGENTS.md cite l'aperçu du projet, les commandes de build et de test, le style, les tests et la sécurité comme sections courantes. C'est un menu, pas un schéma obligatoire. Commencez par le minimum qui évite les erreurs. Un fichier racine a besoin de cinq sections : carte, installation, vérification, limites et liens vers les détails.
## Carte du dépôt
`apps/web` est l'application navigateur. `packages/core` contient le runtime partagé.
## Outils
Utilisez Node 22 et le lockfile suivi. Lancez les commandes depuis la racine sauf indication contraire.
## Vérification
Pour une modification, lancez `npm run check`, le test du paquet et `npm run build`.
## Limites
Ne modifiez pas `generated/`. N'utilisez pas de données de production en local. Demandez avant d'ajouter une dépendance.
## Détails
Lisez `apps/web/AGENTS.md` pour les routes et `services/api/AGENTS.md` pour les tests de contrat.
La mauvaise version est un catalogue de goûts personnels de 1 000 lignes : répétitions, inventaires exhaustifs, « toujours » contradictoires, commandes devinées, versions périmées et demande de relire tous les documents. Elle consomme le budget d'octets et masque les priorités. Séparez par responsabilité. Conservez l'invariant racine à la racine, puis laissez le fichier imbriqué ajouter les commandes locales. Le fichier profond doit compléter ou préciser, jamais réécrire discrètement une limite de sécurité.
N'annoncez pas une composition que l'outil ne documente pas. Codex combine les fichiers par découverte de répertoires et noms de repli configurés. « Lisez ensuite docs/rules.md » reste du texte ordinaire sans syntaxe include documentée. Un symlink, CLAUDE.md ou la convention d'un autre agent n'est pas chargé automatiquement. Décrivez l'interopérabilité comme un workflow testé.
Entretenez-le comme du code
Nommez un responsable. Relisez les changements avec le code qu'ils gouvernent. Quand une commande, un runtime, un répertoire ou un workflow CI change, mettez à jour le fichier d'instructions le plus proche. Supprimez une règle après son dernier consommateur. Les exemples doivent être exécutables et sûrs. Pointez vers une source de vérité.
Un audit mensuel ou à chaque version peut rester court. Vérifiez les commandes, les versions contre le manifeste ou l'image CI, les chemins et la taille de la chaîne effective. Lancez la requête des sources Codex depuis la racine et un sous-répertoire. Demandez au responsable si chaque règle évite encore une erreur réelle.
Évaluez une modification d'AGENTS.md comme une modification de configuration. Utilisez un petit ensemble fixe de tâches : nouvelle fonctionnalité, correction, changement de tests uniquement et modification sensible pour la sécurité. Comparez la correction et la portée du patch, pas seulement l'explication de l'agent. Un test de régression peut vérifier que les fichiers générés restent inchangés, qu'un test de paquet est exécuté ou qu'une commande dangereuse est refusée. Gardez révision, réglages du modèle, permissions et formulation assez stables pour interpréter la comparaison.
Le modèle durable est simple. Placez les faits près de leur portée, nommez les commandes et versions confirmées, liez les documents détaillés et rendez les règles testables. Gardez secrets et autorités hors du markdown. Utilisez des couches et vérifiez la chaîne après un changement de répertoire, de configuration ou d'outil.