AGENTS.md schreiben: Projektregeln und Team-Workflows für Codex

Codex sagt „fertig“, Sie führen pnpm test aus, und erst dann fällt auf: Die Tests liefen gar nicht. Oder Codex steht im Root eines monorepos und startet die Tests für das falsche package. Solche Wiederholungen kosten Zeit: npm run build, pnpm test, generated-Verzeichnisse nicht anfassen, vor dem Abschluss lint ausführen. AGENTS.md ist der Ort, an dem Sie diese Regeln festhalten, damit Codex sie beim nächsten Mal nicht wieder erfragen muss.

Wenn Sie gerade den Codex-Einstieg und die Wahl des passenden Einstiegspunkts abgeschlossen haben, ist der nächste Schritt nicht die große Refactoring-Aufgabe. Schreiben Sie zuerst die Projektregeln auf, die Sie sonst jedes Mal wiederholen.

Wir starten mit einer 12- bis 20-zeiligen Seed-Vorlage. Danach geht es um die drei Lade-Layer, die Prüfung, ob Codex die Datei wirklich gelesen hat, Dinge, die nicht hineingehören, die Koexistenz mit CLAUDE.md oder Cursor Rules und den richtigen Zeitpunkt für Updates.

AGENTS.md ist keine README, sondern Codex’ dauerhafte Arbeitsanweisung

README.md ist für menschliche Leser. Sie erklärt, was das Projekt ist, wie man es installiert und wie man loslegt. AGENTS.md ist für Codex. Dort steht, was bei jedem Start relevant ist: wie gebaut wird, wie getestet wird, welche Verzeichnisse tabu sind und welche Checks vor „fertig“ zählen.

Laut OpenAI-Dokumentation liest Codex AGENTS.md vor Arbeitsbeginn und nimmt die Datei in den aktiven Kontext auf. Das ist etwas anderes, als in jedem Chat erneut „npm run build“ oder „pnpm test“ zu schreiben. AGENTS.md ist persistente Projektanweisung, nicht eine einmalige Chat-Nachricht.

Eine Grenze ist wichtig: AGENTS.md ist kein Langzeitgedächtnis und keine automatisch lernende Wissensdatenbank. Es ist eine statische Anweisung, die beim Start geladen wird. Wenn Sie Wissen über Sitzungen hinweg sammeln oder Gedächtnis steuern wollen, erklärt der frühere Leitfaden zu AI-Agent-Gedächtnis die Trennung zwischen Langzeitgedächtnis und Projektregeln.

Wie Codex AGENTS.md findet: die drei Lade-Layer

Codex’ Lade-Reihenfolge lässt sich in drei Ebenen denken: global, projektbezogen und zusammengeführt. Wenn Sie diese Kette kennen, können Sie beurteilen, wo eine Regel greift und warum sie manchmal scheinbar nicht greift.

Globale Ebene: Ihre persönlichen Standards

Codex sucht zuerst in Ihrem Benutzerverzeichnis ~/.codex. Diese Ebene ist für persönliche Gewohnheiten gedacht, etwa Antwortsprache, Code-Stil oder bevorzugte Tools. Wichtig: Auf globaler Ebene wird höchstens eine Datei gelesen, in der Reihenfolge AGENTS.override.md -> AGENTS.md. Beide werden nicht addiert.

Projektebene: von der Git-Wurzel bis zum aktuellen Verzeichnis

Für Projektanweisungen scannt Codex von der Git- oder Projektwurzel bis zum aktuellen Arbeitsverzeichnis. Auf jeder Ebene wird ebenfalls höchstens eine Datei gelesen: AGENTS.override.md -> AGENTS.md -> fallback filenames. Fallback-Namen lassen sich über project_doc_fallback_filenames konfigurieren, etwa um TEAM_GUIDE.md einzubeziehen. Die exakten Optionsnamen sollten Sie als dokumentationsabhängig behandeln.

Zusammenführung: nähere Verzeichnisse erscheinen später und sind spezifischer

Alle gefundenen Dateien werden von der Wurzel bis zum aktuellen Verzeichnis zusammengefügt. Je näher eine Datei am aktuellen Verzeichnis liegt, desto später steht sie im Kontext. Dadurch kann Codex diese spezifischere Anweisung leichter priorisieren.

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

Ein Beispiel: Im Root eines monorepos steht in AGENTS.md „Tests mit pnpm test ausführen“. In apps/web/AGENTS.md steht „Tests mit pnpm --filter web test ausführen“. Startet Codex in apps/web, lautet die Kette: Root-Regeln -> apps/web-Regeln. Das test-Kommando aus apps/web ist die spezifischere Anweisung.

