CLAUDE.md vs AGENTS.md ist kein Entweder-oder, sondern die Frage, wer deine Anweisungen liest. CLAUDE.md ist die Datei, die Claude Code beim Start jeder Sitzung lädt: Rolle, Regeln, Grenzen, in normalem Text. AGENTS.md ist dasselbe Prinzip als offenes Format, das laut der Seite agents.md viele Coding-Agenten lesen, darunter Codex und OpenCode. Seit Version 2.1.277 liest laut Anthropic-Doku auch Claude Code eine AGENTS.md, wenn keine CLAUDE.md im Arbeitsordner oder darüber liegt; liegen beide da, liest Claude die CLAUDE.md, und mit einer Import-Zeile liest es beide. Beide Dateien sind Markdown, ohne Sonderformat. Das ist der eigentliche Punkt hinter dem Vergleich: Was einen Wechsel des Modells oder des Werkzeugs überlebt, ist nicht die Konfiguration in einer Oberfläche, sondern die Textdatei, die du selbst lesen kannst.
Bei mir ist jeder KI-Mitarbeiter ein Ordner mit genau solchen Dateien: eine Personalakte, eine CLAUDE.md als Regelwerk, Skills und Subagents als weitere Markdown-Dateien. Was in die CLAUDE.md gehört und wie ihre vier Ebenen zusammenspielen, habe ich in CLAUDE.md: das Gedächtnis von Claude Code erklärt und wiederhole es hier nicht. Hier geht es um die Frage danach: Was passiert mit diesen Dateien, wenn das Modell wechselt, wenn das Werkzeug wechselt, oder wenn ich morgen mit Codex weiterarbeiten muss? Alles Weitere zu Claude sammle ich auf der Claude-Übersichtsseite.
Was in CLAUDE.md steht und was in AGENTS.md
Inhaltlich sind die beiden Dateien Geschwister. Anthropic beschreibt CLAUDE.md als den Ort für das, was du sonst jedes Mal neu erklären würdest: „Treat CLAUDE.md as the place you write down what you'd otherwise re-explain." Die Seite agents.md beschreibt ihr Format als „a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project". Codex sagt in seiner Doku: „Codex reads AGENTS.md files before doing any work." Drei Formulierungen, ein Gedanke: eine Textdatei, die der Agent liest, bevor er anfängt.
Der wichtigste Unterschied steht nicht in der Tabelle: Wer welche Datei liest, hängt vom Werkzeug ab, nicht vom Inhalt. Du kannst dieselben Sätze in beide schreiben.
Die Ebenen, die Claude Code kennt
Claude Code lädt laut Doku vier Ebenen in dieser Reihenfolge: eine von der Organisation verwaltete Datei, deine persönliche ~/.claude/CLAUDE.md, die Projekt-Datei ./CLAUDE.md oder ./.claude/CLAUDE.md, und eine lokale ./CLAUDE.local.md, die nicht ins Repository gehört. Die Dateien überschreiben sich nicht, sie werden hintereinander in den Kontext gelegt, von der Wurzel des Dateisystems bis zum Ordner, in dem du gestartet hast. Dazu kommen Regeln in .claude/rules/, wahlweise nur für bestimmte Pfade, und Imports per @pfad. Für einen KI-Mitarbeiter reicht bei mir die Projekt-Ebene: Der Ordner des Mitarbeiters ist das Projekt, seine CLAUDE.md sein Regelwerk. Die Details zu den Ebenen und zu /init, /memory und /context stehen im Beitrag zur CLAUDE.md.
Wann Claude Code AGENTS.md liest
Anthropic schreibt: „Claude Code can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without adding a CLAUDE.md, an import, or a setting." Die Regel im Standard ist einfach:
Das Verhalten lässt sich in /config unter „Project instructions" umstellen, zum Beispiel auf beide Dateien zusammen. Zwei Einschränkungen nennt die Doku ausdrücklich: Das direkte Lesen braucht Version 2.1.277 oder neuer, und in manchen Sitzungen, etwa über Amazon Bedrock oder mit abgeschalteter Telemetrie, liest Claude AGENTS.md nicht direkt. Für diese Fälle empfiehlt Anthropic den Import aus einer CLAUDE.md heraus. Das ist zugleich die Lösung, wenn du eine Datei für mehrere Werkzeuge pflegen willst:
@AGENTS.md
## Claude Code
Regeln, die nur für Claude Code gelten, stehen unter dem Import.
Die Doku nennt als Alternative einen Symlink von CLAUDE.md auf AGENTS.md, rät aber unter Windows davon ab.
Skills und Subagents: auch nur Markdown
Das Regelwerk ist nicht die einzige Datei, die einen KI-Mitarbeiter ausmacht. Bei mir hat jeder Mitarbeiter Skills für seine wiederkehrenden Aufgaben und manche einen Subagenten für eine getrennte Prüfrolle. Beides ist laut Doku ebenfalls Text. Ein Skill ist ein Ordner mit einer SKILL.md: „YAML frontmatter between --- markers that tells Claude when to use the skill, and markdown content with the instructions Claude follows when the skill runs." Ein Subagent ist eine Markdown-Datei unter .claude/agents/ oder ~/.claude/agents/: „The frontmatter defines the subagent's metadata and configuration. The body becomes the system prompt that guides the subagent's behavior." Im Frontmatter des Subagenten steht auch das Modell, als Alias wie sonnet oder opus, als volle Modell-ID oder als inherit.
Das heißt: Der ganze Mitarbeiter, von der Rolle über die Arbeitsanweisungen bis zur Prüfrolle, ist ein Ordner mit Textdateien. Nichts davon liegt in einer Oberfläche, die ich nicht öffnen kann. Wie du Skills schreibst und einsetzt, steht in Claude Skills: erstellen und nutzen.
Modell wechseln per Befehl, Werkzeug wechseln mit denselben Dateien
Innerhalb von Claude Code wechsle ich das Modell mit einem Befehl. Die Doku: „During session: use /model <alias|name> to switch immediately, or run /model with no argument to open the picker." Die Aliase heißen sonnet, opus, haiku, fable, dazu default, best und opusplan. Das ist ein Wechsel innerhalb der Claude-Familie. Ein GPT- oder Gemini-Modell gibt es in Claude Code nicht, und ich schreibe das hier so klar, weil „ich kann das Modell austauschen" sonst mehr verspricht, als die Doku hergibt.
Was ich stattdessen kann: das Werkzeug wechseln. Meine Dateien liegen lokal in einem Obsidian-Vault, als Markdown. Fällt Claude aus, arbeite ich mit Codex weiter oder mit OpenCode und lokalen Modellen, und beide lesen dieselben Dateien. Codex liest laut eigener Doku AGENTS.md, von der Projektwurzel abwärts. OpenCode liest laut Doku beim Start „AGENTS.md, CLAUDE.md" aus dem Projekt und zusätzlich die ~/.claude/CLAUDE.md, und es unterstützt lokale Modelle: „You can configure opencode to use local models through Ollama." Für Codex braucht es eine AGENTS.md neben der CLAUDE.md, oder die eine zeigt auf die andere, wie oben gezeigt. Der Aufwand ist eine Zeile.
Das Second-Brain-Bild um den Vault herum ist für mich eher Spielerei. Entscheidend ist, dass das Werkzeug die richtige Datei im richtigen Moment findet, und das tun Claude Code, Codex und OpenCode, weil sie nach demselben Muster suchen: Textdatei im Projektordner, aneinandergehängt von oben nach unten.
Nimm Frieda, meine Büro-Assistenz. Ihre Regeln für den Posteingang, welche Mail auf welchen Stapel gehört und dass sie nie selbst versendet, stehen in ihrer CLAUDE.md und in einer Regeldatei, die auch der Beitrag Posteingang sortieren: das Stapel-System beschreibt. Wenn ich das Werkzeug wechsle, bleiben die Regeln, wo sie sind. Frieda weiß am nächsten Morgen noch, was ein Stapel ist.
Das Gegenbild: Workflow-JSON, Szenarien, Agent-Konfigurationen
Bei einem Workflow-Tool liegt dieselbe Beschreibung der Arbeit als Workflow vor: ein Diagramm aus Knoten, dahinter JSON, die Regeln im Prompt-Feld eines Agent-Knotens. Bei Make heißt das Szenario, bei einer Plattform für Organisationen ist es eine Agent-Konfiguration in der Oberfläche, mit Anweisungen und hochgeladenen Dokumenten. Alle drei Formen funktionieren, und für feste Abläufe mit Volumen sind sie die passende Wahl. Sie unterscheiden sich von der Textdatei in einem Punkt: Sie gehören zum Werkzeug, in dem sie entstanden sind. Einen Workflow öffnest du mit dem Workflow-Tool, eine Agent-Konfiguration mit der Plattform. Ich habe das selbst so betrieben, n8n lief lange in meinem eigenen Cluster, und ich habe es dort nicht als Mangel empfunden. Ich habe erst gemerkt, was mir fehlt, als ich dieselben Regeln einem anderen Modell geben wollte. Die sechs Bauweisen mit ihren Stärken stehen in KI-Mitarbeiter bauen: sechs Wege im Vergleich, die Begriffe dahinter in Agentische KI: was das ist und was nicht.
CLAUDE.md Best Practices: was sich bei mir bewährt hat
Die Empfehlungen aus der Anthropic-Doku sind kurz: unter 200 Zeilen je Datei bleiben, weil längere Dateien Kontext kosten und die Befolgung sinkt; Überschriften und Listen statt dichter Absätze; Anweisungen so konkret, dass man sie prüfen kann; keine zwei Regeln, die sich widersprechen. Dazu kommt bei mir, über viele Personalakten hinweg:
- Rolle statt Tech-Stack. Die meisten CLAUDE.md-Beispiele im Netz beschreiben ein Software-Projekt. Meine beschreiben eine Person: Wer bist du, was ist dein Job, was darfst du nicht.
- Grenzen als Sätze, die man zitieren kann. „Du versendest nie selbst, du legst Entwürfe hin." Ein Satz, der in jeder Sitzung geladen wird und den ich im Zweifel nachlesen kann.
- Ein Freigabe-Gate, wörtlich. Was das Haus verlässt oder Zustand ändert, braucht meine Freigabe in der laufenden Unterhaltung. Das steht bei jedem Mitarbeiter, nicht nur bei den heiklen.
- Learnings in einer eigenen Datei, die vor jeder Arbeit gelesen wird. Feedback wandert nicht in die CLAUDE.md, sondern in eine Datei, auf die die CLAUDE.md zeigt. So bleibt das Regelwerk kurz und die Erfahrung wächst trotzdem.
- Harte Verbote nicht in die Datei. Die Doku sagt es deutlich: CLAUDE.md ist „context, not enforced configuration". Was unter keinen Umständen passieren darf, gehört in einen Hook oder in
permissions.deny.
Ein Beispiel dafür, wie so eine Grenze aussieht, aus dem Regelwerk von Falk, meinem Red-Teamer, auf drei Zeilen gekürzt:
## Grenzen (nicht verhandelbar)
- Aktive Tests laufen nur gegen Systeme, die Kevin gehören oder für die
er die schriftliche Autorisierung erteilt hat, und nur nach seiner
Freigabe je Engagement, wörtlich mit Zeitpunkt dokumentiert.
- Niemals fremde Systeme ohne schriftlichen Scope testen.
- Keine destruktiven Aktionen.
Das ist keine technische Sperre, und ich behandle es auch nicht so. Es ist die Personalakte eines Mitarbeiters, dessen Job es ist, Grenzen anderer zu testen, und der deshalb seine eigenen besonders klar braucht. Weil es Text ist, kann ich es lesen, ändern und jedem Werkzeug geben, das den Ordner öffnet.
Häufige Fragen
Liest Claude Code AGENTS.md?
Ja, laut Anthropic-Doku seit Version 2.1.277, im Standard aber nur, wenn im Arbeitsordner und darüber keine CLAUDE.md oder CLAUDE.local.md liegt. Liegt eine CLAUDE.md da, liest Claude nur diese. Mit der Einstellung „Project instructions" in /config kannst du auf beide Dateien umstellen. In Sitzungen über Amazon Bedrock oder mit abgeschalteter Telemetrie klappt das direkte Lesen nicht; dort hilft ein @AGENTS.md-Import in der CLAUDE.md.
Kann ich CLAUDE.md und AGENTS.md gleichzeitig nutzen?
Ja, auf zwei Wegen. Entweder du stellst in /config „Project instructions" auf claude-md-and-agents-md, dann liest Claude je Ordner erst die CLAUDE.md und dann die AGENTS.md. Oder du schreibst @AGENTS.md in die CLAUDE.md, dann kommt der Inhalt über den Import. Doppelt gelesen wird laut Doku nichts, eine bereits geladene AGENTS.md überspringt Claude.
Was ist der Unterschied zwischen CLAUDE.md und AGENTS.md?
Der Inhalt kann derselbe sein, beide sind Markdown mit Anweisungen für einen Agenten. Der Unterschied ist, wer die Datei sucht: Claude Code sucht zuerst CLAUDE.md, Codex sucht AGENTS.md, OpenCode sucht beide. Kleinere Unterschiede nennt die Anthropic-Doku für AGENTS.md: Sie taucht nicht in /memory und /context auf, und der InstructionsLoaded-Hook feuert nicht, wenn Claude sie direkt liest.
Liest Codex meine CLAUDE.md?
Die Codex-Doku nennt AGENTS.md und AGENTS.override.md als Dateien, die Codex liest, eine CLAUDE.md ist dort nicht dokumentiert. Wenn du mit beiden Werkzeugen arbeiten willst, leg eine AGENTS.md an und lass die CLAUDE.md sie per @AGENTS.md importieren. Dann liest Codex die AGENTS.md direkt und Claude Code über den Import.
Kann ich in Claude Code auf GPT wechseln?
Nein. /model wechselt zwischen Claude-Modellen und, je nach Einrichtung, zwischen Anbietern, die Claude hosten, etwa Amazon Bedrock oder Google Cloud. Für ein Modell eines anderen Herstellers wechselst du das Werkzeug, etwa zu Codex oder OpenCode. Der Punkt dieses Beitrags ist, dass deine Dateien diesen Wechsel mitmachen.
Brauche ich beide Dateien?
Nur, wenn du mehrere Werkzeuge nutzt. Wer ausschließlich mit Claude Code arbeitet, kommt mit CLAUDE.md aus. Wer Codex daneben laufen lässt oder ein Repository mit anderen teilt, hält eine AGENTS.md und lässt die CLAUDE.md darauf zeigen. Das ist der Aufwand einer Zeile, und wer dabei unsicher ist, bringt die Frage in die Community, dort haben mehrere Leute genau diese Einrichtung schon gebaut.
Wie du weitermachst
Öffne die CLAUDE.md deines ersten Mitarbeiters und lies sie einmal so, als wärst du ein anderes Werkzeug: Steht alles drin, was ein Fremder braucht, um die Rolle zu übernehmen? Wenn ja, hast du eine Datei, die einen Werkzeugwechsel überlebt. Wenn nein, weißt du jetzt, was fehlt. Auf welcher Stufe die CLAUDE.md überhaupt dran ist, steht in Claude lernen: der Weg in fünf Stufen. Und in den Calls meiner Community bauen wir deine Frieda in deinem Werkzeug nach, einmal als Datei und einmal in der Oberfläche, dann siehst du den Unterschied selbst: Claude Practitioners.
