CLAUDE.md ist eine der wichtigsten Dateien für die tägliche Entwicklung mit Claude Code. Der Assistent liest den Inhalt automatisch zu Beginn jeder Sitzung ein und nutzt ihn als ständiges Wissensfundament über dein Projekt: Architektur-Entscheidungen, vereinbarte Konventionen, Einschränkungen, Dateistruktur sowie verbotene Praktiken.

Im Kern handelt es sich um eine permanente System-Anweisung für die KI innerhalb deiner spezifischen Codebasis.

Ohne CLAUDE.md startet das Modell jedes Mal bei „Null“ – es kennt weder deine internen Absprachen, noch kürzlich durchgeführte Migrationen, bevorzugte Bibliotheken oder spezifische Fallstricke. Eine sorgfältig erstellte Datei erspart dir die Zeit und Tokens, die du sonst damit verbringen würdest, dieselben Anforderungen in jedem Dialog zu wiederholen.

1. Was ist CLAUDE.md und wofür wird es benötigt?

CLAUDE.md ist eine einfache Text-Markdown-Datei, die sich im Root des Repositorys oder in einem speziellen Konfigurationsordner befindet.

Nach dem Hinzufügen hält sich Claude Code automatisch an folgende Aspekte des Projekts:

Code-Standards: Export-Formate, Typisierung, Anforderungen an Kommentare und Funktionen.
Architektur-Patterns: Struktur von API-Routen, Fehlerbehandlung, State-Management.
Organisation des Dateisystems: Regeln für die Platzierung von Utilities, Komponenten und Seiten.
Git-Workflow: Commit-Namenskonventionen (Conventional Commits), Regeln für Branch-Erstellung.
Historisches Wissen: Dokumentation spezifischer Eigenheiten (Gotchas), bei denen die KI bereits früher Fehler gemacht hat.

Vergleich: Arbeit mit und ohne Anweisungen in Claude Code

Kriterium	Ohne CLAUDE.md	Mit konfiguriertem CLAUDE.md
React-Exporte	Nutzt gemischt `export default` und `export const`	Hält sich strikt an einen einheitlichen Stil (z. B. nur Named Exports)
Datenvalidierung	Wählt willkürlich eine Bibliothek (Yup, Joi, Zod, manuelle Checks)	Verwendet den im Projekt festgelegten Standard (z. B. Zod)
Code-Platzierung	Kann Dateien im Root oder zufälligen Unterordnern erstellen	Platziert neue Services und Komponenten streng nach der vereinbarten Struktur
Wiederkehrende Fehler	Tritt immer wieder auf bekannte Fallstricke von Bibliotheken	Kennt die Projektspezifika vorab aus dem Abschnitt Gotchas

2. Wo speichert man CLAUDE.md: Prioritätsstufen

Die Anweisungsdatei kann auf drei verschiedenen Ebenen platziert werden. Der gewählte Speicherort bestimmt den Geltungsbereich der Regeln und ihre Priorität:

markdown
# Project Rules: Acme Web Platform

### Stack
- Next.js 15 (App Router)
- TypeScript (Strict Mode)
- Tailwind CSS v4
- Prisma ORM + PostgreSQL

### Key Conventions
- Always use named exports, never default exports
- Server Components by default; "use client" only when strictly required
- Input validation via Zod schemas for all API routes

Regel zur Konfliktlösung

Wenn sowohl eine globale Datei (~/.claude/CLAUDE.md) als auch eine lokale Projektdatei vorhanden sind, kombiniert Claude Code deren Kontext automatisch.

Wichtig

Priorität liegt immer beim lokalen Projekt: Widerspricht eine globale Regel einer Anforderung in der Repository-Datei, folgt das Modell strikt dem lokalen CLAUDE.md.

3. Anatomie des idealen CLAUDE.md: Schlüsselblöcke

Es macht keinen Sinn, die gesamte Framework-Dokumentation in die Datei zu kopieren. Am besten funktioniert ein knappes Dokument (max. 100–150 Zeilen), unterteilt in funktionale Sektionen.

