Die Idee

Du bittest ein Coding-Tool, einen fehlschlagenden Test zu reparieren. Es kennt vielleicht die Aufgabe, aber nicht, wo dieses Projekt produktiven Code ablegt, welcher Check passt oder welche Dateien nicht geändert werden dürfen. Diese Details in jedem Prompt zu wiederholen, ist mühsam und fehleranfällig.

Eine Datei namens AGENTS.md ist eine Markdown-Datei im Projekt. Sie gibt einem Coding-Agenten lokale Arbeitshinweise. Im dokumentierten Codex-Workflow kann sie Navigationshinweise, Coding-Konventionen und Befehle zum Ausführen oder Testen von Code enthalten. OpenAI beschreibt AGENTS.md als projektnahe Anweisungsdatei für solche Details.

Stell sie dir als schriftliche Arbeitsvereinbarung mit einem Agenten vor, nicht als Spezifikation dafür, was die Software leisten muss. Sie kann wiederkehrendes Projektwissen an einer sichtbaren, versionierbaren Stelle verfügbar machen. Dein Prompt beschreibt weiterhin das Ziel der aktuellen Aufgabe.

Einfach gesagt: AGENTS.md ist eine kurze Datei, die einem Coding-Agenten sagt: „So ist dieses Projekt organisiert und so wird es geprüft.“ Sie ersetzt nicht die Erklärung, was der Agent ändern soll.

Für Codex gilt eine AGENTS.md für den Verzeichnisbaum unterhalb ihres Speicherorts. Codex sucht solche Dateien vom erkannten Projektstamm bis zum aktuellen Arbeitsverzeichnis und führt die Anweisungen in dieser Reihenfolge zusammen. Eine Datei in einem tieferen Ordner kann spezifischere Hinweise für diesen Ordner geben. Dieses Such- und Zusammenführungsverhalten ist im offiziellen Codex-Repository dokumentiert.

Dabei gibt es eine wichtige Reihenfolge. Spezifischere AGENTS.md-Hinweise aus tieferen Ordnern gewinnen, wenn AGENTS.md-Dateien einander widersprechen. Direkte System-, Entwickler- und Nutzeranweisungen haben jedoch eine höhere Anweisungspriorität als AGENTS.md. Der offizielle Codex-Prompt dokumentiert beide Teile dieser Reihenfolge. Die Projektdatei ist also dauerhafte Orientierung, keine unumstößliche Richtlinie.

Ein kleines Beispiel

Beispiel — hypothetisches Repository-Layout. Ein Team hat ein Repository mit src/ für produktiven Code und docs/ für generierte Dokumentation. Im Root des Repositorys legt es diese kleine Datei an:

# Projekt-Hinweise

- Lege produktiven Code in `src/` ab.
- Führe nach Änderungen am Anwendungscode `npm test` aus.
- Bearbeite keine generierten Dateien in `docs/`.

Das ist keine offizielle Pflichtvorlage. Es veranschaulicht die dokumentierten Arten von Inhalten: Code-Organisation, Konventionen und Befehle zum Ausführen oder Testen. Die Codex-Dokumentation nennt solche Informationen als passende Inhalte für AGENTS.md.

Angenommen, src/payments/ hat ein ungewöhnliches Test-Setup. Dieser Ordner könnte eine weitere AGENTS.md mit einer engen Anweisung enthalten, etwa mit dem passenden Zahlungs-Testbefehl. In Codex kann diese tiefere Datei eine widersprüchliche Root-Regel für ihren eigenen Teilbaum überstimmen. Halte die Root-Datei bei repositoryweiten Fakten; schreibe Ausnahmen nah an den Code, den sie betreffen.

Probier es aus

Nimm dir fünf Minuten und erstelle einen Entwurf für AGENTS.md in einem Repository. Versuche nicht, alles zu dokumentieren.

  1. Notiere eine überprüfte Strukturinformation, etwa den Ort des Anwendungscodes.
  2. Ergänze einen Befehl, den du wirklich zum Testen oder Prüfen des betroffenen Bereichs verwendest.
  3. Ergänze eine Grenze, etwa ein generiertes Verzeichnis, das nicht bearbeitet werden soll.
  4. Lies jede Zeile und entferne alles, was vage, veraltet oder nur für seltene Aufgaben relevant ist.

Nutze dazu einen konkreten Prompt: „Repariere den fehlschlagenden Validierungstest in src/ und nenne den ausgeführten Test.“ So verbindest du dauerhaften lokalen Kontext mit einer klaren unmittelbaren Aufgabe. Du kannst auch einfach prüfen, ob die Datei hilft: Untersuche die Änderungen und führe die genannten Checks selbst aus.

Darauf solltest du achten

Behandle AGENTS.md nicht als Beweis dafür, dass erzeugter Code korrekt oder sicher ist. OpenAI empfiehlt menschliche Validierung von generiertem Code. Prüfe den Diff, die Testausgabe und mögliche Nebenwirkungen. Die Codex-Einführung von OpenAI betont diese Notwendigkeit ausdrücklich.

Mache aus der Datei kein langes Handbuch. OpenAI empfiehlt, AGENTS.md regelmäßig zu prüfen und veraltete oder unnötige Hinweise zu entfernen. Sie wird bei der Arbeit im Repository berücksichtigt, und überlange Anweisungen verbrauchen Kontext. OpenAI Developers erläutert diesen Wartungsaspekt.

Diese Lektion beschreibt außerdem dokumentiertes Codex-Verhalten, keinen allgemeinen Standard für alle KI-Coding-Tools. Prüfe die Dokumentation jedes Tools, bevor du annimmst, dass es AGENTS.md liest oder dieselbe Hierarchie verwendet.