AGENTS.md Best Practices: Wie lang sie sein sollte, Vorlage, Beispiele

AGENTS.md ist eine Markdown-Datei im Stammverzeichnis eines Code-Repositorys, die KI-Coding-Agenten sagt, wie sie in diesem Projekt arbeiten sollen: Stack, Build- und Testbefehle, Code-Stil, Architekturvorgaben und Grenzen. Die Seite agents.md listet mehr als 20 Tools auf, die sie lesen, darunter OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Jules, Zed, Windsurf, Devin, Aider und opencode. Auch Claude Code liest sie, standardmäßig aber nur dann, wenn das Projekt keine CLAUDE.md hat.

Minimale AGENTS.md-Vorlage (zum Kopieren)

# AGENTS.md

## Project overview
Next.js 15 App Router, React 19, TypeScript, Tailwind CSS, Drizzle ORM.

## Setup
Install: `pnpm install`  ·  Env: copy `.env.example` to `.env.local`

## Build and test
Build: `pnpm build`  ·  Test: `pnpm test`  ·  Lint: `pnpm lint --fix`

## Code style
Functional components with hooks only. Named exports only.

## Boundaries
Never edit files in /generated/. Never commit .env or secrets.

Tauschen Sie Ihren eigenen Stack und Ihre eigenen Befehle ein, halten Sie die Datei kurz und ergänzen Sie Abschnitte nur, wenn ein Agent etwas falsch macht. Die kommentierte Version weiter unten erklärt, was in jeden Abschnitt gehört.

Das Format ist auf agents.md definiert und wird auf GitHub gepflegt (agentsmd/agents.md). Mehr als 60.000 Open-Source-Projekte setzen es ein, und inzwischen wird es von der Agentic AI Foundation unter dem Dach der Linux Foundation betreut. Trotzdem sind die meisten AGENTS.md-Dateien zu lang, zu vage oder von einem LLM erzeugt, was den Agenten schlechter macht. Hier erfahren Sie, wie Sie eine schreiben, die funktioniert, und wie sie das auch bleibt.

Unser Coding-Agent erzeugte ständig Klassenkomponenten. Die gesamte Codebasis bestand aus funktionalem React mit Hooks. In der README stand "React 19, functional components". Der Contributing-Guide erklärte es ausführlich.

Der Agent hat die README nicht gelesen. Er weiß gar nicht, dass er das tun soll.

Dann haben wir eine AGENTS.md-Datei mit einer einzigen Zeile im Stil-Abschnitt hinzugefügt: Always use functional components with hooks. Never use class components. Dazu ein Codebeispiel, das den richtigen Weg zeigt.

Das Problem war sofort verschwunden.

Sie betreiben mehr als einen Agenten? Lesen Sie, wie Sie AGENTS.md über mehrere Agenten hinweg organisieren, ohne Konflikte und Drift.

Wie lang sollte AGENTS.md sein?

Kurze Antwort: Unter 100 Zeilen ist das Ziel, 150 ist das Warnsignal, und 200 ist die harte Obergrenze, die Anthropic für die eigene Entsprechung setzt. Unserer Erfahrung nach sind die meisten guten Dateien 30 bis 80 Zeilen lang.

Hier sehen Sie, woher die einzelnen Zahlen stammen, denn sie messen unterschiedliche Dinge (geprüft am 23. Oktober 2026):

Warum sagen wir also unter 100, wenn Anthropic 200 sagt? Weil jede Zeile in jede Sitzung geladen wird, jede Zeile bei jedem Lauf Token kostet und fast jede Zeile jenseits der ersten 50 eine Regel ist, der das Modell ohnehin folgen würde. Das ETH-Zürich-Team stellte fest, dass Repository-Übersichten, also das, was Modellanbieter am häufigsten zum Einbinden empfehlen, im Grunde nichts brachten, weil Agenten die Codebasis selbst lesen. Streichen Sie diese, und die meisten Dateien landen deutlich unter 100 Zeilen.

Zwei ehrliche Einschränkungen. Erstens: Eine kontrollierte Studie von Damon McMillan aus dem Jahr 2026 (arXiv:2605.10039, 1.650 Claude-Code-Sitzungen, 16.050 Beobachtungen) ergab, dass bei einer einzelnen, einfachen Code-Stil-Regel weder die Dateigröße noch die Position der Regel in der Datei noch das Aufteilen der Datei noch eine widersprechende Datei im Nachbarordner einen nachweisbaren Unterschied bei der Befolgung machten. Entscheidend waren die Aufgabe und wie weit der Agent in der Sitzung schon war: Jede zusätzliche Funktion, die er schrieb, war mit etwa 5,6 % geringeren Chancen verbunden, die Regel zu befolgen. Länge ist also keine Magie. Zweitens: Diese Studie testete eine einzige triviale Regel an Claude-Modellen. Echte Dateien enthalten Dutzende Regeln, die um Aufmerksamkeit konkurrieren, und genau dort greift Anthropics Warnung zur Befolgung.

Die praktische Lesart: Eine kurze Datei repariert keine schlechte Aufgabe, aber eine lange Datei macht jede Aufgabe teurer und gibt dem Agenten mehr Gelegenheiten, genau die eine Regel zu übersehen, auf die es ankommt.

Anzeichen dafür, dass Ihre AGENTS.md zu lang ist:

• Sie erklärt, warum Sie sich für Ihren Stack entschieden haben, oder beschreibt die Geschichte des Projekts.
• Sie enthält einen Verzeichnisbaum oder eine Abhängigkeitsliste, die der Agent selbst aus dem Repo lesen könnte.
• Sie enthält ein mehrstufiges Verfahren (eine Release-Checkliste, ein Migrations-Runbook). Das gehört in einen Skill, der nur bei Bedarf geladen wird.
• Sie finden zwei Regeln, die zum selben Verhalten Unterschiedliches sagen.
• Claude Code warnt Sie beim Start, oder Codex verwirft stillschweigend Dateien jenseits von 32 KiB.
• Sie wissen nicht mehr, warum die Hälfte der Regeln da ist.

