Codex et AGENTS.md : lire les fichiers que Codex utilise

Codex lit ses instructions dans des fichiers Markdown appelés AGENTS.md. Quand tu le lui demandes, il peut aussi écrire des plans, des spécifications et des notes sous forme de fichiers .md dans ton projet. Cette page explique où Codex cherche AGENTS.md et comment lire confortablement tous ces fichiers.

Où Codex cherche AGENTS.md

Au démarrage, Codex construit une seule chaîne d’instructions : un fichier global, puis les fichiers du projet le long du chemin jusqu’à ton dossier de travail.

1. Ton fichier global. Dans le dossier d’accueil de Codex, ~/.codex (ou le dossier défini par CODEX_HOME). Codex utilise AGENTS.override.md s’il existe, sinon AGENTS.md. Un seul fichier est utilisé ici.

2. Ton projet. Codex part de la racine du projet (la racine Git par défaut ; project_root_markers peut changer cela) et descend jusqu’au dossier dans lequel tu travailles. Dans chaque dossier, il prend au plus un fichier, en vérifiant dans cet ordre :

  1. AGENTS.override.md
  2. AGENTS.md
  3. Tout nom que tu as indiqué dans project_doc_fallback_filenames

S’il n’y a pas de racine de projet, Codex ne vérifie que le dossier actuel.

Comment les fichiers se combinent

Codex assemble les fichiers de la racine vers le bas, avec des lignes vides entre eux. Un fichier plus proche de ton dossier de travail vient plus tard, et ses instructions l’emportent donc sur les précédentes. Les fichiers vides sont ignorés.

Il y a une limite de taille : Codex arrête d’ajouter des fichiers quand leur taille cumulée atteint project_doc_max_bytes, 32 KiB (32 768 octets) par défaut. Si tes instructions sont longues, augmente la limite ou répartis-les dans des fichiers AGENTS.md placés dans des sous-dossiers.

Ces deux réglages se trouvent dans config.toml dans ton dossier d’accueil de Codex (par défaut ~/.codex/config.toml) :

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

Lance une nouvelle session Codex après les avoir modifiés.

Un AGENTS.md simple

# AGENTS.md

## Commands
- Build: `npm run build`
- Test: `npm test`

## Rules
- Write plans to `docs/plans/<task>.md` before changing code.
- Keep each change small; explain it in the pull request.

Codex n’enregistre pas les plans dans des fichiers de son propre chef. Pour obtenir des plans que tu pourras relire plus tard, demande-lui d’en écrire un dans un fichier, dans AGENTS.md (comme la deuxième règle) ou dans ton invite.

Lire ce que Codex écrit

Avec quelques fichiers, n’importe quel éditeur convient. Avec beaucoup (un plan par tâche, des notes, des rapports), il est utile de les lire sous forme de pages et de voir ce qui a changé.

Sur Mac, avec PilcrowMD (gratuit, bêta) :

PilcrowMD pour Mac (bêta) · En savoir plus sur la lecture des fichiers d’agents

Questions fréquentes

AGENTS.md est-il réservé à Codex ? Non. C’est une convention ouverte que plusieurs agents de programmation lisent, pas un format propre à Codex. Claude Code, par exemple, peut lire AGENTS.md quand un projet n’a pas de CLAUDE.md (page Claude Code).

Pourquoi Codex ignore-t-il une partie de mes instructions ? Vérifie la limite de taille (32 KiB par défaut) et si un AGENTS.override.md dans le même dossier prend la place de ton AGENTS.md.

Puis-je lire ces fichiers sur mon téléphone ? Si le dossier du projet est synchronisé avec Google Drive, ajoute-le dans Mes dossiers dans PilcrowMD pour Android. Ouvre une note pour voir sa dernière version ; il n’y a pas de rechargement en direct sur Android.

Aussi sur Mac : PilcrowMD pour Mac (bêta)