Documentation ChatGPT
Français
Contact goolvyouyou@gmail.com

Instructions personnalisées avec AGENTS.md

Donnez à Codex des instructions et du contexte supplémentaires pour votre projet

Codex lit les fichiers AGENTS.md avant de commencer toute tâche. En combinant des consignes globales avec des remplacements propres au projet, vous pouvez démarrer chaque tâche avec des attentes cohérentes, quel que soit le dépôt que vous ouvrez.

Comment Codex trouve les consignes

Codex construit une chaîne d’instructions à son démarrage (une fois par exécution ; dans la TUI, cela signifie généralement une fois par session lancée). La détection suit cet ordre de priorité :

  1. Portée globale : Dans votre répertoire d’accueil Codex (par défaut ~/.codex, sauf si vous définissez CODEX_HOME), Codex lit AGENTS.override.md s’il existe. Sinon, Codex lit AGENTS.md. Codex utilise uniquement le premier fichier non vide à ce niveau.
  2. Portée du projet : En partant de la racine du projet (généralement la racine Git), Codex descend jusqu’à votre répertoire de travail actuel. Si Codex ne trouve pas de racine de projet, il vérifie uniquement le répertoire actuel. Dans chaque répertoire du chemin, il recherche AGENTS.override.md, puis AGENTS.md, puis les éventuels noms de secours définis dans project_doc_fallback_filenames. Codex inclut au maximum un fichier par répertoire.
  3. Ordre de fusion : Codex concatène les fichiers de la racine vers le bas, en les séparant par des lignes vides. Les fichiers les plus proches de votre répertoire actuel remplacent les consignes précédentes, car ils apparaissent plus tard dans l’invite combinée.

Codex ignore les fichiers vides et cesse d’ajouter des fichiers lorsque la taille combinée atteint la limite définie par project_doc_max_bytes (32 Kio par défaut). Pour en savoir plus sur ces paramètres, consultez Détection des instructions du projet. Augmentez la limite ou répartissez les instructions entre des répertoires imbriqués lorsque vous l’atteignez.

Créer des consignes globales

Créez des valeurs par défaut persistantes dans votre répertoire d’accueil Codex afin que chaque dépôt hérite de vos conventions de travail.

  1. Vérifiez que le répertoire existe :

    mkdir -p ~/.codex

  2. Créez ~/.codex/AGENTS.md avec des préférences réutilisables :

    # ~/.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.

  3. Exécutez Codex depuis n’importe quel emplacement pour vérifier qu’il charge le fichier :

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

    Résultat attendu : Codex cite les éléments de ~/.codex/AGENTS.md avant de proposer des modifications.

Utilisez ~/.codex/AGENTS.override.md lorsque vous avez besoin d’un remplacement global temporaire sans supprimer le fichier de base. Supprimez ce remplacement pour rétablir les consignes partagées.

Superposer les instructions du projet

Les fichiers au niveau du dépôt permettent à Codex de connaître les conventions du projet tout en continuant à hériter de vos valeurs globales par défaut.

  1. À la racine de votre dépôt, ajoutez un fichier AGENTS.md qui décrit la configuration de base :

    # AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

  2. Ajoutez des remplacements dans des répertoires imbriqués lorsque certaines équipes ont besoin de règles différentes. Par exemple, dans services/payments/, créez AGENTS.override.md :

    # 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. Démarrez Codex depuis le répertoire des paiements :

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

    Résultat attendu : Codex indique d’abord le fichier global, puis le fichier AGENTS.md à la racine du dépôt et, enfin, le remplacement propre aux paiements.

Codex cesse la recherche lorsqu’il atteint votre répertoire actuel ; placez donc les remplacements aussi près que possible des tâches spécialisées.

Voici un exemple de dépôt après l’ajout d’un fichier global et d’un remplacement propre aux paiements :

<FileTree class="mt-4" tree={[ { name: "AGENTS.md", comment: "Attentes du dépôt", highlight: true, }, { name: "services/", open: true, children: [ { name: "payments/", open: true, children: [ { name: "AGENTS.md", comment: "Ignoré, car un remplacement existe", }, { name: "AGENTS.override.md", comment: "Règles du service de paiement", highlight: true, }, { name: "README.md" }, ], }, { name: "search/", children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }], }, ], }, ]} />

Ajouter des règles de revue de code

