Cursor Rules vs. CLAUDE.md vs. AGENTS.md: Wir haben eine Config durch alle drei laufen lassen (2026)

Cursor Rules vs. CLAUDE.md vs. AGENTS.md: Wir haben eine Config durch alle drei laufen lassen (2026)

Die Frage Cursor Rules vs. CLAUDE.md enthält von Anfang an eine Falle: Es sind keine zwei Optionen, zwischen denen man wählt. Es sind zwei Dateien, gelesen von zwei unterschiedlichen Tools, die zufällig denselben Job erledigen. Legt man eine CLAUDE.md in ein Cursor-Projekt, ignoriert Cursor sie einfach. Legt man eine AGENTS.md in Claude Code ab, passiert ebenfalls nichts. Das hat uns selbst überrascht. AGENTS.md steckt inzwischen in über 60.000 Repos als offener Standard, betreut von der Agentic AI Foundation unter der Linux Foundation, doch Claude Code liest die Datei bis heute nicht von allein. Hier ist die Kompatibilitätskarte, getestet an unserem eigenen Repo.

Key Takeaways

• Cursor liest .cursor/rules/*.mdc und AGENTS.md, aber nicht CLAUDE.md.
• Claude Code liest ausschließlich CLAUDE.md, nicht nativ AGENTS.md.
• Für eine gemeinsame Datei: AGENTS.md per Symlink auf CLAUDE.md legen oder mit @AGENTS.md importieren.
• Standardisiert auf AGENTS.md (offener Standard, 60k+ Repos) und ergänzt tool-spezifische Overrides.

Welches Config-Format solltet ihr nutzen? Die 30-Sekunden-Entscheidung

Wählt das Format nach eurer Teamstruktur, nicht nach Hype. Nutzt ihr nur ein Tool, verwendet dessen native Datei. Setzt ihr zwei oder mehr ein, macht AGENTS.md zur Quelle der Wahrheit und ergänzt Tool-spezifische Overrides nur dort, wo ein Tool etwas braucht, das die anderen nicht brauchen. Diese eine Regel klärt die meiste Verwirrung.

Steht ihr noch vor der Wahl des Assistenten, bevor die Config überhaupt eine Rolle spielt? Startet mit unserem Leitfaden zur Wahl des richtigen KI-Coding-Agenten und kommt danach für das Datei-Setup zurück.

Die entscheidende Achse ist Portabilität. Eine .cursor/rules-Datei ist innerhalb von Cursor mächtig und außerhalb davon nutzlos. Eine AGENTS.md reist mit. Wenn ihr also nicht für immer an ein Tool gebunden seid, ist die tool-unabhängige Datei die sicherere Wahl.

Was jedes Format eigentlich ist (in je 30 Sekunden)

Diese drei Dateien machen alle dasselbe: Sie geben einem KI-Coding-Tool die Regeln, Konventionen und Stolperfallen eures Projekts, bevor es die erste Zeile schreibt. Der Unterschied liegt darin, wer sie liest und wie der Geltungsbereich definiert ist. Hier die Kurzversion. Die ausführliche Anleitung zu jedem Format lebt in einem eigenen Guide.

Cursor Rules sind .mdc-Dateien innerhalb von .cursor/rules/. Cursor unterstützt vier Regeltypen (always-on, agent-requested, glob-scoped und manuelles @-Mention), sodass ihr eine Regel gezielt an eure *.tsx-Dateien oder nur an eure Migrationen hängen könnt. Zu Frontmatter, Globs und Token-Budget lest unseren Guide Wie man .cursor/rules-Dateien tatsächlich schreibt.

CLAUDE.md ist die Memory-Datei von Claude Code. Claude läuft vom Arbeitsordner aus den Verzeichnisbaum nach oben und hängt jede gefundene CLAUDE.md aneinander. Es ist reines Markdown, kein Frontmatter nötig. Struktur und die Regeln, die dafür sorgen, dass Claude die Datei nicht ignoriert, findet ihr unter was eine CLAUDE.md ausmacht, die Claude nicht ignoriert.

AGENTS.md ist der offene Standard. Eine einzige Plain-Markdown-Datei im Repo-Root, nativ gelesen von Cursor, Codex, Copilot, Windsurf, Zed, Aider und Dutzenden weiteren Tools. Sie wird von der Agentic AI Foundation betreut und lebt bereits in über 60.000 Projekten.

Hier die Neurahmung, die man sich merken sollte: AGENTS.md, CLAUDE.md und .cursor/rules sind keine Konkurrenten, sondern dieselbe Anweisung, adressiert an unterschiedliche Leser.

Cursor Rules vs. CLAUDE.md vs. AGENTS.md: Der große Vergleich

Am schnellsten sieht man den Unterschied nebeneinander. Die entscheidende Spalte ist die Portabilität: Welche Tools lesen die Datei ohne zusätzliches Setup. AGENTS.md gewinnt bei der Reichweite, Cursor Rules bei der Präzision der Geltungsbereiche, und CLAUDE.md gewinnt für alle, die voll auf Claude Code setzen.

Beachtet die Zeile zu .cursorrules. Diese einzelne Root-Datei funktioniert in Cursor noch, ist aber aus der Dokumentation verschwunden, also behandelt sie als Legacy. Neue Projekte sollten stattdessen .cursor/rules/*.mdc oder AGENTS.md nutzen.

Welches Tool liest welche Datei? (Der AGENTS.md-Mythos im Faktencheck)

Hier die Tatsache, die die halbe Internet-Community falsch versteht: Claude Code liest AGENTS.md nicht nativ, und Cursor liest kein CLAUDE.md. Cursor liest .cursor/rules/*.mdc plus AGENTS.md. Claude Code liest ausschließlich CLAUDE.md. In keine Richtung gibt es einen automatischen Fallback, was Teams stolpern lässt, die annehmen, eine Standarddatei würde alles abdecken.

Das wird ständig gefragt, also seien wir deutlich. Eine AGENTS.md in ein Claude-Code-Projekt zu legen, bewirkt für sich genommen gar nichts. Claude Code liest CLAUDE.md und nur CLAUDE.md. Anthropics Claude Code Memory-Dokumentation beschreibt das Ladeverhalten ohne jede Erwähnung von AGENTS.md, die AGENTS.md-Spezifikation listet Cursor und Codex als native Reader, aber nicht Claude Code, Cursors eigene Rules-Dokumentation bestätigt die Trennung, und die Claude Code GitHub Issues sind voll von Entwicklern, die genau gegen diese Wand laufen.

Liest Cursor also claude.md? Nein. Liest Claude Code agents.md? Nicht ohne Hilfe. Genau diese "Hilfe" ist der ganze Grund, warum dieser Beitrag existiert, und sie besteht aus zwei kurzen Befehlen, die gleich kommen.

Wie Vorrang & Verschachtelung funktionieren, im Vergleich

Jedes Tool löst Konflikte unterschiedlich auf, und genau das ist die häufigste Ursache für "warum wird meine Regel ignoriert?"-Verwirrung. Cursor führt Regeln nach Quellpriorität zusammen. Claude Code hängt sie nach Verzeichnistiefe aneinander. AGENTS.md wählt die nächstgelegene Datei im Baum. Gute CLAUDE.md-Verwaltung beginnt damit, zu wissen, in welchem mentalen Modell man sich gerade befindet.

In unserem Setup ist die praktische Konsequenz einfach: breite Regeln nach oben (Repo-Root), spezifische Regeln nach unten (in einen Paketordner). Sowohl bei Claude Code als auch bei AGENTS.md hat die Datei Vorrang, die am nächsten am Arbeitsort liegt, sodass eine packages/api/AGENTS.md die Root-Datei für alles innerhalb dieses Ordners überschreibt. Cursor ist der Ausreißer und löst nach Quell-Ebene auf, nicht nach Ordnertiefe.

Wir haben eine Config durch Cursor + Claude Code laufen lassen, das hat jedes Tool wirklich geladen

Wir haben das an einem echten Techsy-Kunden-Repo getestet (ein Next.js-15-Backend) mit Cursor 3.7 (Build vom 17. Juni 2026) und Claude Code v2.1.x (Anfang Juli 2026). Eine AGENTS.md, drei Sharing-Setups, derselbe Prompt in beiden Tools geöffnet. Hier genau, was jedes Tool tatsächlich geladen hat.

Wir starteten mit einer minimalen Datei:

# AGENTS.md
- Package manager: pnpm, never npm.
- Tests: Vitest. Run `pnpm test` before any commit.
- DB access goes through `lib/db.ts` only, no inline SQL.

Setup 1: Nur AGENTS.md. Cursor hat sie sofort aufgenommen. Die Datei tauchte im Kontext auf, und Cursor weigerte sich korrekt, npm install vorzuschlagen. Claude Code tat damit gar nichts. /memory in Claude Code listete null Projekt-Memory-Dateien: keine CLAUDE.md gefunden, und AGENTS.md wurde nicht einmal erwähnt. Bestätigt: kein nativer Fallback.

Setup 2: Symlink. Wir haben CLAUDE.md auf dieselbe Datei verweisen lassen:

ln -s AGENTS.md CLAUDE.md

Jetzt listete /memory in Claude Code ./CLAUDE.md als Project Memory, und der geladene Inhalt war unsere AGENTS.md byteidentisch. Cursor las weiterhin direkt AGENTS.md. Eine physische Datei, beide Tools zufrieden. Unter Windows braucht es dafür Admin-Rechte oder aktivierten Developer Mode, sonst schlägt ln/mklink stillschweigend fehl.

Setup 3: @-Import. Wir haben den Symlink gelöscht und stattdessen eine einzige Zeile ganz oben in eine echte CLAUDE.md gesetzt:

@AGENTS.md

/memory zeigte daraufhin CLAUDE.md als geladene Datei, mit AGENTS.md darunter als importierte Referenz eingebunden. Das ist der Weg, den Anthropic tatsächlich dokumentiert, und er braucht keine besonderen Betriebssystem-Rechte.

Das Fazit aus unserem Test: Der Symlink lässt Claude Code AGENTS.md byteidentisch lesen; der @AGENTS.md-Import ist die Windows-sichere Variante, die Anthropic tatsächlich empfiehlt. Beide geben euch eine einzige Quelle der Wahrheit. Wählt den Symlink auf macOS/Linux für null Indirektion, oder die Import-Zeile, wenn jemand im Team auf Windows arbeitet.

Zwischen Formaten migrieren: .cursorrules → .cursor/rules → AGENTS.md

Die meisten Teams landen hier mit einer alten .cursorrules-Datei und wollen aus der Einzeldatei-Falle raus. Die Migration ist in jede Richtung kurz, und die Schritte sind Copy-Paste. Die eine Stolperfalle, die viele erwischt: Eine .md-Datei innerhalb von .cursor/rules wird ohne Frontmatter stillschweigend ignoriert, sie muss also .mdc sein.

Um eine alte .cursorrules zu modernisieren, gibt es zwei saubere Wege:

• Zu .cursor/rules/*.mdc: erstellt .cursor/rules/general.mdc, fügt Frontmatter hinzu (alwaysApply: true für eine globale Regel) und fügt euren alten Inhalt darunter ein. Löscht .cursorrules, sobald alles geprüft ist.
• Zu AGENTS.md (empfohlen für Multi-Tool-Teams): Um cursorrules in agents.md umzuwandeln, kopiert den Inhalt von .cursorrules in eine neue AGENTS.md am Repo-Root. Kein Frontmatter nötig, es ist reines Markdown. Dann ergänzt den Symlink oder den @AGENTS.md-Import, damit Claude Code sie ebenfalls liest.

Wenn ihr bei Cursor bleibt und mehr rausholen wollt, deckt unser Guide wie ihr im Alltag mehr aus Cursor herausholt die praktische Regel-Scoping-Anwendung ab.

Der umgekehrte Weg (AGENTS.md → CLAUDE.md) ist einfach der Symlink oder Import aus dem letzten Abschnitt. Es gibt keine verlustbehaftete Konvertierung, weil alle drei unter der Haube Markdown sind.

Wo passen SKILL.md und Copilot Instructions rein?

Zwei weitere Formate tauchen in dieser Diskussion auf, und SKILL.md ist gerade ein Suchbegriff im Aufwind, daher lohnt sich eine kurze Einordnung. Keines der beiden ersetzt die drei Hauptdateien, sie stehen daneben.

SKILL.md ist Anthropics Skills-Format: aufgabenspezifische Anweisungen, gebündelt in .claude/skills/*/SKILL.md, die Claude bei Bedarf lädt, wenn eine Aufgabe passt, statt immer aktiv wie CLAUDE.md. Stellt es euch als spezialisiertes Playbook vor, zu dem Claude greift, nicht als projektweite Memory-Datei. Der Umfang ist noch im Wandel, also investiert noch nicht zu viel hinein. Wie es in einen echten Workflow passt, zeigt wo CLAUDE.md in einen echten Claude-Code-Workflow passt.

