Le fichier AGENTS.md pour donner tes consignes à Codex
- Je mets dans AGENTS.md les règles qui doivent rester d'une tâche à l'autre.
- Je distingue les préférences personnelles des conventions du projet.
- Je vérifie le chargement puis le travail rendu sur une petite modification.
- Je garde les permissions techniques et les secrets hors des consignes partagées.
Pour donner tes consignes durables à Codex, crée un fichier AGENTS.md dans le dossier principal de ton projet. Écris-y les vérifications attendues, les fichiers à consulter et les actions qui demandent ton accord. Lance ensuite une nouvelle session dans ce dossier et vérifie les consignes chargées avant de confier une modification.
Je vois surtout l'intérêt quand une même correction revient d'une conversation à l'autre. Pas besoin de rédiger un règlement énorme : on va préparer une base courte, l'essayer et regarder ce qu'elle change vraiment.
Tu en es où ?
AGENTS.md garde les consignes que tu répètes
Un fichier AGENTS.md est un document texte qui donne à Codex les habitudes de travail de ton projet. Je peux y préciser où chercher, comment vérifier une modification et ce qui demande mon accord. Markdown, le format du fichier, sert simplement à écrire des titres et des listes lisibles. Tu n'as pas besoin de savoir programmer pour préparer ces consignes.
Moi, je pars du résultat que je veux pouvoir contrôler. Pour une boutique, ce serait conserver les références produits. Pour un site de contenu, respecter les sources. Écrire « fais du bon travail » ne m'aide pas à vérifier quoi que ce soit. Écrire « indique les vérifications exécutées et les erreurs restantes » me donne quelque chose à relire.
Quand j'ai relancé Quel Canapé, j'ai confié la conception à Claude Code et l'exécution à Codex. Le catalogue est passé de 160 à 950 canapés avec les filtres dynamiques. Ce que j'en retiens ici, c'est l'intérêt de répartir les rôles et de préciser le résultat attendu. Je veux pouvoir dire à l'agent ce qui rend la tâche terminée.
Je sépare donc la règle durable de la demande du jour. Le fichier dit comment travailler sur le site. Mon message dit quelle page modifier maintenant. Si tu découvres ces outils, je regroupe les autres prises en main dans Codex et les agents de code.
Où placer AGENTS.md dans ton projet ?
Pour commencer, je place un AGENTS.md à la racine du projet, son dossier principal. Un dépôt Git est un projet dont les versions sont suivies par Git. Dans Codex CLI, l'interface qui s'utilise dans un terminal, le dossier depuis lequel tu lances la session compte dans la découverte des consignes.
La documentation décrit une lecture des consignes globales, puis des dossiers allant de la racine au dossier de travail. À chaque niveau, AGENTS.override.md passe avant AGENTS.md. Les règles proches du dossier courant priment sur les règles plus générales en cas de conflit. Sans racine de projet trouvée, Codex ne vérifie que le dossier courant. Source OpenAI sur AGENTS.md.
Je garderais mes préférences personnelles dans le fichier global du répertoire Codex, normalement ~/.codex/AGENTS.md. Le signe ~ représente ton dossier personnel. Les conventions utiles à toute l'équipe restent dans le projet. CODEX_HOME est une variable d’environnement, un paramètre transmis au programme. Si elle est définie, il désigne un autre répertoire Codex : vérifie ce point avant de corriger le mauvais fichier.
Je réserve un fichier dans un sous-dossier à une vraie différence de méthode. Voici une arborescence fictive : `boutique/AGENTS.md`, `boutique/contenus/AGENTS.md` et `boutique/paiements/AGENTS.override.md`. Pour une session lancée dans `boutique/contenus`, sans consigne globale ni autre override, Codex retient le fichier de la racine puis celui de `contenus`. Celui de `paiements` ne fait pas partie de ce chemin. Dans `paiements`, il retient la racine puis l'override local.
Un premier fichier prêt à adapter
Dans ton éditeur, crée un fichier texte nommé exactement AGENTS.md. Vérifie aussi l'extension affichée : AGENTS.md.txt ne porte pas le nom attendu. Enregistre-le dans le dossier principal. Le contenu peut être en français ; je privilégie la langue dans laquelle tu peux repérer une consigne ambiguë.
Voici une base pour un site éditorial. Elle exprime des choix de travail, pas une configuration imposée par OpenAI. Je la ferais adapter après lecture du projet : « Prépare un AGENTS.md court à partir des fichiers existants. Justifie les commandes proposées. Ne modifie encore aucun autre fichier. »
# Consignes du site ## Objectif Aider le lecteur à agir avec des informations vérifiées. ## Avant de modifier Lire le document qui décrit le projet. Repérer les fichiers concernés et les changements déjà présents. ## Pendant le travail Conserver les adresses publiques. Réutiliser les composants existants. Ne pas inventer de prix ni de témoignage. ## Vérification Chercher les commandes de contrôle documentées. Exécuter celles qui concernent la modification. Signaler un contrôle impossible. ## Livraison Indiquer ce qui a changé, les vérifications et ce qui reste à faire. Demander mon accord avant une publication.
Je n'inscris pas npm test dans tous les projets par réflexe. npm est un outil de gestion de paquets JavaScript ; cette commande n'a de sens que si le projet a prévu le test correspondant. Une commande copiée sans comprendre son rôle peut échouer ou vérifier autre chose que ta modification.
Pour ton premier essai, remplace l'objectif générique par le résultat concret que tu veux préserver : une commande client valide, une fiche sourcée ou une page accessible sur téléphone. Je garde les consignes du projet dans AGENTS.md et les détails éditoriaux dans un document séparé, dont j'indique le chemin réel. Le fichier reste lisible sans recopier toute la documentation.

