Claude Code2026-04-07· 5 Min

"CLAUDE.md Masterclass: So steuerst du Claude Code perfekt"

"CLAUDE.md erstellen und optimieren: Aufbau, Best Practices, Beispiele für verschiedene Projekttypen und häufige Fehler vermeiden."

Boris Dittberner

Founder, SixSides Academy

## Was ist CLAUDE.md?

CLAUDE.md ist eine Markdown-Datei, die Claude Code beim Start automatisch liest. Sie enthält alle Informationen, die Claude Code über dein Projekt wissen muss: Tech Stack, Konventionen, Regeln, Projektstruktur und spezifische Anweisungen.

Die Definition: CLAUDE.md ist die zentrale Konfigurationsdatei für Claude Code — ein projektspezifisches Briefing, das das Verhalten des KI-Agenten steuert und konsistente Ergebnisse sicherstellt.

Stell dir CLAUDE.md wie ein Onboarding-Dokument für einen neuen Senior-Entwickler vor. Du würdest ihm nicht sagen "Schreib einfach Code" — du würdest ihm erklären, welchen Stack ihr nutzt, welche Konventionen gelten und wie das Projekt aufgebaut ist. Genau das macht CLAUDE.md.

Warum CLAUDE.md den entscheidenden Unterschied macht

Matching Course

Claude Basics — 297 €

6 live sessions · Prompting · Workflows · Certificate

View course

Ohne CLAUDE.md muss Claude Code bei jeder Aufgabe raten: - Welchen Tech Stack nutzt das Projekt? - Welche Code-Konventionen gelten? - Wie ist das Projekt strukturiert? - Welche Patterns sollen verwendet werden?

Mit CLAUDE.md: - Claude Code hält sich konsistent an deine Regeln - Du sparst 30–50 % der Korrekturen - Code-Qualität bleibt über Wochen und Monate stabil - Neue Teammitglieder können sofort produktiv arbeiten - Wiederkehrende Fehler werden eliminiert

Der Aufbau einer guten CLAUDE.md

Eine effektive CLAUDE.md folgt einer klaren Struktur. Hier ist das bewährte Schema:

1. Projekt-Übersicht

```markdown # Projektname

Kurze Beschreibung: Was das Projekt ist und wofür es dient. ```

Halte das kurz — ein bis zwei Sätze reichen. Claude Code braucht den Business-Kontext, um bessere Entscheidungen zu treffen.

2. Tech Stack

```markdown ## Tech Stack - Framework: Next.js 16 mit App Router - Sprache: TypeScript (strict mode) - Styling: Tailwind CSS v4 - Datenbank: Supabase (PostgreSQL) - Auth: Supabase Auth - Hosting: Vercel - Package Manager: pnpm ```

Which course fits you?

5 questions · 2 minutes · Personal recommendation

Start Course Finder

Sei spezifisch. Nicht nur "React" — sondern "React 19 mit Server Components". Nicht nur "Tailwind" — sondern "Tailwind CSS v4". Je präziser du bist, desto besseren Code bekommst du.

3. Projektstruktur

```markdown ## Projektstruktur - src/app/ — Next.js App Router (Seiten und Layouts) - src/components/ — Wiederverwendbare UI-Komponenten - src/components/ui/ — Basis-Komponenten (Button, Input, Card) - src/lib/ — Utilities, Hilfsfunktionen, Konfigurationen - src/hooks/ — Custom React Hooks - src/types/ — TypeScript Typen und Interfaces - content/ — Markdown-Dateien (Blog, Dokumentation) - public/ — Statische Assets (Bilder, Fonts) ```

Claude Code nutzt diese Information, um Dateien am richtigen Ort zu erstellen und bestehende Dateien zu finden.

4. Code-Konventionen

```markdown ## Konventionen - Verwende `import type` für Type-Only-Imports - Keine Enums — verwende `as const` Pattern - Funktionale Komponenten mit Arrow Functions - Deutsche Kommentare, englische Variablennamen - Jede Komponente hat einen eigenen Ordner mit index.tsx - Tests neben den Dateien: ComponentName.test.tsx - Fehlerbehandlung: Immer try/catch mit spezifischen Error-Typen ```

5. Spezifische Regeln

```markdown ## Regeln - KEINE CSS-Dateien — nur Tailwind-Klassen - KEINE `any` Types — immer explizite Typen - KEINE Default-Exports — nur Named Exports - Commit-Messages auf Deutsch - Maximale Dateigröße: 200 Zeilen — danach aufteilen ```

Großbuchstaben-Regeln wie "KEINE" und "IMMER" werden von Claude Code als strenge Constraints interpretiert. Nutze das bewusst.

6. Häufige Patterns

```markdown ## Patterns

Datenbank-Zugriff Immer über Server Actions in src/app/actions/: ```typescript "use server" export async function getUser(id: string) { const supabase = await createClient() const { data, error } = await supabase .from("users") .select("*") .eq("id", id) .single() if (error) throw new Error(error.message) return data } ```

API-Fehlerbehandlung ```typescript try { const result = await apiCall() return { success: true, data: result } } catch (error) { console.error("[API]", error) return { success: false, error: "Beschreibung" } } ``` ```