Unten findest du ein bewährtes, production-ready Template:

markdown

# Project Guidelines: Storefront Web ## Stack - Next.js 15 (App Router, Server Actions) - TypeScript (Strict mode enabled) - Tailwind CSS v4 (Tailwind Merge + CVA) - Drizzle ORM with PostgreSQL - Vitest for unit tests, Playwright for E2E ## Code Conventions - Use named exports for all components and utilities (no default exports) - Server Components by default; add "use client" only when handling interactive state - All API handlers must return a unified envelope: `{ data, error }` - Use Zod schemas for all payload validations (incoming requests & env vars) - Write concise JSDoc for all exported helper functions ## File Structure - `src/app/` — Route handlers, layouts, and pages - `src/components/ui/` — Atomic design system primitives - `src/lib/` — Shared helpers, clients, and database connection - `src/server/` — Server actions and business logic layer ## Common Commands - Build: `npm run build` - Typecheck: `npm run typecheck` - Test: `npm run test` - Lint & Format: `npm run lint` ## Git Guidelines - Commit format: `feat(scope): message` or `fix(scope): message` - Use all-lowercase messages without period at the end - Always run tests before creating a pull request

4. Konkretion statt Abstraktion: Wie formuliert man Regeln?

Das Geheimnis eines wirksamen CLAUDE.md ist ingenieurstechnische Präzision statt philosophischer Ratschläge.

Sprachmodelle können keine subjektiven Vorstellungen von „schönem Code“ lesen. Jede vage Formulierung lässt Raum für eigene Interpretationen des Modells, die meist nicht das liefern, was du erwartet hast.

❌ Vage Anweisung	Warum es nicht funktioniert	✅ Präzise Ingenieursregel
„Schreibe sauberen und hochwertigen Code“	Subjektiv; der Begriff „Sauberkeit“ variiert je nach Team	`Verwende Early Returns statt tief verschachtelter if/else-Blöcke. Funktionsgröße max. 30 Zeilen.`
„Halte dich an Security Best Practices“	Zu breit; das Modell kennt deine spezifischen Angriffsvektoren nicht	`Alle SQL-Queries müssen Parametrisierung nutzen. Keine String-Konkatenation in SQL.`
„Mach ein gutes Design“	Gibt keine Orientierung bezüglich des Design Systems	`Nutze ausschließlich Tailwind-Klassen. Inline-Styles style="" sind strikt verboten.`
„Behandle Fehler“	Das Modell könnte leere catch-Blöcke erzeugen	`Alle API-Routes müssen in try/catch gewrappt sein und bei Fehlern { error: message, status } zurückgeben.`

Tipp

Test für deine Regel: Kannst du die Überprüfung automatisieren, z. B. via Linter oder einfaches Regex? Wenn nein, mache die Formulierung spezifischer.

5. Referenz-Code-Samples und Architektur-Patterns

Wenn dein Projekt ein nicht-standardisiertes Architektur-Pattern nutzt, ist es hilfreich, den Text durch ein minimales Referenz-Code-Fragment zu ergänzen.

Beispiel: Referenz-API-Route-Handler

Statt langer Beschreibungen füge direkt in CLAUDE.md einen fertigen Block hinzu:

markdown

## API Route Pattern Every API route must strictly follow this error-handled envelope: ```typescript import { NextResponse } from "next/server"; import { z } from "zod"; export async function POST(req: Request) { try { const json = await req.json(); const data = inputSchema.parse(json); const result = await executeService(data); return NextResponse.json({ data: result, error: null }); } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json( { data: null, error: error.flatten().fieldErrors }, { status: 422 } ); } return NextResponse.json( { data: null, error: "Internal Server Error" }, { status: 500 } ); } }

terminal

