Comment écrire AGENTS.md pour donner à Codex vos règles de projet

Codex annonce “terminé”, vous lancez pnpm test, et vous découvrez qu’il n’a jamais lancé les tests. Ou bien, dans un monorepo, il exécute depuis la racine les tests du mauvais package. Répéter ces consignes fatigue vite : npm run build, pnpm test, ne pas modifier le dossier generated, lancer lint avant de conclure. AGENTS.md sert à écrire ces règles dans le projet pour que Codex ne vous les redemande pas à chaque session.

Si vous venez de suivre le guide de démarrage Codex et le choix des différents points d’entrée, l’étape suivante n’est pas de lui confier un refactoring complet. Écrivez d’abord les règles projet que vous répétez à l’oral.

On part d’un squelette de 12 à 20 lignes, puis on voit les trois niveaux de chargement, comment vérifier que cela fonctionne, ce qu’il ne faut pas écrire dedans, comment cohabiter avec CLAUDE.md ou Cursor Rules, et quand le mettre à jour.

AGENTS.md n’est pas un README, c’est le mode d’emploi durable de Codex

README.md est destiné aux humains. Il explique ce qu’est le projet, comment l’installer et comment démarrer. AGENTS.md est destiné à Codex. Il décrit les règles chargées à chaque début de tâche : comment builder, comment tester, quels dossiers ne pas toucher et quels contrôles faire avant de dire que c’est terminé.

La documentation OpenAI indique que Codex lit AGENTS.md avant de commencer et l’inclut dans le contexte actif. Ce n’est pas la même chose que répéter “npm run build” ou “pnpm test” dans chaque conversation. AGENTS.md est une consigne projet persistante.

Mais il faut poser une limite : AGENTS.md n’est pas une mémoire long terme et n’apprend pas tout seul. C’est un fichier statique chargé au démarrage. Si vous voulez accumuler des connaissances entre sessions ou gouverner la mémoire d’un agent, le guide précédent sur la mémoire des agents IA traite la séparation entre mémoire long terme et règles projet.

Comment Codex trouve votre AGENTS.md : trois niveaux de chargement

L’ordre de lecture de Codex se comprend en trois niveaux : global, projet, puis ordre de fusion. Cette mécanique aide à savoir où une règle s’applique et pourquoi elle semble parfois ignorée.

Niveau global : vos habitudes personnelles

Codex regarde d’abord le répertoire utilisateur ~/.codex. Ce niveau contient vos habitudes personnelles : langue de réponse, préférences de style de code, outils courants. Attention : le niveau global lit au plus un fichier, dans l’ordre AGENTS.override.md -> AGENTS.md. Les deux ne sont pas empilés.

Niveau projet : de la racine Git au répertoire courant

Au niveau projet, Codex parcourt la racine Git ou projet jusqu’au répertoire de travail courant. À chaque niveau, il lit aussi au plus un fichier, dans l’ordre AGENTS.override.md -> AGENTS.md -> fallback filenames. Les noms fallback peuvent être configurés avec project_doc_fallback_filenames, par exemple pour ajouter TEAM_GUIDE.md. Les noms exacts de configuration doivent rester alignés avec la documentation officielle.

Ordre de fusion : plus le répertoire est proche, plus la règle est spécifique

Tous les fichiers trouvés sont concaténés de la racine vers le répertoire courant. Plus un fichier est proche du répertoire courant, plus il apparaît tard dans le contexte. Codex peut donc prioriser plus facilement cette règle locale.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Exemple : la racine d’un monorepo contient AGENTS.md avec “les tests se lancent avec pnpm test”. Le fichier apps/web/AGENTS.md contient “les tests se lancent avec pnpm --filter web test”. Si Codex démarre dans apps/web, il lit d’abord les règles racine, puis les règles apps/web. La commande de test apps/web est la plus spécifique.

Tableau récapitulatif des trois niveaux

