Wer mehrere KI-Coding-Agenten im selben Repository einsetzt, landet schnell bei mehreren Anweisungsdateien: AGENTS.md für Codex, CLAUDE.md für Claude Code, dazu Cursor-Rules und oft noch eine GEMINI.md. Der offene Standard dafür heißt AGENTS.md. Laut der Seite agents.md nutzen ihn über 60.000 Open-Source-Projekte. Dieser Beitrag vergleicht anhand der Herstellerdokumentation, welche Datei welcher Agent tatsächlich liest, wo sich die Formate überschneiden und wie ihr eine gemeinsame Anleitung aufsetzt, ohne dass sich die Werkzeuge widersprechen.
Was AGENTS.md ist
AGENTS.md ist eine gewöhnliche Markdown-Datei ohne Pflichtfelder. Die offizielle Beschreibung lautet: eine README für Agenten. Während die menschliche README den Schnellstart und die Beitragsregeln trägt, liegen in AGENTS.md typischerweise Build- und Testbefehle, Konventionen, Testhinweise und Sicherheitsregeln, also alles, was ein Coding-Agent bei jeder Aufgabe braucht und eine README unnötig aufblähen würde.
OpenAI hat das Format im August 2025 veröffentlicht. Seit der Gründung der Agentic AI Foundation am 9. Dezember 2025 liegt es unter dem Dach der Linux Foundation, zusammen mit dem Model Context Protocol und dem Agent-Framework goose. Das steht in der Mitteilung der Linux Foundation. Die Datei bleibt bewusst schlicht: beliebige Überschriften, reiner Text, verschachtelte Dateien in Unterprojekten. Laut agents.md gilt bei widersprüchlichen Anweisungen die jeweils nächstgelegene Datei; explizite Hinweise im Chat gehen vor.
Welche Datei welcher Agent liest
Die folgende Übersicht stützt sich auf die Dokumentation von Codex, Claude Code, Cursor und Gemini CLI, Stand 21. November 2026. Sie ist kein Hands-on-Test. Wo ein Hersteller ein Format in seinen Docs nicht erwähnt, steht das ausdrücklich so.
| Datei | Codex | Claude Code | Cursor | Gemini CLI |
|---|---|---|---|---|
AGENTS.md |
Ja, plus AGENTS.override.md |
Ab v2.1.277, standardmäßig nur ohne CLAUDE.md |
Ja, im Projektstamm und in Unterordnern | Nur nach Konfiguration |
CLAUDE.md |
Nur als Fallback, wenn konfiguriert und in diesem Ordner keine AGENTS.md liegt |
Ja, die eigene Datei | Ja, wird in jeder Unterhaltung angewendet | Nur nach Konfiguration |
.cursor/rules/*.mdc |
In den Docs nicht erwähnt | In den Docs nicht erwähnt | Ja, mit vier Anwendungsmodi | In den Docs nicht erwähnt |
GEMINI.md |
Nur als Fallback, wenn konfiguriert | In den Docs nicht erwähnt | In den Docs nicht erwähnt | Ja, die Standarddatei |
.claude/rules/ |
In den Docs nicht erwähnt | Ja, auch pfadbezogen | In den Docs nicht erwähnt | In den Docs nicht erwähnt |
Die Unterschiede sitzen in den Randfällen. Wer nur eine der Dateien pflegt, hat oft das Gefühl, alle Agenten seien informiert. Sobald zwei Dateien nebeneinanderliegen, liest aber nicht jedes Werkzeug dasselbe.
Die Besonderheit bei Claude Code
Claude Code kann AGENTS.md seit Version 2.1.277 direkt lesen. Die Dokumentation zu Projektanweisungen macht den Standardfall klar: Existiert im Arbeitsverzeichnis oder darüber eine CLAUDE.md, eine .claude/CLAUDE.md oder eine CLAUDE.local.md, lädt Claude unter der Voreinstellung claude-md-or-agents-md nur die Claude-Dateien und überspringt AGENTS.md. Ein persönliches CLAUDE.local.md, das lokale, nicht committete Hinweise halten soll, reicht dafür bereits aus.
Es gibt drei praxisnahe Auswege, alle aus derselben Dokumentation:
- Keine projekteigene
CLAUDE.mdanlegen, wenn AGENTS.md die einzige Quelle sein soll. Die persönliche Datei~/.claude/CLAUDE.mdund Dateien unter.claude/rules/zählen bei dieser Prüfung nicht mit und bleiben neben AGENTS.md geladen. - Eine schlanke
CLAUDE.mdmit dem Import@AGENTS.mdanlegen. Claude zieht die gemeinsame Datei dann über den Import und liest sie nicht doppelt, unabhängig von der Einstellung. - Unter
/configdie Projekteinstellung aufclaude-md-and-agents-mdstellen, wenn Claude beide Dateien nacheinander lesen soll.
Anthropic warnt ausdrücklich: Widersprechen sich zwei Anweisungen, kann Claude eine beliebig auswählen. Deshalb gehören Claude-spezifische Regeln besser nach .claude/rules/, nicht in die gemeinsame AGENTS.md. In manchen Sitzungen, etwa vor v2.1.277 oder wenn das eingebaute Plugin deaktiviert ist, liest Claude AGENTS.md gar nicht direkt. Der Import aus einer CLAUDE.md bleibt dann der robuste Weg.
Cursor Rules und CLAUDE.md
Cursor behandelt AGENTS.md als einfache Alternative zu den Projektregeln. Laut den Cursor-Docs zu Rules liegen die Dateien im Projektstamm und in Unterordnern; Anweisungen werden mit denen der übergeordneten Ordner kombiniert, die spezifischere Datei hat Vorrang.
Daneben bleiben die strukturierten Projektregeln in .cursor/rules/ das Mittel für Fälle, die AGENTS.md nicht abdeckt. Es sind Markdown-Dateien mit der Endung .mdc und YAML-Frontmatter. Eine gewöhnliche .md-Datei in diesem Ordner ignoriert Cursor. Es gibt vier Modi: immer anwenden, intelligent anhand der Beschreibung, nur bei passenden Dateipfaden oder manuell per Erwähnung im Chat. Die Docs halten fest, dass diese Regeln den Cursor-Tab und andere KI-Funktionen außerhalb des Agent-Chats nicht beeinflussen.
In der Cursor-Hilfe zu Rules stehen zwei weitere Punkte, die in gemischten Teams leicht untergehen. Erstens liest Cursor CLAUDE.md wie AGENTS.md und wendet sie in jeder Unterhaltung an, unabhängig von einem alwaysApply-Frontmatter. Ein ausführliches CLAUDE.md mit Claude-only-Hinweisen landet damit auch in Cursor. Zweitens gilt die Datei .cursorrules im Projektstamm als veraltet und soll durch eine Regel vom Typ „Always Apply“ in .cursor/rules/ ersetzt werden.
Team Rules stehen in Cursor auf Team- und Enterprise-Tarifen zur Verfügung und gehen bei Konflikten vor Projekt- und Benutzerregeln. Werkzeugspezifische, pfadbezogene Hinweise gehören deshalb in .cursor/rules/, gemeinsame Konventionen nach AGENTS.md.
Gemini CLI und GEMINI.md
Die Gemini CLI lädt standardmäßig GEMINI.md: global aus ~/.gemini/GEMINI.md, dann aus dem Arbeitsbereich und seinen übergeordneten Ordnern, zusätzlich just-in-time, wenn ein Werkzeug ein Verzeichnis berührt. Die Gemini-CLI-Dokumentation zu Kontextdateien zeigt, wie sich der Dateiname in settings.json umstellen lässt, etwa so:
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}
Ohne diesen Eintrag sieht die CLI eine vorhandene AGENTS.md nicht. Wer Gemini-spezifische Hinweise behalten will, kann GEMINI.md in der Liste lassen und dort nur das ablegen, was die anderen Agenten nicht brauchen.
So setzt ihr eine gemeinsame Anleitung auf
Aus den genannten Docs ergibt sich ein Setup, das in gemischten Teams stabil bleibt:
- Gemeinsame Konventionen, Build- und Testbefehle und Sicherheitsregeln liegen in einer
AGENTS.mdim Repository-Stamm. In einem Monorepo kommt je Paket eine eigene, nähere Datei dazu. - Codex liest diese Datei von allein, inklusive verschachtelter Dateien und optionaler
AGENTS.override.md. Die Entdeckung beschreibt der Codex-Leitfaden zu AGENTS.md: zuerst global unter~/.codex, dann vom Projektstamm bis zum aktuellen Verzeichnis, später im kombinierten Text stehende Dateien überschreiben frühere. Standardmäßig endet die Kette bei 32 KiB. - Für Claude Code liegt neben jeder AGENTS.md eine schlanke
CLAUDE.mdmit nur einer Zeile@AGENTS.md. Das funktioniert auch in Sitzungen, die AGENTS.md nicht direkt laden, und verhindert, dass eine zusätzlicheCLAUDE.local.mddie gemeinsame Datei verdrängt, sofern ihr nicht beide Dateien explizit laden wollt. - Cursor liest AGENTS.md nativ. Claude-spezifischen Text haltet ihr aus der
CLAUDE.mdheraus, weil Cursor diese Datei ebenfalls immer anwendet. Glob-bezogene Cursor-Regeln gehören nach.cursor/rules/. - In der Gemini CLI tragt ihr
AGENTS.mdincontext.fileNameein, wenn das Team die CLI nutzt.
Dieses Muster trennt die gemeinsame Quelle von den werkzeugspezifischen Erweiterungen. Gerade wenn im Team auch grafische Oberflächen für Terminal-Agenten im Spiel sind, bleibt die Anweisung im Repository die stabile Schicht, unabhängig davon, welche Oberfläche jemand gerade nutzt. Einen Vergleich solcher Oberflächen haben wir unter Orca vs Monocode vs T3 Code zusammengestellt. Welche Ausführungsumgebung die Erfolgsrate stärker prägt als das Modell, thematisiert der Vergleich der Coding-Agent-Harnesses. Claude-eigene Erweiterungen jenseits der Anweisungsdatei beschreibt der Beitrag zu den Claude Code Mods.
Was in die Datei gehört
agents.md empfiehlt als typische Abschnitte einen Projektüberblick, Build- und Testbefehle, Stilregeln, Testhinweise und Sicherheitsaspekte. Dazu können Commit- oder Pull-Request-Regeln, Stolperfallen und Hinweise zu großen Datenbeständen kommen, also alles, was ihr einem neuen Teammitglied ebenfalls sagen würdet. Die Datei soll lebendige Dokumentation bleiben, keine einmal geschriebene Richtlinie.
Drei Punkte aus den Herstellerdocs lohnen sich als Schreibregeln:
- Kurz und konkret bleiben. Claude Code betont, dass knappe, spezifische Anweisungen zuverlässiger greifen als lange Essays. Codex begrenzt die geladene Menge standardmäßig auf 32 KiB; zu lange Dateien werden abgeschnitten oder sollten auf Unterordner verteilt werden.
- Prüfbare Schritte in die CI legen, nicht in die Agenten-Datei. Codex empfiehlt, Formatierung und mechanische Checks in der Pipeline zu halten und in AGENTS.md die Urteile festzuhalten, die ein Review sonst immer wieder erklären müsste.
- Widersprüche vermeiden. Liegen in einem Repository AGENTS.md und ein ausführliches
CLAUDE.mdmit abweichendem Testbefehl, folgt Claude dem einen, Codex dem anderen, und Cursor kann beide Texte gleichzeitig sehen.
Ein knappes Gerüst kann so aussehen:
# AGENTS.md
## Überblick
- App unter `apps/web`, API unter `apps/api`.
## Build und Tests
- Abhängigkeiten: `pnpm install`
- Tests: `pnpm test`
- Lint: `pnpm lint`
## Konventionen
- Neuer Code in TypeScript, bestehende Muster im Verzeichnis übernehmen.
- Öffentliche Funktionen dokumentieren, wenn sich das Verhalten ändert.
## Sicherheit
- Keine Geheimnisse in die Versionskontrolle schreiben.
- Produktionsabhängigkeiten nicht ohne Rückfrage hinzufügen.
AGENTS.md ersetzt weder eine menschliche README noch CI und Code-Review. Sie gibt den Agenten eine gemeinsame, vorhersagbare Stelle für das, was sie bei jeder Aufgabe wissen müssen. Wer die gemeinsame Datei pflegt und werkzeugspezifische Regeln in den nativen Ordnern belässt, muss Konventionen nicht in drei Formaten wiederholen.



