Instructions personnalisées avec AGENTS.md

Codex lit les fichiers AGENTS.md avant de commencer à travailler. Vous pouvez définir des instructions globales, puis les remplacer au besoin pour chaque projet. Ainsi, Codex aborde chaque tâche avec les règles appropriées, quel que soit le dépôt que vous ouvrez.

Comment Codex recherche les instructions

Au démarrage, Codex construit une chaîne d’instructions. Il le fait une fois par exécution, ce qui correspond généralement à une fois par session dans l’interface en mode texte (TUI). La recherche suit cet ordre de priorité :

1. Au niveau global : dans votre répertoire personnel Codex (~/.codex par défaut, sauf si vous définissez CODEX_HOME), Codex lit AGENTS.override.md si ce fichier existe. Sinon, il lit AGENTS.md. À ce niveau, Codex utilise uniquement le premier fichier non vide.
2. Au niveau du projet : Codex parcourt les répertoires depuis la racine du projet (généralement la racine du dépôt Git) jusqu’au répertoire de travail courant. S’il ne trouve pas la racine du projet, il examine uniquement le répertoire courant. Dans chaque répertoire du parcours, il recherche AGENTS.override.md, puis AGENTS.md, puis les noms de fichiers de repli définis dans project_doc_fallback_filenames. Codex retient au plus un fichier par répertoire.
3. Ordre de fusion : Codex concatène les fichiers en partant de la racine et les sépare par des lignes vides. Les instructions des fichiers les plus proches du répertoire courant priment sur les précédentes, car elles apparaissent plus loin dans le prompt final.

Codex ignore les fichiers vides et cesse d’ajouter des fichiers dès que leur taille cumulé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 la section Recherche des instructions du projet. Si vous atteignez la limite, augmentez-la ou répartissez les instructions entre plusieurs sous-répertoires.

Définissez des instructions globales

Enregistrez vos règles de travail par défaut dans votre répertoire personnel Codex pour qu’elles s’appliquent à tous vos dépôts.

1. Assurez-vous que le répertoire existe :

   mkdir -p ~/.codex

2. Créez le fichier ~/.codex/AGENTS.md et indiquez-y les préférences que vous souhaitez réutiliser :

   # ~/.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. Lancez Codex depuis n’importe quel répertoire pour vérifier qu’il charge le fichier :

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

   Résultat attendu : Codex cite les consignes de ~/.codex/AGENTS.md avant de proposer des actions.

Pour remplacer temporairement les instructions globales sans supprimer le fichier de base, utilisez ~/.codex/AGENTS.override.md. Supprimez ce fichier pour rétablir les instructions communes.

Ajoutez des instructions propres au projet

Les fichiers du dépôt permettent à Codex de suivre les conventions du projet tout en appliquant vos règles globales par défaut.

1. À la racine de votre dépôt, ajoutez un fichier AGENTS.md qui décrit les règles 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. Si certaines équipes ont besoin de règles différentes, ajoutez des fichiers d’instructions prioritaires dans leurs sous-répertoires. Par exemple, dans services/payments/, créez le fichier 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. Lancez Codex depuis le répertoire du service de paiement :

   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 fichier prioritaire du service de paiement.

Codex arrête sa recherche lorsqu’il atteint le répertoire courant. Placez donc les fichiers prioritaires aussi près que possible du code auquel leurs règles s’appliquent.

Voici un exemple de dépôt après l’ajout d’un fichier global et d’un fichier prioritaire propre au service de paiement :

Ajoutez des règles de revue de code

Pour la revue de code avec Codex sur GitHub, ajoutez une section ## Code Review Rules au fichier AGENTS.md le plus proche du code concerné. Placez les vérifications communes à tout le dépôt dans le fichier à la racine et celles qui concernent un service dans le fichier de son sous-répertoire.

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

Rédigez des règles concises. Précisez le comportement à signaler, la marche à suivre pour éviter le problème et les éventuelles exceptions. Réservez les vérifications de formatage et de lint à l’intégration continue. Pour configurer la revue et rédiger vos règles, consultez la section Personnalisez les vérifications de Codex.

Personnalisez les noms de fichiers de repli

Si votre dépôt utilise déjà un autre nom de fichier (par exemple TEAM_GUIDE.md), ajoutez ce nom à la liste de repli pour que Codex reconnaisse le fichier comme une source 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 pour charger la configuration mise à jour.

Codex recherche désormais les fichiers dans chaque répertoire dans l’ordre suivant : AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Lors de la recherche d’instructions, il ignore les fichiers dont le nom ne figure pas dans cette liste. En augmentant la limite en octets, vous permettez à Codex de combiner davantage d’instructions avant qu’elles ne soient tronquées.

Une fois la liste de repli configurée, Codex utilise ces autres fichiers comme sources d’instructions :

Définissez la variable d’environnement CODEX_HOME pour utiliser un autre profil, par exemple celui d’un compte dédié à l’automatisation d’un projet :

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

Résultat attendu : la sortie affiche les chemins des fichiers par rapport au répertoire .codex personnalisé.

Vérifiez votre configuration

• Exécutez codex --ask-for-approval never "Summarize the current instructions." à la racine d’un dépôt. Codex devrait reprendre les instructions des fichiers globaux et de ceux 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 instructions prioritaires des sous-répertoires remplacent les règles plus générales.
• Pour vérifier quels fichiers d’instructions Codex a chargés, activez le journal en texte brut de la TUI avec codex -c log_dir=./.codex-log, puis consultez ./.codex-log/codex-tui.log. Si vous avez activé la journalisation des sessions, vous pouvez aussi consulter le fichier session-*.jsonl le plus récent.
• Si les instructions semblent obsolètes, redémarrez Codex dans le répertoire concerné. Codex reconstruit la chaîne d’instructions à chaque exécution et au début de chaque session TUI. Vous n’avez donc aucun cache à vider manuellement.

Résolvez les problèmes de recherche d’instructions

• Aucune instruction ne se charge : vérifiez que vous êtes dans le bon dépôt et que codex status indique la racine attendue pour l’espace de travail. Vérifiez que les fichiers d’instructions ont bien un contenu. Codex ignore les fichiers vides.
• Les instructions affichées ne sont pas celles attendues : recherchez un fichier AGENTS.override.md plus haut dans l’arborescence ou dans votre répertoire personnel Codex. Renommez ou supprimez le fichier prioritaire pour que Codex utilise de nouveau le fichier habituel.
• Codex ignore les noms de fichiers de repli : vérifiez que les noms indiqués dans project_doc_fallback_filenames ne contiennent pas de fautes de frappe, puis redémarrez Codex pour appliquer la configuration mise à jour.
• Les instructions sont tronquées : augmentez la valeur de project_doc_max_bytes ou répartissez le contenu des fichiers volumineux entre plusieurs sous-répertoires pour conserver l’intégralité des instructions essentielles.
• Le profil utilisé ne correspond pas au profil attendu : exécutez echo $CODEX_HOME avant de lancer Codex. Si la valeur diffère de celle par défaut, Codex utilise un autre répertoire personnel que celui que vous avez modifié.

Pour aller plus loin

• Pour en savoir plus, consultez le site officiel AGENTS.md.
• Consultez le guide Rédigez des prompts pour Codex pour découvrir des façons de dialoguer avec Codex qui complètent vos instructions persistantes.