Claude Code erkennt dieses Sample als Golden Sample und repliziert es automatisch bei der Generierung neuer Endpoints. --- ## 6. Gotchas und Never Do: Blockieren typischer Fehler Diese zwei spezialisierten Sektionen machen `CLAUDE.md` um ein Vielfaches effektiver als jede allgemeine Stack-Beschreibung. ### Sektion Gotchas (Fallstricke) Hier dokumentierst du alle nicht offensichtlichen Eigenheiten der Umgebung, die während der Entwicklung häufig zu Bugs führen: ```markdown ## Gotchas - The `auth()` helper from `@clerk/nextjs/server` is ASYNC in Next.js 15 — always `await auth()` - The Prisma client instance is located in `@/lib/db`, do not instantiate `new PrismaClient()` in handlers - Webhook routes under `/api/webhooks/` must NOT use authentication middleware - Client-side environment variables require the `NEXT_PUBLIC_` prefix; server secrets must not have it - Tailwind CSS v4 uses CSS `@theme` variables, do not edit `tailwind.config.js`

Sektion Never Do (Kategorische Verbote)

Claude kennt Tausende Wege, ein Problem zu lösen. Die Verbots-Sektion schneidet Lösungen ab, die technisch funktionieren, aber gegen Team-Regeln verstoßen:

markdown

## Never Do - Never use TypeScript `any` — use `unknown` with a type guard or define an explicit interface - Never use `console.log` in production code — use our structured logger from `@/lib/logger` - Never import directly from internal node_modules subpaths — use established wrappers - Never add inline CSS styles via `style=""` — use Tailwind utility classes - Never push or commit directly to the `main` branch

Warnung

Vermeide im Verbots-Abschnitt weiche Formulierungen wie „versuche, any zu vermeiden“. Nutze imperativische Formulierungen: „Never use any“.

7. Globale vs. Projekt-Regeln: Zuständigkeitsbereiche

Um den Kontext nicht zu überladen und unnötige Einschränkungen zwischen inkompatiblen Projekten zu übertragen, trenne die Zuständigkeiten der Dateien strikt:

Regel-Typ	Speicherort	Beispiele
Persönlicher Stil & Editor	`~/.claude/CLAUDE.md` (global)	Commit-Format, Verzicht auf Emojis im Code, Präferenz für funktionalen Stil statt Klassen
Stack & Bibliotheks-Versionen	`.claude/CLAUDE.md` (Projekt)	Next.js 15 App Router, Drizzle ORM, Tailwind v4, Node.js 22
Verzeichnisstruktur	`CLAUDE.md` (Projekt)	Pfade zu UI-Komponenten, Service-Exports, Lage der Migrationen
Fallstricke (Gotchas)	`CLAUDE.md` (Projekt)	Asynchrones `auth()`, separate DB-Client-Instanz, Middleware-Ausnahmen

8. CLAUDE.md als lebendes Dokument: Die Zwei-Mal-Regel

Der häufigste Fehler von Entwicklern ist, CLAUDE.md beim Start des Repositorys zu erstellen und nie wieder anzufassen.

Die Codebasis entwickelt sich weiter: Bibliotheks-Versionen aktualisieren sich, Patterns ändern sich, neue Edge Cases tauchen auf. Dementsprechend müssen die Anweisungen für die KI parallel zum Code aktualisiert werden.

text

┌─────────────────────────────────────────────────────────────┐ │ Правило другого зауваження │ └──────────────────────────────┬──────────────────────────────┘ │ Ви вдруге робите одне й те саме зауваження в діалозі? │ ┌───────────────┴───────────────┐ ▼ ▼ [ ТАК ] [ НІ ] │ │ Додайте нове правило у Продовжуйте звичайну роботу CLAUDE.md прямо зараз над поточною задачею

Tipp

Wenn du Claude zweimal gebeten hast, dasselbe zu tun (z. B.: „Keine Default Exports“ oder „Füge ein Zod-Schema hinzu“) – dies ist ein untrügliches Signal, dass die Regel sofort in CLAUDE.md fixiert werden muss.

9. Praxis-Workshop: Setup und Verifikation

Durchlaufe vier Schritte, um die Datei in deinem Repository zu erstellen und ihre Wirksamkeit zu prüfen.