Was in eine AGENTS.md gehört (und was nicht)

Der häufige Fehler ist, AGENTS.md wie Dokumentation zu behandeln. Lange Erklärungen. Architekturphilosophie. Begründungen fürs Design. Die Geschichte des Projekts.

Ihr Agent muss nicht wissen, warum Sie sich für Next.js statt Remix entschieden haben. Er muss wissen, dass Sie Next.js 15 mit App Router verwenden und dass der Testbefehl pnpm test lautet, nicht npm test.

Das sind die Abschnitte, auf die es ankommt, in der Reihenfolge, in der sie stehen sollten:

Projekt-Stack (5 bis 10 Zeilen)

Sprache, Framework, wichtige Abhängigkeiten, Laufzeit. Seien Sie konkret.

Gut: Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun

Schlecht: Dies ist eine moderne Webanwendung, die mit React und verschiedenen unterstützenden Bibliotheken gebaut wurde.

Build- und Testbefehle (5 bis 10 Zeilen)

Exakte Befehle mit exakten Flags. Der Paketmanager spielt eine Rolle. Die Build-Ziele spielen eine Rolle.

Gut: Build: bun run build. Test: bun test. Lint: bun run lint --fix. Deploy: bun run deploy:staging

Schlecht: Führen Sie die üblichen Build- und Testbefehle aus, wie in der package.json beschrieben.

Code-Stil-Konventionen (10 bis 20 Zeilen, mit Beispielen)

Ein Codebeispiel pro Konvention schlägt drei Absätze Beschreibung. Das ist die wichtigste Lehre aus wirksamen AGENTS.md-Dateien. Zeigen, nicht erzählen.

Architekturvorgaben (5 bis 15 Zeilen)

Regeln zur Verzeichnisstruktur. Modulgrenzen. Import-Beschränkungen. Richtung des Datenflusses.

Grenzen (5 bis 10 Zeilen)

Was der Agent nie anfassen soll. "Niemals Secrets committen" war die häufigste hilfreiche Einschränkung in GitHubs Analyse von mehr als 2.500 agents.md-Dateien. Ergänzen Sie: generierte Dateien, Legacy-Module, Konfigurationsdateien, die sich nicht ändern sollen, und Verzeichnisse, die von anderen Tools verwaltet werden.

Git-Workflow (5 Zeilen)

Branch-Namen, Format der Commit-Nachrichten, PR-Konventionen. Nur Squash-Merge. Conventional Commits: feat:, fix:, chore:, docs:.

Was Sie weglassen sollten

Mehrstufige Verfahren (eine Release-Checkliste, ein Migrations-Runbook) gehören nicht in eine Datei, die in jede Sitzung geladen wird. Anthropics Memory-Doku sagt dasselbe über CLAUDE.md: Verschieben Sie sie in einen Skill, den der Agent nur lädt, wenn die Aufgabe es verlangt. Unser Leitfaden Agent Skills vs. MCP behandelt, wo diese Grenze verläuft, und das Laden bei Bedarf ist ein wichtiger Grund dafür, dass Skills den Token-Verbrauch senken können.

Auch Tool-Verbindungen gehören nicht in AGENTS.md. Das sind MCP-Server, die im Tool selbst konfiguriert werden (siehe Was MCP ist). AGENTS.md kann sagen, wann ein Tool zu verwenden ist, nicht wie man sich mit ihm verbindet.

Regeln, die niemals gebrochen werden dürfen, gehören ebenfalls nicht dorthin. AGENTS.md ist Orientierung, keine Durchsetzung. Wenn etwas vor jedem Commit immer passieren muss oder gar nie passieren darf, nutzen Sie einen Pre-Commit-Hook, einen Claude-Code-Hook oder eine Berechtigungsregel. Die Datei kann die Regel erklären; der Hook setzt sie durch.

Der Regel-Lebenszyklus: hinzufügen, wenn es hakt, löschen, wenn es gelernt ist

Diese Gewohnheit hält eine AGENTS.md jahrelang kurz statt nur wenige Wochen.

1. Beginnen Sie mit 30 bis 50 Zeilen: Stack, Befehle, Code-Stil mit je einem Beispiel, Grenzen.
2. Fügen Sie eine Regel nur hinzu, wenn ein Agent etwas falsch macht, und zwar mehr als einmal. Ein Fehler kann an der Aufgabe liegen; zwei sind eine Lücke in der Datei.
3. Formulieren Sie die Regel als Vorgabe mit Beispiel, nicht als Erklärung. "Money is Decimal, never float" schlägt einen Absatz über Präzision.
4. Testen Sie nach ein paar Wochen oder nach einem Modell-Upgrade ohne die Regel. Löschen Sie die Zeile und führen Sie dieselbe Art von Aufgabe aus. Wenn der Agent es ohne Hinweis richtig macht, ist die Regel toter Ballast. Neuere Modelle befolgen viele Konventionen von selbst, die ältere noch ausgeschrieben bekommen mussten.
5. Prüfen Sie die gesamte Datei jedes Quartal, und im selben PR, sobald sich eine Konvention ändert.

Ein nützlicher Test für jede Zeile: Würde ein kompetenter Entwickler, der dieses Repo nie gesehen hat, das hier falsch machen? Wenn nein, löschen. Sie zahlen Token dafür, dem Modell seine eigenen Standardwerte vorzusagen.

Widersprüchliche Regeln richten mehr Schaden an als doppelte

Eine doppelte Regel verschwendet ein paar Token. Ein Widerspruch macht das Verhalten des Agenten unvorhersehbar, weil er sich für eine Seite entscheiden muss und Sie nicht steuern, für welche.

