Constantin, Platform Engineering bei Pexon Consulting | 8 Min. Lesezeit | 12.08.2026
TL;DR
AGENTS.md ist die Anweisungsdatei, die Coding-Agenten wie Codex, Claude Code und GitHub Copilot beim Start lesen. Sie beschreibt Build-Befehle, Tests, Code-Style und Verbote. Halten Sie die Datei unter 32 KiB, denn Codex schneidet darüber stillschweigend ab. Ein Codebeispiel je Konvention wirkt stärker als lange Fließtexte.
Was AGENTS.md ist und was nicht
AGENTS.md ist eine Markdown-Datei im Projekt-Wurzelverzeichnis, deren Inhalt beim Start eines Coding-Agenten in den Modell-Kontext geladen wird. Sie sagt dem Agenten, wie Ihr Projekt gebaut, getestet und formatiert wird. Sie ist ein offener Standard, den Codex, Claude Code und GitHub Copilot lesen.
Wichtig ist die Abgrenzung: AGENTS.md ist eine Anweisung, keine Durchsetzung. Der Text landet im Kontext des Modells, aber nichts zwingt den Agenten technisch dazu, sich daran zu halten. Wer echte Garantien braucht, setzt weiterhin auf Linter, Pre-Commit-Hooks und CI. Die Datei senkt die Fehlerrate, sie ersetzt keine Absicherung.
Genau deshalb zahlt sich Konkretheit aus. Ein Codebeispiel je Konvention wirkt stärker als drei Absätze Beschreibung. Statt zu erklären, dass Sie asynchrone Funktionen bevorzugen, zeigen Sie eine Zeile Code, die genau das tut. Der Agent kopiert Muster zuverlässiger, als er Prosa interpretiert.
Der Kontext für 2026: Codex nutzt seit dem 23.04.2026 GPT-5.5 als Default-Modell, und OpenAI zählt 4 Millionen wöchentliche Codex-Entwickler. Die Datei, die diese Agenten lesen, ist damit kein Nischenthema mehr, sondern Teil des täglichen Werkzeugs.
Das 32-KiB-Limit und die stille Truncation
Codex begrenzt die kombinierte Größe der Anweisungsdateien standardmäßig auf 32 KiB (project_doc_max_bytes). Wird diese Grenze überschritten, schneidet Codex den Rest ab. Und zwar ohne Warnung: keine Meldung im TUI, kein Hinweis im Log. Ihre unteren Regeln verschwinden einfach aus dem Kontext.
Das ist die tückischste Falle in der Praxis. Eine gewachsene AGENTS.md fühlt sich vollständig an, aber der Agent sieht nur den Anfang. Verbote am Ende der Datei greifen dann nicht mehr, und niemand merkt, warum der Agent plötzlich Regeln ignoriert, die klar dokumentiert sind.
Sie können das Limit erhöhen, etwa auf 64 KiB per project_doc_max_bytes = 65536. Das kostet allerdings mehr Token pro Lauf, weil bei jedem Start mehr Text in den Kontext wandert.
Unsere Empfehlung: Bleiben Sie unter 32 KiB und behandeln Sie die Grenze als Qualitätssignal. Wenn die Datei zu groß wird, ist sie meist zu geschwätzig. Kürzen Sie auf Befehle und Codebeispiele, bevor Sie das Limit hochsetzen. Das Limit anzuheben ist die zweitbeste Lösung.
Verschachtelte AGENTS.md für Monorepos
In größeren Repositories dürfen mehrere AGENTS.md-Dateien nebeneinander existieren. Codex liest sie von der Wurzel zum Blatt (root zu leaf) und fügt sie mit Leerzeilen zusammen. Die Regeln der Wurzel gelten überall im Projekt. Regeln in einem Unterverzeichnis überschreiben die Wurzel-Regeln, aber nur für ihren eigenen Teilbaum.
Damit lässt sich ein Monorepo sauber strukturieren. Die Wurzel-Datei hält die projektweiten Grundlagen: Sprache, gemeinsame Test-Befehle, allgemeine Verbote. Ein Frontend-Unterordner bekommt seine eigene AGENTS.md mit den Konventionen, die nur dort gelten, etwa Framework-spezifische Muster oder ein anderer Formatter.
Für die Aufteilung gibt es eine handhabbare Faustregel: Ab etwa 150 bis 200 Zeilen sollten Sie eine Datei in verschachtelte Dateien pro Unterverzeichnis zerlegen. Das hält jede einzelne Datei lesbar und reduziert das Risiko, unbemerkt an die 32-KiB-Grenze zu stoßen, weil die Wurzel-Datei schlank bleibt.
Das kopierfertige AGENTS.md-Template
Der schnellste Start ist eine vorhandene Struktur, die Sie an Ihr Projekt anpassen. Das folgende Template deckt die vier Dinge ab, die ein Agent zuerst braucht: wie er baut, wie er testet, welchen Stil er einhält und was er nicht tun darf. Passen Sie die Befehle an Ihren Stack an und ersetzen Sie die Beispiele durch echte Muster aus Ihrem Code.
# AGENTS.md
## Projekt
Kurzbeschreibung: Was macht dieses Projekt in einem Satz.
Sprache: TypeScript (Node 22). Paketmanager: pnpm.
## Setup
# Abhängigkeiten installieren
pnpm install
## Build
# Produktions-Build erzeugen
pnpm build
## Tests
# Immer VOR dem Fertigmelden ausführen
pnpm test
# Einzelnen Test laufen lassen
pnpm test -- <dateiname>
## Code-Style
# Formatter und Linter sind Pflicht vor jedem Commit
pnpm lint
pnpm format
# Beispiel-Konvention: asynchrone Funktionen mit async/await,
# kein .then()-Chaining
async function ladeNutzer(id: string): Promise<Nutzer> {
const res = await fetch(`/api/nutzer/${id}`)
return res.json()
}
## Verbote
# - Keine neuen Abhängigkeiten ohne Rückfrage hinzufügen
# - Keine console.log im Produktionscode, stattdessen den Logger nutzen
# - Keine bestehenden Tests löschen oder deaktivieren
# - Keine Secrets oder API-Keys in den Code schreiben
## Commit
# Konventionelle Commit-Messages: feat:, fix:, chore:Das Template ist bewusst knapp. Jede Zeile hat einen Zweck, und die Code-Kommentare erklären dem Agenten den Kontext direkt an der Stelle, an der er ihn braucht. Erweitern Sie es sparsam, denn jede zusätzliche Zeile zählt gegen das 32-KiB-Budget.
AGENTS.md vs CLAUDE.md vs copilot-instructions.md
AGENTS.md ist der gemeinsame offene Standard, aber die drei großen Tools nutzen unterschiedliche Dateinamen. Codex liest AGENTS.md direkt. Claude Code liest AGENTS.md seit Version 2.1.277 (18.09.2026), aber nur als Ersatz, wenn keine CLAUDE.md vorhanden ist – nicht zusätzlich, und noch nicht auf Bedrock, Vertex oder Foundry. GitHub Copilot erwartet die Anweisungen unter .github/copilot-instructions.md. Der Inhalt ist in allen Fällen dieselbe Idee: Kontext-Instruktionen in Markdown.
Wir raten davon ab, für jedes Tool eine getrennte, inhaltlich abweichende Datei zu pflegen. Das führt zu Drift: Die Regeln laufen auseinander, und niemand weiß mehr, welche Version aktuell ist. Pflegen Sie eine einzige Quelle der Wahrheit in AGENTS.md und spiegeln Sie sie bei Bedarf per Symlink oder kurzem Verweis auf die anderen Dateinamen. Die offizielle Codex-Dokumentation zu AGENTS.md finden Sie unter developers.openai.com/codex/guides/agents-md.
Häufig gestellte Fragen
Wo muss die AGENTS.md liegen?
Die Hauptdatei gehört ins Wurzelverzeichnis des Projekts. In Monorepos dürfen zusätzliche AGENTS.md-Dateien in Unterverzeichnissen liegen. Codex liest sie von der Wurzel zum Blatt und fügt sie zusammen, wobei die tiefer liegende Datei die Wurzel-Regeln für ihren Teilbaum überschreibt.
Was passiert, wenn die AGENTS.md zu groß ist?
Codex schneidet Anweisungsdateien ab der kombinierten Standardgröße von 32 KiB ab, und zwar ohne Warnung im TUI oder Log. Ihre unteren Regeln verschwinden dann stillschweigend aus dem Kontext. Sie können das Limit per project_doc_max_bytes = 65536 auf 64 KiB erhöhen, zahlen aber mit höherem Token-Verbrauch.
Was ist der Unterschied zwischen AGENTS.md und CLAUDE.md?
Beides ist derselbe offene Standard mit demselben Zweck, aber kein Gleichstand: Claude Code liest AGENTS.md seit Version 2.1.277 (18.09.2026) nur als Fallback, wenn keine CLAUDE.md vorhanden ist, nicht zusätzlich – und (Stand 18.09.2026) noch nicht auf Bedrock, Vertex oder Foundry. Quelle: code.claude.com/docs/en/changelog (v2.1.277). GitHub Copilot nutzt für dieselbe Idee copilot-instructions.md.
Erzwingt AGENTS.md die Regeln technisch?
Nein. AGENTS.md ist eine Anweisung, keine Durchsetzung. Der Inhalt landet im Modell-Kontext und beeinflusst das Verhalten, aber echte Garantien liefern nur Linter, Pre-Commit-Hooks und CI. Nutzen Sie die Datei zusätzlich zu diesen Mechanismen, nicht als deren Ersatz.
Wie halte ich die Datei wirksam und kurz?
Setzen Sie auf Befehle und Codebeispiele statt auf lange Beschreibungen, denn ein Codebeispiel je Konvention wirkt stärker als drei Absätze Text. Teilen Sie die Datei ab etwa 150 bis 200 Zeilen in verschachtelte Dateien pro Unterverzeichnis auf, damit jede Einzeldatei lesbar bleibt und Sie unter dem 32-KiB-Limit bleiben.
Nächster Schritt
Verwandte Themen
→Codex und Claude Code im Vergleich
→OpenAI Codex im Unternehmen
→AI Engineering Stack als Fundament