La racine doit contenir les règles communes de l’équipe. Les sous-dossiers doivent contenir les règles locales, par exemple une commande de test différente pour un package. AGENTS.override.md convient à un remplacement temporaire ou local. N’en faites pas la norme de l’équipe : les règles deviennent cachées dans un override, ce qui complique la collaboration.

Le modèle minimal : quelles sont les 6 sections à écrire ?

OpenAI présente AGENTS.md comme un “open-format README for agents”. En pratique, il doit être court, vrai et vérifiable. Ne copiez pas un modèle de 300 lignes trouvé en ligne. Écrivez d’abord 6 blocs de base, puis étendez au besoin.

Le squelette de départ contient ces 6 blocs :

1. repo layout : la stack et la structure des dossiers, pour que Codex sache où se trouvent frontend, backend et tests
2. Commands : les commandes exactes de build, test et lint. Écrivez pnpm test, pas “lancer les tests”
3. Constraints : les dossiers ou actions à éviter, par exemple src/generated/
4. PR expectations : ce qui doit être vérifié avant soumission et ce que la review attend
5. Done when : les critères de fin vérifiables, par exemple pnpm test et pnpm build
6. Les conventions propres au projet, comme le gestionnaire de paquets, le style de code ou les règles de nommage

Pour un tableau de bord SaaS, le fichier de départ peut ressembler à ceci :

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Database: PostgreSQL
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review

## PR expectations
- Add tests for new features
- Run `pnpm test` before marking done

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Ce modèle est assez court pour rester visible dans le contexte. Ajoutez d’autres règles seulement quand un problème réel se répète. N’y mettez pas dès le départ la vision produit, toute la liste des dépendances, les diagrammes d’architecture ou les index de documentation API. Un fichier énorme enterre les règles utiles.

Vérifier que Codex a vraiment lu AGENTS.md

Après avoir écrit AGENTS.md, utilisez une commande de vérification au lieu de supposer que tout marche. La documentation OpenAI recommande :

codex --ask-for-approval never "Summarize the current instructions."

Cette commande demande à Codex de résumer les instructions chargées. Si la sortie contient vos règles, comme la commande de test ou le dossier interdit, le fichier est pris en compte. Si rien n’apparaît, ou si d’autres règles apparaissent, il faut déboguer la chaîne de chargement.

Checklist de dépannage

Si cela ne fonctionne toujours pas, consultez la documentation OpenAI Custom instructions ou mettez Codex à jour. Ne considérez pas le chargement d’AGENTS.md comme magique. Le chemin, la version, la configuration et le répertoire courant comptent.

Ce qu’il ne faut pas mettre dans AGENTS.md

AGENTS.md n’est pas un entrepôt universel. Certains contenus créent un risque de sécurité, une charge de maintenance ou du bruit dans le contexte. Gardez-les dehors.

1. Secrets, API keys et mots de passe de production

Aucun secret, mot de passe de production ni API token ne doit être écrit dans AGENTS.md. Codex lit le fichier dans le contexte, et il peut être visible par l’équipe ou commité dans Git. Les secrets doivent passer par des variables d’environnement, des fichiers .env non commités ou un système dédié. Si Codex doit utiliser un secret dans un workflow sandboxé, traitez cela au niveau exécution.

2. Grandes listes qui vieillissent vite

Ne listez pas toutes les dépendances, les chiffres d’écosystème, les prix, les quotas, les routes ou les champs de base de données. Une liste du type “React 18.2, Vue 3.4, TypeScript 5.0…” sera vite fausse. Mieux vaut écrire la procédure pour ajouter une dépendance que l’inventaire complet.

3. Slogans abstraits

“Garder une haute qualité”, “écrire du code élégant” ou “rendre le code maintenable” ne se vérifie pas. Remplacez-les par des contrôles : pnpm test passe, pnpm lint ne remonte aucune erreur, les nouvelles fonctionnalités ont des tests, ou le score Lighthouse ne descend pas sous le seuil convenu.

