AGENTS.md vs CLAUDE.md erklärt

Problem: Du öffnest einen Repo, der sowohl eine AGENTS.md als auch eine CLAUDE.md hat. Sie sehen ähnlich aus. Sie sagen ähnliche Dinge. Du weißt nicht, welche Claude Code liest, welche die anderen Tools lesen und warum zwei Dateien überhaupt existieren.

Quick Win: Claude Code liest CLAUDE.md. Jedes andere große KI-Tool liest AGENTS.md. Wenn du nur Claude Code nutzt, brauchst du nur CLAUDE.md. Wenn dein Team mehrere Tools nutzt, sorgt ein Symlink dafür, dass beide Tools dieselbe Datei lesen:

ln -s CLAUDE.md AGENTS.md

Eine einzige Quelle der Wahrheit. Keine Duplikation.

Was AGENTS.md wirklich ist

AGENTS.md ist ein Cross-Tool-Standard, veröffentlicht von der Linux Foundation und der Agent Interoperability Initiative Foundation (AAIF). Das Ziel ist eine einzige Kontextdatei, die jedes KI-Coding-Tool lesen kann, wenn es deinen Repo öffnet.

Stand April 2026 unterstützen 18+ Tools es. OpenAI Codex, Gemini CLI, Devin, Cursor, Windsurf, Continue, Amp, Warp und Goose lesen alle AGENTS.md. Es ist in über 60.000 GitHub-Projekten aktiv.

Die AAIF-Spec definiert ein Schema für die Datei: Felder wie allowed_tools, disallowed_tools, agent_instructions, output_format und environment. Jedes Tool liest die Felder, die es versteht, und überspringt die, die es nicht versteht.

Claude Code ignoriert diese Schema-Felder vollständig. Es hat sein eigenes Permission-System in settings.json. Wenn es AGENTS.md-Inhalte aufnimmt (via Import), liest es die Prosa-Anweisungen und ignoriert die strukturierten Felder.

Was CLAUDE.md wirklich ist

CLAUDE.md ist Claude Codes native Kontext-Datei. Jede Session lädt sie, bevor das erste Gesprächstoken kommt.

Die Datei ist keine Dokumentation, die Claude lesen soll. Sie ist der Betriebsparameter dafür, wie Claude läuft. Leg deine Workflows, Routing-Logik, Qualitätsregeln und Delegationsmuster hier ab. Projektdokumentation, Stack-Notizen und Technologie-Spezifika gehören in Skills, die bei Bedarf geladen werden.

Zielgröße: 200-500 Zeilen für ein Solo-Setup. 50-100 Zeilen für eine geteilte Team-Datei, bei der jeder Mitwirkende verstehen muss, was drin ist.

Die 6-Ebenen-Prioritätshierarchie

Claude Code lädt nicht nur eine Datei. Es lädt einen Stapel von Dateien und löst sie in Reihenfolge auf. Innen gewinnt über außen:

Ebene 1 setzt globale Standardwerte. Ebene 2 setzt Repo-Regeln. Ebene 3 enthält maschinenspezifische Dinge, die deinen Laptop nie verlassen sollten.

Der CLAUDE.local.md-Fallstrick: Claude Code fügt diese Datei nicht automatisch zu .gitignore hinzu. Du musst das selbst tun. Wenn du es vergisst, trackt git sie und sie kommt mit deinem nächsten Commit hoch. Gute Kandidaten für die Datei: lokale API-Endpoints, persönliche Debugging-Präferenzen, Sandbox-URLs. Keines davon gehört in den geteilten Baum.

@imports und die Brücke zu AGENTS.md

In jeder CLAUDE.md-Datei kannst du eine andere Datei mit @path/to/file.md einbinden. Der importierte Inhalt wird dort injiziert, wo die @-Zeile sitzt.

So lässt dich Claude Code 2.1.59+ AGENTS.md überbrücken:

# CLAUDE.md
@AGENTS.md
<!-- Claude reads AGENTS.md content here, but CLAUDE.md rules below take priority -->

## Claude-specific rules
- Use TodoWrite to track multi-step tasks
- Never use --dangerously-skip-permissions outside containers

Der importierte AGENTS.md-Inhalt wird geladen. Aber Ebene 6 (Imports) ist die schwächste Ebene in der Hierarchie. Wenn eine Regel in AGENTS.md mit einer direkt in CLAUDE.md geschriebenen Regel in Konflikt steht, gewinnt immer die direkte Regel.

Das bedeutet, AGENTS.md-Inhalte sind immer advisory, wenn sie via Import eingebracht werden. Sie informieren Claudes Verhalten. Sie überschreiben nicht, was du in der Root-Datei geschrieben hast.

Der Symlink-Trick

Das sauberste Multi-Tool-Setup vermeidet die Import-Komplexität vollständig. Führe das einmal im Repo-Root aus:

ln -s CLAUDE.md AGENTS.md

