Codex liest AGENTS.md-Dateien, bevor es mit der Arbeit beginnt. Du kannst globale Vorgaben festlegen und sie für einzelne Projekte überschreiben. So gelten bei jeder Aufgabe deine Grundregeln, egal welches Repository du öffnest.
So findet Codex deine Anweisungen
Codex stellt die Anweisungen bei jedem Start einmal zusammen. In der TUI geschieht das in der Regel einmal pro gestarteter Sitzung. Dabei geht Codex in dieser Reihenfolge vor:
- Globale Anweisungen: In deinem Codex-Home-Verzeichnis (standardmäßig
~/.codex, sofern duCODEX_HOMEnicht gesetzt hast) liest CodexAGENTS.override.md, falls die Datei vorhanden ist. Andernfalls liest CodexAGENTS.md. Auf dieser Ebene verwendet Codex nur die erste Datei, die nicht leer ist. - Projektanweisungen: Codex durchsucht die Verzeichnisse vom Projektstamm (in der Regel dem Stammverzeichnis des Git-Repositorys) bis zu deinem aktuellen Arbeitsverzeichnis. Findet Codex keinen Projektstamm, prüft es nur das aktuelle Verzeichnis. In jedem Verzeichnis auf diesem Pfad sucht Codex zuerst nach
AGENTS.override.md, dann nachAGENTS.mdund schließlich nach den alternativen Dateinamen ausproject_doc_fallback_filenames. Pro Verzeichnis berücksichtigt Codex höchstens eine Datei. - Reihenfolge beim Zusammenführen: Codex fügt die Dateiinhalte vom Stammverzeichnis aus der Reihe nach zusammen und trennt sie durch Leerzeilen. Anweisungen aus Dateien, die näher an deinem aktuellen Verzeichnis liegen, haben Vorrang vor früheren Vorgaben, weil sie im gemeinsamen Prompt weiter hinten stehen.
Codex überspringt leere Dateien und fügt keine weiteren Dateien hinzu, sobald die Gesamtgröße den in project_doc_max_bytes festgelegten Grenzwert erreicht (standardmäßig 32 KiB). Einzelheiten zu diesen Einstellungen findest du im Abschnitt So findet Codex Projektanweisungen. Wenn du den Grenzwert erreichst, erhöhe ihn oder verteile die Anweisungen auf Unterverzeichnisse.
Globale Anweisungen festlegen
Lege dauerhafte Vorgaben in deinem Codex-Home-Verzeichnis fest, damit deine Arbeitsregeln für jedes Repository gelten.
-
Stelle sicher, dass das Verzeichnis existiert:
mkdir -p ~/.codex -
Erstelle
~/.codex/AGENTS.mdmit Vorgaben, die du immer wieder verwenden möchtest:# ~/.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. -
Starte Codex in einem beliebigen Verzeichnis, um zu prüfen, ob es die Datei lädt:
codex --ask-for-approval never "Summarize the current instructions."Erwartetes Ergebnis: Codex zitiert die Vorgaben aus
~/.codex/AGENTS.md, bevor es Arbeitsschritte vorschlägt.
Mit ~/.codex/AGENTS.override.md kannst du deine globalen Vorgaben vorübergehend überschreiben, ohne die ursprüngliche Datei zu löschen. Entferne die Override-Datei, damit wieder die gemeinsamen Vorgaben gelten.
Projektanweisungen nach Verzeichnis festlegen
Mit Anweisungsdateien im Repository gibst du Codex die Regeln für das Projekt vor. Deine globalen Vorgaben gelten weiterhin.
-
Lege im Stammverzeichnis deines Repositorys eine
AGENTS.mdmit den grundlegenden Anweisungen für das Setup an:# AGENTS.md ## Repository expectations - Run `npm run lint` before opening a pull request. - Document public utilities in `docs/` when you change behavior. -
Wenn einzelne Teams andere Regeln benötigen, lege Override-Dateien in den jeweiligen Unterverzeichnissen an. Erstelle beispielsweise in
services/payments/die DateiAGENTS.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. -
Starte Codex im Verzeichnis des Zahlungsdienstes:
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."Erwartetes Ergebnis: Codex nennt zuerst die globale Datei, dann die
AGENTS.mdim Stammverzeichnis des Repositorys und zuletzt die Override-Datei für den Zahlungsdienst.
Codex beendet die Suche, sobald es dein aktuelles Verzeichnis erreicht. Lege Override-Dateien daher möglichst nah an dem Code ab, für den die Regeln gelten.
So kann ein Repository aussehen, nachdem du eine globale Datei und eine Override-Datei für den Zahlungsdienst angelegt hast:
- AGENTS.md Vorgaben für das Repository
-
services/
-
payments/
- AGENTS.md Wird ignoriert, weil eine Override-Datei vorhanden ist
- AGENTS.override.md Regeln für den Zahlungsdienst
- README.md
-
-
search/
- AGENTS.md
- …
-
-
Regeln für Code Reviews hinzufügen
Für Code Reviews mit Codex auf GitHub fügst du einen Abschnitt ## Code Review Rules in die AGENTS.md ein, die dem betreffenden Code am nächsten liegt. Lege Prüfregeln für das gesamte Repository im Stammverzeichnis ab und Regeln für einzelne Dienste in einer Datei im jeweiligen Unterverzeichnis.
## 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.
Halte die Regeln kurz. Beschreibe, welches Verhalten Codex melden soll, wie sich das Problem vermeiden lässt und welche Ausnahmen gelten. Überlasse Formatierungs- und Lint-Prüfungen der CI. Hinweise zum Setup und zum Formulieren von Regeln findest du im Abschnitt Festlegen, was Codex überprüft.
Alternative Dateinamen konfigurieren
Wenn dein Repository bereits einen anderen Dateinamen verwendet (zum Beispiel TEAM_GUIDE.md), füge ihn zur Liste der alternativen Dateinamen hinzu. So erkennt Codex die Datei als Anweisungsdatei.
-
Bearbeite deine Codex-Konfiguration:
# ~/.codex/config.toml project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] project_doc_max_bytes = 65536 -
Starte Codex neu oder führe einen neuen Befehl aus, damit Codex die aktualisierte Konfiguration lädt.
Codex prüft die Dateinamen jetzt in jedem Verzeichnis in dieser Reihenfolge: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Dateien mit anderen Namen berücksichtigt Codex bei der Suche nach Anweisungen nicht. Mit dem höheren Byte-Limit kann Codex mehr Anweisungen zusammenführen, bevor es den Inhalt kürzt.
Mit dieser Liste erkennt Codex auch Dateien mit alternativen Namen als Anweisungsdateien:
- TEAM_GUIDE.md Über die Liste der alternativen Dateinamen erkannt
- .agents.md Alternative Anweisungsdatei im Stammverzeichnis
-
support/
- AGENTS.override.md Überschreibt die Vorgaben aus der alternativen Anweisungsdatei
-
playbooks/
- …
-
-
Setze die Umgebungsvariable CODEX_HOME, wenn du ein anderes Profil verwenden möchtest, etwa für ein projektspezifisches Automatisierungskonto:
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"
Erwartetes Ergebnis: Die Ausgabe listet die Dateipfade relativ zum eigens festgelegten .codex-Verzeichnis auf.
Setup überprüfen
- Führe
codex --ask-for-approval never "Summarize the current instructions."im Stammverzeichnis eines Repositorys aus. Codex sollte die Anweisungen aus den globalen und projektspezifischen Dateien in der Reihenfolge wiedergeben, in der es sie zusammenführt. - Prüfe mit
codex --cd subdir --ask-for-approval never "Show which instruction files are active.", ob die Override-Dateien in Unterverzeichnissen die allgemeineren Regeln überschreiben. - Um nachzuvollziehen, welche Anweisungsdateien Codex geladen hat, aktiviere mit
codex -c log_dir=./.codex-logdas TUI-Protokoll im Klartext und prüfe./.codex-log/codex-tui.log. Wenn du die Sitzungsprotokollierung aktiviert hast, kannst du auch die neuestesession-*.jsonl-Datei prüfen. - Wenn die Anweisungen veraltet wirken, starte Codex im Zielverzeichnis neu. Codex stellt die Anweisungen bei jedem Start und zu Beginn jeder TUI-Sitzung neu zusammen. Du musst keinen Cache leeren.
Probleme bei der Suche nach Anweisungen beheben
- Codex lädt keine Anweisungen: Prüfe, ob du dich im richtigen Repository befindest und ob
codex statusdas erwartete Stammverzeichnis deines Workspaces anzeigt. Stelle sicher, dass deine Anweisungsdateien Inhalt haben. Leere Dateien ignoriert Codex. - Codex zeigt die falschen Anweisungen an: Suche in übergeordneten Verzeichnissen oder in deinem Codex-Home-Verzeichnis nach einer
AGENTS.override.md. Benenne die Override-Datei um oder entferne sie, damit Codex wieder die reguläre Datei verwendet. - Codex ignoriert alternative Dateinamen: Prüfe, ob alle gewünschten Dateinamen richtig in
project_doc_fallback_filenamesstehen. Starte Codex anschließend neu, damit die aktualisierte Konfiguration wirksam wird. - Codex kürzt die Anweisungen: Erhöhe
project_doc_max_bytesoder verteile den Inhalt großer Dateien auf Unterverzeichnisse, damit wichtige Anweisungen vollständig erhalten bleiben. - Codex verwendet das falsche Profil: Führe
echo $CODEX_HOMEaus, bevor du Codex startest. Ein vom Standard abweichender Wert verweist Codex auf ein anderes Home-Verzeichnis als das, in dem du die Datei bearbeitet hast.
Nächste Schritte
- Weitere Informationen findest du auf der offiziellen Website von AGENTS.md.
- Im Leitfaden Prompts für Codex formulieren findest du Beispiele dafür, wie du Gespräche mit Codex auf deinen dauerhaften Vorgaben aufbauen kannst.