Code-Beispiele in der CLAUDE.md sind extrem wertvoll. Claude Code orientiert sich daran und reproduziert deine Patterns konsistent.

Beispiele für verschiedene Projekttypen

CLAUDE.md für eine Marketing-Website

```markdown # Marketing Website — Firma XYZ

Website für Lead-Generierung mit Blog, Landing Pages und Kontaktformular.

Tech Stack - Next.js 16, React 19, Tailwind CSS v4 - TypeScript strict, Framer Motion für Animationen - Supabase für Kontaktformular und Newsletter - Vercel Hosting, Vercel Analytics

Design-System - Farben: Primary #2563EB, Secondary #7C3AED, Neutral #1F2937 - Font: Inter (Body), Cal Sans (Headlines) - Spacing: 4px Basis-Grid (Tailwind Default) - Border-Radius: rounded-xl für Karten, rounded-full für Buttons - Schatten: shadow-lg für erhobene Elemente

SEO-Regeln - Jede Seite hat: title, description, og:image - H1 nur einmal pro Seite - Bilder immer mit alt-Text und next/image - Interne Links mit relativem Pfad - Strukturierte Daten (JSON-LD) für Blogposts

Content - Blog-Artikel in content/blog/ als Markdown - Sprache: Deutsch, Du-Ansprache - CTA am Ende jedes Artikels ```

CLAUDE.md für eine SaaS-Anwendung

```markdown # SaaS Dashboard — AppName

B2B SaaS für Projektmanagement mit Team-Funktionen.

Tech Stack - Next.js 16, React 19, TypeScript strict - Supabase (Auth, DB, Realtime, Storage) - Tailwind CSS v4, shadcn/ui Komponenten - Zustand für Client State, React Query für Server State - Stripe für Billing

Auth-Flow - Supabase Auth mit Email + Google OAuth - Middleware prüft Auth für /app/* Routen - Rollen: admin, member, viewer - RLS-Policies auf allen Tabellen

Datenbank-Konventionen - Tabellen: snake_case, Plural (users, projects, tasks) - Spalten: snake_case (created_at, updated_at) - Immer: id (UUID), created_at, updated_at - Soft Deletes: deleted_at statt DELETE - RLS auf jeder Tabelle — keine Ausnahmen

API-Pattern - Server Actions für Mutations - React Query für Reads - Optimistic Updates für bessere UX - Error Boundaries pro Feature-Bereich ```

CLAUDE.md für ein CLI-Tool

```markdown # CLI Tool — toolname

Node.js CLI-Tool für Batch-Verarbeitung von Markdown-Dateien.

Tech Stack - Node.js 22, TypeScript - Commander.js für CLI-Parsing - Chalk für farbige Ausgaben - Zod für Input-Validierung

Konventionen - ESM only (type: "module" in package.json) - Alle Funktionen mit JSDoc-Kommentaren - Exit-Codes: 0 = Erfolg, 1 = Fehler, 2 = falsche Argumente - Stderr für Fehler, Stdout für Output - Verbose-Flag (-v) für Debug-Output

Testing - Vitest für Unit Tests - Test-Fixtures in fixtures/ - Mindestens 80% Coverage ```

Die drei Ebenen von CLAUDE.md

Claude Code unterstützt CLAUDE.md-Dateien auf drei Ebenen:

1. Projekt-Level (Stamm-Verzeichnis)

``` mein-projekt/ ├── CLAUDE.md ← Hauptdatei, gilt für das gesamte Projekt ├── src/ ├── package.json ```

Diese Datei liest Claude Code bei jedem Start. Sie enthält die globalen Regeln.

2. Verzeichnis-Level (Unterordner)

``` mein-projekt/ ├── CLAUDE.md ├── src/ │ ├── components/ │ │ └── CLAUDE.md ← Gilt nur für Komponenten │ ├── api/ │ │ └── CLAUDE.md ← Gilt nur für API-Routes ```

Verzeichnis-spezifische CLAUDE.md-Dateien überschreiben oder ergänzen die globale Datei. Nützlich für unterschiedliche Konventionen in verschiedenen Bereichen.

3. User-Level (~/.claude/CLAUDE.md)

``` ~/.claude/ └── CLAUDE.md ← Gilt für ALLE deine Projekte ```

Persönliche Präferenzen, die projektübergreifend gelten: bevorzugte Sprache, allgemeine Code-Style-Regeln, wiederkehrende Patterns.

Priorität: User-Level → Projekt-Level → Verzeichnis-Level (spezifischere Regeln überschreiben allgemeinere).

Die 10 häufigsten Fehler

1. Zu viel auf einmal

Eine CLAUDE.md mit 500 Zeilen ist kontraproduktiv. Claude Code hat ein Kontextfenster — jedes Token in CLAUDE.md nimmt Platz weg, der für deine Aufgabe fehlt.