Pour la revue de code Codex dans GitHub, ajoutez une section ## Code Review Rules au fichier AGENTS.md le plus proche du code auquel les règles s’appliquent. Placez les vérifications valables pour l’ensemble du dépôt à la racine et les vérifications propres à un service dans un fichier imbriqué.

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Gardez les règles concises, expliquez le comportement à signaler ainsi que toute procédure sûre ou exception, et réservez les vérifications de mise en forme et de lint à la CI. Consultez Personnaliser les éléments revus par Codex pour obtenir des conseils sur la configuration et la rédaction des règles.

Personnaliser les noms de fichiers de secours

Si votre dépôt utilise déjà un autre nom de fichier (par exemple TEAM_GUIDE.md), ajoutez-le à la liste de secours afin que Codex le traite comme un fichier d’instructions.

  1. Modifiez votre configuration Codex :

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

  2. Redémarrez Codex ou exécutez une nouvelle commande afin de charger la configuration mise à jour.

Codex vérifie désormais chaque répertoire dans cet ordre : AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Les noms de fichiers absents de cette liste sont ignorés lors de la détection des instructions. La limite en octets plus élevée permet de combiner davantage de consignes avant leur troncature.

Avec la liste de secours en place, Codex traite les fichiers alternatifs comme des instructions :

<FileTree class="mt-4" tree={[ { name: "TEAM_GUIDE.md", comment: "Détecté grâce à la liste de secours", highlight: true, }, { name: ".agents.md", comment: "Fichier de secours à la racine", }, { name: "support/", open: true, children: [ { name: "AGENTS.override.md", comment: "Remplace les consignes de secours", highlight: true, }, { name: "playbooks/", children: [{ name: "…", placeholder: true }], }, ], }, ]} />

Définissez la variable d’environnement CODEX_HOME lorsque vous souhaitez utiliser un autre profil, par exemple un utilisateur d’automatisation propre au projet :

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

Résultat attendu : la sortie répertorie les fichiers avec des chemins relatifs au répertoire .codex personnalisé.

Vérifier votre configuration

  • Exécutez codex --ask-for-approval never "Summarize the current instructions." depuis la racine d’un dépôt. Codex doit afficher les consignes des fichiers globaux et du projet dans leur ordre de priorité.
  • Utilisez codex --cd subdir --ask-for-approval never "Show which instruction files are active." pour vérifier que les remplacements imbriqués remplacent les règles plus générales.
  • Pour examiner les fichiers d’instructions chargés par Codex, activez un journal TUI en texte brut avec codex -c log_dir=./.codex-log et consultez ./.codex-log/codex-tui.log, ou examinez le fichier session-*.jsonl le plus récent si vous avez activé la journalisation des sessions.
  • Si les instructions semblent obsolètes, redémarrez Codex dans le répertoire cible. Codex reconstruit la chaîne d’instructions à chaque exécution (et au début de chaque session TUI) ; il n’y a donc aucun cache à vider manuellement.

Résoudre les problèmes de détection

  • Rien ne se charge : Vérifiez que vous vous trouvez dans le dépôt prévu et que codex status indique la racine d’espace de travail attendue. Assurez-vous que les fichiers d’instructions contiennent du texte ; Codex ignore les fichiers vides.
  • Des consignes incorrectes apparaissent : Recherchez un fichier AGENTS.override.md plus haut dans l’arborescence des répertoires ou dans votre répertoire d’accueil Codex. Renommez ou supprimez le remplacement pour revenir au fichier normal.
  • Codex ignore les noms de secours : Vérifiez que vous avez indiqué les noms dans project_doc_fallback_filenames sans faute de frappe, puis redémarrez Codex afin que la configuration mise à jour prenne effet.
  • Les instructions sont tronquées : Augmentez project_doc_max_bytes ou répartissez les fichiers volumineux entre des répertoires imbriqués afin de préserver les consignes essentielles.
  • Confusion concernant le profil : Exécutez echo $CODEX_HOME avant de lancer Codex. Une valeur autre que celle par défaut dirige Codex vers un répertoire d’accueil différent de celui que vous avez modifié.

Étapes suivantes

  • Consultez le site officiel AGENTS.md pour en savoir plus.
  • Consultez Formuler des invites pour Codex pour découvrir des modèles de conversation qui se combinent efficacement avec des consignes persistantes.