Anthropic sagt das in seiner Memory-Doku direkt: "Wenn zwei Anweisungen einander widersprechen, wählt Claude möglicherweise willkürlich eine aus." Das gilt auch dateiübergreifend: Ihre Root-Datei, eine Datei im Unterverzeichnis, eine persönliche globale Datei und alle Regeldateien landen im selben Kontext.

Wo sich Widersprüche meist verstecken:

• Eine Root-Datei sagt "Jest verwenden", und die Datei eines Pakets sagt "Vitest verwenden", ohne dass dort steht, dass das nur für dieses Paket gilt.
• Ihre persönliche globale Datei (~/.codex/AGENTS.md oder ~/.claude/CLAUDE.md) enthält eine projektspezifische Regel, die in anderen Repos falsch ist.
• Eine alte Regel, die nach einer Migration nie gelöscht wurde ("use the v1 API client").
• Eine Regel und ihre Ausnahme stehen in verschiedenen Abschnitten.

So finden Sie sie:

• Führen Sie in Claude Code /doctor prompt-audit aus (ab v2.1.283). Anthropics Doku beschreibt es als Prüfung, die "Anweisungen für ältere Modelle, Verweise auf nicht existierende Dateien oder Befehle und einander widersprechende Dateien" findet, und es schlägt Änderungen vor, ohne etwas zu ändern, bevor Sie zustimmen. Standardmäßig deckt es Ihre Dateien CLAUDE.md, CLAUDE.local.md und AGENTS.md ab.
• In jedem Tool können Sie den Agenten fragen: "List every instruction you've been given about testing, and flag any two that conflict."
• Schreiben Sie Regeln für Unterverzeichnisse als Spezialisierungen ("dieses Paket verwendet Vitest"), nie als Umkehrung der Root-Datei.

Eine Nuance der Genauigkeit halber: Die oben erwähnte McMillan-Studie fand, dass eine widersprechende Datei im Nachbarverzeichnis auf eine einzelne triviale Regel keinen nachweisbaren Effekt hatte. Das macht Widersprüche nicht ungefährlich. Es bedeutet, dass der Schaden bei Regeln auftritt, die konkurrieren, und genau diese Situation schafft eine wachsende Datei.

Die drei Fehler, die AGENTS.md nutzlos machen

Fehler 1: Von einem LLM erzeugen lassen

Das ist der häufigste und schädlichste Fehler. In der ETH-Zürich-Studie senkten LLM-generierte Dateien den Erfolg um 0,5 % auf SWE-bench Lite und um 2 % auf AGENTbench, verloren in 5 von 8 Szenarien und fügten pro Aufgabe 2,45 bis 3,92 zusätzliche Schritte hinzu. Von Entwicklern geschriebene Dateien schnitten besser ab (etwa +4 % auf AGENTbench), kosteten aber immer noch bis zu 19 % mehr.

Warum? LLMs erzeugen generische, wortreiche Anweisungen, die das Offensichtliche sagen. "Follow best practices for error handling." "Write clean, maintainable code." "Use descriptive variable names." Das weiß Ihr Agent bereits.

Schreiben Sie Ihre AGENTS.md von Hand. Wenn Sie einen Agenten für den Entwurf nutzen, behandeln Sie ihn wie den ersten PR eines neuen Mitarbeiters: Löschen Sie alles Generische und behalten Sie nur, was für Ihr Projekt spezifisch ist.

Fehler 2: Konventionen beschreiben, statt sie zu zeigen

Schlecht:

Use our custom error handling approach where errors bubble up through
the service layer and are caught by the global error handler rather
than being caught at individual function level.

Gut:

// Error handling: Let errors propagate. Do not wrap individual calls
// in try/catch. The global handler catches everything.

// CORRECT
async function getUser(id) {
  const user = await db.users.findById(id);
  return user;
}

// WRONG
async function getUser(id) {
  try {
    const user = await db.users.findById(id);
    return user;
  } catch (e) {
    logger.error(e);
    throw e;
  }
}

Das Codebeispiel vermittelt sofort, was drei Absätze Beschreibung nicht schaffen.

Fehler 3: Sie nicht aktualisieren

Eine AGENTS.md mit veralteten Tabellennamen, abgekündigten Befehlen oder überholten Architekturvorgaben ist schlimmer als gar keine AGENTS.md. Sie führt den Agenten aktiv in die Irre.

Aktualisieren Sie sie im selben PR, in dem sich Konventionen ändern, und folgen Sie dem oben beschriebenen Regel-Lebenszyklus. Wenn ein Agent wiederholt dieselbe falsche Ausgabe erzeugt, ist das eine Lücke in Ihrer Datei. Wenn er ohne die Regel die richtige Ausgabe liefert, ist das eine Zeile zum Löschen.

Funktioniert AGENTS.md wirklich?

Ja, aber nur die handgeschriebene, spezifische Variante.

Die Skepsis ist berechtigt. Wenn Sie einen Agenten Ihre AGENTS.md schreiben ließen, ihn ausgeführt haben und keine Verbesserung sahen, ist genau das, was die Forschung vorhersagt. Die Autoren der ETH Zürich stellten fest, dass Agenten die Anweisungen in diesen Dateien gut befolgen. Das Problem ist, dass die meisten Dateien voller Anweisungen sind, die nichts verändern.

Was funktioniert, ist eng gefasst: Anweisungen, die dem Agenten etwas sagen, das er aus der Codebasis nicht hätte ableiten können. Ihr Paketmanager. Ihr Testbefehl mit den exakten Flags. Das eine Verzeichnis, das er nie anfassen darf. Die Konvention Ihrer Codebasis, die für ein Modell, das auf dem Code aller anderen trainiert wurde, ungewöhnlich aussieht.

