Codex AGENTS.md: wohin damit, in welcher Reihenfolge sie lädt und was hineingehört

Wo Codex nach AGENTS.md sucht, in Ladereihenfolge

Codex baut die Anweisungskette einmal beim Start auf (in der Terminal-Oberfläche einmal pro Session). Die Dateien werden von oben nach unten in dieser Tabelle zusammengefügt, sodass Anweisungen näher an deinem Arbeitsverzeichnis später kommen und gewinnen.

So richtest du AGENTS.md für Codex ein

1. Leg globale Standards an

   Führe mkdir -p ~/.codex aus und schreibe in ~/.codex/AGENTS.md die Vorlieben, die in jedem Repository gelten sollen. Ob sie geladen wurde, prüfst du, indem du Codex bittest, seine Anweisungen zusammenzufassen.

   # ~/.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.

2. Füge eine Projektdatei hinzu und Overrides, wo Teams abweichen

   Leg eine AGENTS.md in den Repository-Root für das gemeinsame Setup. In einem Ordner mit anderen Regeln fügst du AGENTS.override.md hinzu: Sie ersetzt die AGENTS.md dieses Ordners, die Codex dann ignoriert.

   # AGENTS.md (repository root)
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.
   
   # 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. Prüfe, was geladen wurde

   Starte Codex in dem Ordner, um den es geht, zum Beispiel mit codex --cd services/payments, und bitte es, die geladenen Anweisungsquellen aufzulisten. Es sollte die globale Datei nennen, dann die Root-Datei, dann die Datei des Ordners.

4. Nutze einen vorhandenen Dateinamen oder heb das Limit an

   Wenn dein Repository Anweisungen schon in einer anderen Datei hält, trag sie in project_doc_fallback_filenames in ~/.codex/config.toml ein. Codex fügt keine weiteren Dateien hinzu, sobald die Gesamtgröße project_doc_max_bytes erreicht, standardmäßig 32 KiB.

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536

5. Füge Regeln für das Code Review von Codex hinzu

   Für @codex review auf GitHub fügst du der AGENTS.md, die dem betreffenden Code am nächsten liegt, einen Abschnitt ## Code Review Rules hinzu. Schreib, was markiert werden soll und was die sichere Alternative ist; Formatierung und Lint überlässt du der CI.

   ## Code Review Rules
   
   ### Experiment cohorts
   
   - Do not filter treatment comparisons on post-exposure behavior.
     Safe path: build cohorts from assignment or exposure.

Quelle: Codex-Dokumentation, Custom instructions with AGENTS.md

Best Practices für AGENTS.md

• Beschränke dich auf das, was Codex nicht selbst herausfindet: exakte Build-, Test- und Lint-Befehle (auch, wie man einen einzelnen Test ausführt), Stolperfallen im Code und Entscheidungen, die nirgends aufgeschrieben sind.
• Leg die spezifischsten Regeln nah an den Code: Eine verschachtelte AGENTS.md in services/payments/ ist besser als eine lange Root-Datei mit einem Payments-Abschnitt.
• Behalte das 32-KiB-Budget im Blick: Dateien werden vom Root abwärts hinzugefügt und der Rest abgeschnitten, also teile lange Dateien in verschachtelte auf oder heb project_doc_max_bytes an.
• Nutze AGENTS.override.md für vorübergehende Änderungen, global oder in einem Ordner, und lösche sie, um zurückzukehren.
• Eine leere AGENTS.md wird übersprungen, und die Suche in diesem Verzeichnis geht zum nächsten Dateinamen weiter.
• Nutze für Automatisierungs-Benutzer ein eigenes CODEX_HOME, damit sich ihre globalen Anweisungen nicht mit deinen vermischen.

AGENTS.md in Codex vs Claude Code und andere

AGENTS.md ist ein offenes Format, das viele Agenten lesen, und damit der beste Ort für Anweisungen, die du teilen willst. Claude Code hat eine eigene Datei, CLAUDE.md; Details findest du in der CLAUDE.md-Anleitung.

AGENTS.md sagt Codex, wie. Crewmark sagt, was als Nächstes kommt.

Eine gute AGENTS.md lässt jede Codex-Session informiert starten, aber die Session wartet trotzdem auf deinen Prompt. Crewmark macht aus einer Session von Codex, Claude Code, DeepSeek Harness oder OpenCode einen KI-Mitarbeiter mit Rolle, Ziel und Arbeitszeiten und weckt ihn per Heartbeat, damit er das nächste Issue von einem Board übernimmt.

1. Lass AGENTS.md im Repository

   Die Codex-Session des Mitarbeiters liest sie genau wie deine, also kommen Konventionen und Testbefehle mit.

2. Lass den Heartbeat die Arbeit starten

   Während seiner Arbeitszeiten wacht der Mitarbeiter alle 15, 30 oder 60 Minuten in derselben Konversation auf; siehe Codex proaktiv machen.

3. Misch Agenten auf einem Board

   Eine AGENTS.md kann Codex- und Claude-Code-Mitarbeiter nebeneinander bedienen; vergleiche beide in Claude Code vs Codex.

FAQ zu Codex AGENTS.md