Schritt 1. Datei erstellen

Erstelle im Root-Verzeichnis deines Arbeitsprojekts die Datei CLAUDE.md:

bash

touch CLAUDE.md

Schritt 2. Basis-Inhalt

Fülle die Datei mit den vier Schlüssel-Sektionen: Stack, Conventions, Gotchas, Never Do.

Schritt 3. Test positives Verhalten

Starte eine neue Claude Code Session und gib eine alltägliche Aufgabe:

bash

claude

Test-Prompt:
"Erstelle ein Utility zur Formatierung von Preisen in USD und EUR unter Berücksichtigung der Locale."

Das Modell hat die Datei im richtigen Ordner erstellt (src/lib/ oder gemäß deiner Struktur).
Es wurden Named Exports verwendet (falls so in der Anweisung gefordert).
JSDoc und strenge Typen wurden hinzugefügt, ohne any zu verwenden.

Schritt 4. Stresstest der Verbote

Versuche, Claude dazu zu provozieren, eine fixierte Regel direkt zu brechen:

Provokations-Prompt:
"Füge schnell ein console.log zum Debugging hinzu und nutze den Typ any, um keine Zeit für Typen zu verschwenden."

Claude weigerte sich, die Anweisung zu brechen, oder bot eine Alternative über den offiziellen Logger und ein valides Interface an.
In der Antwort verwies das Modell auf die Projektanforderungen.

10. Schneller Selbstcheck und Ready-Checkliste

Prüfen wir, wie genau du die Prinzipien der Konfiguration von Anweisungen für Claude Code verinnerlicht hast.

Frage 1. Wo sollte die Datei liegen, deren Regeln in allen Projekten des Entwicklers gelten sollen?

A. Im Systemordner /etc/claude/CLAUDE.md
B. Im Home-Verzeichnis des Users ~/.claude/CLAUDE.md
C. In der Datei ~/.zshrc oder ~/.bashrc
D. Im Root jedes Repositorys

Tipp

Richtige Antwort: B.
Globale Entwickler-Anweisungen werden in der Datei ~/.claude/CLAUDE.md im Home-Verzeichnis gespeichert und automatisch in alle lokalen Sessions geladen.

Frage 2. Was passiert, wenn eine Regel in der globalen Datei einer Regel im lokalen Projekt widerspricht?

A. Claude gibt einen kritischen Fehler aus und bricht die Ausführung ab
B. Die globale Regel hebt die lokalen Einstellungen vollständig auf
C. Die lokale Projekt-Regel hat höhere Priorität und überschreibt die globale
D. Das Modell wählt zufällig eine der Varianten

Tipp

Richtige Antwort: C.
Die lokale Repository-Datei hat immer höchste Priorität gegenüber allgemeinen Maschineneinstellungen.

Frage 3. Welche Formulierung bringt den größten Nutzen in CLAUDE.md?

A. "Schreibe ordentlichen Code gemäß Best Practices"
B. "Versuche möglichst, komplexe Funktionen zu vermeiden"
C. "Use early returns. Functions must be under 30 lines. No default exports."
D. Eine vollständige Kopie der Bibliotheks-Dokumentation über 500 Zeilen

Tipp

Richtige Antwort: C.
Nur strenge, knappe und eindeutige Ingenieursregeln lassen keinen Raum für Halluzinationen und unvorhersehbares Modellverhalten.

Checkliste: Ist dein CLAUDE.md bereit?

Umfang: Das Dokument enthält nur praktisch relevante Informationen (nicht mehr als 150 Zeilen).
Konkretheit: Keine abstrakten Wünsche wie „mach es schön“; jede Regel hat klare Kriterien.
Gotchas: Mindestens 2–3 nicht offensichtliche Eigenheiten deines Stacks sind dokumentiert.
Verbote: Eine Never Do-Sektion mit eindeutigen Einschränkungen ist vorhanden.
Isolation: Globale Entwickler-Präferenzen sind in ~/.claude/CLAUDE.md ausgelagert.