Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Eigene Anweisungen mit AGENTS.md

Gib Codex zusätzliche Anweisungen und Kontext für dein Projekt

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:

  1. Globale Anweisungen: In deinem Codex-Home-Verzeichnis (standardmäßig ~/.codex, sofern du CODEX_HOME nicht gesetzt hast) liest Codex AGENTS.override.md, falls die Datei vorhanden ist. Andernfalls liest Codex AGENTS.md. Auf dieser Ebene verwendet Codex nur die erste Datei, die nicht leer ist.
  2. 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 nach AGENTS.md und schließlich nach den alternativen Dateinamen aus project_doc_fallback_filenames. Pro Verzeichnis berücksichtigt Codex höchstens eine Datei.
  3. 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.

  1. Stelle sicher, dass das Verzeichnis existiert:

    mkdir -p ~/.codex
  2. Erstelle ~/.codex/AGENTS.md mit 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.
  3. 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.

  1. Lege im Stammverzeichnis deines Repositorys eine AGENTS.md mit 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.
  2. Wenn einzelne Teams andere Regeln benötigen, lege Override-Dateien in den jeweiligen Unterverzeichnissen an. Erstelle beispielsweise in services/payments/ die Datei 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. 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.md im 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.

  1. Bearbeite deine Codex-Konfiguration:

    # ~/.codex/config.toml
    project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
    project_doc_max_bytes = 65536
  2. 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-log das TUI-Protokoll im Klartext und prüfe ./.codex-log/codex-tui.log. Wenn du die Sitzungsprotokollierung aktiviert hast, kannst du auch die neueste session-*.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 status das 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_filenames stehen. Starte Codex anschließend neu, damit die aktualisierte Konfiguration wirksam wird.
  • Codex kürzt die Anweisungen: Erhöhe project_doc_max_bytes oder verteile den Inhalt großer Dateien auf Unterverzeichnisse, damit wichtige Anweisungen vollständig erhalten bleiben.
  • Codex verwendet das falsche Profil: Führe echo $CODEX_HOME aus, 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.