Copilot Instructions liegen in .github/copilot-instructions.md für GitHub Copilot. Die gute Nachricht: Copilot liest ebenfalls AGENTS.md, wenn ihr also bereits auf den offenen Standard setzt, ist Copilot ohne separate Datei mit abgedeckt.

Welches Format solltet ihr nutzen? (Nach Teamstruktur)

Passt das Format daran an, wie euer Team tatsächlich arbeitet:

• Solo-Claude-Code-User: nutzt einfach CLAUDE.md. Kein Grund, AGENTS.md hinzuzufügen, außer ihr plant, später Cursor oder Codex einzubinden.
• Solo-Cursor-User: .cursor/rules/*.mdc für das Glob-Scoping, oder eine einzelne AGENTS.md, wenn ihr von Anfang an Portabilität wollt.
• Team mit gemischten Tools: eine AGENTS.md als Quelle der Wahrheit, per Symlink oder Import in CLAUDE.md eingebunden. Fügt eine kleine .cursor/rules-Datei nur für cursor-spezifisches Verhalten hinzu.
• Monorepo: AGENTS.md im Root plus verschachtelte Dateien pro Paket, sodass jedes Teilprojekt sich selbst beschreibt und die nächstgelegene Datei gewinnt.

Bei Techsy standardisieren wir AI-Coding-Configs für Teams mit gemischten Tools, meist mit einer AGENTS.md als Quelle der Wahrheit und Tool-spezifischen Overrides dort, wo sie gebraucht werden. Wenn euer Team gerade drei Config-Dateien von Hand jongliert, holt euch eine kostenlose Beratung und wir bringen Ordnung rein.

Ein letzter Hinweis: Dieser Beitrag vergleicht die Config-Dateien. Wenn ihr euch eigentlich zwischen den Tools selbst entscheiden wollt, lest der Vergleich der Assistenten selbst, nicht ihrer Config.

Frequently Asked Questions

Liest Cursor CLAUDE.md?

Nein. Cursor liest nativ .cursor/rules/*.mdc und AGENTS.md, aber CLAUDE.md wird in der Cursor-Dokumentation nirgends erwähnt und auch nicht geladen. Wenn ihr Cursor nutzt und eure Config mit Claude-Code-Usern teilen wollt, packt eure Regeln in AGENTS.md (die Cursor liest) statt in CLAUDE.md.

Liest Claude Code AGENTS.md?

Nicht nativ. Claude Code liest ausschließlich CLAUDE.md, ohne automatischen Fallback auf AGENTS.md. Damit es funktioniert, entweder die Dateien per Symlink verbinden (ln -s AGENTS.md CLAUDE.md), sodass Claude AGENTS.md byteidentisch liest, oder @AGENTS.md in Zeile 1 einer CLAUDE.md einfügen, um sie zu importieren. Der Import ist die von Anthropic empfohlene, Windows-sichere Option.

Kann ich einfach eine Datei für alle drei Tools nutzen?

Ja. Macht AGENTS.md zu eurer einzigen Quelle der Wahrheit, Cursor und Codex lesen sie direkt. Für Claude Code braucht ihr eine Brücke: entweder AGENTS.md per Symlink auf CLAUDE.md legen oder @AGENTS.md oben in eine CLAUDE.md setzen. Ihr pflegt eine Datei, und jedes Tool lädt dieselben Regeln. Das ist das komplette Rezept für eine gemeinsame Config.

Ist .cursorrules veraltet?

Sanft veraltet. Die einzelne .cursorrules-Datei im Repo-Root funktioniert in Cursor noch, steht aber nicht mehr in der offiziellen Dokumentation, was üblicherweise das Zeichen ist, dass ein Format auf dem Weg raus ist. Neue Projekte sollten .cursor/rules/*.mdc für gescopte Regeln oder AGENTS.md für Portabilität nutzen.

Wie konvertiere ich .cursorrules zu AGENTS.md?

Kopiert den Inhalt eurer .cursorrules-Datei in eine neue AGENTS.md am Repo-Root. Es ist reines Markdown, also braucht es kein Frontmatter und keine Neuformatierung. Fügt danach einen Symlink oder @AGENTS.md-Import hinzu, damit Claude Code sie ebenfalls liest, und löscht die alte .cursorrules, sobald bestätigt ist, dass Cursor die neue Datei aufnimmt.

Was ist der Unterschied zwischen CLAUDE.md und AGENTS.md?

CLAUDE.md ist Claude Codes proprietäre Memory-Datei, die nur von Claude Code gelesen wird. AGENTS.md ist ein offener Standard, gelesen von Cursor, Codex, Copilot und 20+ weiteren Tools, aber nicht nativ von Claude Code. Gleiches Markdown-Format, gleicher Job. Der Unterschied liegt in der Reichweite. AGENTS.md reist über Tools hinweg, CLAUDE.md bleibt innerhalb von Claude Code.

Auf welches Format sollte ein Team mit mehreren KI-Tools standardisieren?

AGENTS.md. Es ist der offene Standard, nativ von den meisten Tools gelesen und bereits in über 60.000 Repos im Einsatz. Standardisiert eure gemeinsamen Regeln dort, verbindet sie per Symlink oder Import mit Claude Code, und ergänzt kleine tool-spezifische Dateien (wie .cursor/rules) nur dort, wo ein Tool ein Verhalten braucht, das die anderen nicht haben.

Wie funktioniert der Vorrang bei verschachtelten Config-Dateien?

Sowohl bei Claude Code als auch bei AGENTS.md gewinnt die Datei, die eurem Arbeitsverzeichnis am nächsten liegt, sodass eine Regel in packages/api/AGENTS.md die Root-Datei für alles innerhalb dieses Ordners überschreibt. Cursor tickt anders: Es führt Team-, Projekt- und User-Regeln nach Quell-Ebene zusammen statt nach Ordnertiefe, wobei frühere Quellen Konflikte gewinnen.

Wo passt SKILL.md rein?

SKILL.md ist Anthropics aufkommendes Skills-Format: aufgabenspezifische Anweisungen in .claude/skills/*/SKILL.md, die Claude bei Bedarf lädt, wenn eine Aufgabe passt, statt immer aktiv wie CLAUDE.md. Es ergänzt CLAUDE.md, statt es zu ersetzen. Der Umfang ist 2026 noch im Wandel, behandelt es also als spezialisierte Erweiterung, nicht als vierte Datei, die jedes Projekt braucht.