Codex AGENTS.md
AGENTS.md est le fichier d'instructions personnalisées de Codex qui vous permet de définir des consignes globales et des conventions de workflow pour Codex.
Cette section détaille comment créer et utiliser AGENTS.md.
Qu'est-ce que AGENTS.md ?
Codex lit automatiquement au démarrageAGENTS.mdfichier, en utilisant le mécanisme hiérarchique de « configuration globale + surcharges au niveau du projet », afin que chaque tâche hérite de conventions de travail cohérentes quel que soit le dépôt de code que vous ouvrez.
AGENTS.md est un fichier d'instructions que Codex lit avant d'effectuer tout travail, ce qui vous permet de :
- Définir des normes de codage globales
- Définir des flux de travail spécifiques au projet
- Fournir des conseils différents pour différents répertoires
- Standardiser les pratiques de développement de l'équipe

Avec AGENTS.md, vous pouvez garantir que Codex suit des conventions cohérentes dans l'ensemble de la base de code.
Comment Codex découvre les guides
Codex construit la chaîne d'instructions selon les priorités suivantes.
Mécanisme de chargement à trois niveaux
| Niveau | Règle de chargement | Description |
|---|---|---|
| Niveau global | Lit~/.codex/AGENTS.override.md |
S'il n'existe pas, lit~/.codex/AGENTS.md, ne prend que le premier fichier non vide |
| Niveau projet | Parcourt depuis le répertoire racine Git, niveau par niveau, jusqu'au répertoire courant | Vérifie chaque niveau dans l'ordreAGENTS.override.md → AGENTS.md → project_doc_fallback_filenamesnoms de fichiers alternatifs dans |
| Niveau de fusion | Concatène de la racine à la feuille dans l'ordre | Les fichiers plus proches du répertoire courant apparaissent plus tard et ont une priorité plus élevée |
La limite de taille totale par défaut après fusion est de 32 KiB (contrôlée par
project_doc_max_bytes), et la partie excédentaire sera tronquée.
Étape 1 : Créer une configuration globale
La configuration globale s'applique à tous les projets et convient aux conventions de travail universelles.
Créer un répertoire de configuration
mkdir -p ~/.codex
Assurez-vous que le répertoire personnel de Codex existe ; toutes les configurations globales sont placées dans ce répertoire.
Écrire les conventions globales
Créez~/.codex/AGENTS.mdfichier, écrivez les conventions communes à tous les projets :
# ~/.codex/AGENTS.md ## 全局工作约定 - 修改 JavaScript 文件后,始终运行 npm test - 安装依赖时优先使用 pnpm - 新增生产依赖前先请求确认
Vérifier que la configuration prend effet
Exécutez la commande suivante ; Codex devrait afficher les entrées que vous avez écrites :
codex --ask-for-approval never "Summarize the current instructions."
Si vous avez besoin d'une surcharge globale temporaire, vous pouvez créer
AGENTS.override.md, et la suppression de ce fichier restaure la configuration d'origine.
Étape 2 : Configurer en couches par dépôt
Les fichiers au niveau du projet font en sorte que Codex suive les conventions propres au dépôt tout en héritant toujours de la configuration globale.
Ajouter des conventions au niveau du dépôt
Créer dans le répertoire racine du projetAGENTS.md:
# AGENTS.md ## 仓库约定 - 提 PR 前运行 npm run lint - 修改公共工具行为时,同步更新 docs/ 中的文档
Ajouter des surcharges pour les sous-répertoires
Pour les sous-répertoires ayant des besoins spécifiques (commeservices/payments/), créezAGENTS.override.mdpour effectuer des surcharges locales :
# services/payments/AGENTS.override.md ## 支付服务规则 - 使用 make test-payments 替代 npm test - 轮换 API Key 前必须通知安全频道
Structure complète des répertoires
Voici une arborescence de répertoires typique après le chargement d’un dépôtAGENTS.md:
repo/
├── AGENTS.md # 仓库级约定(加载)
└── services/
├── payments/
│ ├── AGENTS.md # 被跳过(override 优先)
│ └── AGENTS.override.md # 支付服务覆写(加载)
└── search/
└── AGENTS.md # 搜索服务约定(加载)
Dans le même répertoire,
AGENTS.override.mdlorsqu’il existe, le fichier frèreAGENTS.mdsera ignoré.
Vérifier l’ordre de chargement
Démarrez Codex depuis un sous-répertoire et affichez les sources des instructions chargées :
codex --cd services/payments --ask-for-approval never \ "List the instruction sources you loaded."
Résultat attendu : listez le fichier global, le fichier racine du dépôt et le fichier de remplacement du service de paiement dans l'ordre.
Options avancées
Les deux fonctionnalités suivantes s'appliquent aux scénarios où vous devez personnaliser davantage le comportement de chargement des instructions.
Nom de fichier personnalisé
Si le projet possède déjà un nom de fichier habituelTEAM_GUIDE.md, vous pouvez l'ajouter à la liste de repli dans le fichier de configuration, et Codex le traitera comme un fichier d'instructions :
# ~/.codex/config.toml # 追加回退文件名并提高合并上限 project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] project_doc_max_bytes = 65536
Après modification, l'ordre d'inspection pour chaque répertoire devient :AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md, prenez le premier fichier existant.
Après avoir modifié la configuration, vous devez redémarrer Codex pour faire
config.tomlen sorte que les modifications prennent effet.
Changer de répertoire de configuration
ViaCODEX_HOMEvariable d'environnement, vous pouvez utiliser des profils de configuration indépendants pour différents projets ou processus automatisés :
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"
À ce stade, Codex utilisera le.codexsous-répertoire sous le répertoire courant pour lire la configuration globale, plutôt que celui par défaut~/.codex。
Vérification et débogage
La commande suivante permet de vérifier rapidement la source des instructions actuellement actives.
Vérification rapide
# 从仓库根目录检查全局 + 项目指令 codex --ask-for-approval never "Summarize the current instructions." # 从子目录检查嵌套覆写 codex --cd subdir --ask-for-approval never "Show which instruction files are active."
Activer les journaux détaillés
Si vous devez auditer en détail le processus de chargement des instructions, vous pouvez activer la journalisation TUI :
# 输出 TUI 日志到本地目录 codex -c log_dir=./.codex-log # 日志文件位于 ./.codex-log/codex-tui.log
Dépannage des problèmes courants
Le tableau suivant résume les problèmes possibles lors de la configuration et les pistes de dépannage.
| Symptôme | Piste de dépannage |
|---|---|
| Rien n'est chargé | Confirmez que le fichier n'est pas vide ; exécutezcodex statusVérifiez si le répertoire racine de l'espace de travail est correct |
| Des instructions incorrectes sont apparues | Vérifiez s'il y a des éléments résiduelsAGENTS.override.md |
| Le nom du fichier de secours ne prend pas effet | Confirmezconfig.tomll'orthographe est correcte dans le , et redémarrez Codex pour que cela prenne effet. |
| Le contenu de l'instruction est tronqué | Augmentezproject_doc_max_bytes, ou divisez les fichiers volumineux en plusieurs niveaux de répertoires |
| Confusion de profil | Exécutezecho $CODEX_HOME, confirmez qu'il pointe vers le répertoire attendu |