4. Commandes vagues

“Lancer les tests” et “vérifier le build” sont trop flous. Écrivez les commandes exactes : pnpm test, pnpm build ou lighthouse --preset=desktop.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

5. Exigences non vérifiables

“Garantir de meilleures performances” ou “améliorer l’UX” n’a pas de limite de fin. Utilisez des contrôles mesurables, comme une réponse API sous 200 ms ou un objectif Lighthouse.

6. Préférences personnelles dans la racine du repo

“Répondre en chinois”, “réponses sous 100 mots” ou “utiliser VS Code par défaut” sont des préférences personnelles, pas des règles projet partagées. Placez-les dans ~/.codex/AGENTS.md. La racine du repo doit contenir les standards de l’équipe.

Le principe est simple : court, vrai, vérifiable. AGENTS.md réduit les consignes répétées. Ce n’est pas l’endroit pour coller toute la documentation du projet.

Si CLAUDE.md ou Cursor Rules existent déjà

Si vous utilisez Claude Code ou Cursor, le dépôt contient peut-être déjà CLAUDE.md ou Cursor Rules. Vous n’avez pas besoin de maintenir trois copies. Utilisez l’import ou la coexistence.

AGENTS.md vs CLAUDE.md : importer les règles partagées

Claude Code lit CLAUDE.md, pas AGENTS.md. Si le dépôt possède déjà AGENTS.md, créez un petit CLAUDE.md qui l’importe :

@AGENTS.md

## Claude-specific
- Prefer Chinese responses
- Keep responses concise (under 100 words unless requested)

@AGENTS.md est la syntaxe d’import. Claude Code lit AGENTS.md, puis la section Claude-specific. Les règles projet partagées restent dans AGENTS.md, et les préférences propres à Claude restent dans CLAUDE.md.

AGENTS.md vs Cursor Rules : Cursor a son propre système

Cursor possède son propre système Rules, avec des règles projet, équipe et utilisateur. Les documents officiels et les résumés de recherche de Cursor mentionnent la prise en charge d’AGENTS.md, mais les détails de chargement doivent être vérifiés dans la documentation Cursor actuelle. Si vous utilisez Cursor et Codex, gardez les règles projet communes dans AGENTS.md et les comportements propres à l’éditeur Cursor dans Cursor Rules.

AGENTS.md vs config.toml, Rules, Skills et MCP

AGENTS.md est la couche d’instruction. Il dit à Codex comment travailler. Les contrôles d’exécution vivent ailleurs : permissions, sandbox, politique de commande et intégrations d’outils.

AGENTS.md résout les explications répétées de règles projet. Rules, config, sandbox et permissions gèrent l’exécution. Skills gère les workflows réutilisables. MCP connecte les outils externes. Gardez ces frontières nettes.

Quand mettre AGENTS.md à jour ?

AGENTS.md n’a pas besoin de changer à chaque évolution du projet. Mettez-le à jour quand la même friction revient.

Déclencheurs de mise à jour

La documentation OpenAI recommande de l’actualiser dans ces situations :

1. Codex répète la même erreur : il modifie deux fois le mauvais dossier ou lance toujours le test du mauvais package. Ajoutez une contrainte concrète, comme “Do NOT edit src/generated/” ou “Use pnpm --filter web test for web changes.”

2. La PR review répète la même remarque : les reviewers disent souvent “cette modification a besoin de tests”, “ne modifiez pas le generated code” ou “évitez default export”. Ajoutez ce motif dans PR expectations.

3. Codex lit trop de fichiers pour trouver la réponse : s’il doit fouiller plusieurs docs pour trouver la bonne commande de test ou le bon build, ajoutez l’information clé en haut.

Mettre la règle dans le répertoire le plus proche

Placez la règle là où l’erreur se produit. Ne mettez pas tout dans la racine. Dans un monorepo, les packages peuvent avoir des règles différentes, donc chaque package peut avoir son AGENTS.md local.

