AGENTS.md und CLAUDE.md: so richtest du beide richtig ein

AGENTS.md oder CLAUDE.md: was gehört wohin?

AGENTS.md ist die gemeinsame Anleitungsdatei, die Codex, Cursor, GitHub Copilot und die meisten anderen Coding-Agenten lesen, CLAUDE.md ist die Hausdatei von Claude Code. Seit Version 2.1.277 liest Claude Code auch AGENTS.md, aber nur, wenn keine CLAUDE.md da ist, deshalb fährst du am besten mit einer AGENTS.md für alle und höchstens einer kurzen CLAUDE.md, die sie importiert.

Die Regel, die alles andere einfacher macht: Gemeinsame Regeln stehen nur in der AGENTS.md. Brauchst du etwas nur für Claude, kommt eine CLAUDE.md dazu, deren erste Zeile @AGENTS.md lautet. Dieselbe Regel in zwei Dateien zu pflegen, geht garantiert irgendwann schief.

Alle Angaben hier habe ich am 3. November 2026 mit den Dokus der Hersteller abgeglichen. Wo nur Fremdquellen etwas behaupten, sage ich dir das dazu.

Was steht in einer AGENTS.md überhaupt?

Eine AGENTS.md ist eine ganz normale Markdown-Datei im Projektordner, so etwas wie eine README für den Agenten. Drin steht, wie gebaut und getestet wird, welche Ordner tabu sind und welcher Stil gilt. Es gibt kein Pflichtschema, keine Pflichtüberschriften und keine Versionsnummer.

Das Format ist als Gemeinschaftsprojekt mehrerer KI-Firmen entstanden und liegt heute bei der Agentic AI Foundation unter dem Dach der Linux Foundation. Laut der offiziellen Seite agents.md nutzen es über 60.000 Open-Source-Projekte.

CLAUDE.md hat denselben Zweck, ist aber an Claude Code gebunden und kann mehr. Sie bindet andere Dateien per @ und Pfad ein, liegt auf Ebene von Nutzer, Projekt und Organisation und lässt sich über den Ordner .claude/rules nach Dateitypen aufteilen.

Welches Tool liest welche Datei?

Claude Code hat CLAUDE.md, .claude/CLAUDE.md, die private CLAUDE.local.md und deine globale CLAUDE.md im Ordner .claude in deinem Benutzerverzeichnis. AGENTS.md liest es ab Version 2.1.277, standardmäßig nur ohne Projekt-CLAUDE.md, umstellbar unter Project instructions in /config. Codex CLI hat keine eigene Datei, sondern lebt von AGENTS.md, dazu kommen AGENTS.override.md und die globale AGENTS.md im Ordner .codex. Insgesamt liest Codex höchstens 32 KiB.

Gemini CLI nutzt GEMINI.md und liest AGENTS.md nur, wenn du sie in der Einstellung context.fileName einträgst. Beachte, dass Gemini CLI seit dem 18. Juni 2026 keine privaten Google-Konten mehr bedient, sondern nur noch mit API-Key oder einer Code-Assist-Lizenz läuft. Google empfiehlt Privatnutzern die Antigravity CLI. Ob die AGENTS.md liest, behaupten bisher nur Fremdquellen, offiziell bestätigt ist das nicht.

Cursor hat eigene Regeln unter .cursor/rules, liest aber auch AGENTS.md im Projektstamm und in Unterordnern und führt verschachtelte Dateien zusammen. Der Copilot Coding Agent von GitHub hat .github/copilot-instructions.md und liest laut GitHub-Changelog vom 28. August 2025 AGENTS.md, außerdem CLAUDE.md und GEMINI.md.

Aider ist der Sonderfall. Dort heißt die Datei nach Konvention CONVENTIONS.md, und AGENTS.md liest Aider nicht von selbst. Du bindest sie über den Eintrag read in der Datei .aider.conf.yml ein.

Wann Claude Code deine AGENTS.md liest und wann nicht

Claude Code schaut beim Start in den Arbeitsordner und in jeden Ordner darüber. Entscheidend sind drei Dateien: CLAUDE.md, .claude/CLAUDE.md und CLAUDE.local.md. Findet Claude mindestens eine davon, liest es die CLAUDE-Dateien, und die AGENTS.md bleibt liegen. Findet es keine, lädt es jede AGENTS.md und .claude/AGENTS.md auf dem Weg nach oben. Die AGENTS.md eines Unterordners kommt dazu, sobald Claude dort eine Datei öffnet. Nie gelesen werden AGENTS.local.md, AGENTS.override.md und alles unter .agents.

Jetzt die Stolperfalle, über die fast jeder einmal fällt: Deine globale CLAUDE.md im Benutzerordner zählt nicht, eine private CLAUDE.local.md im Projekt aber schon. Legst du dir eine an, ignoriert Claude ab sofort die AGENTS.md des Teams, und zwar ohne jede Warnung.

Die Abhilfe: Stell in /config den Punkt Project instructions auf claude-md-and-agents-md. Dauerhaft geht das in deinen Nutzereinstellungen, also der settings.json im Ordner .claude in deinem Benutzerverzeichnis. Dort setzt du unter pluginConfigs beim Eintrag cc-plugin-agents-md@builtin die Option instructionFiles auf claude-md-and-agents-md. Bis Version 2.1.285 hieß das Plugin noch agents-md@builtin. In der .claude/settings.json des Projekts wird der Eintrag ignoriert.

