CLAUDE.md erstellen: Anleitung und Template

Eine gute CLAUDE.md erspart dir nicht das Denken. Sie erspart dir, bei jeder Sitzung dieselben technischen Fakten, Grenzen und Prüfungen neu zu erklären.

Das funktioniert besonders gut, wenn die Datei keine Wunschliste ist. Sie sollte Claude Code zeigen, welche Befehle funktionieren, wo wichtiger Code liegt, was auf keinen Fall geändert werden darf und woran ein Ergebnis erkennbar ist.

Was eine CLAUDE.md leistet

CLAUDE.md ist eine normale Markdown-Datei. Claude Code lädt sie als Projektgedächtnis und verwendet ihren Inhalt als zusätzliche Arbeitsanweisung. Die Datei ist daher ein guter Ort für Dinge, die bei vielen Aufgaben gelten.

• verlässliche Befehle für Entwicklung, Tests und Builds
• eine kurze Karte der wichtigen Verzeichnisse und Einstiegspunkte
• architektonische Regeln und Abhängigkeiten
• harte Grenzen wie „keine Datenbankmigration ohne Freigabe“
• klare Kriterien, mit denen Claude eine Aufgabe prüfen kann

Sie ist kein Ersatz für einen guten Auftrag. Das konkrete Ziel, der gewünschte Umfang und Akzeptanzkriterien gehören weiterhin in den aktuellen Prompt. Ein Chat kann verdichtet werden oder einen früheren Detailkontext verlieren. Eine wichtige, dauerhafte Projektregel gehört deshalb in die Datei und nicht nur in eine Unterhaltung.

Hierarchie: global, Projekt und Unterordner

Claude Code kombiniert Speicherdateien entlang deines Arbeitswegs. Beim Start werden die Dateien vom äußeren zum inneren Verzeichnis zusammengesetzt. Eine CLAUDE.local.md wird im selben Verzeichnis nach der CLAUDE.md geladen. Eine weitere CLAUDE.md in einem Unterordner kommt hinzu, wenn Claude Dateien in diesem Bereich liest.

~/.claude/CLAUDE.md
  Persönliche, projektübergreifende Arbeitsregeln

~/projekte/shop/CLAUDE.md
  Gemeinsame Regeln für den Shop

~/projekte/shop/apps/admin/CLAUDE.md
  Regeln, die nur für das Admin-Frontend gelten

~/projekte/shop/apps/admin/src/payments/CLAUDE.md
  Zusätzliche Regeln für Zahlungsabläufe

Lege gemeinsame Projektinformationen entweder als CLAUDE.md oder als .claude/CLAUDE.md im Projekt-Root ab. Entscheide dich für eine Variante und bleib im Repository konsistent. Formuliere Regeln möglichst ohne Widerspruch. Claude Code setzt die Inhalte zusammen, statt daraus ein fehleranfälliges Prioritätssystem zu machen.

Die Details zu Projekt-, Benutzer- und lokalen Speicherdateien beschreibt Anthropic in der offiziellen Dokumentation zu Memory. Die Oberfläche und einzelne Begriffe können sich ändern, die Datei-Hierarchie solltest du deshalb bei größeren Umstellungen dort erneut prüfen.

Welche Information wohin gehört

Globale CLAUDE.md

~/.claude/CLAUDE.md ist für deine eigenen, projektübergreifenden Regeln. Dazu passen zum Beispiel Formatvorlieben, deine bevorzugte Sprache für Code und Kommentare oder eine persönliche Prüfroutine. Sie sollte keine Annahmen über ein einzelnes Repository enthalten.

Projekt-CLAUDE.md

Die Datei im Repository beschreibt den gemeinsamen Stand. Halte sie versioniert, wenn das Team dieselben Befehle und Grenzen kennen soll. Schreibe nur Dinge hinein, die sich aus Code, Konfiguration oder einer getroffenen Teamentscheidung ableiten lassen.

In VS Code kannst du die Projektdatei neben der Claude-Code-Erweiterung öffnen. Das Beispiel enthält kurze Regeln zu Änderungen und Tests:

CLAUDE.local.md

Nutze CLAUDE.local.md für persönliche Ergänzungen am selben Ort, etwa lokale Testdaten oder einen eigenen Arbeitsablauf. Trage die Datei in .gitignore ein. Passwörter, API-Keys, Kundendaten und andere Geheimnisse bleiben außerhalb von CLAUDE.md-Dateien.

Unterordner-Regeln

Ein Unterordner lohnt sich, wenn ein Bereich eigene Risiken oder Konventionen hat. Beispiele sind Zahlungen, Datenmigrationen oder eine mobile App. Wiederhole dort nicht die gesamte Root-Datei. Ergänze nur das, was in diesem Bereich zusätzlich gilt.

Eine globale CLAUDE.md für deine Arbeitsweise

