CLAUDE.md-Vorlage und AGENTS.md: welche Datei wofür? (mit Beispielen)
CLAUDE.md, AGENTS.md, SKILL.md: drei Dateien, die alle irgendwie „Anweisungen für die KI“ enthalten. Wer liest welche, und wann?
Dieser Guide klärt die Aufgabenteilung, gibt dir eine CLAUDE.md-Vorlage zum Kopieren und zeigt, wie du AGENTS.md und CLAUDE.md aus einer Quelle pflegst.
CLAUDE.md, AGENTS.md, SKILL.md: wer liest was?
Tabelle: Datei · Tool · Ort · wann geladen
| Datei | Gelesen von | Typischer Ort | Wann geladen |
|---|---|---|---|
CLAUDE.md | Claude Code | ./CLAUDE.md oder ./.claude/CLAUDE.md | Zu Beginn jeder Session |
AGENTS.md | Cursor, Claude Code (ab v2.1.277) und andere Coding-Agents | Projekt-Root, auch Unterordner | Claude Code: nur, wenn keine CLAUDE.md vorhanden ist (Standard, siehe unten) |
SKILL.md | Claude Code (Agent-Skills-Standard) | .claude/skills/<name>/SKILL.md | Beschreibung immer, Inhalt erst bei Bedarf |
Die Faustregel aus der Claude-Code-Doku: In die CLAUDE.md gehören Fakten, die Claude in jeder Session braucht, also Build-Befehle, Konventionen, Projektaufbau und „mach immer X“-Regeln. Ist ein Eintrag ein mehrstufiger Ablauf oder betrifft er nur einen Teil des Codes, gehört er in einen Skill oder eine pfadbezogene Regel.
Wichtig: Claude behandelt CLAUDE.md als Kontext, nicht als erzwungene Konfiguration. Was auf keinen Fall passieren darf, regelst du mit einem PreToolUse-Hook oder Berechtigungsregeln in den Settings.
Wo die CLAUDE.md liegt
| Ebene | Ort | Für wen |
|---|---|---|
| Benutzer | ~/.claude/CLAUDE.md | Nur du, in allen Projekten |
| Projekt | ./CLAUDE.md oder ./.claude/CLAUDE.md | Das Team, über Git |
| Lokal | ./CLAUDE.local.md | Nur du, in diesem Projekt (in .gitignore eintragen) |
Dazu kommt eine zentral verwaltete Datei für Organisationen (z. B. /etc/claude-code/CLAUDE.md unter Linux).
Verschachtelt: Claude Code lädt CLAUDE.md und CLAUDE.local.md aus dem Arbeitsverzeichnis und allen Ordnern darüber. Die Dateien werden aneinandergehängt, nicht überschrieben. Dateien in Unterordnern lädt Claude erst, wenn es dort eine Datei liest oder bearbeitet.
Import mit @: Mit @pfad/zur/datei bindest du weitere Dateien ein. Relative Pfade gelten relativ zur Datei mit dem Import, maximal vier Ebenen tief. Achtung: Importierte Dateien werden beim Start mitgeladen. Sie helfen beim Ordnen, sparen aber keinen Kontext.
Schnellstart: /init erzeugt eine erste CLAUDE.md aus deinem Code. Mit /context prüfst du unter „Memory files“, welche Dateien geladen wurden.
CLAUDE.md-Vorlage zum Kopieren
Die Doku empfiehlt unter 200 Zeilen pro Datei und konkrete, überprüfbare Anweisungen. Diese Vorlage bleibt bewusst kurz:
# Projekt: <Name>
## Befehle
- Installieren: `npm install`
- Dev-Server: `npm run dev`
- Tests: `npm test` (vor jedem Commit ausführen)
- Lint: `npm run lint`
## Code-Stil
- TypeScript für alle neuen Dateien
- 2 Leerzeichen Einrückung
- Benannte Exporte statt Default-Exporte
## Aufbau
- API-Handler liegen in `src/api/handlers/`
- Gemeinsame Typen in `src/types/`
## Grenzen
- `migrations/` nicht anfassen, ohne zu fragen
- Keine neuen Abhängigkeiten ohne Rückfrage
- Keine Secrets in Code oder Logs
## Mehr Kontext
- Überblick: @README.mdErsetze die Beispiele durch deine echten Befehle. „Run npm test before committing“ statt „Test your changes“: So formuliert es auch die Doku.
Notizen nur für Menschen kannst du als HTML-Kommentar (<!-- ... -->) schreiben. Block-Kommentare entfernt Claude Code, bevor der Text in den Kontext geht.
AGENTS.md und CLAUDE.md gemeinsam pflegen
Was Claude Code standardmäßig liest
| Dein Repository hat | Claude liest |
|---|---|
Nur AGENTS.md, keine CLAUDE.md/CLAUDE.local.md im Arbeitsordner oder darüber | AGENTS.md |
AGENTS.md und CLAUDE.md | Nur CLAUDE.md |
CLAUDE.md, die AGENTS.md importiert | CLAUDE.md inkl. AGENTS.md |
Direktes Lesen von AGENTS.md setzt Claude Code v2.1.277 oder neuer voraus. Über /config → „Project instructions“ kannst du das Verhalten ändern, z. B. auf claude-md-and-agents-md, damit beide Dateien gelesen werden.
Achtung bei CLAUDE.local.md: Sie zählt als CLAUDE.md. Legst du eine an, liest Claude deine AGENTS.md standardmäßig nicht mehr.
Eine Quelle, zwei Tools
Cursor unterstützt AGENTS.md im Projekt-Root und in Unterordnern (Cursor-Doku). Wenn du beide Tools nutzt, ist AGENTS.md die gemeinsame Quelle. Für Claude Code hast du zwei Wege:
1. Import (empfohlen, wenn du Claude-spezifische Zusätze hast):
@AGENTS.md
## Claude Code
Plan-Modus für Änderungen unter `src/billing/` verwenden.2. Symlink (wenn du nichts Claude-Spezifisches brauchst):
ln -s AGENTS.md CLAUDE.mdDie Doku rät zum Import, sobald jemand im Team unter Windows arbeitet: Symlinks brauchen dort Admin-Rechte oder den Entwicklermodus, und Git checkt sie sonst als einfache Textdatei aus.
Wie Cursor-Regeln als .mdc-Datei aufgebaut sind, steht im Guide Cursor Rules (.mdc) erklärt. Die Entscheidung Rules vs. AGENTS.md behandelt Cursor Rules vs. AGENTS.md (englisch).
Wann ein Skill statt einer Regel?
- Regel (
CLAUDE.md,.claude/rules/): Gilt immer oder für bestimmte Dateien. Beispiel: „Komponenten insrc/components/nutzen Tailwind.“ Mitpaths:im Frontmatter einer Datei unter.claude/rules/lädt die Regel nur bei passenden Dateien. - Skill (
SKILL.md): Ein Ablauf, den du ab und zu brauchst. Beispiel: „Release-Notes aus dem Git-Log schreiben.“ Der Inhalt kostet erst Kontext, wenn der Skill läuft.
Wie du einen Skill anlegst, zeigt SKILL.md Format & Template (englisch).
Wiederkehrende Abläufe gehören nicht in die CLAUDE.md, sondern in Skills: Claude-Code-Skills erstellen.
Häufige Fehler
- Zu lang: Über 200 Zeilen verbraucht mehr Kontext und senkt laut Doku die Befolgung. Teile auf in pfadbezogene Regeln.
- Veraltete Befehle: Ein
npm run build, das es nicht mehr gibt, führt Claude in die Irre. Ab v2.1.283 sucht/doctor prompt-auditnach veralteten oder widersprüchlichen Anweisungen. - Widersprüche: Sagen zwei Dateien Unterschiedliches, nimmt Claude womöglich irgendeine. Prüfe Benutzer-, Projekt- und Unterordner-Dateien zusammen.
- „Bitte lies AGENTS.md“ als Satz: Dann sieht Claude die AGENTS.md nur, wenn es sich entscheidet, die Datei zu öffnen. Ersetze den Satz durch einen Import mit
@AGENTS.md.
Fertige Vorlagen
Fertige Vorlagen für AGENTS.md und CLAUDE.md plus 13 Regeln: das Cursor + Claude Code Rules Pack von Aramac, geprüft gegen das Cursor-Rules-Format (.mdc, Stand Oktober 2026). Nur für eigene, nicht gewerbliche Zwecke (Lizenz). 19 € inkl. MwSt., Updates bis 16.04.2027.
Für wiederkehrende Abläufe gibt es separat das Claude Code Skills Pack (29 € inkl. MwSt.).
FAQ
Was ist der Unterschied zwischen AGENTS.md und CLAUDE.md?
Beide enthalten dauerhafte Projektanweisungen. CLAUDE.md ist das Format von Claude Code. AGENTS.md ist ein toolübergreifendes Format, das auch Cursor liest. Claude Code liest AGENTS.md ab v2.1.277 standardmäßig nur, wenn keine CLAUDE.md vorhanden ist.
Liest Claude Code beide Dateien gleichzeitig?
Standardmäßig nein. Entweder importierst du AGENTS.md mit @AGENTS.md in deiner CLAUDE.md, oder du stellst unter /config die Option Project instructions auf claude-md-and-agents-md.
Wo lege ich die CLAUDE.md ab?
Für das Projekt in ./CLAUDE.md oder ./.claude/CLAUDE.md, für dich persönlich in ~/.claude/CLAUDE.md. Private Projektnotizen kommen in ./CLAUDE.local.md, die du in .gitignore einträgst.
Wie lang darf eine CLAUDE.md sein?
Die Doku empfiehlt unter 200 Zeilen pro Datei. Längere Dateien verbrauchen mehr Kontext und werden weniger zuverlässig befolgt.
Wann nehme ich einen Skill statt CLAUDE.md?
Wenn es um einen mehrstufigen Ablauf geht, den du nur manchmal brauchst. Ein Skill lädt seinen Inhalt erst bei Bedarf, CLAUDE.md ist in jeder Session komplett im Kontext.
Quellen
- Anthropic, Claude Code Doku: How Claude remembers your project
- Anthropic, Claude Code Doku: Extend Claude with skills
- Cursor-Doku: Rules
- AGENTS.md
Alle geprüft am 16. Oktober 2026.
---
Ein unabhängiges Produkt der Aramac GmbH. Nicht mit Anysphere (Cursor) oder Anthropic (Claude Code) verbunden oder von ihnen unterstützt. Cursor und Claude sind Marken ihrer jeweiligen Inhaber.