Faustregel: 50–150 Zeilen sind optimal. Fokussiere dich auf die wichtigsten Regeln.

2. Zu vage Formulierungen

Schlecht: *"Schreibe guten Code"* Besser: *"Verwende Error Boundaries für jede Route, TypeScript strict mode, keine any-Types"*

3. Widersprüchliche Regeln

Wenn du an einer Stelle schreibst "Verwende CSS Modules" und an anderer "Nur Tailwind-Klassen", wird Claude Code verwirrt. Prüfe deine CLAUDE.md auf Konsistenz.

4. Veraltete Informationen

Dein Stack entwickelt sich weiter — deine CLAUDE.md muss mitziehen. Plane eine monatliche Review ein.

5. Keine Code-Beispiele

Regeln ohne Beispiele sind interpretierbar. Ein konkretes Code-Snippet sagt mehr als drei Absätze Beschreibung.

6. Tech Stack nicht spezifisch genug

"React" kann React 16, 17, 18 oder 19 bedeuten — mit fundamental unterschiedlichen Patterns. Gib Versionsnummern an.

7. Projektstruktur fehlt

Ohne Strukturangabe erstellt Claude Code Dateien an unvorhersehbaren Orten. Definiere, wo was hingehört.

8. Keine Negativregeln

Sage nicht nur was du willst, sondern auch was du nicht willst. "KEINE Default Exports" ist genauso wichtig wie "Named Exports verwenden".

9. Formatierung ignoriert

CLAUDE.md ist Markdown — nutze Überschriften, Listen und Code-Blöcke für Klarheit. Eine gut formatierte Datei wird besser interpretiert als ein Fließtext.

10. CLAUDE.md nie updaten

Eine einmal geschriebene CLAUDE.md, die nie aktualisiert wird, wird mit der Zeit nutzlos. Behandle sie wie lebende Dokumentation.

Fortgeschrittene Techniken

Bedingte Anweisungen

```markdown ## Wenn du neue Komponenten erstellst: 1. Erstelle den Ordner unter src/components/ 2. Erstelle index.tsx mit der Komponente 3. Erstelle ComponentName.test.tsx mit mindestens 3 Tests 4. Exportiere aus src/components/index.ts ```

Referenzen auf andere Dateien

```markdown ## Referenzen - Design Tokens: siehe src/styles/tokens.ts - API-Types: siehe src/types/api.ts - Datenbank-Schema: siehe supabase/migrations/ ```

Claude Code kann diese Dateien dann bei Bedarf lesen.

Workflow-Anweisungen

```markdown ## Workflow für neue Features 1. Branch erstellen: feature/beschreibung 2. Implementation 3. Tests schreiben und ausführen 4. Commit mit aussagekräftiger Message 5. Nicht pushen — ich reviewe zuerst ```

Template für den Schnellstart

Hier ist ein universelles Template, das du für jedes Projekt anpassen kannst:

```markdown # [Projektname]

[Ein Satz: Was ist das Projekt?]

Tech Stack - [Framework + Version] - [Sprache + Konfiguration] - [Styling-Lösung] - [Datenbank/Backend] - [Hosting]

Projektstruktur - [Ordner] — [Zweck] - [Ordner] — [Zweck] - [Ordner] — [Zweck]

Konventionen - [Regel 1] - [Regel 2] - [Regel 3]

Regeln - KEINE [Anti-Pattern] - IMMER [Best Practice]

Patterns [Code-Beispiel für das wichtigste Pattern] ```

CLAUDE.md und Team-Arbeit

In Teams ist CLAUDE.md besonders wertvoll:

Versionskontrolle: CLAUDE.md gehört ins Git-Repository — jeder im Team arbeitet mit denselben Regeln
Code Reviews: Änderungen an CLAUDE.md werden genauso reviewed wie Code
Onboarding: Neue Teammitglieder lesen CLAUDE.md und verstehen sofort die Konventionen
Konsistenz: Alle Claude-Code-Nutzer im Team produzieren einheitlichen Code

Dein nächster Schritt

CLAUDE.md ist der Hebel, der dich von "Claude Code benutzen" zu "Claude Code beherrschen" bringt. Ohne CLAUDE.md nutzt du vielleicht 30 % des Potenzials. Mit einer guten CLAUDE.md sind es 90 %.

Willst du CLAUDE.md und Context Engineering im Detail lernen — mit Live-Übungen und Feedback? In unseren [Workshops](/de/workshops) baust du CLAUDE.md-Dateien für echte Projekte und lernst die Techniken, die den Unterschied machen.

Nicht sicher, welcher Kurs zu dir passt? Unser [Kurs-Finder](/de/kurs-finder) empfiehlt dir in 2 Minuten den passenden Einstieg. Oder schau dir unsere [Kurs-Bundles](/de/bundles) an, die CLAUDE.md Mastery mit praktischen Projekten kombinieren.

Deine CLAUDE.md ist der wichtigste Code, den du schreiben wirst — obwohl es gar kein Code ist.