AGENTS.md dans Codex : où le placer, dans quel ordre il se charge et quoi y écrire

Où Codex cherche AGENTS.md, dans l’ordre de chargement

Codex construit la chaîne d’instructions une seule fois au démarrage (dans l’interface terminal, une fois par session). Les fichiers sont assemblés du haut vers le bas de ce tableau : les instructions les plus proches de votre répertoire de travail arrivent en dernier et l’emportent.

Configurer AGENTS.md pour Codex

1. Créez les valeurs globales par défaut

   Lancez mkdir -p ~/.codex et écrivez dans ~/.codex/AGENTS.md les préférences que vous voulez dans tous vos dépôts. Pour vérifier qu’il est chargé, demandez à Codex de résumer ses instructions.

   # ~/.codex/AGENTS.md
   
   ## Working agreements
   
   - Always run `npm test` after modifying JavaScript files.
   - Prefer `pnpm` when installing dependencies.
   - Ask for confirmation before adding new production dependencies.

2. Ajoutez un fichier de projet, et des overrides là où les équipes diffèrent

   Placez un AGENTS.md à la racine du dépôt pour la configuration commune. Dans un dossier aux règles différentes, ajoutez AGENTS.override.md : il remplace l’AGENTS.md de ce dossier, que Codex ignore alors.

   # AGENTS.md (repository root)
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.
   
   # services/payments/AGENTS.override.md
   
   ## Payments service rules
   
   - Use `make test-payments` instead of `npm test`.
   - Never rotate API keys without notifying the security channel.

3. Vérifiez ce qui a été chargé

   Lancez Codex dans le dossier qui vous intéresse, par exemple codex --cd services/payments, et demandez-lui la liste des sources d’instructions chargées. Il doit citer le fichier global, puis celui de la racine, puis celui du dossier.

4. Réutilisez un nom de fichier existant, ou relevez la limite

   Si votre dépôt garde déjà ses instructions dans un autre fichier, ajoutez-le à project_doc_fallback_filenames dans ~/.codex/config.toml. Codex cesse d’ajouter des fichiers une fois que la taille cumulée atteint project_doc_max_bytes, 32 KiB par défaut.

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536

5. Ajoutez des règles pour la code review de Codex

   Pour @codex review sur GitHub, ajoutez une section ## Code Review Rules à l’AGENTS.md le plus proche du code concerné. Dites ce qu’il faut signaler et l’alternative sûre ; laissez la mise en forme et le lint à la CI.

   ## Code Review Rules
   
   ### Experiment cohorts
   
   - Do not filter treatment comparisons on post-exposure behavior.
     Safe path: build cohorts from assignment or exposure.

Source : documentation de Codex, Custom instructions with AGENTS.md

Bonnes pratiques pour AGENTS.md

• Limitez-vous à ce que Codex ne peut pas deviner : les commandes exactes de build, de test et de lint (y compris comment lancer un seul test), les pièges du code et les décisions qui ne sont écrites nulle part.
• Placez les règles les plus spécifiques au plus près du code : un AGENTS.md imbriqué dans services/payments/ vaut mieux qu’un long fichier racine avec une section paiements.
• Surveillez le budget de 32 KiB : les fichiers sont ajoutés de la racine vers le bas et le reste est coupé, alors découpez les fichiers longs en fichiers imbriqués ou relevez project_doc_max_bytes.
• Utilisez AGENTS.override.md pour des changements temporaires, globalement ou dans un dossier, et supprimez-le pour revenir en arrière.
• Un AGENTS.md vide est ignoré, et la recherche dans ce répertoire passe au nom de fichier suivant.
• Utilisez un CODEX_HOME distinct pour les comptes d’automatisation, afin que leurs instructions globales ne se mélangent pas aux vôtres.

AGENTS.md dans Codex vs Claude Code et les autres

AGENTS.md est un format ouvert lu par de nombreux agents, ce qui en fait le meilleur endroit pour les instructions à partager. Claude Code a son propre fichier, CLAUDE.md ; consultez le guide CLAUDE.md pour les détails.

AGENTS.md dit à Codex comment faire. Crewmark lui dit quoi faire ensuite.

Un bon AGENTS.md fait démarrer chaque session Codex bien informée, mais la session attend toujours votre prompt. Crewmark transforme une session Codex, Claude Code, DeepSeek Harness ou OpenCode en employé IA avec un rôle, un objectif et des horaires de travail, et la réveille à intervalle régulier (heartbeat) pour qu’elle prenne la prochaine issue d’un tableau.

1. Gardez AGENTS.md dans le dépôt

   La session Codex de l’employé le lit comme la vôtre : conventions et commandes de test sont donc de la partie.

2. Laissez la pulsation lancer le travail

   Pendant ses horaires de travail, l’employé se réveille toutes les 15, 30 ou 60 minutes dans la même conversation ; voir comment rendre Codex proactif.

3. Mélangez les agents sur un même tableau

   Un seul AGENTS.md peut servir des employés Codex et Claude Code côte à côte ; comparez-les dans Claude Code vs Codex.

FAQ AGENTS.md pour Codex