CLAUDE.md ist eine einfache Markdown-Datei im Stammverzeichnis deines Projekts. Claude liest sie automatisch in jeder Sitzung. Projektebene: ./CLAUDE.md. Global (alle Projekte): ~/.claude/CLAUDE.md. Projekt überschreibt global: Die globale Datei enthält deine Standardwerte, die Projektdatei die Besonderheiten dieses Repos.
Stell es dir wie das Onboarding-Dokument vor, das du einem hochqualifizierten Auftragnehmer gibst, der nichts über dein Projekt weiß. Ohne sie beginnt jede Sitzung damit, dass Claude deinen Stack, deine Namenskonventionen und deine früheren Entscheidungen errät. Vermutungen werden zu Code, Code wird zu Fehlern. CLAUDE.md unterbricht diese Kette. Eine Datei ist besser als ein cleverer Prompt, weil sie funktioniert, egal ob du dich erinnerst oder nicht.
Fünf Abschnitte, die sich bewähren. Drei bis sechs Aufzählungspunkte pro Abschnitt:
1. Stack: Frameworks, DB, Auth, E-Mail, mit Versionen. „Next.js 16, Postgres auf Neon, Resend für E-Mails, Stripe für Zahlungen, Supabase für Auth.“
2. Routen: wo die Dinge liegen. „App in /app, Server-Aktionen in /actions, API unter /app/api/v2, geteilte Komponenten in /components/ui.“
3. Konventionen: Regeln, die für dich offensichtlich, für Claude unsichtbar sind. „Geld in Cents (int), Daten UTC, Dateinamen kebab-case, IDs als UUID v4.“
4. Sicherheitsregeln: Dinge, die niemals passieren dürfen. „API-Schlüssel niemals protokollieren. Alle SQL-Abfragen parametrisieren. Alle öffentlichen Endpunkte ratenbegrenzen.“
5. Das nicht tun: Fallen, in die du bereits getappt bist. „Abhängigkeiten nicht ohne Nachfrage hinzufügen. Migrationen nicht von lokal gegen Prod ausführen.“
Eine ausgearbeitete Vorlage. Ersetze deine echten Projektdetails:
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth mit Google OAuth
## Routes
- App in /app, actions in /actions, API unter /app/api/v2
## Conventions
- Money in cents (int), dates UTC, filenames kebab-case
- IDs: UUID v4. Boolean columns: is_ or has_ prefix
## Security Rules
- Never log secrets, parameterize SQL
- Rate-limit all POST/PUT/DELETE endpoints (10/min per IP)
- New Supabase tables ship with RLS policies in same commit
## Don't Do This
- Don't add deps without asking
- Don't run migrations from local against prod
- Don't use select(*)Beachte die Spezifität. „10/min pro IP“ ist umsetzbar. „Ratenbegrenzung verwenden“ ist es nicht.
Der teuerste Fehler: vage Regeln, die spezifisch klingen.
Schwach: „Geld sorgfältig behandeln.“ Claude wird Geld so behandeln, wie es am besten erscheint, was möglicherweise nicht mit deinem System übereinstimmt.
Stark: „Alle Geldbeträge sind ganze Cents. Niemals Gleitkommazahlen. Niemals rohe Cents anzeigen; durch 100 teilen und mit einem Währungssymbol formatieren.“ Speichertyp, Verarbeitungsregel, Anzeigeregel. Keine Mehrdeutigkeit.
Der zweite Fehler: Aspirationen statt Einschränkungen schreiben. „Wir legen Wert auf sauberen, lesbaren Code“ ist eine Aspiration. „Dateien über 200 Zeilen werden in Module aufgeteilt“ ist eine Einschränkung. Aspirationen erfordern Urteilsvermögen; Einschränkungen führen zu konsistentem Verhalten. Fülle deine CLAUDE.md mit Einschränkungen.
CLAUDE.md ist ein lebendiges Dokument. Drei Signale, dass es aktualisiert werden muss:
Du fügst denselben Kontext zum zweiten Mal in einen Prompt ein. Wenn du es wieder sagst, gehört es in CLAUDE.md.
Claude macht einen Fehler, den eine Regel verhindert hätte. Der Fehler ist die Regel. Schreibe sie vor der nächsten Sitzung auf.
Du erklärst einem Kollegen eine Konvention. Wenn es sich lohnte, es laut auszusprechen, lohnt es sich, es automatisch zu laden.
Längendisziplin: drei bis sechs Aufzählungspunkte pro Abschnitt; nach acht, den Abschnitt aufteilen. Eine CLAUDE.md, die zu lang zum Überfliegen ist, funktioniert nicht mehr, weil die wichtigen Regeln vergraben werden. Sechs richtige Zeilen sind besser als sechzig Zeilen Füllmaterial.
Skalierung über etwa 300 Zeilen hinaus: Aufteilung in Themendateien mit @filename-Includes:
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.mdJede Themendatei bleibt fokussiert; das Root bleibt kurz.
CLAUDE.md in die Versionskontrolle committen. Regeln werden in PRs überprüfbar, und ein neues Teammitglied klont das Repo mit bereits konfiguriertem Claude. Füge jede „Das nicht tun“-Regel im selben Commit wie den Bugfix hinzu, der sie gelehrt hat. Eine Vorsichtsmaßnahme: maschinenspezifische Pfade vor dem Commit verallgemeinern.
Was gehört in CLAUDE.md vs. einen Prompt? Explosionsradius. Wenn eine Regel eine Fehlerklasse verhindert, deren Behebung eine Stunde oder mehr kostet, gehört sie in CLAUDE.md. Sitzungsspezifische Anweisungen bleiben in Prompts.
Erstelle deine erste CLAUDE.md in zehn Minuten. Gib Claude diesen Prompt:
„Ich richte Claude Code für ein Projekt mit diesem Stack ein: [Stack]. Wichtige Konventionen, die jemand Neues nicht kennen würde: [Konventionen]. Sicherheitsregeln, die niemals verletzt werden dürfen: [Regeln]. Dinge, die zuvor Fehler verursacht haben: [Fallen]. Entwerfe eine CLAUDE.md mit fünf Abschnitten: Stack, Routen, Konventionen, Sicherheitsregeln, Das nicht tun.“
Der erste Entwurf gibt dir 80 Prozent. Verfeinere ihn mit dem, was Claude übersehen hat; die restlichen 20 Prozent sind das, was spezifisch für deine tatsächliche Erfahrung mit dem Projekt ist.
CLAUDE.md im Projekt-Root lädt deinen Stack, Routen, Konventionen, Sicherheitsregeln und Fallen in jede Sitzung. Globale Datei für projektübergreifende Standardwerte, Projektdatei für Überschreibungen. Einschränkungen, keine Aspirationen. Sechs richtige Zeilen sind besser als sechzig. Aktualisiere sie, wann immer Claude einen Fehler macht, den eine geschriebene Regel verhindert hätte.