AGENTS.md vs. CLAUDE.md vs. .cursorrules (welche brauchen Sie?)

Beginnen Sie mit AGENTS.md und ergänzen Sie toolspezifische Dateien nur, wenn Sie deren besondere Funktionen brauchen.

AGENTS.md hat die breiteste Kompatibilität. Mehr als 20 Tools lesen sie nativ. Es ist das universelle Format.

CLAUDE.md ist die eigene Datei von Claude Code. Sie bringt Funktionen mit, die AGENTS.md nicht hat, etwa @path-Importe und .claude/rules/-Dateien, die auf Dateitypen zugeschnitten sind. Sie brauchen sie nicht mehr, nur damit Claude Code Ihre AGENTS.md sieht (siehe Wie Claude Code AGENTS.md liest weiter unten), aber sobald eine CLAUDE.md existiert, liest Claude Code standardmäßig keine AGENTS.md mehr. Wenn Sie also beide pflegen, lassen Sie die CLAUDE.md die gemeinsame Datei importieren:

@AGENTS.md

Behalten Sie AGENTS.md als einzige Quelle der Wahrheit für jedes Tool, und lassen Sie die CLAUDE.md diesen Import plus die Claude-spezifischen Überschreibungen enthalten, die Sie wirklich brauchen. Beachten Sie, dass Importe eine Datei ordnen, aber nicht verkleinern: Anthropics Doku weist darauf hin, dass importierte Dateien zusammen mit der CLAUDE.md geladen werden, die sie importiert, und daher zum selben Kontext zählen. Ein Symlink von CLAUDE.md auf AGENTS.md funktioniert ebenfalls, aber Anthropic empfiehlt den Import, wenn jemand im Team Windows nutzt, wo Git einen Symlink als einfache Textdatei auschecken kann.

.cursorrules ist Cursor-spezifisch. Sein besonderes Merkmal ist Frontmatter mit Datei-Globs, die für verschiedene Dateitypen unterschiedliche Anweisungen aktivieren. Wenn Ihr Team Cursor nutzt und Regeln pro Dateityp braucht, ergänzen Sie sie.

Der Großteil des Inhalts ist in allen drei Dateien identisch. Build-Befehle, Architekturregeln, Testkonventionen und Grenzen ändern sich nicht von Tool zu Tool. Ein Konverter namens rule-porter kann bei Bedarf zwischen den Formaten übersetzen.

Wie Claude Code AGENTS.md liest

Claude Code liest AGENTS.md seit v2.1.277 (veröffentlicht am 18. September 2026), mit einer großen Bedingung: Standardmäßig liest es AGENTS.md nur, wenn es keine CLAUDE.md gibt. Das stammt direkt aus Anthropics Memory-Dokumentation:

Die Details, über die man stolpert:

• Was als "eine CLAUDE.md" zählt: eine CLAUDE.md, .claude/CLAUDE.md oder CLAUDE.local.md in Ihrem Arbeitsverzeichnis oder einem darüberliegenden Verzeichnis. Ihre persönliche ~/.claude/CLAUDE.md, die verwaltete CLAUDE.md Ihrer Organisation und .claude/rules/-Dateien zählen nicht und werden weiterhin zusammen mit AGENTS.md geladen.
• Die CLAUDE.local.md-Falle: Wenn Sie eine CLAUDE.local.md für Ihre eigenen, nicht committeten Notizen anlegen, schaltet Claude Code stillschweigend von der AGENTS.md Ihres Teams weg.
• Was geladen wird: jede AGENTS.md und .claude/AGENTS.md von Ihrem Arbeitsverzeichnis aufwärts beim Sitzungsstart, plus die AGENTS.md eines Unterverzeichnisses, wenn Claude dort eine Datei öffnet. In einer interaktiven Sitzung sehen Sie eine Zeile wie no CLAUDE.md found; AGENTS.md loaded: ....
• Was ignoriert wird: AGENTS.local.md, AGENTS.override.md und alles unter einem .agents/-Verzeichnis. Die Override-Datei ist eine Codex-Konvention, keine von Claude Code.
• Das Standardverhalten ändern: Geben Sie /config ein und setzen Sie Project instructions auf claude-md-or-agents-md (der Standard), claude-md-and-agents-md (beide lesen, je Verzeichnis zuerst die CLAUDE.md), claude-md (AGENTS.md ignorieren) oder managed-only.
• Größenwarnungen: Claude Code warnt beim Start und in /status, wenn eine Datei länger als empfohlen ist und wenn mehrere einzeln unbedenkliche Dateien zusammen ein gemeinsames Limit überschreiten.

Zwei Versionshinweise. Vor v2.1.281 (23. September 2026) lasen Sitzungen auf Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM-Gateways oder mit deaktivierter Telemetrie weiterhin nur die CLAUDE.md. Und die erste Sitzung nach dem Upgrade von v2.1.276 oder früher nimmt AGENTS.md eventuell noch nicht auf; sie wird ab der nächsten Sitzung geladen. Wenn Sie eine ältere Version nutzen, funktioniert der @AGENTS.md-Import in einer CLAUDE.md weiterhin überall und führt nie dazu, dass die Datei doppelt gelesen wird.

Falls Sie das bisher von Hand verdrahtet hatten, lautet Anthropics Rat: Behalten Sie eine CLAUDE.md, die nur @AGENTS.md enthält (harmlos), oder löschen Sie sie; ersetzen Sie eine CLAUDE.md, die Claude in Worten anweist, AGENTS.md zu lesen, durch einen echten Import; und entfernen Sie jeden SessionStart-Hook, der AGENTS.md ausgibt, denn er fügt dem Kontext jetzt eine zweite Kopie hinzu.

Claude Code liest AGENTS.md nicht? Die vier Ursachen

