Codex AGENTS.md
AGENTS.md ist Codex' benutzerdefinierte Anweisungsdatei, mit der du globale Richtlinien und Workflow-Konventionen für Codex festlegen kannst.
Dieser Abschnitt beschreibt detailliert, wie man AGENTS.md erstellt und verwendet.
Was ist AGENTS.md?
Codex liest beim Start automatischAGENTS.mdDatei, die den hierarchischen Mechanismus von "globaler Konfiguration + Überschreibungen auf Projektebene" verwendet, sodass jede Aufgabe konsistente Arbeitskonventionen erbt, egal, welches Code-Repository du öffnest.
AGENTS.md ist eine Anweisungsdatei, die Codex vor jeder Arbeit liest, und ermöglicht dir:
- Globale Programmierstandards festlegen
- Projektspezifische Workflows definieren
- Unterschiedliche Anleitungen für verschiedene Verzeichnisse bereitstellen
- Team-Entwicklungspraktiken standardisieren
Mit AGENTS.md kannst du sicherstellen, dass Codex in der gesamten Codebasis konsistenten Konventionen folgt.
Wie Codex Anleitungen entdeckt
Codex erstellt die Anweisungskette gemäß den folgenden Prioritäten.
Dreistufiger Lademechanismus
| Stufe | Laderegel | Beschreibung |
|---|---|---|
| Globale Ebene | Liest~/.codex/AGENTS.override.md |
Wenn sie nicht existiert, liest~/.codex/AGENTS.md, nimmt nur die erste nicht leere Datei |
| Projekt-Ebene | Durchsucht vom Git-Wurzelverzeichnis Ebene für Ebene bis zum aktuellen Verzeichnis | Prüft jede Ebene in der ReihenfolgeAGENTS.override.md → AGENTS.md → project_doc_fallback_filenamesalternative Dateinamen in |
| Zusammenführungs-Ebene | Verkettet von der Wurzel zum Blatt in der Reihenfolge | Dateien, die näher am aktuellen Verzeichnis liegen, erscheinen später und haben höhere Priorität |
Das standardmäßige Gesamtgrößenlimit nach dem Zusammenführen beträgt 32 KiB (gesteuert durch
project_doc_max_bytes), und der überschüssige Teil wird abgeschnitten.
Schritt 1: Globale Konfiguration erstellen
Die globale Konfiguration gilt für alle Projekte und eignet sich für allgemeine Arbeitskonventionen.
Ein Konfigurationsverzeichnis erstellen
mkdir -p ~/.codex
Stellen Sie sicher, dass das Codex-Home-Verzeichnis vorhanden ist; alle globalen Konfigurationen werden in diesem Verzeichnis abgelegt.
Globale Konventionen schreiben
Erstelle~/.codex/AGENTS.mdDatei, schreiben Sie Konventionen, die für alle Projekte gelten:
# ~/.codex/AGENTS.md ## 全局工作约定 - 修改 JavaScript 文件后，始终运行 npm test - 安装依赖时优先使用 pnpm - 新增生产依赖前先请求确认
Überprüfen, ob die Konfiguration wirksam wird
Führen Sie den folgenden Befehl aus; Codex sollte die von Ihnen geschriebenen Einträge ausgeben:
codex --ask-for-approval never "Summarize the current instructions."
Wenn Sie eine temporäre globale Überschreibung benötigen, können Sie erstellen
AGENTS.override.md, und das Löschen dieser Datei stellt die ursprüngliche Konfiguration wieder her.
Schritt 2: Konfiguration nach Repository schichten
Dateien auf Projektebene sorgen dafür, dass Codex repositoriespezifische Konventionen befolgt und dabei weiterhin die globale Konfiguration erbt.
Konventionen auf Repository-Ebene hinzufügen
Im Projektstammverzeichnis erstellenAGENTS.md：
# AGENTS.md ## 仓库约定 - 提 PR 前运行 npm run lint - 修改公共工具行为时，同步更新 docs/ 中的文档
Überschreibungen für Unterverzeichnisse hinzufügen
Für Unterverzeichnisse mit besonderen Anforderungen (wie z. B.services/payments/), erstellen SieAGENTS.override.mdum lokale Überschreibungen vorzunehmen:
# services/payments/AGENTS.override.md ## 支付服务规则 - 使用 make test-payments 替代 npm test - 轮换 API Key 前必须通知安全频道
Vollständige Verzeichnisstruktur
Das Folgende ist ein typisches Verzeichnislayout nach dem Laden eines RepositorysAGENTS.md:
repo/
├── AGENTS.md # 仓库级约定（加载）
└── services/
├── payments/
│ ├── AGENTS.md # 被跳过（override 优先）
│ └── AGENTS.override.md # 支付服务覆写（加载）
└── search/
└── AGENTS.md # 搜索服务约定（加载）
Im selben Verzeichnis,
AGENTS.override.mdwird, wenn sie existiert, die benachbarte DateiAGENTS.mdübersprungen.
Ladereihenfolge überprüfen
Starte Codex aus einem Unterverzeichnis und sieh dir die Quellen der geladenen Anweisungen an:
codex --cd services/payments --ask-for-approval never \ "List the instruction sources you loaded."
Erwartetes Ergebnis: Liste die globale Datei, die Datei im Repository-Stammverzeichnis und die Überschreibungsdatei des Zahlungsdienstes in dieser Reihenfolge auf.
Erweiterte Optionen
Die folgenden zwei Funktionen gelten für Szenarien, in denen du das Ladeverhalten für Anweisungen weiter anpassen musst.
Benutzerdefinierter Dateiname
Wenn das Projekt bereits eine üblicheTEAM_GUIDE.md, kannst du sie an die Fallback-Liste in der Konfigurationsdatei anhängen, und Codex behandelt sie als Anweisungsdatei:
# ~/.codex/config.toml # 追加回退文件名并提高合并上限 project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] project_doc_max_bytes = 65536
Nach der Änderung wird die Prüfreihenfolge für jedes Verzeichnis zu:AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md, nimm die erste vorhandene Datei.
Nach dem Ändern der Konfiguration musst du Codex neu starten, damit
config.tomldie Änderungen wirksam werden.
Konfigurationsverzeichnis wechseln
DurchCODEX_HOMEUmgebungsvariable können Sie unabhängige Konfigurationsprofile für verschiedene Projekte oder automatisierte Prozesse verwenden:
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"
An diesem Punkt wird Codex das.codexUnterverzeichnis unter dem aktuellen Verzeichnis, um die globale Konfiguration zu lesen, anstelle der Standardeinstellung~/.codex。
Überprüfung und Debugging
Mit dem folgenden Befehl können Sie schnell die Quelle der aktuell aktiven Anweisungen überprüfen.
Schnellprüfung
# 从仓库根目录检查全局 + 项目指令 codex --ask-for-approval never "Summarize the current instructions." # 从子目录检查嵌套覆写 codex --cd subdir --ask-for-approval never "Show which instruction files are active."
Ausführliche Protokolle aktivieren
Wenn Sie den Ladevorgang der Anweisungen im Detail überprüfen müssen, können Sie die TUI-Protokollierung aktivieren:
# 输出 TUI 日志到本地目录 codex -c log_dir=./.codex-log # 日志文件位于 ./.codex-log/codex-tui.log
Fehlerbehebung bei häufigen Problemen
Die folgende Tabelle fasst mögliche Probleme während der Konfiguration und Ansätze zur Fehlerbehebung zusammen.
| Symptom | Fehlerbehebungsrichtung |
|---|---|
| Es wird nichts geladen | Bestätigen Sie, dass die Datei nicht leer ist; führen Sie sie auscodex statusPrüfen Sie, ob das Workspace-Stammverzeichnis korrekt ist |
| Fehlerhafte Anweisungen sind aufgetreten | Prüfen Sie, ob Reste vorhanden sindAGENTS.override.md |
| Fallback-Dateiname wird nicht wirksam | Bestätigenconfig.tomlSchreibweise ist korrekt in der , und starten Sie Codex neu, damit es wirksam wird. |
| Anweisungsinhalt ist abgeschnitten | Erhöhenproject_doc_max_bytes, oder teilen Sie große Dateien in mehrere Verzeichnisebenen auf |
| Profilverwechslung | Führen Sieecho $CODEX_HOME, bestätigen Sie, dass es auf das erwartete Verzeichnis verweist |