Une petite correction pour vérifier les consignes
Commence sans modification : lance `codex` dans ton projet puis écris « Indique les fichiers de consignes chargés, dans leur ordre de priorité. Explique ce qu'ils demandent pour une modification de contenu. Ne change aucun fichier. » Je compare sa réponse avec les fichiers présents. Pour contrôler le chargement au-delà de cette déclaration, la documentation propose de lancer `codex -c log_dir=./.codex-log`, puis de consulter `./.codex-log/codex-tui.log`. Si tu as activé l'enregistrement des sessions, tu peux aussi inspecter le fichier `session-*.jsonl` le plus récent. Je cherche les chemins des consignes retenues, pas seulement leur reformulation. Vérifier la configuration avec les journaux.
Ensuite, prends une copie de travail et demande une correction minuscule. Exemple fictif : dans `contenus/livraison.md`, remplacer « les colis arrive » par « les colis arrivent », sans toucher à l'adresse publique `/livraison`. Le résultat attendu est concret : la comparaison avant/après ne montre que ce remplacement, l'adresse reste identique et le compte rendu indique le contrôle exécuté avec son résultat. Si aucun contrôle adapté n'existe, il doit le dire. Je relis la différence entre les versions et la sortie du contrôle avant de valider l'essai.
C'est ce qui m'intéresse dans Automate Your Busywork, d'Aytekin Tank. Il raconte comment Jotform a commencé par transformer les formulaires courants en modèles avant d'aller vers des processus d'équipe plus complexes. Je reprends cette progression pour ton essai : stabilise une petite tâche récurrente avant de demander la refonte du site. Le récit se trouve dans l'introduction du livre, accessible sur le site de l'auteur.
Je ne présente pas le calcul fictif proposé plus bas comme une mesure de productivité de Codex. Il sert à choisir la répétition que tu veux supprimer. Note plutôt ta propre observation : quelle consigne a évité une reprise et laquelle n'a rien changé ? Garde le fichier et le résultat de cet essai ensemble pour pouvoir comparer la prochaine version.
Les erreurs récurrentes donnent les règles utiles
Je n'essaierais pas de prévoir tous les problèmes au premier lancement. J'ajouterais une règle quand une correction revient : modifier le mauvais dossier, créer un composant déjà présent ou oublier une vérification. OpenAI recommande justement de faire évoluer AGENTS.md à partir des erreurs répétées et des retours de relecture. Source sur la personnalisation.
Dans Work the System, Sam Carpenter explique sa méthode avec un objectif stratégique, des principes de fonctionnement et des procédures de travail. Le rapprochement qui m'aide : une procédure décrit comment obtenir un résultat reproductible. Dans ton fichier, « préserver les adresses publiques » devient utile si tu ajoutes « signale tout changement d'adresse dans le compte rendu ».
Sur Quel Canapé, j'ai mis un juge IA pour noter les rendus de canapés. Quand la note descend sous 7 sur 10, je garde la vraie photo. J'ai donc associé un critère à une décision concrète. Pour ton projet, tu peux appliquer cette idée à une source absente : demander de signaler l'information manquante au lieu d'inventer un chiffre.
Dans mon Carnet, je raconte aussi avoir corrigé le même bogue sur plusieurs OS avant de centraliser les comptes IA dans un coffre commun. Chaque OS consulte ensuite ce coffre, avec ses comptes locaux en secours. Ça montre une correction d'architecture, pas une consigne AGENTS.md que j'aurais testée. Pour ton fichier, l'application serait : « Avant de créer une gestion locale des comptes, consulter le mécanisme partagé du projet. » C'est un exemple à adapter, pas un extrait de mes consignes. Je veux encore documenter la règle réellement ajoutée après une erreur de Codex et ce qu'elle a changé.
Écris aussi le comportement attendu quand le résultat est insuffisant. Source introuvable : signaler le manque. Contrôle en échec : expliquer l'erreur et ce qui reste à corriger. Si tu laisses ce cas dans le flou, tu devras reprendre la décision à chaque passage. Pour découvrir les autres usages de ces systèmes, tu peux partir de ma rubrique IA et automatisation.
Les droits d'accès se règlent en dehors du texte
Écrire « ne supprime pas mes fichiers » indique une intention. Je ne le confonds pas avec une restriction technique. Les permissions définissent les accès aux fichiers et au réseau. Le bac à sable est l'environnement qui limite les actions possibles. Une phrase dans AGENTS.md ne donne pas un accès que l'environnement refuse. Source sur les permissions.
Laisse les clés et mots de passe hors du fichier, surtout si tu le partages dans le dépôt. Tu peux y indiquer le nom d'une variable nécessaire sans y coller sa valeur secrète. Avant de travailler sur un projet téléchargé, je lirais ses consignes comme je relirais un script inconnu avant de l'exécuter.
Je garderais aussi des frontières claires entre les outils. AGENTS.md porte des consignes durables. config.toml contient des réglages de Codex. Une skill est une méthode réutilisable avec ses instructions et, parfois, ses ressources. MCP relie l'agent à des outils ou services externes. Ajouter un nom de service dans AGENTS.md ne crée pas cette connexion.
Pour ce premier essai, utilise un projet sans données sensibles. Les approbations règlent les actions qui demandent une validation ; les connexions MCP se configurent séparément pour rendre un service accessible. Je vérifie ces réglages avant de déléguer une publication. Le droit de modifier une copie de travail et le droit de publier doivent correspondre à ce que tu veux effectivement déléguer.
Si Codex ignore le fichier, je vérifie dans cet ordre
Je commencerais par le nom exact, le contenu non vide et le dossier de lancement. Ensuite, je chercherais un AGENTS.override.md sur le chemin et dans le répertoire Codex. Après modification des consignes, relance une session depuis le dossier visé pour contrôler la nouvelle lecture.
Je regarderais ensuite la taille cumulée des instructions. La documentation indique une limite par défaut de 32 Kio, soit 32 768 octets, réglable avec project_doc_max_bytes. Les octets mesurent la taille du texte, pas son nombre de mots. Je préfère retirer les répétitions avant d'augmenter cette limite. Source sur la découverte des instructions.
Si ton équipe utilise un autre nom, project_doc_fallback_filenames permet de déclarer des noms de repli dans config.toml. Je garderais cependant AGENTS.md pour débuter : tu évites un réglage supplémentaire. Ne suppose pas non plus que CLAUDE.md est automatiquement reconnu parce que Claude Code l'utilise. Sans nom de repli configuré pour lui, ce fichier ne remplace pas AGENTS.md dans la découverte décrite ici.
Je finirais par chercher les contradictions. « Ne change jamais les adresses » et « renomme toutes les pages » ne donnent pas un objectif clair. Fais reformuler le conflit avant la modification. Pour décrire la tâche du jour, la documentation sur les demandes à l'agent recommande de préciser le résultat, le contexte utile et les limites : je commencerais par corriger cette demande si elle reste floue.
Un fichier qui évolue avec ton projet
Dans Playing to Win, A. G. Lafley et Roger L. Martin décrivent la cascade de choix stratégiques : ambition, terrain de jeu, manière de gagner, capacités et systèmes de gestion. Ce cadre me donne un filtre concret : avant d'ajouter une règle, je me demande quel résultat elle protège. Une exigence de source protège la fiabilité ; une préférence décorative n'a pas forcément la même priorité.
Je garde les consignes courtes et je renvoie vers les documents détaillés avec leur chemin et leur usage. Par exemple : « Pour modifier une fiche produit, lire docs/fiches.md ». Ce chemin est un exemple fictif, à remplacer par un document réel. OpenAI invite également à réviser les instructions accumulées plutôt qu'à les faire grossir à chaque changement d'outil. Source sur l'entretien des consignes.
Tu peux faire générer un premier fichier avec /init dans Codex CLI, puis le relire. Je vérifie chaque commande et chaque promesse avant de le partager. Un brouillon automatique reste un brouillon. Le cas pratique OpenAI sur les processus de développement présente AGENTS.md comme une convention facultative, utile pour garder les attentes du projet.
Pour ta prochaine tâche, écris le résultat attendu en une phrase, utilise ton fichier et conserve la correction que tu auras encore dû répéter. C'est probablement cette correction qui mérite la prochaine ligne de ton AGENTS.md.
Exemple fictif pour choisir la consigne à écrire en premier
- Je suppose que tu répètes la même instruction pendant 8 sessions, avec 3 minutes de reformulation par session.
- Le temps consacré aux rappels est de 8 × 3 = 24 minutes.
- Je suppose maintenant 10 minutes pour rédiger et vérifier une consigne commune : la différence théorique est de 24 - 10 = 14 minutes.
- Je ne compte ce gain que si la consigne évite effectivement les rappels. Si elle reste ignorée, je diagnostique son chargement avant d'en ajouter.
Je t'invite à chronométrer ta propre répétition. Ce calcul fictif ne mesure ni un résultat de Codex ni un gain obtenu sur mes sites.
Les erreurs fréquentes
Ta check-list
Tout le guide en une image
Pour aller plus loin
Questions fréquentes
Où dois-je mettre mon fichier AGENTS.md ?
Je te conseille le dossier principal du projet pour commencer. Les préférences communes à tes projets peuvent aller dans le répertoire personnel de Codex. Je vérifie toujours le dossier de lancement, car il détermine le chemin de découverte des consignes.
AGENTS.md est-il obligatoire pour utiliser Codex ?
Non. Je peux donner une demande directement dans la conversation. Le fichier devient utile pour conserver une méthode commune entre les sessions et la partager avec les personnes qui travaillent sur le dépôt.
Puis-je écrire mes consignes en français ?
Oui, je peux rédiger les instructions en français. Je conserve les noms de fichiers, les chemins et les commandes dans leur forme exacte. Je préfère une règle dont tu comprends chaque mot à un modèle anglais que tu ne peux pas vérifier.
Pourquoi mon AGENTS.md n'est-il pas pris en compte ?
Je vérifierais son nom, son contenu, le dossier courant, les fichiers prioritaires et le répertoire Codex réellement utilisé. Je relancerais ensuite une session. Si le chargement est correct, je regarderais si la demande contredit une règle ou si celle-ci manque de précision.
Quelle différence entre AGENTS.md et AGENTS.override.md ?
Dans un même dossier, le fichier override est choisi avant le fichier ordinaire. Je le réserverais à une exception volontaire, facile à retrouver. Pour éviter les surprises, je demande à Codex quels fichiers de consignes il a effectivement chargés.
Est-ce que je peux partager mon AGENTS.md avec mon équipe ?
Oui. Je partagerais les conventions du projet dans le dépôt, en retirant secrets et préférences strictement personnelles. Avant de reprendre un fichier externe, je relirais ses commandes et ses adresses. Le nom du fichier ne dit rien sur la fiabilité de son contenu.
AGENTS.md remplace-t-il CLAUDE.md, les skills ou config.toml ?
Je ne les considère pas comme interchangeables. AGENTS.md exprime les consignes durables de Codex, une skill décrit une méthode réutilisable et config.toml règle le logiciel. Pour CLAUDE.md, je vérifie la prise en charge ou les noms de repli plutôt que de supposer une lecture automatique.
Sources
- Ordre global puis projet, priorité des fichiers override et des consignes proches du dossier courant ; chargement au lancement ; taille par défaut de 32 Kio, soit 32 768 octets. : https://learn.chatgpt.com/docs/agent-configuration/agents-md (consulté le 2026-11-19)
- CODEX_HOME détermine le répertoire Codex ; réglages project_doc_max_bytes et project_doc_fallback_filenames pour la découverte des instructions. : https://learn.chatgpt.com/docs/config-file/config-advanced (consulté le 2026-11-19)
- Les permissions gouvernent les accès aux fichiers et au réseau ; elles sont distinctes des instructions rédigées dans le projet. : https://learn.chatgpt.com/docs/permissions (consulté le 2026-11-19)
- AGENTS.md, skills et MCP ont des rôles complémentaires ; les consignes peuvent évoluer avec les corrections récurrentes et renvoyer vers les ressources utiles. : https://learn.chatgpt.com/docs/customization/overview (consulté le 2026-11-19)
- Une demande utile précise le résultat attendu, le contexte nécessaire et les limites adaptées à la tâche. : https://learn.chatgpt.com/docs/prompting (consulté le 2026-11-19)
- AGENTS.md est facultatif ; /init peut générer un premier fichier ; les conventions et contrôles doivent être adaptés au dépôt. : https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex (consulté le 2026-11-19)
- Revoir les instructions accumulées et la portée des skills aide à limiter le contexte superflu. : https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra (consulté le 2026-11-19)
- Visuels : fichiers vides ignorés, priorité à AGENTS.override.md, reconstruction des consignes au lancement et limite cumulée par défaut de 32 Kio (32 768 octets), réglable avec project_doc_max_bytes ; page officielle ouverte pendant cette session. : https://learn.chatgpt.com/docs/agent-configuration/agents-md (consulté le 2026-11-19)
- Journaux pour contrôler les consignes chargées : log_dir, codex-tui.log et fichier session-*.jsonl si l'enregistrement des sessions est activé. : https://learn.chatgpt.com/docs/agent-configuration/agents-md (consulté le 2026-11-19)
- Automate Your Busywork, introduction publiée par Aytekin Tank : les formulaires courants deviennent des modèles avant l'extension aux processus d'équipe. : https://atank.interlogy.com/books/automate-your-busywork/free-chapter/introduction (consulté le 2026-11-19)
- Sam Carpenter renvoie à Work the System pour sa méthode documentaire : objectif stratégique, principes de fonctionnement et procédures de travail. : https://s3-us-west-2.amazonaws.com/tsm-book/the_systems_mindset.pdf (consulté le 2026-11-19)
- Roger L. Martin explique la cascade de Playing to Win : ambition, terrain, manière de gagner, capacités et systèmes de gestion interdépendants. : https://rogerlmartin.substack.com/p/2023-02-20_decoding-the-strategy-choice-cascade-475d40555eb1html (consulté le 2026-11-19)