Wenn Claude Code Ihre AGENTS.md ignoriert, steckt fast immer eine von vier Ursachen dahinter. Prüfen Sie sie in dieser Reihenfolge. Alles hier stammt aus Anthropics Memory-Doku und dem Claude-Code-Changelog, geprüft am 23. Oktober 2026.

1. Die Datei liegt am falschen Ort oder hat den falschen Namen. Beim Sitzungsstart lädt Claude Code AGENTS.md und .claude/AGENTS.md aus Ihrem Arbeitsverzeichnis und jedem darüberliegenden Verzeichnis. Wenn Sie Claude in einem Ordner über dem Repo starten, ist die AGENTS.md des Repos eine Datei in einem Unterverzeichnis und wird beim Start nicht geladen. Starten Sie im Repo-Root und nennen Sie die Datei genau AGENTS.md.

2. Eine CLAUDE.md hat Vorrang. Meist ist eine vergessene CLAUDE.local.md der Übeltäter. Fügen Sie @AGENTS.md in die CLAUDE.md ein oder setzen Sie in /config Project instructions auf claude-md-and-agents-md. Prüfen Sie, dass die Einstellung nicht claude-md oder managed-only lautet, denn beide überspringen AGENTS.md vollständig.

3. Sie nutzen eine Version mit einem inzwischen behobenen Fehler. Führen Sie claude --version aus. Vor v2.1.281 lasen Sitzungen mit Bedrock, Vertex, Foundry, Gateway und ohne Telemetrie nur die CLAUDE.md. v2.1.290 (5. Oktober 2026) behob, dass die AGENTS.md eines Unterverzeichnisses nicht angehängt wurde, wenn Sie eine Datei darunter per @ erwähnten. Aktualisieren Sie Claude Code und starten Sie eine neue Sitzung.

4. Es ist eine verschachtelte Datei, die noch nicht geladen wurde. Die AGENTS.md eines Unterverzeichnisses wird nicht beim Start gelesen. Claude Code lädt sie, wenn Claude eine Datei in diesem Verzeichnis öffnet, und nur, wenn dieses Verzeichnis keine eigene CLAUDE.md hat. Legen Sie Regeln, die immer gelten müssen, in die Root-Datei.

Um zu bestätigen, was geladen wurde, führen Sie /memory aus und suchen Sie nach dem Pfad Ihrer AGENTS.md.

Funktioniert AGENTS.md mit OpenAI Codex?

Ja. Codex liest AGENTS.md nativ, und dieselbe Datei funktioniert in Codex, Cursor, Gemini CLI und Claude Code ohne Änderungen.

Die Auflösungsregeln von Codex sind stärker geschichtet als bei den meisten Tools. Laut OpenAIs Codex-Leitfaden zu AGENTS.md baut es die Instruktionskette einmal pro Lauf auf:

• Global: In Ihrem Codex-Home (~/.codex, oder wohin CODEX_HOME zeigt) liest Codex AGENTS.override.md, falls vorhanden, andernfalls AGENTS.md. Auf dieser Ebene wird nur eine Datei verwendet.
• Projekt: Ausgehend vom Projekt-Root (meist dem Git-Root) geht es bis zu Ihrem aktuellen Arbeitsverzeichnis hinunter. In jedem Verzeichnis prüft es AGENTS.override.md, dann AGENTS.md, dann alle Namen, die Sie in project_doc_fallback_filenames aufgeführt haben, und nimmt pro Verzeichnis höchstens eine Datei.
• Zusammenführung: Die Dateien werden von der Wurzel abwärts aneinandergehängt, sodass die Dateien, die am nächsten an Ihrem Arbeitsort liegen, zuletzt stehen und frühere Vorgaben überschreiben.

Größenlimit. Codex überspringt leere Dateien und hört auf, Dateien hinzuzufügen, sobald die Gesamtgröße project_doc_max_bytes erreicht, standardmäßig 32 KiB. Das gilt für die gesamte Kette, nicht pro Datei. Sie können den Wert erhöhen, aber wenn Sie in der Nähe des Limits liegen, ist es besser, Zeilen zu löschen:

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

Prüfen, was geladen wurde. Führen Sie codex --ask-for-approval never "Summarize the current instructions." im Repo-Root aus. Codex baut die Kette bei jedem Lauf neu auf (in der interaktiven TUI einmal pro Sitzung), es gibt also keinen Cache zu leeren, wenn Sie eine Datei bearbeiten; starten Sie es einfach neu. Wenn dieser Testlauf mit stream disconnected before completion abbricht, ist das ein Verbindungsfehler und kein Problem der Instruktionsdatei.

Eine praktische Warnung. Codex führt die Build- und Testbefehle aus Ihrer AGENTS.md in seiner Sandbox aus. Ein falscher Befehl erzeugt keinen hilfreichen Fehler; der Agent führt ihn aus, sieht ihn scheitern und umgeht das Problem. Bevor Sie sich auf einen Befehl in Ihrer AGENTS.md verlassen, führen Sie ihn wortgetreu in einem frischen Terminal aus.

Claude Code liest weder AGENTS.override.md noch die Fallback-Dateinamen von Codex. Wenn also ein Repo beide Agenten bedient, halten Sie die gemeinsamen Regeln in normalen AGENTS.md-Dateien.

Globale vs. verzeichnisbezogene AGENTS.md

Es gibt drei Geltungsbereiche, und ihre Verwechslung ist eine häufige Quelle für "warum ignoriert der Agent meine Anweisungen".

Global (persönlich). Eine Datei im Konfigurationsverzeichnis Ihres Tools, etwa ~/.codex/AGENTS.md. Sie gilt für jedes Projekt, das Sie öffnen. Nutzen Sie sie für Vorlieben, die Sie betreffen und nicht das Projekt. Sie wird nicht committet, Teamkollegen sehen sie also nie.