Zusammenfassung der drei Ebenen

Im Root sollten gemeinsame Team-Regeln stehen. Unterverzeichnisse bekommen lokale Regeln, etwa ein anderes Testkommando für ein bestimmtes package. AGENTS.override.md eignet sich für temporäre oder lokale Overrides. Machen Sie daraus nicht den Team-Standard, sonst liegen die echten Regeln versteckt in einer override-Datei.

Die kleinste nützliche Vorlage: welche 6 Blöcke gehören hinein?

OpenAI beschreibt AGENTS.md als „open-format README for agents“. Praktisch heißt das: kurz, wahr und prüfbar. Kopieren Sie keine 300-zeilige Internetvorlage. Beginnen Sie mit sechs Grundblöcken und erweitern Sie nur, wenn das Projekt es wirklich verlangt.

Die Seed-Datei enthält diese 6 Blöcke:

1. repo layout: Stack und Verzeichnisplan, damit Codex Frontend, Backend und Tests findet
2. Commands: konkrete build-, test- und lint-Kommandos. Schreiben Sie pnpm test, nicht „Tests ausführen“
3. Constraints: Verzeichnisse und Aktionen, die Codex vermeiden soll, etwa src/generated/
4. PR expectations: Was vor dem Einreichen geprüft werden soll und was review erwartet
5. Done when: prüfbare Abschlusskriterien, etwa pnpm test und pnpm build
6. Optionale Projektkonventionen, etwa Paketmanager, Code-Stil oder Namensregeln

Für ein SaaS-Adminprojekt reicht als Start etwa:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Database: PostgreSQL
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review

## PR expectations
- Add tests for new features
- Run `pnpm test` before marking done

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Diese Vorlage ist kurz genug, um im Kontext sichtbar zu bleiben. Ergänzen Sie erst dann weitere Regeln, wenn ein wiederholtes Problem auftaucht. Projektvision, Abhängigkeitslisten, Architekturdiagramme oder API-Dokumentationsindizes gehören nicht in die erste Version. Sonst begraben sie die Regeln, die Codex wirklich braucht.

Prüfen, ob Codex AGENTS.md wirklich gelesen hat

Nach dem Schreiben der Datei sollten Sie die Wirkung prüfen. Die OpenAI-Dokumentation empfiehlt:

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

Die Antwort sollte Ihre Regeln erwähnen, etwa Testkommando oder verbotene Verzeichnisse. Wenn nichts davon auftaucht oder andere Regeln erscheinen, prüfen Sie die Lade-Kette.

Troubleshooting-Checkliste

Wenn es danach immer noch nicht funktioniert, prüfen Sie die OpenAI-Custom-instructions-Dokumentation oder aktualisieren Sie Codex. Behandeln Sie AGENTS.md-Loading nicht als Magie. Pfad, Version, Konfiguration und aktuelles Verzeichnis beeinflussen das Ergebnis.

Was nicht in AGENTS.md gehört

AGENTS.md ist kein universelles Projektlager. Manche Inhalte erzeugen Security-Risiken, Wartungsaufwand oder Kontextlärm. Diese Dinge sollten draußen bleiben.

1. Secrets, API keys und Produktionspasswörter

Secrets, Produktionspasswörter und API tokens gehören nicht in AGENTS.md. Codex liest die Datei in den Kontext, und sie kann für Teammitglieder sichtbar oder in Git commitet werden. Nutzen Sie Umgebungsvariablen, nicht commitete .env-Dateien oder ein dediziertes Secrets-System. Wenn Codex in einer sandbox Zugriff auf secrets braucht, ist das eine Frage der Ausführungsebene.

2. Große Listen, die schnell veralten

Listen aller dependencies, Ökosystemzahlen, Preise, quotas, routes oder Datenbankfelder veralten schnell. Eine Liste wie „React 18.2, Vue 3.4, TypeScript 5.0 …“ ist nach wenigen Monaten falsch. Beschreiben Sie lieber den Prozess zum Hinzufügen einer dependency als den aktuellen Bestand.

3. Abstrakte Slogans

„Hohe Qualität“, „eleganter Code“ oder „wartbar bleiben“ sind nicht ausführbar. Übersetzen Sie solche Wünsche in Checks: pnpm test besteht, pnpm lint ist fehlerfrei, neue Features haben Tests oder ein Lighthouse-Performancewert darf nicht unter die vereinbarte Grenze fallen.

4. Vage Kommandos

