Fiche d'instructions du projet AGENTS.md : Intégrer les règles dans le flux de démarrage de Codex

📚 Navigation de la série : L'article précédent 10 · Codex Cloud dans le Cloud a expliqué en détail la logique de « faire tourner Codex à distance et récupérer les PR plus tard ». Cet article revient en local pour parler d'un fichier que chaque projet devrait avoir, mais que 90 % des débutants rédigent mal : AGENTS.md, la fiche d'instructions du projet que Codex doit lire avant chaque début de travail.

Laissez-moi vous raconter une bêtise que j'ai faite quand j'ai commencé avec Codex.

C'était l'année dernière, j'ai confié un projet Node à Codex. Pour clarifier les choses dès le départ, j'ai écrit un fichier AGENTS.md à la racine, avec la première ligne indiquant clairement : « Ce projet utilise pnpm, npm est interdit ». En retour, il m'a sorti un npm install. J'ai immédiatement pensé qu'il ne l'avait pas lu, alors en colère, j'ai copié cette règle trois fois, je l'ai mise en gras et j'ai ajouté des points d'exclamation. Il n'écoutait toujours pas.

Après avoir cherché pendant un moment, j'ai découvert que Codex l'avait lu, mais que j'avais enterré cette règle à la ligne 140. Avant cela, j'avais inséré la présentation de l'entreprise, la feuille de route du produit et l'historique des choix technologiques, le tout sur plus de cent lignes. Quand Codex est arrivé à la phrase « npm interdit », son attention avait déjà été diluée par toutes ces futilités précédentes. Le problème n'a jamais été qu'il n'était pas obéissant, c'est que j'avais soudé la seule règle utile au milieu d'un tas de choses inutiles.

L'importance de AGENTS.md pour Codex est la même que celle de CLAUDE.md pour Claude Code, c'est le même concept avec un nom de fichier différent. Cependant, le mécanisme de découverte, les règles de surcharge et la limite d'octets de Codex lui sont propres et comportent quelques pièges faciles à éviter. Cet article va tout clarifier, y compris « ce qu'il faut écrire et ce qu'il ne faut pas écrire ».

Après avoir lu cet article, vous obtiendrez :

• La chaîne de découverte complète de AGENTS.md par Codex (niveau global → niveau projet → ordre de fusion), et qui a le dernier mot en cas de conflit
• Le mécanisme de « tampon temporaire » AGENTS.override.md, qui n'existe pas dans Claude Code, et quand l'utiliser
• Une liste « à écrire vs à ne pas écrire » pour éviter le piège du « ligne 140 que personne n'écoute » dans lequel je suis tombé
• L'utilisation officielle des deux paramètres pour changer le nom du fichier (project_doc_fallback_filenames) et ajuster la limite de taille (project_doc_max_bytes)
• Un processus pratique à suivre pour vérifier si Codex a bien lu les instructions

Note : Cet article se concentre uniquement sur la façon d'écrire et de charger le fichier AGENTS.md. Le mécanisme de « mémoire (Memories) », avec lequel il est facile de le confondre (qui est une couche de rappel locale automatique, désactivée par défaut), a déjà été abordé dans [02 Concepts Clés]. Retenez une chose : les règles d'équipe qui doivent s'appliquer à chaque fois doivent être écrites dans AGENTS.md, ne comptez pas sur la mémoire.

---

01 Comprendre d'abord : AGENTS.md est la « liste de passage de relais » avant que Codex ne commence à travailler

Voici la conclusion directe : AGENTS.md est une instruction persistante que vous écrivez pour Codex. Avant de démarrer et de commencer à travailler, il la lit systématiquement pour charger le contexte de ce projet dans son cerveau.

Pourquoi est-ce nécessaire ? Parce que Codex repart d'une page blanche à chaque cycle (chaque exécution (per run) — terme officiel, qui correspond généralement au démarrage d'une session dans le TUI). Ce que vous lui avez expliqué patiemment au cycle précédent (« utilisez pnpm, ne touchez pas à legacy/, lancez les tests comme ça »), il ne s'en souvient plus du tout. Sans AGENTS.md, vous devriez tout lui réexpliquer à chaque fois.

