ChatGPT-Dokumentation
Deutsch
Kontakt goolvyouyou@gmail.com

Benutzerdefinierte Anweisungen mit AGENTS.md

Geben Sie Codex zusätzliche Anweisungen und Kontext für Ihr Projekt

Codex liest AGENTS.md-Dateien, bevor es mit der Arbeit beginnt. Indem Sie globale Richtlinien mit projektspezifischen Überschreibungen kombinieren, können Sie jede Aufgabe mit einheitlichen Erwartungen beginnen – unabhängig davon, welches Repository Sie öffnen.

So findet Codex Richtlinien

Codex erstellt beim Start eine Anweisungskette (einmal pro Ausführung; in der TUI bedeutet dies normalerweise einmal pro gestarteter Sitzung). Die Ermittlung erfolgt in dieser Rangfolge:

  1. Globaler Geltungsbereich: In Ihrem Codex-Stammverzeichnis (standardmäßig ~/.codex, sofern Sie nicht CODEX_HOME festlegen) liest Codex AGENTS.override.md, falls die Datei vorhanden ist. Andernfalls liest Codex AGENTS.md. Codex verwendet auf dieser Ebene nur die erste nicht leere Datei.
  2. Projekt-Geltungsbereich: Ausgehend vom Projektstamm (in der Regel dem Git-Stammverzeichnis) durchläuft Codex den Verzeichnispfad bis zu Ihrem aktuellen Arbeitsverzeichnis. Wenn Codex keinen Projektstamm findet, prüft es nur das aktuelle Verzeichnis. In jedem Verzeichnis entlang dieses Pfads sucht es zuerst nach AGENTS.override.md, dann nach AGENTS.md und anschließend nach allen in project_doc_fallback_filenames angegebenen Ausweichnamen. Codex berücksichtigt höchstens eine Datei pro Verzeichnis.
  3. Zusammenführungsreihenfolge: Codex verkettet die Dateien vom Stammverzeichnis abwärts und trennt sie durch Leerzeilen. Dateien, die näher an Ihrem aktuellen Verzeichnis liegen, überschreiben frühere Richtlinien, da sie später in der kombinierten Eingabeaufforderung erscheinen.

Codex überspringt leere Dateien und fügt keine weiteren Dateien mehr hinzu, sobald die kombinierte Größe den durch project_doc_max_bytes festgelegten Grenzwert erreicht (standardmäßig 32 KiB). Einzelheiten zu diesen Einstellungen finden Sie unter Ermittlung von Projektanweisungen. Erhöhen Sie den Grenzwert oder verteilen Sie die Anweisungen auf verschachtelte Verzeichnisse, wenn Sie die Obergrenze erreichen.

Globale Richtlinien erstellen

Erstellen Sie dauerhafte Standardeinstellungen in Ihrem Codex-Stammverzeichnis, damit jedes Repository Ihre Arbeitsvereinbarungen übernimmt.

  1. Stellen Sie sicher, dass das Verzeichnis vorhanden ist:

    mkdir -p ~/.codex

  2. Erstellen Sie ~/.codex/AGENTS.md mit wiederverwendbaren Einstellungen:

    # ~/.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. Führen Sie Codex an einem beliebigen Ort aus, um zu bestätigen, dass die Datei geladen wird:

    codex --ask-for-approval never "Summarize the current instructions."

    Erwartetes Ergebnis: Codex zitiert die Einträge aus ~/.codex/AGENTS.md, bevor es Arbeitsschritte vorschlägt.

Verwenden Sie ~/.codex/AGENTS.override.md, wenn Sie eine vorübergehende globale Überschreibung benötigen, ohne die Basisdatei zu löschen. Entfernen Sie die Überschreibung, um die gemeinsam genutzten Richtlinien wiederherzustellen.

Projektanweisungen schichten

Dateien auf Repository-Ebene informieren Codex über die Konventionen des Projekts, während Ihre globalen Standardeinstellungen weiterhin übernommen werden.

  1. Fügen Sie im Stammverzeichnis Ihres Repositorys eine AGENTS.md-Datei hinzu, die die grundlegende Einrichtung beschreibt:

    # AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

  2. Fügen Sie Überschreibungen in verschachtelten Verzeichnissen hinzu, wenn bestimmte Teams andere Regeln benötigen. Erstellen Sie beispielsweise innerhalb von 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. Starten Sie Codex aus dem Zahlungsverkehrsverzeichnis:

    codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

    Erwartetes Ergebnis: Codex führt zuerst die globale Datei, anschließend die AGENTS.md-Datei im Repository-Stammverzeichnis und zuletzt die Überschreibung für den Zahlungsverkehr auf.

Codex beendet die Suche, sobald es Ihr aktuelles Verzeichnis erreicht. Platzieren Sie Überschreibungen daher möglichst nah an den spezialisierten Arbeitsbereichen.

So könnte ein Repository aussehen, nachdem Sie eine globale Datei und eine zahlungsverkehrsspezifische Überschreibung hinzugefügt haben:

<FileTree class="mt-4" tree={[ { name: "AGENTS.md", comment: "Repository-Anforderungen", highlight: true, }, { name: "services/", open: true, children: [ { name: "payments/", open: true, children: [ { name: "AGENTS.md", comment: "Ignoriert, da eine Überschreibung vorhanden ist", }, { name: "AGENTS.override.md", comment: "Regeln für den Zahlungsverkehrsdienst", highlight: true, }, { name: "README.md" }, ], }, { name: "search/", children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }], }, ], }, ]} />