Jetzt ist AGENTS.md ein Symlink, der auf CLAUDE.md zeigt. Claude Code liest CLAUDE.md. Cursor, Windsurf, Gemini CLI und jedes andere AGENTS.md-bewusste Tool liest AGENTS.md. Alle treffen dieselben Bytes.

Keine Duplikation. Kein Sync-Problem. Eine Datei zu pflegen.

Der einzige Trade-off: Claude Code ignoriert AGENTS.md-Schema-Felder, und AGENTS.md-bewusste Tools ignorieren Claude Code-spezifische Anweisungen (wie TodoWrite oder --dangerously-skip-permissions-Flags). In der Praxis ist das in Ordnung. Prosa-Anweisungen funktionieren für beide. Schema-Felder werden einfach übersprungen.

Auto-Memory und MEMORY.md

Claude Code 2.1.59+ kann selbstständig in eine MEMORY.md-Datei in deinem Projekt-Root schreiben. Diese Datei liegt auf Ebene 5, derselben Priorität wie deine Repo-Level-CLAUDE.md.

Die Datei hat harte Limits: 200 Zeilen und 25 KB. Für On-Demand-Topic-Dateien (wie memory/auth.md oder memory/payments.md) liegt die Obergrenze bei jeweils 120 Zeilen. MEMORY.md selbst fungiert als Index, der auf diese Topic-Dateien zeigt.

Worauf du achten solltest: Memory-Einträge, die sich gegenseitig widersprechen, verursachen stille Ambiguität. Claude wirft keinen Fehler. Es hat einfach zwei widersprüchliche Anweisungen und löst sie still auf, was möglicherweise nicht deinen Erwartungen entspricht. Überprüfe MEMORY.md regelmäßig. Entferne Einträge, die älter als 30 Tage sind und nicht wieder aufgetreten sind.

Die 7 Wege, wie CLAUDE.md schiefläuft

Die meisten Teams schreiben eine CLAUDE.md einmal und überarbeiten sie nie wieder. Das sind die Fehlermodi, die sich im Laufe der Zeit ansammeln:

Prioritätssättigung: Zu viele ALWAYS- und NEVER- und CRITICAL-Labels. Wenn jede Regel schreit, landet keine. Claude behandelt überladene Dateien, indem es Aufmerksamkeit gleichmäßig auf alle Regeln verteilt. Halte harte Einschränkungen auf maximal 5-7.

Der "may or may not be relevant"-Wrapper: Wenn Claude Code Session-Kontext injiziert, verpackt es ihn manchmal in diesen Vorbehalt. Dieser Wrapper signalisiert, dass der Inhalt geladen wurde, aber als Hintergrund behandelt wird, nicht als Anweisungen. Dateien mit diesem Wrapper werden nicht genau befolgt.

Import-Tiefen-Verwässerung: Anweisungen in einer importierten Datei sind schwächer als direkt geschriebene Anweisungen. Eine Kette wie CLAUDE.md → @a.md → @b.md ist sehr verwässert, bis du b.md erreichst. Halte wichtige Regeln in der Root-Datei.

Trauma-Replay: MEMORY.md sammelt jede Korrektur an, die du je gemacht hast. Nach 50 Sessions versucht Claude, 50 verschiedene vergangene Fehler gleichzeitig zu vermeiden. Die Performance degradiert. Regelmäßige Audits beheben das.

Bias-Akkumulation: Positive Bestätigungen, die in die Memory geschrieben werden ("Nutzer bevorzugt X"), können sich zu Regeln verfestigen, die nicht mehr deinen aktuellen Präferenzen entsprechen. Was du vor sechs Monaten bevorzugtest, ist vielleicht nicht das, was du heute bevorzugst.

Anweisungs-Befolgung vs. Durchsetzung: CLAUDE.md wird als Kontext geladen, nicht wie ein Linter durchgesetzt. Eine Regel, die sagt "verwende nie Gedankenstriche", kann trotzdem verletzt werden. Wenn eine Regel wichtig ist, kombiniere sie mit echten Tools (eine Lint-Regel, ein Hook, ein Formatter), anstatt sich nur auf Kontext zu verlassen.

Post-/compact-Verlust: Das Ausführen von /compact fasst das Gespräch zusammen. Anweisungen, die im Chat waren, aber nicht in CLAUDE.md, überleben die Komprimierung nicht. Schreibe dauerhafte Regeln in die Datei. Behalte sie nicht nur in der Session.

Was in jede Datei kommt

Anthropics Boris Cherny formuliert das Ziel direkt: CLAUDE.md sollte Verhaltensweisen enthalten, die über jede Session hinweg bestehen bleiben müssen.

In CLAUDE.md: operative Workflows, Routing-Logik, Qualitätsstandards, Koordinationsprotokolle, harte Einschränkungen (maximal 5-7), Delegationsmuster.

In Skills (bei Bedarf geladen): Technologiemuster, Framework-Konventionen, projektspezifischer Kontext, Architekturdokumentation, Team-Konventionen.