Analogie : La liste de tâches pour le passage de relais. Dans une usine travaillant en trois-huit, l'équipe sortante écrit sur le tableau mural : « cette machine a un petit problème ne la forcez pas, ce lot de composants doit être inspecté d'abord, voici les contacts d'urgence ». L'équipe suivante prend le relais et travaille en suivant le tableau, sans avoir à faire revenir l'équipe précédente pour des explications orales. AGENTS.md est ce tableau de passage de relais pour Codex — et c'est celui auquel il jette un coup d'œil avant chaque début de service.

(Notez que je n'ai pas utilisé ici le terme « manuel d'intégration » — cette métaphore a déjà été utilisée dans [02]. La « liste de passage de relais » est plus appropriée car elle insiste sur le fait qu'il s'agit d'une relecture à chaque cycle, et non d'une lecture unique le premier jour.)

Quand faut-il y ajouter du contenu ? Voici quelques signaux très concrets :

• Codex fait la même erreur pour la deuxième fois — cette règle doit être gravée dans le marbre, ne la corrigez pas oralement une troisième fois
• Vous venez de retaper la même correction que lors du cycle précédent
• Lors de la revue de code, vous réalisez qu'il aurait déjà dû connaître une certaine convention de la base de code
• Un nouveau coéquipier (ou vous-même dans trois mois) a besoin du même contexte pour démarrer rapidement

Ma méthode préférée, mentionnée dans [02] et que je souligne à nouveau ici, consiste à l'utiliser comme une boucle de rétroaction : si Codex fait une fausse supposition sur votre base de code, ne vous contentez pas de le corriger dans la conversation (c'est temporaire, il l'oubliera au cycle suivant), demandez-lui directement d'écrire cette correction dans AGENTS.md. J'ai ajusté un projet Python pendant deux semaines, et le fichier AGENTS.md, initialement vide, a grandi pour atteindre une vingtaine de lignes. Il ne contenait que les pièges dans lesquels il était tombé, que j'avais détectés et qu'il avait ensuite notés lui-même. Désormais, les nouvelles sessions ne reproduisent pratiquement plus ces erreurs.

💡 En résumé : AGENTS.md est la liste de passage de relais indispensable à chaque cycle de Codex. Notez-y chaque erreur commise, et l'outil deviendra de plus en plus fluide à utiliser. C'est le même concept que le CLAUDE.md de Claude Code, avec un nom différent.

---

02 Chaîne de découverte : comment Codex trouve ces fichiers

Il n'y a pas qu'un seul fichier AGENTS.md. Il peut se trouver à plusieurs endroits, avec une portée allant du plus large au plus restreint. Au démarrage, Codex les enchaîne pour former une « chaîne d'instructions ». Cette section détaille cette chaîne — c'est d'ailleurs la plus grande différence avec Claude Code, lisez attentivement.

Selon la documentation officielle, Codex construit la chaîne d'instructions en deux étapes (une construction par exécution, ce qui correspond généralement au démarrage d'une session dans le TUI) :