Regeln für Code-Reviews hinzufügen

Fügen Sie für Codex-Code-Reviews in GitHub einen Abschnitt ## Code Review Rules zu der AGENTS.md-Datei hinzu, die dem Code, für den die Regeln gelten, am nächsten liegt. Platzieren Sie Repository-weite Prüfungen im Stammverzeichnis und dienstspezifische Prüfungen in einer verschachtelten Datei.

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

Halten Sie Regeln knapp, erläutern Sie das zu kennzeichnende Verhalten sowie alle sicheren Vorgehensweisen oder Ausnahmen und überlassen Sie Formatierungs- und Lint-Prüfungen der CI. Unter Anpassen, was Codex überprüft finden Sie Hinweise zur Einrichtung und zum Verfassen von Regeln.

Ausweichdateinamen anpassen

Wenn Ihr Repository bereits einen anderen Dateinamen verwendet (beispielsweise TEAM_GUIDE.md), fügen Sie ihn der Ausweichliste hinzu, damit Codex ihn wie eine Anweisungsdatei behandelt.

  1. Bearbeiten Sie Ihre Codex-Konfiguration:

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

  2. Starten Sie Codex neu oder führen Sie einen neuen Befehl aus, damit die aktualisierte Konfiguration geladen wird.

Codex prüft nun jedes Verzeichnis in dieser Reihenfolge: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Dateinamen, die nicht in dieser Liste enthalten sind, werden bei der Ermittlung von Anweisungen ignoriert. Der höhere Byte-Grenzwert ermöglicht mehr kombinierte Richtlinien, bevor Inhalte abgeschnitten werden.

Mit der eingerichteten Ausweichliste behandelt Codex die alternativen Dateien als Anweisungen:

<FileTree class="mt-4" tree={[ { name: "TEAM_GUIDE.md", comment: "Über die Ausweichliste erkannt", highlight: true, }, { name: ".agents.md", comment: "Ausweichdatei im Stammverzeichnis", }, { name: "support/", open: true, children: [ { name: "AGENTS.override.md", comment: "Überschreibt die Ausweichrichtlinien", highlight: true, }, { name: "playbooks/", children: [{ name: "…", placeholder: true }], }, ], }, ]} />

Legen Sie die Umgebungsvariable CODEX_HOME fest, wenn Sie ein anderes Profil verwenden möchten, beispielsweise einen projektspezifischen Automatisierungsbenutzer:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

Erwartetes Ergebnis: Die Ausgabe listet Dateien relativ zum benutzerdefinierten .codex-Verzeichnis auf.

Einrichtung überprüfen

  • Führen Sie codex --ask-for-approval never "Summarize the current instructions." im Stammverzeichnis eines Repositorys aus. Codex sollte die Richtlinien aus globalen und projektspezifischen Dateien in ihrer Rangfolge wiedergeben.
  • Verwenden Sie codex --cd subdir --ask-for-approval never "Show which instruction files are active.", um zu bestätigen, dass verschachtelte Überschreibungen allgemeinere Regeln ersetzen.
  • Um zu prüfen, welche Anweisungsdateien Codex geladen hat, aktivieren Sie mit codex -c log_dir=./.codex-log ein TUI-Klartextprotokoll und prüfen Sie ./.codex-log/codex-tui.log. Alternativ können Sie die neueste session-*.jsonl-Datei untersuchen, sofern Sie die Sitzungsprotokollierung aktiviert haben.
  • Wenn Anweisungen veraltet erscheinen, starten Sie Codex im Zielverzeichnis neu. Codex erstellt die Anweisungskette bei jeder Ausführung (und zu Beginn jeder TUI-Sitzung) neu, sodass kein Cache manuell geleert werden muss.

Probleme bei der Ermittlung beheben

  • Es wird nichts geladen: Vergewissern Sie sich, dass Sie sich im vorgesehenen Repository befinden und dass codex status das erwartete Arbeitsbereichsstammverzeichnis meldet. Stellen Sie sicher, dass die Anweisungsdateien Inhalt enthalten; Codex ignoriert leere Dateien.
  • Falsche Richtlinien werden angezeigt: Suchen Sie weiter oben im Verzeichnisbaum oder in Ihrem Codex-Stammverzeichnis nach einer AGENTS.override.md-Datei. Benennen Sie die Überschreibung um oder entfernen Sie sie, um wieder die reguläre Datei zu verwenden.
  • Codex ignoriert Ausweichnamen: Vergewissern Sie sich, dass Sie die Namen ohne Tippfehler in project_doc_fallback_filenames aufgeführt haben, und starten Sie Codex anschließend neu, damit die aktualisierte Konfiguration wirksam wird.
  • Anweisungen werden abgeschnitten: Erhöhen Sie project_doc_max_bytes oder verteilen Sie große Dateien auf verschachtelte Verzeichnisse, damit wichtige Richtlinien vollständig erhalten bleiben.
  • Unklarheit beim Profil: Führen Sie vor dem Start von Codex echo $CODEX_HOME aus. Ein vom Standard abweichender Wert verweist Codex auf ein anderes Stammverzeichnis als das von Ihnen bearbeitete.

Nächste Schritte