# AGENTS.md und CLAUDE.md für Claude Code, Codex und Cursor
> Eine einzige verlässliche Quelle für Claude Code, Codex und Cursor im Jahr 2026: wann Claude Code AGENTS.md selbst liest, AGENTS.md in CLAUDE.md importiert, ein symbolischer Link und /init.
Source: https://ailoot.ai/blog/de/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/de/agents-md-claude-md-one-instruction-file/
Language: de
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-1b2d2eff3a62f5aa6bd8a052c64158c5cef989b74a0a42386e496eff0e532604
Informationen zum Dienst finden Sie in der [Ailoot-Dokumentation](https://ailoot.ai/docs/).
## Was ändert sich, wenn Sie Claude Code, Codex und Cursor gemeinsam verwenden?
Das Wichtigste
Im Jahr 2026 besteht das typische Setup eines Vibe-Coders nicht aus einem Tool, sondern aus 3–5. Claude Code als Haupttool, Codex für lange autonome Aufgaben, Cursor für schnelle Änderungen in der IDE. Jedes hat eine eigene Anweisungsdatei: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Wenn Sie diese manuell synchron halten, ändern Sie eine Zeile an fünf Stellen, vergessen Cursor zu aktualisieren und eine Woche später liefern Claude und Codex für denselben Prompt unterschiedliche Ergebnisse.
Im beschriebenen Beispiel ist Claude Code das Haupttool, während Codex und Cursor für bestimmte Aufgaben verwendet werden. Meine `CLAUDE.md` enthält etwa 250 Zeilen mit Anweisungen: was in welcher Reihenfolge zu lesen ist, was nicht angefasst werden darf, welche Befehle für das Deployment zu verwenden sind und welche Regeln für das Commit-Format gelten. Als ich Codex CLI zum ersten Mal im Projekt ausprobierte, kannte es keine dieser Regeln: Es führte `git push --force` aus, stöberte in `.env` herum und benannte Dateien achtlos um.
Zuerst kopierte ich `CLAUDE.md` von Hand nach `AGENTS.md`. Zwei Wochen später stellte ich fest, dass das Projekt bereits vier Versionen derselben Anweisungen hatte: in `CLAUDE.md`, `AGENTS.md`, `.cursorrules` und `.windsurf/rules/`. Sie unterschieden sich alle ein wenig. Das ist kein Problem von Claude oder Cursor, sondern die grundlegende Falle jedes Systems mit mehreren Wahrheitsquellen. Ich bespreche dieses Problem ausführlicher im [Leitfaden zur Arbeit mit mehreren Agenten](https://ailoot.ai/blog/de/claude-code-codex-together/).
Im Juni 2026 bot Anthropics Dokumentation zum Claude-Code-Speicher eine Lösung: eine gemeinsame Datei plus einen Import. Seit September 2026 liest Claude Code `AGENTS.md` selbst, wenn es im Projekt keine `CLAUDE.md` gibt. Ein Import ist nötig, wenn Sie Regeln haben, die speziell für Claude gelten. Im Folgenden erkläre ich, wann eine einzelne `AGENTS.md` ausreicht, wie Sie einen Import einrichten und wie Sie gemeinsame Regeln von Claude-spezifischen Regeln trennen.
## Liest Claude Code AGENTS.md selbst?
Das Wichtigste
Ja, ab Version 2.1.277, die am 18. September 2026 veröffentlicht wurde, aber nur, wenn es im Arbeitsverzeichnis oder darüber keine `CLAUDE.md`, `.claude/CLAUDE.md` oder `CLAUDE.local.md` gibt. Wenn eine `CLAUDE.md` vorhanden ist, liest Claude Code standardmäßig nur diese Datei, und `AGENTS.md` wird entweder über die Zeile `@AGENTS.md` in `CLAUDE.md` oder über einen symbolischen Link eingebunden. Das Verhalten lässt sich unter Project instructions in `/config` ändern. Vor September las Claude Code `AGENTS.md` überhaupt nicht; der Import war die einzige Möglichkeit.
Vor September 2026 lautete die Antwort „nein“. Issue \#6235, in dem Unterstützung für AGENTS.md angefordert wurde, war seit August 2025 offen und wurde am 17. August 2026 geschlossen. Die Dokumentation zum Speicher verwies während der gesamten Zeit auf eine Lösung: eine CLAUDE.md erstellen und `AGENTS.md` darin als Import einfügen. Ab Version 2.1.277 steht in der Dokumentation etwas anderes:
Claude Code kann AGENTS.md als Projektanweisungen lesen, sodass ein Repository, das bereits für andere Agenten eingerichtet wurde, ohne CLAUDE.md, Import oder Konfiguration funktioniert.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
Welche Dateien Claude Code liest, hängt genau davon ab, welche Dateien im Projekt vorhanden sind:
| Dateien im Projekt | Was Claude Code liest |
|----|----|
| `AGENTS.md`, ohne `CLAUDE.md` oder `CLAUDE.local.md` im Arbeitsverzeichnis oder darüber | `AGENTS.md` |
| `AGENTS.md` und `CLAUDE.md` (oder `CLAUDE.local.md`) im Arbeitsverzeichnis oder darüber | Nur `CLAUDE.md` |
| `CLAUDE.md` mit der Zeile `@AGENTS.md` | `CLAUDE.md` und darin `AGENTS.md` über den Import |
Für diese Prüfung zählen `CLAUDE.md`, `.claude/CLAUDE.md` und `CLAUDE.local.md` im Arbeitsverzeichnis und in allen darüberliegenden Verzeichnissen. Eine persönliche `~/.claude/CLAUDE.md`, eine zentral verwaltete Unternehmensdatei und Regeln aus `.claude/rules/` zählen nicht dazu: Sie werden zusammen mit `AGENTS.md` geladen.
Wenn keine `CLAUDE.md` vorhanden ist, liest Claude Code beim Start alle Dateien `AGENTS.md` und `.claude/AGENTS.md` im Arbeitsverzeichnis und in den darüberliegenden Verzeichnissen. Eine `AGENTS.md` in einem Unterverzeichnis wird geladen, sobald Claude Code eine Datei in diesem Unterverzeichnis öffnet. `@path`-Importe in `AGENTS.md` funktionieren ebenfalls. Claude Code liest weder `AGENTS.local.md` noch `AGENTS.override.md` oder den Inhalt des Verzeichnisses `.agents/`.
Der Haken: Auch eine persönliche `CLAUDE.local.md` zählt. Wenn Sie eine erstellen, um Ihre nicht committeten Regeln aufzubewahren, hört Claude Code stillschweigend auf, `AGENTS.md` zu lesen. Die folgende Einstellung löst das Problem.
Das Verhalten lässt sich unter Project instructions in `/config` ändern:
| Einstellung | Was Claude Code liest |
|----|----|
| `claude-md-or-agents-md` (Standard) | `CLAUDE.md` oder, falls weder diese noch `CLAUDE.local.md` vorhanden ist, `AGENTS.md` |
| `claude-md-and-agents-md` | Beide Dateien: in jedem Verzeichnis zuerst `CLAUDE.md`, dann `AGENTS.md` |
| `claude-md` | Nur `CLAUDE.md` |
| `managed-only` | Nur die zentral verwaltete Unternehmens-`CLAUDE.md` und den automatischen Speicher |
Wenn Sie `CLAUDE.local.md` behalten möchten, ohne auf `AGENTS.md` zu verzichten, stellen Sie `claude-md-and-agents-md` ein. Es kommt zu keinem doppelten Einlesen: Wenn `AGENTS.md` bereits über die Zeile `@AGENTS.md` oder einen symbolischen Link eingebunden ist, lädt Claude Code die Datei unabhängig von der Einstellung kein zweites Mal.
Mit dem Befehl `/memory` können Sie prüfen, ob die Datei erkannt wurde: Ab Version 2.1.280 erscheint der Pfad zu `AGENTS.md` in der Liste. In Versionen vor 2.1.277 und in Sitzungen mit deaktiviertem integriertem Plugin `agents-md` liest Claude Code nur `CLAUDE.md`; außerdem gibt es unter `/config` keinen Eintrag Project instructions. Vor Version 2.1.281 verhielten sich Sitzungen über Amazon Bedrock und Sitzungen mit deaktivierter Telemetrie genauso. Auch in der ersten Sitzung nach einer Aktualisierung von einer älteren Version wird `AGENTS.md` möglicherweise nicht erkannt; ab der nächsten Sitzung funktioniert es.
Was bedeutet das für ein Setup mit einer einzigen Datei? Wenn Sie keine Regeln haben, die nur für Claude gelten, können Sie auf `CLAUDE.md` verzichten: `AGENTS.md` genügt, und Claude Code, Codex und Cursor lesen die Datei. Wenn Sie solche Regeln haben (Planmodus für riskante Verzeichnisse, Skills, Hooks), brauchen Sie `CLAUDE.md`, und Claude Code liest `AGENTS.md` nicht mehr von selbst. Fügen Sie dann `AGENTS.md` in `CLAUDE.md` mit der Zeile `@AGENTS.md` ein; so funktioniert das Setup wie vor September. Es hilft auch bei älteren Claude-Code-Versionen. Weiter unten erkläre ich es genauer.
## Wie importiert man @AGENTS.md in CLAUDE.md?
Das Wichtigste
Ein Import ist nötig, wenn das Projekt eine `CLAUDE.md` hat: Ist sie vorhanden, liest Claude Code `AGENTS.md` standardmäßig nicht selbst. Schreiben Sie zur Einrichtung die Zeile `@AGENTS.md` an den Anfang der Datei `CLAUDE.md`. Wenn Claude Code eine Sitzung startet, setzt es den Inhalt von `AGENTS.md` anstelle dieser Zeile ein und liest das Ergebnis als einen einzigen Text. Unter dem Import können Sie einen Abschnitt „Claude Code“ mit Regeln ergänzen, die nur für Claude gelten. Importe funktionieren mit relativen und absoluten Pfaden und können bis zu vier Ebenen tief verschachtelt werden.
Ein minimales funktionsfähiges Beispiel aus der offiziellen Dokumentation:
```markdown
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
```
So läuft es ab: Die erste Zeile, `@AGENTS.md`, ist eine Importanweisung. Wenn Claude Code zu Beginn einer Sitzung `CLAUDE.md` einliest, findet es diesen Import und setzt den gesamten Inhalt von `AGENTS.md` an dessen Stelle ein. Danach folgt die Überschrift `## Claude Code`: Sie ist einfach Markdown, dient aber als Abschnitt für „Claude-spezifische Ergänzungen“. Darunter steht eine Regel, die nur für Claude Code gilt: Für Änderungen im Abrechnungsverzeichnis soll der Planmodus verwendet werden. Codex CLI oder Cursor öffnen diese Datei nicht; sie verwenden die unveränderte `AGENTS.md`.
Ein Zitat aus der Dokumentation zur Funktionsweise von Importen:
CLAUDE.md-Dateien können mit der Syntax @path/to/import zusätzliche Dateien importieren. Importierte Dateien werden erweitert und beim Sitzungsstart zusammen mit der CLAUDE.md geladen, die auf sie verweist.
— Anthropic, https://code.claude.com/docs/en/memory
Einige praktische Details:
- **Relative und absolute Pfade.** `@AGENTS.md` ist relativ zur Datei, die den Import enthält. `@/Users/me/shared/rules.md` oder `@~/.claude/personal.md` sind absolute Pfade. Ich verwende `@~/.claude/personal.md` für persönliche Präferenzen, die nicht ins Repository gehören.
- **Vier Ebenen tief.** `AGENTS.md` kann `@docs/coding-style.md` importieren, und `coding-style.md` kann bis zu vier Ebenen tief eine weitere Datei importieren. Das reicht für jede praktische Struktur.
- **Backticks verhindern Importe.** Wenn im Text `` `@README` `` steht, ist das nur eine Erwähnung des Namens und kein Import. Das ist nützlich, wenn man Leserinnen und Lesern erklären möchte, wie Importe funktionieren, ohne tatsächlich einen auszulösen.
- **Genehmigung für Dateien außerhalb des Projekts.** Wenn ein Import auf eine Datei außerhalb des Arbeitsverzeichnisses verweist, etwa `@~/.claude/personal.md`, zeigt Claude Code beim ersten Mal einen Dialog mit einer Liste dieser Dateien. Wenn Sie ablehnen, bleiben externe Importe deaktiviert, und der Dialog wird nicht erneut angezeigt. `@AGENTS.md` im Projektstamm löst keinen Dialog aus. So wird verhindert, dass versehentlich eine nicht zugehörige Datei in den Kontext geladen wird.
Nachdem ich im beschriebenen Projekt zu diesem Setup gewechselt hatte, schrumpfte meine `CLAUDE.md` von 250 auf 60 Zeilen: `@AGENTS.md` plus fünf bis sieben Regeln, die nur für Claude Code gelten (Planmodus für riskante Verzeichnisse, was im Admin-Bereich nicht angefasst werden darf und wie Commits formuliert werden). Alles Gemeinsame steht in `AGENTS.md`, die Codex und Cursor lesen.
## Wann sollte man einen symbolischen Link wählen und wann einen Import?
Das Wichtigste
Anthropic bietet zwei Möglichkeiten: einen Import über `@AGENTS.md` oder einen symbolischen Link, `ln -s AGENTS.md CLAUDE.md`. Ein symbolischer Link ist einfacher – er ist lediglich ein Alias und erfordert keine Änderungen an Dateien. Er hat jedoch drei Nachteile: Unter Windows sind Administratorrechte erforderlich, Sie können keine Claude-spezifischen Regeln in `CLAUDE.md` ergänzen, und Git zeigt einen symbolischen Link im Diff manchmal als unbrauchbar an. Der Import ist die universell einsetzbare Lösung. Wenn Sie keine Regeln haben, die nur für Claude gelten, brauchen Sie ab Version 2.1.277 keines von beidem: Claude Code liest `AGENTS.md` selbst.
Die Dokumentation zeigt die Option mit symbolischem Link so:
```bash
ln -s AGENTS.md CLAUDE.md
```
Und direkt danach folgt eine deutliche Warnung zu Windows:
Wenn Sie oder andere Personen, die das Repository klonen, unter Windows arbeiten, verwenden Sie den Import `@AGENTS.md`. Zum Erstellen eines symbolischen Links sind dort Administratorrechte oder der Entwicklermodus erforderlich. Ist `core.symlinks` in Git nicht aktiviert, wird ein committeter Link als gewöhnliche Textdatei ausgecheckt, sodass die `CLAUDE.md` in dieser Kopie nur eine Zeile statt der Anweisungen enthält.
— Anthropic, https://code.claude.com/docs/en/memory
Vergleichstabelle:
| Kriterium | Import `@AGENTS.md` | Symbolischer Link `ln -s` |
|----|----|----|
| **Funktioniert unter Windows ohne Administratorrechte** | ja | nein (Entwicklermodus erforderlich) |
| **Regeln nur für Claude hinzufügbar** | ja, unter dem Import | nein, die Datei ist identisch |
| **Erscheint in Git als gewöhnliches Markdown** | ja | als Link (abhängig von `core.symlinks`) |
| **Kann mehrere Dateien importieren** | ja, bis zu vier Ebenen tief | nein, nur eine Verknüpfung zwischen zwei Dateien |
| **Zwischenspeicherung/Invalidierung in Claude Code** | Standard für CLAUDE.md | funktioniert, aber symbolische Links haben Fallstricke mit Metadaten |
| **Standardwahl** | für alle geeignet | nur, wenn plattformübergreifende Nutzung keine Rolle spielt |
Ich verwende im beschriebenen Projekt Importe. Die Gründe:
1. **Das Team ist gemischt.** Ich arbeite auf dem Mac; im Beispiel ist das Team ungefähr gleichmäßig auf Windows und Mac verteilt. Wenn ein symbolischer Link im Repository liegt, wird er für Windows-Nutzende ohne Entwicklermodus als normale Textdatei mit nur einer Zeile, `AGENTS.md`, ausgecheckt. Das führt zu merkwürdigen Fehlern: Manchmal funktionieren die Regeln, manchmal nicht, und es ist unklar, warum.
2. **Ich möchte Regeln nur für Claude.** Unter `@AGENTS.md` hat meine `CLAUDE.md` einen Abschnitt „Claude Code“ mit Regeln: `--effort high` für Architekturaufgaben verwenden, vor `git push` `npm run build` ausführen und `/api/v1/deploy` nicht von Hand aufrufen. Codex versteht diese Befehle nicht.
3. **Das Debuggen ist einfacher.** Wenn etwas schiefgeht, öffne ich `CLAUDE.md` und sehe den Import und meine Ergänzungen. Bei einem symbolischen Link gibt es kein „das wurde hier hinzugefügt“. Weitere Informationen zur Fehlersuche bei den Claude-Code-Einstellungen finden Sie im [Leitfaden zum sicheren Modus](https://ailoot.ai/blog/de/claude-code-safe-mode-recovery/).
Wenn Sie keine Claude-spezifischen Regeln haben, ist ab Version 2.1.277 kein symbolischer Link mehr nötig: Löschen Sie `CLAUDE.md`, und Claude Code liest `AGENTS.md` selbst. Behalten Sie den symbolischen Link nur, wenn jemand im Team eine ältere Version als 2.1.277 nutzt und nicht aktualisieren kann. Wenn Sie Claude-spezifische Regeln haben, ist ein Import in neun von zehn Fällen bequemer.
## Was lesen Codex, Cursor, Copilot, Windsurf und Gemini CLI?
Das Wichtigste
Jedes Tool liest seine eigene Datei, manchmal auch mehrere. Claude Code liest `CLAUDE.md` und seit September 2026 auch `AGENTS.md`, wenn es im Projekt keine `CLAUDE.md` gibt. Codex CLI liest `AGENTS.md` plus `AGENTS.override.md`. Cursor liest das ältere Format `.cursorrules` oder das neuere `.cursor/rules/*.mdc` und seit Sommer 2026 auch `AGENTS.md`. Copilot liest `.github/copilot-instructions.md` oder `.github/instructions/*.instructions.md`. Windsurf liest das ältere `.windsurfrules` oder das neuere `.windsurf/rules/`. Gemini CLI liest `GEMINI.md`. Aider und Cline haben `AGENTS.md` bereits übernommen.
Eine Übersicht der sieben wichtigsten Tools (basierend auf der offiziellen Dokumentation der Tools):
| Tool | Zentrale Anweisungsdatei | Alternativen | Liest es AGENTS.md? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, zentral verwaltete Richtlinie | ja, wenn es im Projekt keine `CLAUDE.md` gibt (seit 2.1.277), sonst über einen Import |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | ja (nativ) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (veraltet) | ja |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | über Erweiterungen |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (veraltet) | ja |
| **Gemini CLI** | `GEMINI.md` | \- | nein |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | ja (nativ) |
Was folgt daraus? Wenn ein Repository eine `AGENTS.md` hat (sowie bei Bedarf eine `CLAUDE.md` mit Import für Claude-spezifische Regeln), erhalten fünf der sieben Tools automatisch aktuelle Anweisungen. Cursor und Windsurf haben eigene native Dateien. Sie können sie unverändert lassen (`AGENTS.md` wird von ihnen ebenfalls gelesen) oder einen `@AGENTS.md`-Import hinzufügen. Ihre Syntax unterscheidet sich allerdings und wird nicht immer unterstützt.
Die einfachste Strategie für ein neues Projekt:
1. **Alle gemeinsamen Regeln in `AGENTS.md` ablegen** – 95 % der Regeln gehören dorthin.
2. **`CLAUDE.md` erstellen, wenn Sie Regeln nur für Claude brauchen:** `@AGENTS.md` in die erste Zeile schreiben und darunter einen Abschnitt mit Claude-spezifischen Regeln ergänzen. Wenn es keine solchen Regeln gibt, ist `CLAUDE.md` unnötig; Claude Code liest `AGENTS.md` seit Version 2.1.277 selbst.
3. **`.cursor/rules/` für Cursor behalten**, wenn Sie seltene Cursor-spezifische Funktionen wie die Befehle `@Codebase` und `@Docs` benötigen.
4. **Für Windsurf genauso vorgehen:** das alte `.windsurfrules` vergessen und `.windsurf/rules/` nur verwenden, wenn Regeln für die eigene Syntax nötig sind.
Mit diesem Ansatz erhalten Sie 80 % des Nutzens bei 20 % des Aufwands. Als ich gemischte Teams in „Antigravity“ organisierte, stellte sich heraus, dass mehr als zwei Wahrheitsquellen (gemeinsam plus nur für Claude) mühsam zu pflegen sind. Wenn jemand im Team eine Regel zu `.cursorrules` hinzufügt und `AGENTS.md` nicht aktualisiert, sind Cursor und Codex eine Woche später uneins.
## Wie übernimmt /init in Claude Code eine vorhandene AGENTS.md?
Das Wichtigste
`/init` erstellt aus dem vorhandenen Repository eine `CLAUDE.md` und spart 20–30 Minuten Handarbeit. Standardmäßig übernimmt es Cursor-Regeln (`.cursor/rules/`, `.cursorrules`) und Copilot-Regeln (`.github/copilot-instructions.md`); `AGENTS.md`, `.windsurfrules` und `.clinerules` liest es im Modus `CLAUDE_CODE_NEW_INIT=1`. Derselbe Modus startet einen interaktiven Ablauf in mehreren Phasen: Er stellt Fragen, untersucht den Code mit einem Subagenten und schlägt vor dem Schreiben einen Plan vor. Seit September 2026 hat `/init` in einem Projekt mit `AGENTS.md` einen Nachteil: Eine neue `CLAUDE.md` deaktiviert das direkte Lesen von `AGENTS.md`, sodass die Regeln am Ende in zwei Dateien stehen.
Anthropic beschreibt `/init` in der Dokumentation so:
Bei der Ausführung liest /init die Anweisungsdateien anderer Tools und übernimmt relevante Teile in die erzeugte CLAUDE.md: Cursor-Regeln aus .cursor/rules/ oder .cursorrules, Copilot-Regeln aus .github/copilot-instructions.md und mit CLAUDE_CODE_NEW_INIT=1 auch AGENTS.md, `.devin/rules/`, `.windsurf/rules/` oder `.windsurfrules` sowie `.clinerules`.
— Anthropic, https://code.claude.com/docs/en/memory
Was bedeutet das in der Praxis? Das beschriebene Repository hatte eine `.cursorrules` aus der Zeit, als ich Cursor ausprobierte (etwa 80 Zeilen), und eine von Hand zusammengestellte `AGENTS.md` (120 Zeilen). Als ich `claude /init` ausführte, nahm der Befehl beide Dateien, fasste ähnliche Regeln zusammen und erstellte innerhalb einer Minute eine saubere `CLAUDE.md`. Anschließend prüfte ich sie und nahm kleinere Änderungen vor: Ich entfernte veraltete Punkte und ergänzte eine Struktur mit Überschriften. Das ging schneller als ein vollständiger Neuanfang.
Der interaktive Modus, in dem `/init` auch `AGENTS.md` liest, wird über eine Umgebungsvariable aktiviert:
```bash
CLAUDE_CODE_NEW_INIT=1 claude
```
Nach dem Start von `/init` stellt Claude mehrere Rückfragen: welche Artefakte konfiguriert werden sollen (`CLAUDE.md`, Skills, Hooks), welchen Technologie-Stack das Projekt verwendet und welche Befehle für Tests zu nutzen sind. Anschließend untersucht ein Subagent die Codebasis – er liest `package.json`, `README.md` und Konfigurationsdateien – und ergänzt fehlende Teile. Am Ende zeigt er einen Vorschlag, den Sie vor dem Speichern bearbeiten können. Weitere Informationen zur Einrichtung von Claude Code beim Start eines Projekts finden Sie im [separaten Leitfaden](https://ailoot.ai/blog/de/spec-kit-claude-code-spec-driven-development/).
Nun zum Nachteil. Wenn das Projekt bereits eine aktive `AGENTS.md` hat, erstellt `/init` daneben eine `CLAUDE.md` mit einer Kopie ihrer Regeln. Von diesem Zeitpunkt an liest Claude Code standardmäßig nur noch `CLAUDE.md`. Damit gibt es wieder zwei Wahrheitsquellen: Sie aktualisieren `AGENTS.md`, während Claude weiterhin mit der alten Kopie arbeitet. Der Befehl `/import` macht etwas Ähnliches: Er hängt eine einmalige Kopie von `AGENTS.md` an `CLAUDE.md` an. Um eine einzige Quelle zu bewahren, setzen Sie nach `/init` den Import `@AGENTS.md` in die erste Zeile von `CLAUDE.md` und entfernen Sie daraus alles, was `AGENTS.md` wiederholt.
`/init` ist der richtige Ausgangspunkt für ein neues Projekt oder eines, das von Cursor oder Copilot umgestellt wird. Sie müssen nicht online nach der „besten CLAUDE.md-Vorlage“ suchen – Anthropic berücksichtigt bereits, was sich im Repository befindet. Wenn das Projekt bereits eine aktive `AGENTS.md` hat und es keine Claude-spezifischen Regeln gibt, ist `/init` unnötig: Claude Code liest `AGENTS.md` selbst.
## Wie trennt man gemeinsame und Claude-spezifische Anweisungen?
Das Wichtigste
Legen Sie Regeln, die jeder KI-Agent verstehen kann, in `AGENTS.md` ab: was nicht angefasst werden darf, wie Branches benannt werden, dass `.env` ein Geheimnis enthält und welche Befehle für Tests zu verwenden sind. Regeln speziell für Claude Code gehören in `CLAUDE.md` (unter den Import): Planmodus, Skills, Hooks, Verweise auf Skills und Modellnamen nach Version. Die Unterscheidung ist einfach: Beginnt eine Regel mit „Claude soll“, gehört sie in `CLAUDE.md`. Beginnt sie mit „das Tool soll“, gehört sie in `AGENTS.md`.
Ich trenne sie nach diesem Grundsatz. Gemeinsame Regeln für `AGENTS.md`:
- **Was im Code nicht angefasst werden darf.** Die Ordner `.env`, `node_modules`, `prisma/migrations` (nur über `prisma migrate`), `.next/`, `.git/`.
- **Wie Dinge benannt werden.** Branches: `feat/`, `fix/`, `chore/`. Commits: Präfixe `feat:`, `fix:`, `docs:` plus eine kurze Beschreibung. Komponentendateien in `kebab-case`.
- **Test- und Lint-Befehle.** `npm run build`, `npm run lint`, `npm test`. Welchen Befehl Sie vor `git push` ausführen müssen.
- **Architekturprinzipien.** Was in `src/lib/` und `src/components/` gehört, wo die Geschäftslogik liegt und wo die Benutzeroberfläche ist.
- **Sicherheit.** Geheimnisse niemals committieren. Auf die Produktionsdatenbank nur über `prod-psql` zugreifen. Per SSH nur über den Alias `prod` auf die Produktion zugreifen, nicht über `root@IP`.
Claude-spezifische Regeln für `CLAUDE.md` (unter `@AGENTS.md`):
- **Planmodus.** Für Änderungen in riskanten Verzeichnissen (zum Beispiel `src/billing/`) den `plan mode` verwenden.
- **Aufwandsstufe.** Für Architekturaufgaben `--effort high`, für Routinearbeiten `medium` verwenden.
- **Skills.** Welche KI-Agenten und Skills in welchen Situationen ausgeführt werden sollen. Zum Beispiel: „Bei der Arbeit an einem Leitfaden den Skill `build-masterskaya-guide` ausführen.“
- **Claude-Speicher.** Was in den automatischen Speicher und was in `CLAUDE.local.md` gehört. Weitere Informationen zum Claude-Speicher finden Sie im [Leitfaden zu Memory und CLAUDE.md](https://ailoot.ai/blog/de/claude-memory-claude-md-auto-memory/).
- **Hooks.** Wenn in `.claude/settings.json` Hooks konfiguriert sind, beschreiben Sie in `CLAUDE.md`, was sie tun (Codex und Cursor kennen sie nicht und müssen sie auch nicht kennen).
- **Skills und Befehle.** Eine Liste der Schrägstrichbefehle, die ich häufig verwende (`/init`, `/cd`, `/memory`, `/plan`).
Die Grenze ist nicht immer eindeutig. „Führe `git push --force` niemals für `main` aus“ ist klar eine gemeinsame Regel und gehört daher in `AGENTS.md`. „Verwende vor einem `git push` auf einen Hot-Branch zuerst den Planmodus“ ist dagegen spezifisch für Claude Code und gehört in `CLAUDE.md`. Die Prüffrage lautet: „Wenn ich Claude Code morgen entfernte und nur Codex behielte, würde diese Regel weiterhin gelten?“ Wenn ja, gehört sie in `AGENTS.md`. Wenn nein, gehört sie in `CLAUDE.md`.
## Was gehört in AGENTS.md und was in CLAUDE.md oder .claude/rules?
Das Wichtigste
Bei einem großen Projekt reicht eine einzige `AGENTS.md` nicht aus: Sie wird zu umfangreich, und jeder Agent übernimmt unnötiges Material in seinen Kontext. Die Lösung ist ein Verzeichnis `.claude/rules/` mit separaten Dateien nach Themen sowie YAML-Frontmatter `paths:` für pfadbasierte Auslöser. Eine API-Regel gilt beispielsweise nur, wenn Claude in `src/api/` arbeitet. Das spart viel Kontextfenster. Das entsprechende Verzeichnis für Cursor ist `.cursor/rules/`, für Windsurf `.windsurf/rules/`.
Wenn die Regeln mehr als 200 Zeilen umfassen, ist es Zeit, sie aufzuteilen. Anthropics Dokumentation empfiehlt, pro Datei etwa 200 Zeilen anzustreben, weil Claude bei langen `CLAUDE.md`-Dateien die Regeln zunehmend stillschweigend weniger befolgt, obwohl es sie anscheinend liest.
Eine Struktur für ein großes Projekt, die sich bei mir bewährt hat:
```
my-project/
├── AGENTS.md # 100-150 Zeilen, gemeinsam
├── CLAUDE.md # 30-50 Zeilen: @AGENTS.md + nur für Claude
└── .claude/
├── CLAUDE.md # Alternative zur Datei im Stammverzeichnis, gleiche Datei
└── rules/
├── api.md # mit paths: ['src/api/**']
├── components.md # mit paths: ['src/components/**']
├── testing.md # ohne paths, immer aktiv
└── security.md # ohne paths, immer aktiv
```
Jede Datei in `.claude/rules/` kann ein Frontmatter enthalten:
```markdown
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required
```
Claude lädt diese Regeln nur, wenn es mit Dateien arbeitet, die diesem Muster entsprechen. Wenn es `src/components/Button.tsx` bearbeitet, werden die API-Regeln nicht in den Kontext aufgenommen. So wird das Kontextfenster nur für relevante Inhalte verwendet. Das Verzeichnis `.claude/rules/` funktioniert auch ohne `CLAUDE.md`: Wenn das Projekt nur eine `AGENTS.md` enthält, werden seine Regeln zusätzlich geladen und deaktivieren das direkte Lesen von `AGENTS.md` nicht.
Cursor und Windsurf unterstützen dasselbe Vorgehen über ihre Verzeichnisse `.cursor/rules/` und `.windsurf/rules/`. Der AGENTS.md-Standard kann auf diese Verzeichnisse verweisen, aber die Syntax für mehrere Tools ist noch nicht vollständig stabil. Sicherer ist es, gemeinsame Regeln in `AGENTS.md` zu belassen und pfadbezogene Regeln in `.claude/rules/` und `.cursor/rules/` zu duplizieren. Das sind seltene Sonderfälle, nicht der Großteil der Regeln.
Nützliche Speicherorte für CLAUDE.md (von der weitesten bis zur engsten Reichweite geordnet):
| Ebene | Speicherort | Zweck |
|----|----|----|
| **Zentral verwaltete Richtlinie** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Unternehmensregeln, IT/DevOps |
| **Benutzer** | `~/.claude/CLAUDE.md` | Persönliche Präferenzen für alle Projekte |
| **Projekt** | `./CLAUDE.md` oder `./.claude/CLAUDE.md` | Regeln des Projektteams |
| **Lokal** | `./CLAUDE.local.md` (in `.gitignore`) | Persönliche Präferenzen für ein bestimmtes Projekt |
Eine beispielhafte `~/.claude/CLAUDE.md` könnte zwei Regeln enthalten: „Antworte in der bevorzugten Sprache des Benutzers“ und „Schreibe Ailoot genau so.“ Diese Regeln gelten für jedes Projekt und müssen daher nicht in jedem Repository wiederholt werden.
Von diesen vier Ebenen deaktivieren nur eine projektbezogene `CLAUDE.md` und `CLAUDE.local.md` das direkte Lesen von `AGENTS.md`. Eine persönliche `~/.claude/CLAUDE.md` und eine zentral verwaltete Richtlinie stehen dem nicht im Weg; Claude Code liest sie zusammen mit `AGENTS.md`.
## Was tun, wenn AGENTS.md im Projekt bereits veraltet ist?
Das Wichtigste
Wenn `AGENTS.md` 2025 für Codex oder Aider zusammengestellt und seitdem nicht bearbeitet wurde, öffnen Sie das Projekt in Claude Code und bitten Sie Claude, die Datei zu bearbeiten. `AGENTS.md` ist ein lebendiges Dokument; die Spezifikation der Linux Foundation wird aktualisiert. Die wichtigste Regel, um sie aktuell zu halten: Jede Regel muss die Frage beantworten: „Was wiederhole ich Claude/Codex immer wieder?“ Ist das nicht der Fall, archivieren Sie sie.
Im beschriebenen Projekt hatte ich eine `AGENTS.md` aus dem Mai 2025 – 180 Zeilen, viele davon veraltet (sie erwähnte Anthropic-API-Endpunkte, die sich inzwischen geändert hatten, Beispiele mit der nicht mehr existierenden Syntax `claude --tools` und Regeln zu `~/.claude/projects/` mit einer veralteten Struktur).
So bin ich beim Aktualisieren vorgegangen:
1. **Im Planmodus mit `claude` überprüfen.** Ich öffne das Repository, führe `claude --safe-mode` aus und frage: „Lies `AGENTS.md` erneut und schlage eine Liste veralteter oder wiederholter Punkte vor. Bearbeite nichts; liste sie nur auf.“ In zwei Minuten erhielt ich eine Liste mit 23 Punkten zur Prüfung.
2. **Offensichtlich überholte Punkte entfernen.** Von den 23 Punkten waren 9 eindeutig veraltet – Befehlssyntax, Endpunkte und Flag-Namen. Ich löschte diese Zeilen.
3. **Doppelte Einträge zusammenführen.** Weitere 6 Punkte wiederholten einander in anderer Formulierung („nicht mit Force pushen“, „niemals `--force` verwenden“, „`git push -f` vermeiden“). Ich fasste sie zu einer Zeile zusammen.
4. **Neue Punkte hinzufügen.** Ich ergänzte, was Claude/Codex im vergangenen Monat regelmäßig falsch gemacht hatten, nach dem Grundsatz „eine Zeile pro Fehlermuster“. So kamen 8 neue Punkte hinzu.
5. **Einen Subagenten zur abschließenden Prüfung einsetzen.** Ich bat Claude um eine Prüfung mit der Anweisung „Widersprüche, Mehrdeutigkeiten und Duplikate finden.“ Dabei wurden drei Formulierungen entdeckt, die klarer sein konnten. Ich überarbeitete sie.
Nach einer Stunde umfasste `AGENTS.md` 110 aktuelle Zeilen, und ich kannte jede einzelne persönlich. Daraus ließ sich leicht eine 30-zeilige `CLAUDE.md` erstellen. Auch Codex ging anschließend merklich sorgfältiger mit Tests um – ich vermute, einige seiner „merkwürdigen“ Entscheidungen gingen auf veraltete Anweisungen zurück, denen es in gutem Glauben gefolgt war.
Die wichtigsten Grundsätze für eine aktuelle `AGENTS.md`:
- **Jede Regel behandelt einen wiederkehrenden Fehler.** Wenn mir eine Regel im Laufe des Monats kein einziges Mal eingefallen ist, lohnt es sich nicht, sie beizubehalten.
- **Regeln als Anweisungen, nicht als Theorie formulieren.** „Zwei Leerzeichen verwenden“ ist eine Regel. „Der Code-Stil sollte ordentlich sein“ ist keine.
- **Konkretes vor Allgemeinem.** „Vor `git push` `npm run build` ausführen“ ist eine Regel. „Änderungen testen“ ist keine.
## Was funktioniert mit diesem Setup definitiv NICHT?
Das Wichtigste
Der Import `@AGENTS.md` sorgt nicht dafür, dass sich verschiedene Tools gleich verhalten. Jedes hat seine Eigenheiten: Codex CLI kennt `.claude/rules/` oder Hooks nicht. Cursor hat eine eigene Autovervollständigung, die beim Vervollständigen von Text keine CLAUDE.md liest. Copilot richtet sich nach `.github/copilot-instructions.md`, und Regeln allein in AGENTS.md reichen dafür nicht aus. Es gilt nicht „eine Datei = ein Verhalten“, sondern „eine Quelle für die grundlegenden Regeln, dazu Ergänzungen für jedes Tool“.
Einige Dinge, die ich in sechs Monaten Arbeit mit diesem Setup auf die harte Tour gelernt habe:
**1. Die Autovervollständigung von Cursor verwendet AGENTS.md nicht.** Wenn Cursor im Editor eine Zeile vervollständigt, liest es `AGENTS.md` nicht in Echtzeit – dafür ist eine separate, schnelle Engine zuständig. Regeln in AGENTS.md sind nur dann relevant, wenn Sie im Cursor-Chat eine Anfrage stellen. Die Regel „Verwende kein `var`, sondern `const`“ in AGENTS.md wirkt sich also nicht auf die Autovervollständigung aus; dafür müssen Sie ESLint oder die TypeScript-Konfiguration verwenden.
**2. Claude-Code-Hooks in AGENTS.md funktionieren nicht für Codex.** Wenn in `.claude/settings.json` ein PreToolUse-Hook eingerichtet ist, der eine bestimmte Aktion blockiert, ist diese Information nur für Claude nützlich. Codex kennt keine Hooks; für das Tool ist es so, als „entscheide das Tool selbst“. Sinnvoll ist es, „Tue X nicht“ in `AGENTS.md` zu schreiben und „Es gibt einen Hook, der X physisch blockiert“ in `CLAUDE.md` unter den Import.
**3. Copilot und `.github/copilot-instructions.md`.** GitHub Copilot liest seine eigene Datei und versteht AGENTS.md weiterhin nicht besonders gut. Wenn Ihr Team Copilot aktiv nutzt, erstellen Sie entweder eine separate `.github/copilot-instructions.md` mit einer gekürzten Version der Regeln oder verwenden Sie [Copilot-Erweiterungen](https://github.com/marketplace?type=apps&category=copilot-extensions), die AGENTS.md kennen. Das ändert sich schnell; in drei bis sechs Monaten kann die Lage anders aussehen.
**4. Git verfolgt einen symbolischen Link nicht als Änderung an CLAUDE.md.** Wenn Sie `ln -s AGENTS.md CLAUDE.md` ausführen und eine Woche später `AGENTS.md` aktualisieren, zeigt Git nur einen Diff für `AGENTS.md`. Das ist normal, aber Kolleginnen und Kollegen, die den PR prüfen, bemerken möglicherweise nicht, dass auch `CLAUDE.md` (über den symbolischen Link) aktualisiert wurde. Lösung: Schreiben Sie ausdrücklich in die PR-Beschreibung: „`AGENTS.md` aktualisiert; Claude Code sieht dieselbe Datei über den symbolischen Link.“
**5. Verschachtelte Importe sind schwer zu debuggen.** Wenn `AGENTS.md` `@docs/coding-style.md` importiert, das wiederum `@docs/typescript.md` importiert, lässt sich ein Konflikt zwischen Regeln nur schwer untersuchen. Ich beschränke Importe auf eine Ebene (`CLAUDE.md` → `AGENTS.md`) und verschachtele sie nicht weiter. Anthropic stellt einen `InstructionsLoaded`-Hook bereit, der protokolliert, welche Dateien geladen wurden – nützlich zur Fehlersuche bei gestaffelten Setups. Hinweis: Der Hook wird ausgelöst, wenn `AGENTS.md` über einen Import oder symbolischen Link eingebunden wird, aber nicht, wenn Claude Code die Datei selbst liest.
### Quellen
- [Claude-Code-Dokumentation zum Speicher – Abschnitt AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) – wann Claude Code AGENTS.md selbst liest, Einstellungen für Project instructions, Importe und symbolische Links sowie das Verhalten von `/init`.
- [Claude-Code-Dokumentation zum Speicher – zusätzliche Dateien importieren](https://code.claude.com/docs/en/memory#import-additional-files) – Syntax `@path/to/file`, vier Ebenen Tiefe, relative und absolute Pfade.
- [agents.md – Standard der Linux Foundation](https://agents.md/) – offizieller AGENTS.md-Standard und Liste der unterstützten Tools.
- [Dokumentation zu Cursor-Regeln](https://docs.cursor.com/context/rules-for-ai) – was Cursor liest (`.cursor/rules/*.mdc`, AGENTS.md).
- [Benutzerdefinierte Anweisungen für GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) – Format von `.github/copilot-instructions.md`.
- [AGENTS.md-Spezifikation der Linux Foundation](https://aaif.io/projects/agents-md/) – fortlaufend gepflegte Spezifikation.
Das komplette Vibe-Coding-Setup für einen Abend: **KI-Klon + Second Brain + Context Engineering**.
Lernen Sie [Ailoot](https://ailoot.ai/) kennen.
## Fragen und Antworten
### Wann sollte ich einen Import statt eines Symlinks verwenden?
Nutze `@AGENTS.md` in `CLAUDE.md`, wenn Claude-spezifische Ergänzungen nötig sind oder Teammitglieder Windows verwenden. Ein Symlink lässt beide Namen auf denselben Inhalt zeigen und kann deshalb keinen separaten Claude-Abschnitt enthalten.
### Wie prüfe ich das Laden gemeinsamer Anweisungen?
Rufe `/memory` auf und prüfe die aufgeführten Anweisungsdateien. Unterdrücken `CLAUDE.md` oder `CLAUDE.local.md` direktes AGENTS.md-Laden in deiner Konfiguration, ergänze einen Import oder wähle die Einstellung zum Laden beider Dateien. Starte danach eine neue Sitzung.
## Ailoot · Das Unternehmen und sein Projektportfolio
Ailoot baut auf bewährte Betriebserfahrung, einen großen Kundenstamm, stabilen Service und kontinuierliche KPI-Kontrolle.
Das Unternehmen und sein Projektportfolio: Millionen von Kunden; monatliche Umsätze in Milliardenhöhe.
Ailoot nutzt diese Betriebserfahrung für den API-Zugang zu KI-Funktionen in Kundenprodukten, Agenten, Anwendungen und Automatisierungen.