Première étape : la portée globale (Global scope). Dans votre répertoire principal Codex (par défaut ~/.codex, sauf si vous avez défini la variable d'environnement CODEX_HOME), Codex vérifie d'abord s'il existe un fichier AGENTS.override.md. Si oui, il l'utilise ; sinon, il lit AGENTS.md. À ce niveau, il ne prend que le premier fichier non vide et ne lit pas les deux.

Deuxième étape : la portée du projet (Project scope). En partant de la racine du projet (généralement la racine Git) et en descendant jusqu'à votre répertoire actuel, Codex effectue une sélection dans chaque répertoire traversé selon l'ordre suivant : il cherche d'abord AGENTS.override.md, puis AGENTS.md, et enfin les noms de fichiers alternatifs que vous avez définis dans project_doc_fallback_filenames. Chaque répertoire ne fournit au maximum qu'un seul fichier.

Troisième étape : la fusion (Merge order). Codex concatène du haut vers le bas les fichiers trouvés, en les séparant par des lignes vides. Les fichiers les plus proches de votre répertoire actuel, étant situés à la fin du résultat de la concaténation, ont une priorité plus élevée et peuvent surcharger les précédents.

Cela peut paraître un peu abstrait, voici un schéma :

Ce schéma illustre toute la chaîne : d'abord un choix exclusif au niveau global, puis une sélection progressive d'un fichier par répertoire au niveau du projet, pour enfin tout fusionner de la racine vers les feuilles — plus le fichier est proche de vous, plus il intervient tard et plus il est prioritaire.

Voici deux points essentiels issus de la documentation officielle, à retenir absolument :

Premièrement, il s'agit d'une « fusion », pas d'un « remplacement ». Le fichier global et le fichier du projet s'appliquent simultanément. Écrire un fichier au niveau du projet ne désactive pas le niveau global. Ils entrent tous dans le contexte. Les éléments suivants ne suppriment pas entièrement les précédents, mais les éléments en conflit sont résolus en faveur de ceux qui apparaissent plus tard (plus proches).

Deuxièmement, le plus proche l'emporte. Par exemple, si le fichier global AGENTS.md indique « utilisez des guillemets simples pour les chaînes » et que le fichier AGENTS.md à la racine du projet indique « utilisez des guillemets doubles » — la racine du projet étant plus proche du répertoire actuel et donc placée plus tard dans la concaténation, les guillemets doubles l'emportent. En clair, les règles du projet l'emportent sur vos préférences personnelles, ce qui est exactement ce que l'on recherche dans le travail d'équipe.

Analogie : Les trois niveaux de zoom d'une carte de navigation. La carte nationale vous donne la direction générale (niveau global), la carte de la ville vous montre les itinéraires urbains (racine du projet), et le panneau à l'entrée de la résidence vous indique les derniers pas à faire (sous-répertoire). Les trois niveaux sont valables en même temps et leurs informations ne s'annulent pas. Cependant, si le panneau à l'entrée de la résidence contredit la carte générale, c'est le panneau le plus proche sur le terrain qui fait foi — car c'est lui qui correspond le mieux à l'étape que vous avez sous les yeux. La chaîne d'instructions de AGENTS.md suit exactement cette logique de « plus on est proche de l'emplacement actuel, plus on est spécifique, et la priorité va au plus proche en cas de conflit ».

Ce schéma superpose les trois niveaux du haut vers le bas — niveau global (~/.codex/), racine du dépôt, sous-répertoire, concaténés dans cet ordre et s'appliquant simultanément. L'axe de « priorité » sur la droite vous rappelle que plus la couche est proche du répertoire actuel, plus elle est placée tard dans le résultat de la fusion et plus elle l'emporte en cas de conflit, ce qui correspond à la surcharge par proximité.

💡 En résumé : Chaîne de découverte de Codex = niveau global (~/.codex/, override prioritaire, sélection d'un seul fichier non vide) → niveau projet (de la racine Git jusqu'au répertoire actuel, un fichier par niveau) → fusion du haut vers le bas, avec une priorité croissante pour les fichiers les plus proches ; il s'agit d'une fusion et non d'un remplacement.

---

03 AGENTS.override.md : le « tampon temporaire » qui n'existe pas dans Claude Code

La section précédente mentionnait à plusieurs reprises le nom AGENTS.override.md. Ce concept n'a aucun équivalent dans Claude Code. C'est une conception propre à Codex, et nous allons l'aborder en détail.

Voyons d'abord quel problème il résout. Imaginez que vous ayez écrit un ensemble de règles globales partagées dans ~/.codex/AGENTS.md. C'est très bien pour le quotidien. Mais aujourd'hui, vous travaillez sur une tâche temporaire qui nécessite de remplacer complètement ces directives globales, sans pour autant vouloir supprimer votre fichier d'origine (ce qui vous obligerait à le réécrire plus tard). Comment faire ?

Analogie : Coller une note adhésive « à appliquer en priorité » sur un document. Le contrat d'origine est toujours dans le tiroir, vous ne l'avez pas déchiré ; vous avez simplement collé temporairement une note indiquant : « Ce mois-ci, appliquez ces nouvelles conditions ». Une fois le travail terminé, vous retirez la note et le contrat d'origine s'applique à nouveau automatiquement. AGENTS.override.md est cette note adhésive — lorsqu'il est présent, le fichier AGENTS.md du même niveau est complètement ignoré ; dès que vous le supprimez, le fichier d'origine redevient actif immédiatement.

Deux scénarios typiques décrits dans la documentation officielle :

• Surcharge globale temporaire : écrivez un ensemble de règles globales temporaires dans ~/.codex/AGENTS.override.md, en laissant le fichier ~/.codex/AGENTS.md d'origine intact. Une fois le travail terminé, supprimez le fichier override pour restaurer la version partagée.
• Règles spécifiques à un sous-répertoire : l'équipe d'un sous-répertoire spécifique a besoin de règles complètement différentes de celles de l'extérieur. Par exemple, dans le répertoire du service de paiement services/payments/, placez un fichier AGENTS.override.md :

# services/payments/AGENTS.override.md

## Règles du service de paiement

- Utilisez `make test-payments` à la place de `npm test`
- Vous devez informer le canal de sécurité avant de renouveler une clé API

En plaçant cet override, le fichier AGENTS.md du même niveau dans ce répertoire est ignoré (s'il existe), et Codex se réfère uniquement à ce fichier override lorsqu'il travaille dans ce répertoire.

Il y a un point crucial que les débutants confondent souvent — l'override ne signifie pas « écraser toute la chaîne » :

Portée	Rôle de AGENTS.override.md
Au sein d'un même répertoire	S'il existe → le fichier AGENTS.md du même niveau (et les noms alternatifs) est ignoré, seul le fichier override est pris en compte pour ce niveau
À travers les répertoires (toute la chaîne)	Il ne supprime pas les instructions des répertoires parents ; les instructions parentes sont toujours fusionnées normalement, et l'override ne fait que surcharger les conflits en raison de sa plus grande proximité

En clair : l'override signifie « à ce niveau, utilisez-moi plutôt que le AGENTS.md d'à côté », et non pas « écoutez-moi exclusivement sur toute la chaîne ». Les règles de fusion de toute la chaîne et de priorité au plus proche s'appliquent toujours. La première fois que je l'ai utilisé, j'avais mal compris : je pensais que placer un override dans un sous-répertoire masquerait le niveau global, mais les règles globales continuaient de s'appliquer. C'est en relisant la documentation officielle que j'ai compris qu'il ne choisissait qu'entre les deux options au sein de son propre niveau.

C'est aussi un excellent outil de dépannage : si jamais Codex applique une règle étrange que vous n'avez écrite nulle part, la première chose à faire est de remonter l'arborescence des répertoires, y compris ~/.codex, pour voir si quelqu'un n'y a pas caché un fichier AGENTS.override.md. Renommez-le ou supprimez-le pour revenir au fichier AGENTS.md classique. Cette étape figure explicitement dans la liste de contrôle de dépannage officielle.

💡 En résumé : AGENTS.override.md est le « tampon temporaire » exclusif à Codex. À son niveau, il remplace le fichier AGENTS.md du même niveau, mais il n'affecte pas la fusion des instructions des autres répertoires. C'est le moyen le plus simple de changer temporairement de directives sans supprimer le fichier d'origine. Si vous observez des instructions étranges, commencez par vérifier si un fichier override n'est pas caché quelque part.

---

04 Ce qu'il faut écrire vs ce qu'il ne faut pas écrire

Cette section est le cœur de l'article, et c'est le remède à mon erreur de la « ligne 140 que personne n'écoute ». La plupart des échecs d'écriture de AGENTS.md sont dus au fait que « ce qui devrait être écrit n'est pas clair, tandis que ce qui ne devrait pas l'être y est accumulé en masse ».

Parlons d'abord de ce qu'il faut écrire — en une phrase : écrivez les « faits qui doivent rester constants pour Codex à chaque cycle ». Voici la liste classée en cursive parmi cinq catégories :

Catégorie	Ce qu'il faut écrire précisément	Exemple
Présentation du projet	Expliquer en une phrase ce que fait le projet	« Backend de gestion des commandes basé sur FastAPI »
Technologies utilisées	Langage, framework, base de données, outils clés	« Python 3.11 / PostgreSQL / pytest »
Commandes fréquentes	Comment lancer les tests, le build, le lint / la vérification	npm run lint, make test-payments
Conventions de code	Style, nommage, syntaxes obligatoires	« Les fonctions doivent obligatoirement avoir des annotations de type », « Les chaînes de caractères doivent utiliser des guillemets doubles »
Ce qu'il ne faut absolument pas faire	Zones interdites, fichiers à ne pas modifier, opérations nécessitant confirmation	« Ne pas modifier les fichiers existants dans migrations/ », « Demander confirmation avant d'ajouter une nouvelle dépendance de production »

Parmi ces éléments, les commandes fréquentes sont les plus consultées. Codex s'y réfère avant de lancer des tests ou de soumettre une PR, ce qui lui évite de deviner ou d'utiliser les mauvaises commandes. La première règle du fichier AGENTS.md d'exemple officiel est d'ailleurs une commande : « Lancez npm run lint avant de soumettre une PR ». La liste des interdictions sert de barrière de sécurité pour l'empêcher d'être « trop intelligent mais destructeur » : quels répertoires contiennent du code hérité en lecture seule, ou quelles modifications nécessitent votre validation préalable.

Parlons maintenant de ce qu'il ne faut pas écrire, c'est là que les débutants commettent le plus d'erreurs, et c'est le piège dans lequel je suis tombé :

• ❌ Des explications de contexte interminables : présentation de l'entreprise, vision du produit, raisons historiques des choix technologiques. Codex n'en a pas besoin pour écrire du code, cela encombre inutilement le contexte et dilue les règles vraiment utiles (comme mes 140 lignes du début).
• ❌ Des informations obsolètes : si vous changez de gestionnaire de paquets sans mettre à jour AGENTS.md (qui indique toujours npm), vous risquez de l'induire en erreur.
• ❌ Ce que le code montre déjà de lui-même : ne décrivez pas le rôle de chaque fichier dans la structure des répertoires, ne recopiez pas les règles de style déjà définies par ESLint ou Prettier. Codex sait lire le code par lui-même, les répéter ne fait que gaspiller de l'espace.

La documentation officielle impose des limites strictes pour éviter d'avoir des fichiers trop volumineux, mais sa limite rouge diffère de celle de Claude Code — Claude Code recommande un nombre de lignes (moins de 200), tandis que Codex limite en octets :

Codex ignore les fichiers vides. Une fois que la taille totale combinée des fichiers fusionnés atteint la limite project_doc_max_bytes (par défaut 32 Kio), il arrête d'ajouter de nouveaux fichiers.

Notez bien que cela implique deux choses : premièrement, la limite par défaut est de 32 Kio, au-delà de laquelle le contenu est tronqué (ou le fichier est rejeté en bloc) ; deuxièmement, cette limite s'applique à la somme des fichiers fusionnés (global + projet + sous-répertoires). Ainsi, si l'un de vos fichiers est trop lourd, il risque d'exclure un autre fichier plus important situé plus loin dans la chaîne. Conseil officiel : si vous atteignez la limite, vous pouvez soit augmenter project_doc_max_bytes, soit répartir vos instructions dans plusieurs sous-répertoires (ce qui rejoint les conseils de « réduction de taille de AGENTS.md + répartition par sous-répertoire » pour économiser des tokens décrits dans [04 Tarification]).

Il existe une astuce simple et efficace que j'utilise désormais avant d'écrire chaque règle. Je me pose la question suivante : « Est-ce que Codex peut déduire cette règle de lui-même en lisant le code ? Si oui, je la supprime. » Cette simple question permet de réduire le fichier AGENTS.md d'un projet existant de plus d'une centaine de lignes à quelques dizaines de lignes seulement, pour ne conserver que les contraintes strictes qu'il ne peut pas deviner. Grâce à cela, le nombre de fois où il s'est trompé de gestionnaire de paquets a chuté de manière spectaculaire.

💡 En résumé : Écrivez les « faits qui doivent être mémorisés à chaque cycle » (présentation / technologies / commandes / conventions / interdictions) et supprimez tout ce que Codex peut déduire par lui-même en lisant le code. La limite rouge est exprimée en octets — 32 Kio par défaut après fusion (project_doc_max_bytes). Si vous dépassez cette taille, répartissez vos règles ou réduisez-les au lieu d'augmenter systématiquement la limite.

---

05 Deux paramètres : changer le nom du fichier et ajuster la limite d'octets

Pour la plupart des utilisateurs, le fichier AGENTS.md par défaut convient parfaitement. Cependant, il existe deux situations où vous devrez modifier la configuration. Cette section présente deux paramètres à configurer dans ~/.codex/config.toml (le fichier de configuration utilisateur de Codex).

Paramètre 1 : faire reconnaître par Codex un nom de fichier existant

Imaginez que vous ayez déjà un fichier TEAM_GUIDE.md dans votre dépôt, utilisé comme document de référence par toute l'équipe. Vous ne souhaitez pas créer un doublon avec AGENTS.md, et vous aimeriez que Codex l'utilise directement comme fichier d'instructions. Pour cela, utilisez le paramètre project_doc_fallback_filenames (noms de fichiers de secours) :

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

Une fois cette ligne ajoutée, l'ordre de sélection de Codex dans chaque répertoire devient : AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md, en prenant le premier fichier existant (et non vide).

Codex ignore systématiquement tout nom de fichier qui ne figure pas dans cette liste lors de l'étape de découverte des instructions. Si vous souhaitez qu'un fichier personnalisé soit reconnu comme fiche d'instructions du projet, vous devez impérativement ajouter son nom dans project_doc_fallback_filenames — n'attendez pas de Codex qu'il le « devine ».

Paramètre 2 : augmenter la limite de taille en cas de troncature

Comme mentionné précédemment, la taille maximale cumulée est de 32 Kio par défaut. Si vos instructions dépassent réellement cette taille et que vous ne souhaitez pas diviser votre fichier pour le moment, vous pouvez augmenter la valeur de project_doc_max_bytes :

# ~/.codex/config.toml
project_doc_max_bytes = 65536

Cela permet d'augmenter la limite à 64 Kio, ce qui évite de tronquer les instructions fusionnées. Cependant, je tiens à préciser que ce n'est qu'une solution de contournement. Si le contenu est vraiment utile, augmentez la limite. Mais le plus souvent, atteindre les 32 Kio est un signal d'alarme qui vous indique qu'il est temps de « simplifier » ou de « répartir par sous-répertoire », plutôt que d'augmenter la limite de taille. Personnellement, je préfère toujours diviser ou supprimer des règles avant d'envisager d'augmenter la limite.

Voici un tableau comparatif des scénarios d'utilisation de ces deux paramètres :

Votre situation	Quel paramètre utiliser
Le dépôt contient déjà un fichier TEAM_GUIDE.md à utiliser directement comme instructions	Ajouter son nom à project_doc_fallback_filenames
Les instructions fusionnées dépassent 32 Kio et sont tronquées	Penser d'abord à diviser par sous-répertoire ou à simplifier ; n'augmenter project_doc_max_bytes qu'en dernier recours
Configurer un profil de configuration indépendant (comme un utilisateur d'automatisation)	Définir CODEX_HOME vers un autre répertoire (voir la section pratique ci-dessous)

⚠️ Après avoir modifié config.toml, n'oubliez pas de redémarrer Codex. Ces deux paramètres sont lus au démarrage et ne s'appliqueront pas sans redémarrage. Ce point est spécifiquement souligné dans la liste de dépannage officielle (« Le fichier alternatif n'est pas pris en compte ? Vérifiez l'orthographe et redémarrez Codex »).

💡 En résumé : project_doc_fallback_filenames permet à Codex de reconnaître vos noms de fichiers personnalisés (ceux non listés seront ignorés) ; project_doc_max_bytes augmente la limite de taille fusionnée (32 Kio par défaut). Toutefois, si vous atteignez cette limite, privilégiez la division ou la suppression plutôt que l'augmentation brute. Pensez à redémarrer après modification.

---

06 Pratique : configurer un AGENTS.md correct pour un projet de démonstration et valider son chargement

La théorie ne suffit pas. Nous allons utiliser un projet minimal pour suivre le processus complet : « créer le fichier → écrire les règles → vérifier que Codex les a bien lues ». Suivez ces étapes, cela ne prendra que quelques minutes.

Différences de plateforme : les commandes de création de projet mkdir et git init ci-dessous s'utilisent directement sous Mac / Linux. Sous Windows, nous vous conseillons de les exécuter dans Git Bash ou WSL, ou de créer manuellement les dossiers via l'Explorateur de fichiers. Le symbole ~ fait référence au répertoire personnel de l'utilisateur, ce qui correspond sous Windows à C:\Users\VotreNomUtilisateur\.

Étape 1 : Créer un projet de démonstration et l'initialiser avec git

mkdir agents-md-demo
cd agents-md-demo
git init

Résultat attendu : un répertoire .git apparaît dans le dossier agents-md-demo. L'initialisation de git permet à Codex d'identifier ce dossier comme la « racine du projet » (il commence généralement son balayage à partir de la racine Git) et permet également de versionner ce fichier AGENTS.md pour le partager au sein de l'équipe.

Étape 2 : Écrire un fichier AGENTS.md simplifié au niveau du projet

À l'aide de votre éditeur préféré, créez un fichier AGENTS.md à la racine du projet et insérez-y le contenu suivant (notez qu'il ne fait que quelques lignes — c'est exactement à cela que doit ressembler un bon fichier AGENTS.md) :

# agents-md-demo — Un projet minimal de démonstration

Destiné uniquement à montrer comment écrire un fichier AGENTS.md, sans logique métier réelle.

## Commandes fréquentes

- `npm test` —— Lancer les tests

## Conventions de développement

- Toutes les fonctions doivent obligatoirement comporter des annotations de type
- Les chaînes de caractères doivent obligatoirement utiliser des guillemets doubles

## Attention

- Ne pas ajouter de nouvelles dépendances de production, demandez-moi d'abord

Résultat attendu : le fichier AGENTS.md est créé à la racine du projet avec les sections ci-dessus. Une quinzaine de lignes au total — gardez cette longueur à l'esprit, même pour des projets réels, évitez toute dérive de taille.

Étape 3 : Demander à Codex de reformuler les instructions lues

La documentation officielle propose une méthode de vérification très directe — demander à Codex de résumer les instructions actuellement actives. Exécutez la commande suivante dans le répertoire du projet :

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

Résultat attendu : avant de proposer des solutions, Codex affichera un résumé des règles que vous venez d'écrire (commandes, annotations de type, guillemets doubles, pas de nouvelles dépendances). Si ce résumé s'affiche, cela confirme que le fichier AGENTS.md a bien été chargé dans son contexte pour ce cycle.

ℹ️ L'option --ask-for-approval never sert uniquement à éviter que l'outil ne s'arrête pour demander des validations pendant la démonstration, afin d'obtenir un affichage propre. Cela ne signifie pas qu'il soit conseillé de l'utiliser ainsi au quotidien — pour connaître le mode de validation à utiliser au quotidien, reportez-vous à [02 Concepts Clés] et aux chapitres suivants sur les autorisations. Évitez de désactiver les validations dans des projets que vous ne maîtrisez pas.

Étape 4 (avancée) : Vérifier que la surcharge du sous-répertoire respecte bien la priorité au plus proche

Pour constater par vous-même l'application de la règle « le plus proche l'emporte », réalisez l'étape suivante. Créez un sous-répertoire dans le projet et ajoutez-y un fichier override qui ne surcharge qu'une seule commande :

mkdir -p services/payments

Écrivez le contenu suivant dans services/payments/AGENTS.override.md :

# services/payments/AGENTS.override.md

## Règles du service de paiement

- Utilisez `make test-payments` à la place de `npm test`

Démarrez ensuite Codex depuis ce sous-répertoire et demandez-lui d'afficher les sources d'instructions chargées :

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

Résultat attendu : conformément à la description officielle, Codex listera dans l'ordre : d'abord le fichier global (s'il existe sous ~/.codex), puis le fichier AGENTS.md à la racine du dépôt, et enfin le fichier override du service de paiement. De plus, la commande de test pour ce niveau utilisera la commande override make test-payments, la règle npm test de la racine ayant été surchargée pour ce sous-répertoire. C'est un exemple concret de la priorité au plus proche.

⚠️ Si vous constatez que Codex ne suit pas les règles définies dans AGENTS.md : ① Utilisez d'abord la commande « Summarize the current instructions » pour vérifier qu'il les a bien lues ; ② Exécutez codex status pour vérifier si le répertoire racine du projet identifié correspond bien à celui que vous pensez ; ③ Remontez l'arborescence des répertoires pour vérifier qu'aucun fichier AGENTS.override.md caché ne surcharge vos règles ; ④ Vérifiez que le fichier n'est pas vide (Codex ignore les fichiers vides). Ces étapes suivent l'ordre de la liste de dépannage officielle et permettent généralement de cibler le problème.

💡 En résumé : Suivez les étapes « créer le fichier → écrire des règles simples → demander une reformulation avec 'Summarize the current instructions' » pour vérifier de vos propres yeux que Codex a bien lu votre fichier AGENTS.md. Ajoutez ensuite un fichier override dans un sous-répertoire pour observer comment la commande de test de la racine est surchargée par la règle la plus proche.

---

07 Récapitulatif

Cet article vous a permis de comprendre en détail le fichier AGENTS.md, de son mécanisme de découverte à sa rédaction pratique :

Dimension	Conclusion clé
Qu'est-ce que c'est ?	Une liste de passage de relais indispensable à chaque cycle de travail, qui est simplement un renommage de CLAUDE.md
Chaîne de découverte	Niveau global (override prioritaire, sélection d'un seul fichier non vide) → niveau projet (de la racine Git jusqu'au répertoire actuel, un fichier par niveau) → fusion du haut vers le bas
Qui a le dernier mot ?	Il s'agit d'une fusion et non d'une suppression totale. Plus le fichier est proche du répertoire actuel, plus il est fusionné tard et plus il est prioritaire en cas de conflit
override	Un « tampon temporaire » propre à Codex : il remplace le fichier AGENTS.md du même niveau, sans supprimer les règles des autres répertoires
Que faut-il écrire ?	Présentation / technologies / commandes / conventions / interdictions, en supprimant tout ce que le code montre déjà
Limite de taille	Évaluée en octets — 32 Kio par défaut après fusion (project_doc_max_bytes). Si vous dépassez la taille, divisez ou réduisez en priorité
Deux paramètres	project_doc_fallback_filenames pour personnaliser le nom, project_doc_max_bytes pour augmenter la limite. Redémarrage obligatoire après modification

Vous devriez maintenant être capable de : déterminer si une information doit être intégrée dans AGENTS.md et à quel niveau la placer ; comprendre qui l'emporte en cas de conflit entre plusieurs niveaux de fichiers ; utiliser AGENTS.override.md pour modifier temporairement vos instructions sans toucher au fichier d'origine ; savoir s'il faut diviser ou augmenter la limite en cas de dépassement de taille ; et utiliser la commande « Summarize the current instructions » pour vérifier en une phrase que Codex a bien chargé vos règles. En un mot : vous êtes désormais capable d'écrire un fichier AGENTS.md que Codex écoutera réellement, au lieu de rédiger un pavé de 140 lignes ignoré comme celui de mes débuts.

---

Le chapitre suivant, 12 « Commandes slash et raccourcis clavier », prolonge ce sujet : vous avez déjà saisi la commande codex ... plusieurs fois dans votre terminal. Mais qu'en est-il une fois dans la session ? Les commandes commençant par / vous permettent de changer de mode instantanément, de vider le contexte ou de consulter l'état, le tout complété par des raccourcis clavier bien pratiques pour doubler votre efficacité. Nous allons détailler ce panneau de commande rapide dans le prochain article. Une petite question pour finir : cet article a montré comment « fixer des règles » en écrivant des fichiers. Si vous souhaitez modifier le comportement de l'agent directement au sein de la session de discussion, sans toucher à AGENTS.md, comment pensez-vous devoir procéder ?

---

Lectures recommandées

• Meilleures pratiques : au-delà des « règles évidentes », des conseils réellement applicables
• Conseils avancés et accélération : ce n'est pas le modèle qui vous ralentit, c'est votre contexte de mauvaise qualité
• Prise en main de l'interface en ligne de commande CLI