Repository-Root. Die Datei, die die meisten meinen, wenn sie "AGENTS.md" sagen. Sie ist im Repo committet und wird vom ganzen Team geteilt. Nutzen Sie sie für Regeln, die überall im Projekt gelten.

Unterverzeichnis. Erweitert die Root-Datei für ein Verzeichnis. Nutzen Sie sie, wenn ein Verzeichnis wirklich andere Regeln hat: ein Paket mit eigenem Build-Befehl, ein /mobile-Verzeichnis mit einem anderen Framework.

Die meisten Projekte brauchen nur die Root-Datei. Wenn Ihre Root-AGENTS.md zu lang ist, besteht die Lösung darin, Zeilen zu löschen, nicht sie auf Verzeichnisse zu verteilen.

Verschachtelte und globale AGENTS.md: welche gewinnt

Die kurze Antwort: Die Datei, die dem bearbeiteten Code am nächsten liegt, gewinnt, und alles, was Sie im Chat tippen, schlägt jede Datei. So steht es in den agents.md-FAQ: "Die AGENTS.md, die der bearbeiteten Datei am nächsten liegt, gewinnt; explizite Chat-Prompts der Nutzer überschreiben alles."

Für Claude Code beschreibt Anthropics Doku Instruktionsdateien als aneinandergehängt statt einander überschreibend und warnt, dass Claude bei widersprüchlichen Dateien möglicherweise willkürlich eine auswählt. In Claude Code ist "die nächste gewinnt" also eine Tendenz, keine Garantie. Diese Regeln gelten überall:

• Nicht widersprechen, spezialisieren. Eine Datei im Unterverzeichnis sollte Regeln für dieses Verzeichnis ergänzen, nicht die Regeln der Root-Datei umkehren.
• Persönliche Vorlieben global halten, Projektregeln im Repo.
• Sagen Sie es im Prompt, wenn es darauf ankommt. Eine einmalige Ausnahme gehört in den Prompt, nicht in eine Änderung der AGENTS.md.

Sollte AGENTS.md in Git committet werden?

Ja. AGENTS.md gehört in die Versionskontrolle, neben den Code, den sie beschreibt, im Repo-Root. Jeder Mitwirkende und jedes KI-Tool liest sie von dort, und Änderungen werden im selben PR geprüft wie die Änderung der Konvention, die sie ausgelöst hat.

Zwei Ausnahmen. Persönliche Vorlieben gehören in Ihre globale Datei, nicht ins Repo. Und tragen Sie nie Secrets oder interne URLs direkt ein; verweisen Sie darauf aus .env oder einer per gitignore ausgeschlossenen Datei.

Sicherheit: AGENTS.md ist eine Angriffsfläche für Prompt-Injection

Das AI Red Team von NVIDIA hat eine indirekte AGENTS.md-Injection gegen OpenAI Codex demonstriert, bei der eine bösartige Abhängigkeit das Verhalten des Agenten kapert, indem sie die Rangfolge der Anweisungen ausnutzt. Der Angriff setzt eine bereits kompromittierte Abhängigkeit voraus, es ist also kein Grund zur Panik bei jedem Repo, das Sie klonen. Aber er zeigt, dass Instruktionsdateien für Agenten ausführbarer Kontext sind und die Angriffsfläche der Lieferkette vergrößern.

Die praktischen Schutzmaßnahmen:

• Lesen Sie die AGENTS.md in jedem Repo, das Sie klonen, bevor Sie einen Agenten darauf ansetzen.
• Behandeln Sie AGENTS.md wie ein Makefile oder ein Postinstall-Skript. Sie beeinflusst Befehle, die auf Ihrem Rechner laufen.
• Prüfen Sie Änderungen an AGENTS.md mit derselben Aufmerksamkeit wie Änderungen an der CI-Konfiguration.
• Führen Sie Agenten wenn möglich in einer Sandbox aus, damit eine übersehene Anweisung weniger Schaden anrichtet.

Über Code hinaus: AGENTS.md für Business-Agenten

Die Idee hinter AGENTS.md entstand in Code-Repositories, aber das Prinzip gilt für jeden KI-Agenten: Geben Sie ihm zu Beginn kurzen, spezifischen Kontext, und er arbeitet besser. Auch die Lehre zur Länge gilt. Ein Business-Agent mit einer zweiseitigen Rollenbeschreibung befolgt sie schlechter als einer mit zehn klaren Zeilen.

Bei Business-Agenten (Support, Vertrieb, Betrieb) umfasst die entsprechende Konfiguration:

• Identität: wer der Agent ist, seine Rolle und sein Tonfall.
• Fähigkeiten: welche Tools und Apps er nutzen darf.
• Einschränkungen: was er nicht tun darf und welche Aktionen eine menschliche Freigabe brauchen.
• Vertrauensstufe: nur Entwürfe, handeln mit Freigabe oder eigenständig handeln innerhalb von Grenzen.
• Eskalationsregeln: wann er an einen Menschen übergibt.
• Ausgabeformat: wie er antworten soll.

Für Coding-Agenten ist AGENTS.md eine Datei, die Sie schreiben und pflegen. Für Business-Agenten lässt sich diese Konfiguration in einem visuellen Builder leichter verwalten. So funktioniert der KI-Agenten-Builder von BetterClaw: Identität, Fähigkeiten, Einschränkungen, Vertrauensstufen (Intern, Specialist, Lead), Eskalationsregeln und Ausgabeformat sind Felder im Builder, werden für Sie versioniert, und es gibt keine Datei, die man zu aktualisieren vergessen kann. Jeder Agent kann Ihren eigenen Modellschlüssel ohne Aufschlag nutzen. Jetzt mit BetterClaw starten: Starter kostet $19/month, und Pro kostet $49/month für 5 Agenten.

Die kommentierte Vorlage (kopieren und anpassen)

Hier ist eine minimale, wirksame AGENTS.md. Löschen Sie Abschnitte, die nicht zutreffen. Eine kürzere, korrekte Datei schlägt eine umfassende, generische.