Die globale Datei unter ~/.claude/CLAUDE.md ist bewusst unabhängig von einem Repository. Hier passt hinein, wie Claude grundsätzlich mit dir arbeiten soll. Die Datei darf keine framework- oder projektspezifischen Behauptungen enthalten.

# Persönliche Arbeitsregeln

## Zusammenarbeit
- Erkläre bei größeren Änderungen kurz Plan und Prüfschritt.
- Frage nach, wenn Ziel oder Umfang nicht eindeutig sind.

## Code
- Bevorzuge TypeScript, wenn das Projekt es bereits verwendet.
- Nutze vorhandene Formatierungs- und Testwerkzeuge.

## Vor dem Abschluss
- Nenne geänderte Dateien und ausgeführte Prüfungen.
- Benenne offene Risiken klar.

Ein schlankes Template für den Projekt-Root

Erstelle die Datei direkt im Projekt-Root oder lass Claude Code mit /init einen ersten Entwurf erzeugen. Ein automatisch erzeugter Entwurf kennt dein Projekt noch nicht zuverlässig. Lies ihn durch, streiche Annahmen und ergänze erst dann die Regeln, die wirklich gelten.

# Projektname

Kurzer Satz über Zweck und Nutzergruppe.

## Wichtige Bereiche
- src/app/: Routen und Seiten
- src/lib/: fachliche Logik und Integrationen
- tests/: automatisierte Prüfungen

## Ausführen und prüfen
```bash
npm run lint
npm run test
npm run build
```

## Verbindliche Regeln
- Bestehende Komponenten vor neuen prüfen.
- Eingaben an API-Grenzen validieren.
- Änderungen an öffentlichen Schnittstellen dokumentieren.

## Grenzen
- Keine Secrets in Dateien oder Ausgaben schreiben.
- Keine Datenmigration ohne bestätigten Plan ausführen.
- Bei unklaren fachlichen Anforderungen zuerst nachfragen.

## Fertig, wenn
- Die vereinbarten Prüfungen erfolgreich sind.
- Betroffene Dokumentation und Tests zum Verhalten passen.

Verweise auf ausführlichere, stabile Dokumente mit @-Imports. Ein Eintrag wie @docs/architektur.md lädt die Datei beim Start. Imports können wiederum weitere Dateien referenzieren, aber nur bis zu einer begrenzten Tiefe. Importiere deshalb keine große Dokumentationssammlung auf Verdacht.

CLAUDE.md und Auto Memory unterscheiden

Auto Memory speichert wiederverwendbare Erkenntnisse separat und lokal. Das kann hilfreich sein, wenn Claude Code während der Arbeit eine stabile Eigenheit des Projekts erkennt. Der Mechanismus ist jedoch nicht dasselbe wie eine überprüfte, teamweite Anweisung im Repository.

Für Arbeitsstandards, Sicherheitsgrenzen, Befehle und Architekturentscheidungen bleibt die CLAUDE.md die belastbare Quelle. Verwende Auto Memory als Ergänzung. Mit /memory kannst du die gespeicherten Einträge ansehen und verwalten.

Wenn Claude Code eine Regel nicht beachtet

1. Prüfe mit pwd, ob du Claude Code im erwarteten Projektordner gestartet hast.
2. Öffne /context und kontrolliere, was in der laufenden Sitzung vorhanden ist.
3. Prüfe mit /memory, ob du Auto Memory mit einer expliziten Projektregel verwechselst.
4. Führe claude --version und claude doctor aus, wenn Installation oder Konfiguration verdächtig sind.
5. Starte bei einer kaputten Anpassung testweise mit claude --safe-mode. Dieser Modus lädt keine CLAUDE.md-Dateien, Skills, Plugins, Hooks, MCP-Server oder Auto Memory. Anmeldung, Modellauswahl, eingebaute Tools und Berechtigungen bleiben aktiv. Zentral verwaltete Richtlinien gelten weiterhin.

Wenn die Datei geladen wird und Claude trotzdem anders handelt, formuliere die Regel enger und nenne die Prüfung. Aus „Achte auf Sicherheit“ wird zum Beispiel „Vor dem Senden einer E-Mail zuerst Empfänger, Betreff und Inhalt zur Freigabe zeigen“.

Zusammenarbeit mit anderen Coding-Tools

Manche Teams verwenden zusätzlich AGENTS.md. Kopiere Regeln nicht in mehrere Dateien, wenn du es vermeiden kannst. Claude Code kann eine gemeinsame Datei über einen Import wie @AGENTS.md einbeziehen. Die kurze CLAUDE.md erklärt dann nur, warum diese Datei maßgeblich ist und welche Claude-Code-spezifischen Ergänzungen gelten.

Überprüfe nach jeder größeren Änderung die echten Befehle und die wichtigsten Regeln. Eine kleine, korrekte Datei hilft mehr als eine lange Sammlung überholter Vorgaben.