Was wirklich geladen ist, zeigt dir /context unter Memory files. Seit Version 2.1.281 klappt das AGENTS.md-Lesen auch über Amazon Bedrock, Google Vertex AI, Microsoft Foundry und LLM-Gateways. In manchen Sitzungen funktioniert es trotzdem nicht, zum Beispiel in der ersten nach einem Update von 2.1.276 oder älter. Der Import mit @AGENTS.md in einer CLAUDE.md funktioniert dagegen in jeder Version.

So richtest du das Setup in fünf Minuten ein, Windows zuerst

Du brauchst zwei Dateien im Projektordner: eine AGENTS.md mit deinen Regeln und eine CLAUDE.md, deren einziger Inhalt die Zeile @AGENTS.md ist. Unter Windows lohnt sich dabei ein kleiner Umweg: Set-Content -Encoding utf8 setzt in Windows PowerShell 5.1 eine BOM an den Dateianfang, und damit kommt nicht jedes Tool klar, vor allem bei JSON.

Sauberes UTF-8 ohne BOM bekommst du so: Leg in PowerShell mit $utf8 = New-Object System.Text.UTF8Encoding $false einen Encoder an und schreib dann die Datei mit [IO.File]::WriteAllText("$PWD\CLAUDE.md", "@AGENTS.md`n", $utf8). Für die AGENTS.md machst du dasselbe mit einer Überschrift als Inhalt. Das funktioniert in PowerShell 5.1 und 7.

Nutzt du auch Gemini CLI, legst du einen Ordner .gemini an und darin eine settings.json, in der context.fileName auf die Liste AGENTS.md und GEMINI.md zeigt. Dann liest Gemini CLI deine gemeinsamen Regeln mit. Auf macOS und Linux reichen touch AGENTS.md und printf '@AGENTS.md\n' > CLAUDE.md.

Warum Import statt Symlink? Ein ln -s AGENTS.md CLAUDE.md klappt auf Mac und Linux. Unter Windows braucht ein Symlink aber Adminrechte oder den Entwicklermodus, und Git checkt einen eingecheckten Symlink ohne core.symlinks als einzeilige Textdatei aus. Anthropic rät deshalb in gemischten Teams zum Import, und ich auch.

So sehen gute Vorlagen für CLAUDE.md und AGENTS.md aus

Eine CLAUDE.md neben einer AGENTS.md braucht selten mehr als ein paar Zeilen. Oben steht @AGENTS.md, darunter ein Abschnitt nur für Claude Code. Typische Einträge: Änderungen an einem heiklen Ordner wie der Abrechnung erst im Plan-Modus vorschlagen, vor „fertig“ immer den Testbefehl aus der AGENTS.md ausführen, Antworten und Commit-Texte auf Deutsch.

Für die AGENTS.md haben sich fünf Blöcke bewährt. Projekt sagt in einem Satz, was das ist, etwa ein TypeScript-Dienst auf Node.js mit pnpm. Befehle listet Installieren, Testen, auch für eine einzelne Datei, Lint und Typprüfung. Regeln hält den Stil fest, Verboten die roten Linien wie Lockfiles von Hand ändern oder .env-Dateien anfassen. Fertig heißt definiert, wann eine Aufgabe erledigt ist, zum Beispiel wenn Lint, Typen und Tests grün sind.

Bei einem Python-Projekt mit uv stehen unter Befehle eben uv sync, uv run pytest, ruff und mypy, und unter Verboten pip install direkt. Im Monorepo beschreibt die Wurzel-Datei den Aufbau der Apps und Pakete, jede App bekommt ihre eigene AGENTS.md mit den Besonderheiten, die nächstgelegene Datei gilt. Bei einem WordPress-Plugin gehören Präfixe für Funktionen, Escaping, Nonce-Prüfungen und $wpdb->prepare() in die Regeln.

Schreib die Vorlagen ruhig auf Deutsch, die Agenten verstehen das problemlos. Und halt die Datei kurz: Anthropic empfiehlt unter 200 Zeilen pro CLAUDE.md, Codex liest sowieso nur 32 KiB. Hält sich der Agent nicht an eine Regel, ist die Datei meist zu lang und nicht zu kurz.

Was in keine der beiden Dateien gehört

Doku hat dort nichts verloren. Verlink sie, statt sie einzukopieren. Claude Code bindet Dateien per @ und Pfad bis zu vier Ebenen tief ein, aber eingebundene Dateien fressen genauso Kontext wie direkt geschriebener Text.

Regeln, die hart gelten müssen, gehören nicht in diese Dateien. Beide sind Kontext, keine Konfiguration, der Agent kann sie überlesen. Was sicher blockiert sein soll, regelst du über Berechtigungen oder einen Hook. Mehr zu Freigaben und Sandbox steht im Ratgeber Claude Code oder Codex.

Zugangsdaten, Tokens und interne Adressen schreibst du auch nicht hinein, genauso wenig wie in eine README. Und persönliche Vorlieben wandern in deine globale Datei, also die CLAUDE.md im Ordner .claude oder die AGENTS.md im Ordner .codex deines Benutzerverzeichnisses, nicht ins Repo, wo sie dem ganzen Team aufgedrückt werden.