„Tests ausführen“ oder „Build prüfen“ ist zu ungenau. Schreiben Sie konkrete Kommandos: pnpm test, pnpm build oder lighthouse --preset=desktop.

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

5. Nicht prüfbare Anforderungen

„Performance garantieren“ oder „UX verbessern“ hat keine klare Abschlussgrenze. Nutzen Sie messbare Kriterien, etwa API-Antwort unter 200 ms oder ein Lighthouse-Ziel.

6. Persönliche Vorlieben im Repo-Root

„Auf Deutsch antworten“, „Antworten unter 100 Wörtern halten“ oder „VS Code voraussetzen“ sind persönliche Tool-Gewohnheiten, keine Team-Regeln. Legen Sie sie in ~/.codex/AGENTS.md ab. Der Repository-Root sollte Team-Standards enthalten.

Die Faustregel lautet: kurz, wahr, prüfbar. AGENTS.md reduziert wiederholte Erklärungen. Es ist kein Ort, um alle Projektunterlagen einzufügen.

Wenn CLAUDE.md oder Cursor Rules schon existieren

Wenn Sie Claude Code oder Cursor nutzen, gibt es im Repository vielleicht schon CLAUDE.md oder Cursor Rules. Sie müssen keine drei doppelten Regelwerke pflegen. Import und Koexistenz reichen.

AGENTS.md vs. CLAUDE.md: gemeinsame Regeln importieren

Claude Code liest CLAUDE.md, nicht AGENTS.md. Wenn das repo bereits AGENTS.md hat, können Sie eine kleine CLAUDE.md anlegen, die sie importiert:

@AGENTS.md

## Claude-specific
- Prefer Chinese responses
- Keep responses concise (under 100 words unless requested)

@AGENTS.md ist die Import-Syntax. Claude Code liest zuerst AGENTS.md und danach den Claude-spezifischen Abschnitt. So bleiben gemeinsame Projektregeln in AGENTS.md, während tool-spezifische Präferenzen in CLAUDE.md liegen.

AGENTS.md vs. Cursor Rules: Cursor hat ein eigenes Regelwerk

Cursor hat ein eigenes Rules-System mit project-, team- und user-Regeln. Offizielle Cursor-Dokumentation und Suchzusammenfassungen erwähnen AGENTS.md-Support, aber die genaue Lade-Logik sollten Sie in der aktuellen Cursor-Dokumentation prüfen. Wenn Sie Cursor und Codex parallel nutzen, legen Sie tool-übergreifende Projektregeln in AGENTS.md ab und lassen Cursor-spezifisches Editor-Verhalten in Cursor Rules.

AGENTS.md vs. config.toml, Rules, Skills und MCP

AGENTS.md ist die Anweisungsebene. Sie sagt Codex, wie gearbeitet werden soll. Ausführungssteuerung lebt woanders: Berechtigungen, sandbox, Kommando-Policy und Tool-Integrationen sind separate Mechanismen.

AGENTS.md löst wiederholte Projektregel-Erklärungen. Rules, config, sandbox und permissions steuern Ausführung. Skills kapseln wiederverwendbare Workflows. MCP verbindet externe Tools. Diese Grenzen sollten klar bleiben.

Wann Sie AGENTS.md aktualisieren sollten

AGENTS.md muss nicht bei jeder Projektänderung angepasst werden. Aktualisieren Sie sie, wenn dieselbe Reibung wiederkehrt.

Auslöser für Updates

OpenAI empfiehlt Updates in diesen Situationen:

1. Codex wiederholt denselben Fehler: Es editiert zweimal das falsche Verzeichnis oder startet immer den Test für das falsche package. Ergänzen Sie eine konkrete Constraint-Regel, etwa „Do NOT edit src/generated/“ oder „Use pnpm --filter web test for web changes.“

2. PR review wiederholt denselben Hinweis: Reviewer sagen wiederholt „diese Änderung braucht Tests“, „generated code nicht anfassen“ oder „keine default exports“. Schreiben Sie dieses Muster in PR expectations.

3. Codex liest zu viele Dateien, um die Antwort zu finden: Wenn es jedes Mal mehrere Dokumente durchsucht, um das richtige Testkommando oder den Build-Ablauf zu finden, setzen Sie die Kerninfo nach oben.

Die Regel gehört in das nächste sinnvolle Verzeichnis

Setzen Sie die Regel dort, wo der Fehler passiert. Nicht jede Regel muss in den Root. In monorepos können packages unterschiedliche Regeln haben, also kann jedes package eine lokale AGENTS.md besitzen.