Si Codex lance le mauvais test en travaillant dans apps/web, ajoutez la règle à apps/web/AGENTS.md. Une règle racine serait trop large.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Différence avec la mémoire long terme

AGENTS.md est un fichier statique chargé au démarrage. Ce n’est pas une mémoire qui apprend automatiquement. Codex ne le mettra pas à jour à partir de vos corrections, sauf si vous lui demandez explicitement.

Pour des connaissances projet entre sessions ou une gouvernance de mémoire, le guide sur la mémoire des agents IA est le meilleur point de suite.

Faire grandir le modèle : du fichier de départ à la version étendue

Ne commencez pas par un modèle de 300 lignes. Partez de 12 à 20 lignes, puis étendez seulement quand un déclencheur concret se répète.

Version de départ : seulement les 6 blocs essentiels

La version de départ couvre repo layout, commandes courantes, contraintes, attentes de PR et done/verify. Elle peut rester aussi petite que ceci :

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)

## PR expectations
- Add tests for new features

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Déclencheurs d’extension : quand ajouter un bloc

Après quelques utilisations, étendez uniquement pour des problèmes précis :

1. La première fois que Codex modifie le mauvais dossier : s’il touche migrations/ ou generated/, ajoutez une contrainte comme “Do NOT commit migrations/ without team review” ou “Do NOT edit any file in src/generated/”.

2. La première remarque répétée en PR review : si les reviewers demandent souvent des tests ou named exports, ajoutez “Add tests for new features” ou “Use named exports, not default exports”.

3. La première confusion de gestionnaire de paquets : si un projet pnpm reçoit des commandes npm, ajoutez “Always use pnpm, not npm or yarn”.

4. Le premier oubli de lint : si Codex termine sans lint, ajoutez “pnpm lint passes with no errors” sous Done when.

Version étendue : 30 à 50 lignes

Une version étendue peut ajouter des contraintes, attentes PR, règles de gestionnaire de paquets et exigences lint :

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
- Always use pnpm, not npm or yarn

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review
- Do NOT modify .env files (use .env.example as template)

## PR expectations
- Add tests for new features
- Run `pnpm test` and `pnpm lint` before marking done
- Use named exports, not default exports
- Keep components under 200 lines; split if larger

## Done when
- `pnpm test` passes
- `pnpm build` succeeds
- `pnpm lint` passes with no errors
- New features have corresponding tests

La règle clé : faire grandir le fichier par déclencheur, pas par anticipation. AGENTS.md est utile parce qu’il réduit les explications répétées, pas parce qu’il expose toute la documentation du projet.

Conclusion

AGENTS.md est une consigne projet persistante. Ce n’est pas un entrepôt universel ni une mémoire long terme. Il résout un problème concret : ne plus répéter les mêmes règles projet à chaque démarrage de Codex.

Étapes pratiques :

1. Commencez par une version de 12 à 20 lignes : repo layout, commandes, contraintes, attentes PR et done/verify. Ne commencez pas par un modèle géant.

2. Vérifiez que Codex l’a chargé : lancez codex --ask-for-approval never "Summarize the current instructions." et cherchez vos règles dans la réponse.

3. Étendez par déclencheurs répétés : Codex répète une erreur, la PR review répète une remarque, ou Codex doit fouiller trop loin pour trouver l’information.

4. Gardez dehors ce qui est dangereux ou périssable : pas de secrets, d’inventaires périmés, de slogans, de commandes vagues, d’objectifs invérifiables ni de préférences personnelles dans la racine.

5. Utilisez import et coexistence avec CLAUDE.md ou Cursor Rules : règles projet communes dans AGENTS.md, comportements propres à chaque outil dans leurs fichiers respectifs.

AGENTS.md donne à Codex un contexte projet stable. Les autres articles de cette série Codex pourront déplacer les workflows répétables dans Skills, traiter les limites de permissions et de secrets, puis fiabiliser done/verify avec des failure reviews et des PR checks.