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 parproject_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éerAGENTS.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 faireconfig.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
Autres extensions