Nicht in CLAUDE.md: Architekturdokumentation (aus dem Code lesen), aktueller git-Verlauf (nutze git log), aktueller PR-Status, Boilerplate-Anweisungen, die jedes Modell standardmäßig befolgt.

Der Zeilenanzahl-Ratschlag, den du anderswo findest, sagt unter 60 Zeilen zu bleiben. Das ist falsch. Sechzig Zeilen Projekt-Trivia, die du nur die Hälfte der Zeit brauchst, verschwenden mehr effektiven Kontext als 300 Zeilen universeller operativer Regeln, die auf jede Anfrage zutreffen. Relevanz ist die Metrik, nicht Länge.

Dein Setup wählen

Drei Muster decken die meisten Anwendungsfälle ab:

Wenn du nur Claude Code nutzt, schreibe eine einzige CLAUDE.md und ignoriere AGENTS.md vollständig. Sie existiert für dich nicht.

Wenn dein Team mehrere Tools nutzt, Claude Code aber primär ist, nutze den Symlink. Eine Datei, beide Dateinamen, kein Wartungsaufwand. Schreibe in dem Stil, der für Claude Code funktioniert; andere Tools nehmen, was sie aus der Prosa können.

Wenn du Claude Code in Sync mit einer Repo-weiten AGENTS.md halten musst, die andere Tools pflegen, nutze den @AGENTS.md-Import-Bridge in deiner CLAUDE.md. Denk daran, dass der importierte Inhalt advisory ist. Schreibe deine Claude-spezifischen Overrides unterhalb der Import-Zeile.

Zwei Dateien, eine klare Regel: Claude liest CLAUDE.md, alle anderen lesen AGENTS.md, und ein Symlink ist der schnellste Weg, sie gleich zu machen.

Häufige Fragen

Was ist AGENTS.md?

AGENTS.md ist ein offener Standard, veröffentlicht von der Linux Foundation und der Agent Interoperability Initiative Foundation. Er definiert eine einzige Kontext-Datei, die jedes KI-Coding-Tool lesen kann, wenn es deinen Repo öffnet. Über 18 Tools unterstützen es, darunter Cursor, Windsurf, Gemini CLI, Devin und OpenAI Codex. Es wird in mehr als 60.000 Open-Source-Projekten verwendet.

Liest Claude Code AGENTS.md?

Claude Code liest AGENTS.md nicht nativ. Es liest stattdessen CLAUDE.md. Du kannst AGENTS.md-Inhalte in Claude Code einbringen, indem du eine @AGENTS.md-Import-Zeile in deiner CLAUDE.md-Datei verwendest, oder beide Dateinamen mit einem Symlink auf dieselbe Datei zeigen lassen. Keiner der Ansätze ändert, welche Datei Claude Code als autoritativ behandelt.

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

AGENTS.md ist ein Cross-Tool-Standard, den jeder KI-Coding-Assistent lesen kann. CLAUDE.md ist Claude Codes native Datei, die automatisch zu Beginn jeder Session geladen wird. AGENTS.md verwendet ein strukturiertes Schema mit Feldern wie allowed_tools und output_format. CLAUDE.md verwendet einfache Prosa-Anweisungen und unterstützt Claude Code-spezifische Features wie @imports, CLAUDE.local.md und Auto-Memory.

Was sollte in CLAUDE.md?

Operative Regeln, die für jede Session gelten: Workflows, Routing-Logik, Qualitätsstandards, harte Einschränkungen und Delegationsmuster. Halte harte Einschränkungen auf maximal 5-7. Keine Architekturdokumentation, kein aktueller git-Verlauf und keine Boilerplate-Anweisungen, die jedes Modell standardmäßig befolgt. Technologiespezifika und Projektkontext gehören in Skills, die bei Bedarf geladen werden, nicht in die Root-Datei.

Wofür wird CLAUDE.local.md verwendet?

CLAUDE.local.md enthält maschinenspezifische Einstellungen, die nicht in die Versionskontrolle committed werden sollten. Gute Kandidaten sind lokale API-Endpoints, persönliche Debugging-Präferenzen und Sandbox-URLs. Claude Code fügt es nicht automatisch zu .gitignore hinzu, also musst du das selbst tun. Wenn du es vergisst, kommt die Datei mit deinem nächsten Commit hoch und legt lokale Konfiguration für jeden Mitwirkenden offen.

Wie nutze ich CLAUDE.md und AGENTS.md zusammen?

Der sauberste Ansatz ist ein Symlink in deinem Repo-Root: ln -s CLAUDE.md AGENTS.md. Claude Code liest CLAUDE.md, und jedes andere Tool liest AGENTS.md. Beide treffen dieselben Bytes ohne Duplikation. Wenn du Claude Code nachgelagert mit einer geteilten AGENTS.md halten musst, die das Team pflegt, nutze den @AGENTS.md-Import in deiner CLAUDE.md und schreibe Claude-spezifische Overrides unterhalb der Import-Zeile.