# Project Name

Next.js 15 App Router, React 19, TypeScript 5.4, Tailwind CSS, Drizzle ORM, Bun.

## Commands

Build: `bun run build`
Test: `bun test`
Lint: `bun run lint --fix`
Single test: `bun test path/to/file.test.ts`

## Code Style

Functional components only. Never class components.
Use `const` exclusively. Never `var`, never `let` unless reassignment is needed.
Named exports only. Never default exports.

// Component example:
export const UserCard = ({ name, email }: UserCardProps) => {
  return <div className="p-4">{name}</div>;
};

## Error Handling

Let errors propagate. Do not wrap individual calls in try/catch.
The global error handler in middleware.ts catches everything.

## Architecture

/app         -> Routes and page components
/components  -> Shared UI components
/lib         -> Business logic and utilities
/db          -> Database schema and migrations

Never import from /app into /lib. Data flows one direction.

## Boundaries

Never modify files in /generated/.
Never commit .env or any file containing secrets.
The /legacy/ module uses sync code. Do not convert to async.

## Git

Squash merge only.
Conventional commits: feat:, fix:, chore:, docs:.
Branch format: type/short-description (e.g., feat/user-auth).

Das sind unter 50 Zeilen, und jede Zeile ist spezifisch. Wenn Ihre über 100 wächst, gehen Sie zurück zum Regel-Lebenszyklus und fangen Sie an zu löschen.

AGENTS.md-Beispiele: drei Dateien für drei Projekttypen

Echte Dateien sind kürzer und seltsamer als Vorlagen, weil sie nur das enthalten, was die Agenten dieses Projekts immer wieder falsch gemacht haben. Diese drei sind repräsentative Beispiele, die diese Bandbreite zeigen sollen, keine Kopien der Datei eines bestimmten Repositorys.

Beispiel 1: eine Next.js-Webanwendung (12 Zeilen)

# Storefront

Next.js 15 App Router, TypeScript, Tailwind, Bun.

Build: `bun run build` | Test: `bun test` | Lint: `bun run lint --fix`

Server Components by default. Add `'use client'` only for event handlers or hooks.
Never fetch in a Client Component. Fetch in the page, pass data down as props.
Named exports only.

Never edit `/app/generated/`. It is regenerated on every build.
Never add a dependency without asking. This bundle is size-budgeted.

Was sie richtig macht: Die 'use client'-Regel ist das Eine, was ein Agent in App-Router-Projekten zuverlässig falsch macht, formuliert als Regel samt Ausnahme, in einer Zeile.

Beispiel 2: ein Python-FastAPI-Backend (16 Zeilen)

# Billing API

Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic, uv.

Install: `uv sync` | Run: `uv run uvicorn app.main:app --reload`
Test: `uv run pytest -x` | Single test: `uv run pytest tests/test_invoices.py::test_name`

All DB access is async. Never use the sync Session. Never call `.commit()` in a
route handler; the dependency in `app/deps.py` handles the transaction boundary.

Pydantic models live in `app/schemas/`. SQLAlchemy models live in `app/models/`.
Never import a SQLAlchemy model into a route signature.

Schema changes require a migration: `uv run alembic revision --autogenerate -m "..."`.
Never edit an existing migration that has been merged.

Money is `Decimal`, never `float`. Amounts are stored in minor units (cents).

Was sie richtig macht: die Geldregel. Eine eindeutige Zeile, die eine Klasse von Fehlern verhindert, die später teuer zu finden sind.

Beispiel 3: ein Monorepo (22 Zeilen)

# Platform monorepo

pnpm workspaces + Turborepo. Node 22.

apps/web    -> Next.js 15 storefront
apps/admin  -> Vite + React admin panel
packages/ui -> Shared component library
packages/db -> Drizzle schema and client

Always run commands from the repo root: `pnpm turbo build --filter=web`.
Never `cd` into a package and run `pnpm install` there.

Test: `pnpm turbo test` | Single app: `pnpm turbo test --filter=admin`

