AGENTS.md avec Codex : quels fichiers sont lus, dans quel ordre, jusqu'à quelle taille

AGENTS.md est le fichier dans lequel une équipe décrit à un agent de code comment travailler sur son projet : commandes de test, conventions, interdits. Avec Codex, l'agent de code d'OpenAI, il n'y en a pas un mais plusieurs, lus dans un ordre précis. Comprendre cet ordre évite de chercher pourquoi une consigne n'est pas suivie.

Deux niveaux de lecture

Le niveau global. Codex regarde d'abord dans son dossier personnel, ~/.codex par défaut, modifiable avec la variable CODEX_HOME. Il y lit AGENTS.override.md s'il existe, sinon AGENTS.md. Un seul fichier est retenu à ce niveau.

Le niveau projet. Codex part de la racine du projet, en général la racine du dépôt Git, et descend jusqu'au répertoire courant. Dans chaque dossier traversé, il cherche dans l'ordre AGENTS.override.md, puis AGENTS.md. Il retient au plus un fichier par dossier.

Les fichiers sont ensuite mis bout à bout, de la racine vers le dossier courant. Ceux qui sont les plus proches du répertoire de travail arrivent en dernier, et l'emportent donc sur les consignes plus générales.

Trois règles à retenir

• Les instructions sont assemblées une seule fois, au lancement. Il n'y a pas de cache : après une modification, il suffit de relancer Codex.
• Les fichiers vides sont ignorés.
• Codex cesse d'ajouter des fichiers quand la taille cumulée atteint project_doc_max_bytes, soit 32 Kio par défaut (32 768 octets).

Ce dernier point est le plus piégeux : au-delà de la limite, les consignes ne sont pas chargées. La documentation propose deux remèdes : relever la limite, ou répartir les consignes dans des fichiers placés dans les sous-dossiers concernés.

Un exemple d'organisation

• ~/.codex/AGENTS.md : vos préférences personnelles, valables partout.
• AGENTS.md à la racine du dépôt : les règles communes de l'équipe.
• services/payments/AGENTS.override.md : des règles plus strictes pour un module sensible.

Pour la relecture de code, OpenAI suggère d'ajouter une section ## Code Review Rules dans le fichier le plus proche du code concerné.

Faire lire d'autres noms de fichier

Si votre équipe utilise déjà un autre nom, déclarez-le dans ~/.codex/config.toml :

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Ces noms sont essayés après AGENTS.override.md et AGENTS.md. Les fichiers dont le nom n'est pas dans la liste sont ignorés.

Vérifier ce qui est chargé

La documentation donne des commandes de contrôle, par exemple :

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

Le résultat attendu : le fichier global d'abord, celui de la racine ensuite, puis le fichier du module.

En cas de comportement inattendu, les pistes proposées sont :

• chercher un AGENTS.override.md oublié plus haut dans l'arborescence ou dans le dossier personnel ;
• contrôler la valeur de CODEX_HOME avec echo $CODEX_HOME ;
• vérifier l'orthographe des noms déclarés, puis relancer Codex.

Les limites

La vérification repose sur une question posée au modèle : c'est lui qui déclare ce qu'il a chargé. Pour une preuve plus solide, la documentation mentionne les journaux, activables avec codex -c log_dir=./.codex-log. Le fichier AGENTS.override.md est pratique pour un test, mais un fichier de ce type oublié dans le dossier personnel d'un développeur prend la place du fichier global. Enfin, ces règles de découverte sont celles de Codex : un autre outil qui lit AGENTS.md peut procéder différemment.

Notre lecture

Pour une petite équipe, un seul AGENTS.md à la racine suffit dans la plupart des cas, à condition de rester loin des 32 Kio. Surveillez la taille dès que le fichier grossit : une consigne placée en fin de chaîne peut ne jamais être lue. Réservez les fichiers de sous-dossier aux parties du code qui ont de vraies règles à part, comme les paiements ou les données personnelles, et faites le contrôle une fois, avec la commande ci-dessus, avant de considérer que l'agent connaît vos règles.