Wenn Codex in apps/web den falschen Test ausführt, ergänzen Sie die Regel in apps/web/AGENTS.md. Eine Root-Regel würde sonst leicht zu breit wirken.

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

Unterschied zum Langzeitgedächtnis

AGENTS.md ist eine statische Anweisung, die beim Start geladen wird. Sie ist kein automatisch lernender memory store. Codex aktualisiert sie nicht aus Ihren Korrekturen, außer Sie beauftragen es ausdrücklich damit.

Für projektübergreifendes Wissen oder Memory-Governance ist der Leitfaden zu AI-Agent-Gedächtnis der bessere nächste Bezugspunkt.

Die Vorlage wachsen lassen: von der Seed-Datei zur erweiterten Datei

Starten Sie nicht mit einer 300-zeiligen Vorlage. Beginnen Sie mit 12 bis 20 Zeilen und erweitern Sie nur nach konkreten, wiederholbaren Auslösern.

Seed-Version: nur die 6 Kernblöcke

Die Seed-Version enthält repo layout, Kommandos, Constraints, PR expectations und done/verify. Sie kann so klein sein:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)

## PR expectations
- Add tests for new features

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Erweiterungsauslöser: wann ein Block dazukommt

Nach einigen Läufen erweitern Sie nur für echte Probleme:

1. Wenn Codex zum ersten Mal das falsche Verzeichnis editiert: Berührt es migrations/ oder generated/, ergänzen Sie in Constraints „Do NOT commit migrations/ without team review“ oder „Do NOT edit any file in src/generated/“.

2. Wenn PR review einen Hinweis wiederholt: Wenn Reviewer wieder Tests oder named exports verlangen, ergänzen Sie „Add tests for new features“ oder „Use named exports, not default exports“.

3. Wenn der Paketmanager verwechselt wird: Wenn in einem pnpm-Projekt npm-Kommandos auftauchen, ergänzen Sie „Always use pnpm, not npm or yarn“.

4. Wenn lint vergessen wird: Wenn Codex ohne lint abschließt, ergänzen Sie unter Done when „pnpm lint passes with no errors“.

Erweiterte Version: 30 bis 50 Zeilen

Eine erweiterte Datei kann zusätzliche Constraints, PR expectations, Paketmanager-Regeln und lint-Anforderungen enthalten:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
- Always use pnpm, not npm or yarn

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review
- Do NOT modify .env files (use .env.example as template)

## PR expectations
- Add tests for new features
- Run `pnpm test` and `pnpm lint` before marking done
- Use named exports, not default exports
- Keep components under 200 lines; split if larger

## Done when
- `pnpm test` passes
- `pnpm build` succeeds
- `pnpm lint` passes with no errors
- New features have corresponding tests

Der Kern ist: nach Auslösern wachsen, nicht nach Vorahnung. AGENTS.md ist nützlich, wenn sie wiederholte Erklärungen reduziert. Sie muss nicht jedes Projektdokument zeigen.

Fazit

AGENTS.md ist persistente Projektanweisung. Sie ist kein universelles Lager und kein Langzeitgedächtnis. Sie löst ein konkretes Problem: Sie müssen dieselben Projektregeln nicht bei jedem Codex-Start erneut erklären.

Praktische nächste Schritte:

1. Mit einer 12- bis 20-zeiligen Seed-Datei starten: repo layout, Kommandos, Constraints, PR expectations und done/verify. Keine riesige Vorlage am Anfang.

2. Prüfen, ob Codex sie geladen hat: codex --ask-for-approval never "Summarize the current instructions." ausführen und nach Ihren Regeln in der Antwort suchen.

3. Nur bei wiederholten Auslösern erweitern: Codex wiederholt einen Fehler, PR review wiederholt denselben Hinweis oder Codex muss zu weit suchen.

4. Unsichere und veraltende Inhalte draußen lassen: keine secrets, keine stale inventories, keine Slogans, keine vagen Kommandos, keine nicht prüfbaren Ziele und keine persönlichen Vorlieben im Repo-Root.

5. Mit CLAUDE.md oder Cursor Rules über Import und Koexistenz arbeiten: gemeinsame Projektregeln in AGENTS.md, tool-spezifisches Verhalten in den jeweiligen Dateien.

AGENTS.md gibt Codex stabilen Projektkontext. Weitere Artikel dieser Codex-Serie können wiederholte Workflows in Skills verschieben, Berechtigungen und secret-Grenzen behandeln und done/verify über Failure Review und PR Checks zuverlässiger machen.