apps/* may import from packages/*. packages/* must never import from apps/*.
packages/ui must never import from packages/db. UI takes data as props.

Adding a dependency to a package: `pnpm add <pkg> --filter=<package-name>`.

Each app has its own AGENTS.md with framework-specific rules. This file covers
the workspace-level rules only.

Was sie richtig macht: die Regeln zur Import-Richtung und die letzte Zeile, die dem Agenten sagt, dass weiter unten im Baum spezifischere Anweisungen existieren.

Der rote Faden: Jede Zeile ist eine Regel, die ein Agent ohne Hinweis brechen würde, formuliert als Vorgabe statt als Erklärung. Keine beschreibt, wofür das Projekt da ist, und keine kommt auch nur in die Nähe von 100 Zeilen.

Die Kurzfassung

Die beste AGENTS.md ist die, die Ihr Team tatsächlich pflegt. Beginnen Sie mit 30 Zeilen. Fügen Sie eine Regel hinzu, wenn ein Agent etwas zweimal falsch macht. Löschen Sie sie, wenn der Agent es ohne Hinweis richtig macht. Halten Sie sie unter 100 Zeilen, suchen Sie jedes Quartal nach Widersprüchen und setzen Sie alles Kritische mit einem Hook statt mit einem Satz durch.

Und wenn Ihre Agenten Business-Agenten sind und keine Coding-Agenten, gehört diese ganze Konfiguration in einen visuellen Builder statt in eine Markdown-Datei. Bauen Sie Ihren Agenten in BetterClaw, oder legen Sie direkt los und nutzen Sie Ihren eigenen Modellschlüssel.

Häufig gestellte Fragen

Wie lang sollte eine AGENTS.md-Datei sein?

Peilen Sie unter 100 Zeilen an und fangen Sie an zu löschen, sobald sie 150 überschreitet. Anthropic empfiehlt, CLAUDE.md, die entsprechende Datei, unter 200 Zeilen zu halten, weil "längere Dateien mehr Kontext verbrauchen und die Befolgung senken", und Codex hört standardmäßig bei zusammen 32 KiB auf, Instruktionsdateien zu laden. Eine Studie der ETH Zürich fand, dass Kontextdateien die Inferenzkosten im Schnitt um über 20 % erhöhen, ohne den Erfolg generell zu verbessern, jede zusätzliche Zeile hat also ihren Preis. Unserer Erfahrung nach sind die meisten guten Dateien 30 bis 80 Zeilen lang.

Ist meine AGENTS.md zu lang?

Wahrscheinlich, wenn sie Ihre Stack-Entscheidungen erklärt, einen Verzeichnisbaum oder eine Abhängigkeitsliste enthält, Schritt-für-Schritt-Verfahren umfasst, zwei Regeln hat, die einander widersprechen, oder Sie nicht mehr wissen, warum die Hälfte der Regeln dort steht. Claude Code warnt beim Start außerdem, wenn eine Datei länger als empfohlen ist. Löschen Sie alles, was der Agent selbst aus dem Code lesen könnte, und verschieben Sie Verfahren in Skills.

Was ist eine AGENTS.md-Datei?

AGENTS.md ist eine Markdown-Datei im Stammverzeichnis eines Code-Repositorys, die KI-Coding-Agenten projektspezifische Anweisungen gibt: Build-Befehle, Code-Stil, Architekturvorgaben, Tests und Grenzen. Mehr als 20 Tools lesen sie nativ, darunter OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Jules, Zed, Windsurf und Devin. Claude Code liest sie, wenn das Projekt keine CLAUDE.md hat. Mehr als 60.000 Open-Source-Projekte nutzen sie, und sie wird von der Agentic AI Foundation unter dem Dach der Linux Foundation betreut.

Was soll ich tun, wenn mein Agent eine Regel ignoriert?

Prüfen Sie zuerst, ob die Datei tatsächlich geladen wurde (/memory in Claude Code, oder bitten Sie Codex, seine Anweisungen zusammenzufassen). Machen Sie die Regel dann konkreter und fügen Sie ein Beispiel hinzu. Suchen Sie danach nach einer zweiten Regel, die ihr widerspricht. Wenn die Regel nie gebrochen werden darf, verlassen Sie sich nicht auf die Datei: Nutzen Sie einen Hook oder eine Berechtigungseinstellung, die unabhängig davon gelten, was der Agent entscheidet.

Liest Claude Code AGENTS.md?

Ja, seit Claude Code v2.1.277 (18. September 2026). Standardmäßig liest es AGENTS.md nur, wenn es in Ihrem Arbeitsverzeichnis oder darüber keine CLAUDE.md, .claude/CLAUDE.md oder CLAUDE.local.md gibt. Damit es beide liest, setzen Sie Project instructions auf claude-md-and-agents-md in /config oder schreiben Sie @AGENTS.md in Ihre CLAUDE.md. AGENTS.override.md und AGENTS.local.md liest es nicht.

Wie verhält sich AGENTS.md zu CLAUDE.md und .cursorrules?

AGENTS.md hat die breiteste Kompatibilität. CLAUDE.md ist die eigene Datei von Claude Code und ergänzt @imports und pfadbezogene Regeln. .cursorrules ergänzt Cursor-spezifische, Glob-basierte Regeln. Der Großteil des Inhalts ist in allen dreien identisch. Beginnen Sie mit AGENTS.md als einziger Quelle der Wahrheit, und wenn Sie eine CLAUDE.md ergänzen, beginnen Sie sie mit einem @AGENTS.md-Import.

Soll ich ein LLM nutzen, um meine AGENTS.md zu erzeugen?

Nein. In der ETH-Zürich-Studie senkten LLM-generierte Kontextdateien den Aufgabenerfolg in 5 von 8 Szenarien und fügten pro Aufgabe 2,45 bis 3,92 zusätzliche Schritte hinzu. LLMs schreiben generische Ratschläge, denen der Agent ohnehin folgt. Schreiben Sie sie von Hand, oder behandeln Sie einen KI-Entwurf als etwas, das Sie zusammenstreichen, nicht als etwas, das Sie committen.

Kann ich dieselbe AGENTS.md für Codex und Claude Code verwenden?

Ja. Codex liest sie nativ; Claude Code liest sie, solange das Projekt keine CLAUDE.md hat, und braucht sonst einen @AGENTS.md-Import in der CLAUDE.md. Denken Sie daran, dass Claude Code die AGENTS.override.md von Codex ignoriert. Halten Sie gemeinsame Regeln deshalb in normalen AGENTS.md-Dateien und führen Sie jeden Befehl der Datei in einem frischen Terminal aus, bevor Sie sich darauf verlassen.

Committe ich AGENTS.md oder trage ich sie in .gitignore ein?

Committen Sie sie. Sie ist Projektdokumentation und gehört in den Repo-Root, damit jeder Mitwirkende und jedes Tool dieselben Anweisungen liest. Halten Sie persönliche Vorlieben in der globalen Datei Ihres Tools und tragen Sie nie Secrets ein.

Lassen sich die Prinzipien von AGENTS.md auf Business-Agenten anwenden?

Ja. Dieselbe Idee (kurzer, spezifischer Kontext zu Identität, Fähigkeiten, Einschränkungen und Grenzen) gilt für jeden KI-Agenten. Bei Business-Agenten sind die Abschnitte Identität, Fähigkeiten, Einschränkungen, Vertrauensstufen, Eskalationsregeln und Ausgabeformat, und sie lassen sich in einem visuellen Builder wie BetterClaw leichter verwalten als in einer Markdown-Datei.