So erstellst du die perfekte CLAUDE.md (inkl. Template)

Vielleicht kennst du das:

Claude macht irgendwas Komisches, erstellt plötzlich 10 neue Dateien obwohl du nur einen Bug fixen wolltest, verwendet JavaScript obwohl dein ganzes Projekt TypeScript ist oder verbringt vor jeder Aufgabe erst einmal 5 Minuten oder mehr damit, dein Projekt zu verstehen.

Die Lösung dafür ist, eine bzw. mehrere CLAUDE.md Dateien zu erstellen.

In diesem Blogartikel zeige ich dir, wie du eine perfekte CLAUDE.md Datei erstellen kannst inkl. Template, Beispielen und Profi-Tipps. Damit du nie mehr (oder, realistisch, weniger häufig) „Claude, nein! Was zum Teufel machst du da?“ sagen musst.

1. Was ist eine CLAUDE.md-Datei?

CLAUDE.md ist eine „Hier sind meine Regeln“-Datei für Claude Code. Du sagst ihm einmal, wie er bei dir arbeiten soll, und er merkt es sich für alle zukünftigen Sessions.

Wichtig dabei zu verstehen:

Eine CLAUDE.md ist keine statische Dokumentation, sondern eine lebendige Dokumention von Claudes Fehlern. Jedes Mal, wenn Claude etwas falsch macht, wandert diese Korrektur direkt in meine CLAUDE.md (sodass Claude mit jeder Aufgabe etwas schlauer wird).

Nachdem ich mich wochenlang mit Claude herumgeärgert habe, habe ich mal meine Sessions analysiert. Und mit einer ordentlichen CLAUDE.md klappt's einfach viel besser.

2. Globale, projekt- und ordnerspezifische CLAUDE.md

Es gibt folgende Arten von CLAUDE.md-Dateien:

• Globale CLAUDE.md (~/.claude/CLAUDE.md): Deine persönlichen Einstellungen, die für alle Projekte gelten
• Projektspezigische (im Projekt-Root): Spezifische Anweisungen für ein einzelnes Projekt
• Ordnerspezifische CLAUDE.md (im Projekt-Root): Spezifische Anweisungen für ein einzelnes Ordner

Du musst alle drei Dateitypen nicht in Prompts referenzieren, Claude Code überprüft mit jedem Prompt automatisch, ob globale, projektspezifische oder ordnerspezifische CLAUDE.md-Dateien existieren und lädt sie entsprechend ins Context Window.

Claude lädt CLAUDE.md-Dateien dabei hierarchisch und kombiniert sie intelligent. Die spezifischste (am tiefsten verschachtelte) Datei gewinnt bei Konflikten. Das heißt:

# ~/.claude/CLAUDE.md (Global)
- Verwende immer TypeScript
- Schreibe Tests mit Jest

# ~/projekt/CLAUDE.md (Projekt)
- Schreibe Tests mit Vitest  # Überschreibt Jest

# Resultat für Claude:
- Verwende immer TypeScript (von global)
- Schreibe Tests mit Vitest (von projekt)

Du solltest dennoch Konflikte zwischen den Dateitypen vermeiden oder klar auf Konflikte hinweisen, um unerwartetem Verhalten vorzubeugen.

3. Aufbau und Struktur

CLAUDE.md ist eine normale Markdown-Datei. Nichts Magisches dran. Claude interpretiert sie als zusätzlichen Kontext für jede Anfrage.

Der Trick ist, die richtige Balance zu finden zwischen „zu wenig Info“ und „Token-Verschwendung“. Im Zuge dessen halte ich die Formatierung möglichst einfach. Ich benutze größtenteils nur:

• Überschriften mit # für Struktur
• Bullet Points mit - für Listen
• Code-Blöcke mit ``` für Beispiele
• Bold mit **text** für Wichtiges

Was du vermeiden solltest sind Tabellen (zu viele Token), Bilder (werden ignoriert), Links (meistens nutzlos).

4. Schritt für Schritt die CLAUDE.md erstellen

Lass uns praktisch werden. Ich zeig dir, wie du in 10 Minuten eine solide CLAUDE.md erstellst, die tatsächlich was bringt.

4.1 Globale CLAUDE.md in ~/.claude/ einrichten

Erst mal die globale Datei. Die sollte deine persönlichen Präferenzen enthalten, das heißt Dinge, die du immer willst, egal an welchem Projekt du arbeitest:

# Terminal
mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md

Hier findest du eine Beispiel für eine globale CLAUDE.md:

# Globale Entwickler-Präferenzen

## Allgemeine Regeln
- Bevorzuge TypeScript über JavaScript
- Schreibe Code auf Englisch, Kommentare auf Deutsch
- Verwende moderne ES6+ Syntax
- Keine console.log() in Production-Code

## Code-Qualität
- Schreibe sauberen, lesbaren Code
- Verwende aussagekräftige Variablennamen
- Halte Funktionen klein (max. 20 Zeilen)
- DRY-Prinzip befolgen

## Fehlerbehandlung
- Immer try-catch bei async/await
- Niemals Fehler verschlucken
- Aussagekräftige Fehlermeldungen

## Git
- Commit-Messages auf Deutsch
- Conventional Commits Format nutzen
- Niemals direkt auf main pushen

4.2 Projekt-spezifische Anweisungen definieren

Jetzt die projektspezifische CLAUDE.md. Die sollte alles enthalten, was Claude über dein spezifisches Projekt wissen muss.

Dazu gibst du einfach folgenden Befehl an Claude Code:

Erstelle eine CLAUDE.md für dieses Projekt. Analysiere das Projekt dafür umfassend, um nichts zu vergessen. Nutze folgende Vorlage:"

Und kopierst folgendes Template mit herein (einfach per Copy & Paste):

# [Projekt Name]

[Ein-Satz-Beschreibung des Projekts]

## Tech Stack
- **Framework**: [z.B. Next.js, React, Vue]
- **Sprache**: [z.B. TypeScript, Python]
- **Datenbank**: [z.B. PostgreSQL, MongoDB]
- **Styling**: [z.B. Tailwind, CSS Modules]
- **Testing**: [z.B. Jest, Vitest, Pytest]

## Projektstruktur
```
src/
├── [wichtige ordner]/   # [Beschreibung]
├── [weitere ordner]/    # [Beschreibung]
└── [config dateien]     # [Beschreibung]
```

## Entwicklung
```bash
[install befehl]         # Dependencies installieren
[dev befehl]            # Entwicklungsserver
[build befehl]          # Production Build
[test befehl]           # Tests ausführen
```

## Code-Standards
- [Standard 1, z.B. "TypeScript strict mode"]
- [Standard 2, z.B. "ESLint Regeln befolgen"]
- [Standard 3, z.B. "Keine any Types"]
- [Standard 4, z.B. "Tests für neue Features"]

## Projektspezifische Regeln
- [Regel 1, z.B. "API calls nur über services/"]
- [Regel 2, z.B. "Styling nur mit Tailwind"]
- [Regel 3, z.B. "Komponenten müssen typed sein"]

## Wichtige Hinweise
- [Hinweis 1, z.B. "Production secrets in .env.production"]
- [Hinweis 2, z.B. "Keine direkten DB queries"]
- [Hinweis 3, z.B. "Rate limiting beachten"]

## Häufige Fehler vermeiden
- NICHT: [Häufiger Fehler]
- NICHT: [Weiterer Fehler]
- IMMER: [Best Practice]
- IMMER: [Weitere Best Practice]

Und so kann das dann am Ende aussehen:

# KI-Blog Projekt

Next.js 15 Blog mit TypeScript, fokussiert auf KI und SEO-Themen.

## Tech Stack
- **Framework**: Next.js 15.3.3 mit App Router
- **Sprache**: TypeScript 5.x (strict mode)
- **Styling**: Tailwind CSS v4 mit PostCSS
- **UI**: Radix UI + shadcn/ui Komponenten
- **Datenbank**: PostgreSQL mit Prisma ORM

## Projektstruktur
```
src/
├── app/              # Next.js App Router
│   └── blog/         # Blog-Posts (WICHTIG: Keine /blog/ URL!)
├── components/       # React Komponenten
│   └── ui/          # shadcn/ui Komponenten
├── lib/             # Utilities und Services
└── types/           # TypeScript Types
```

## Wichtige Befehle
```bash
npm run dev          # Entwicklungsserver
npm run build        # Production Build
npm run lint         # ESLint ausführen
npm run typecheck    # TypeScript prüfen
```

## Blog-System Regeln
- Blog-Posts in src/app/blog/[slug]/page.tsx
- URLs OHNE /blog/ Prefix (Rewrite in next.config.ts)
- Immer BlogPostConfig für Metadata nutzen
- CodeBlock Komponente für alle Code-Beispiele
- FAQ Items außerhalb der Komponente definieren

## Code-Standards
- Komponenten in PascalCase
- Utilities in camelCase
- Tailwind statt CSS-Module
- Keine neuen Komponenten ohne Check in ui/
- Deutsche Inhalte, englischer Code

## Häufige Fehler vermeiden
- NICHT: Neue README.md erstellen
- NICHT: console.log in Code lassen
- NICHT: Neue UI-Komponenten von Scratch
- IMMER: Bestehende Dateien bearbeiten
- IMMER: TypeScript strict mode

## Git Workflow
- Feature-Branches von main
- PR vor Merge
- Squash Commits beim Merge

5. Häufige Anfängerfehler vermeiden

Folgende Fehler solltest du dabei vermeiden:

1. Zu vage sein: „Schreibe guten Code" bringt nichts. Sei spezifisch: „Verwende async/await statt Promises"
2. Zu viel reinpacken: 1000+ Zeilen CLAUDE.md? Claude ignoriert die Hälfte. Halte die CLAUDE.md kompakt.
3. Datei am falschen Ort Check mit ls -la ~/.claude/ und im Projekt-Root
4. Nicht updaten: Projekt ändert sich, CLAUDE.md bleibt gleich = Chaos
5. Widersprüchliche Anweisungen „Nutze Tabs" global und „Nutze Spaces" lokal = Chaos (oft kann Claude Konflikte erkennen, aber nicht immer)
6. Falsche Markdown-Syntax Keine Tabs, nur Spaces. Markdown muss valide sein.
7. Alles erklären wollen: Claude kennt die Basics. Du musst nicht erklären was React ist.
8. Copy-Paste ohne Anpassung: Meine Vorlage ist ein Startpunkt, nicht die Lösung.

6. Anpassung an deinen Workflow

Die Vorlage ist nur der Anfang. Was bei mir funktioniert, muss nicht bei dir klappen. Hier mein Workflow zum Anpassen:

1. Starte mit der Basis-Vorlage
2. Arbeite eine Woche oder ein paar Tage normal mit Claude
3. Notiere jeden „Claude macht X falsch“-Moment
4. Füge diese als Regel zur CLAUDE.md hinzu
5. Teste, ob's besser wird
6. Repeat

Nach 2-3 Wochen hast du eine CLAUDE.md, die perfekt zu deinem Stil passt.

7. Profi-Tipps: Erweiterte CLAUDE.md Konfiguration

Zeit für die Advanced-Tricks, die den Unterschied zwischen „ganz okay" und „holy shit das ist gut" ausmachen.

7.1 Kontext-spezifische Anweisungen formulieren

Statt allgemeiner Anweisungen, mach sie situationsspezifisch:

## Kontext-Regeln

### Bei Bug-Fixes
- Erst verstehen, dann fixen
- Root cause analysieren
- Regression-Test schreiben
- Changelog updaten

### Bei neuen Features
- Erst Types/Interfaces definieren
- API-First Design
- Tests parallel schreiben
- Documentation-Comments

### Bei Refactoring
- Funktionalität nicht ändern
- Tests müssen grün bleiben
- Schrittweise vorgehen
- Performance messen

7.2 Code-Standards und Best Practices definieren

Sei ultra-spezifisch bei Code-Standards. Claude macht genau das, was du sagst – nicht mehr, nicht weniger:

## Code-Standards (Detailed)

### Naming Conventions
- Komponenten: PascalCase (UserProfile, NavBar)
- Hooks: camelCase mit 'use' prefix (useAuth, useFetch)
- Utils: camelCase (formatDate, parseJson)
- Constants: SCREAMING_SNAKE_CASE (API_URL, MAX_RETRY)
- Types/Interfaces: PascalCase mit Suffix (UserType, ApiResponse)

### Async Code
```typescript
// IMMER so:
try {
  const data = await fetchData()
  return processData(data)
} catch (error) {
  logger.error('Fetch failed:', error)
  throw new AppError('Data fetch failed', error)
}

// NIEMALS so:
fetchData().then(data => processData(data))
```

### Imports
- Absolute imports für src/ ('@/components/Button')
- Grouped imports (React, Third-party, Local)
- Named exports bevorzugen

7.3 Projektstruktur und Dateipfade optimieren

Claude neigt dazu, Dateien am falschen Ort zu erstellen. Sei explizit:

## Datei-Locations (WICHTIG!)

### Wo neue Dateien hinkommen:
- React Components → src/components/[name]/[Name].tsx
- API Routes → src/app/api/[route]/route.ts
- Utilities → src/lib/utils/[name].ts
- Types → src/types/[name].types.ts
- Hooks → src/hooks/use[Name].ts
- Tests → [same-folder]/[name].test.ts

### Diese Ordner NICHT anfassen:
- node_modules/ (obvious, aber Claude macht's trotzdem)
- .next/ (Build output)
- dist/ (Build output)
- coverage/ (Test output)

### Bei Unsicherheit:
Frag mich IMMER bevor du neue Dateien erstellst!

7.4 Performance-Optimierung großer CLAUDE.md-Dateien

Große CLAUDE.md-Dateien können Claude verlangsamen. Hier kann es helfen, die Anweisungen aus der CLAUDE.md in separate Docs auszulagern:

# Projekt-Kern (Max 100 Zeilen)

## Must-Know (Top Priority)
- [Nur das Allerwichtigste]
- [Max 10 Punkte]

## Quick Reference
```
npm run dev
npm run build
npm run test
```

## Details siehe:
- Architecture: docs/ARCHITECTURE.md
- API: docs/API.md
- Testing: docs/TESTING.md

Lagere Details in separate Docs aus und referenziere sie. Claude kann bei Bedarf nachfragen.

7.5 Versionskontrolle und Team-Synchronisation

Was du machen kannst, wenn du im Team arbeitest:

• CLAUDE.md ins Repo: Ja, committe sie. Alle im Team profitieren.
• CLAUDE.personal.md in .gitignore: Für persönliche Präferenzen
• Changelog am Ende: Dokumentiere Änderungen

# Team Projekt

[... Projekt-Config ...]

---
## Changelog
- 2025-01-25: TypeScript strict mode aktiviert (FH)
- 2025-01-20: Tailwind v4 Update (MK)
- 2025-01-15: Initial version (FH)

8. CLAUDE.md Support bei anderen Tools

CLAUDE.md ist nicht nur für Claude Code. Immer mehr KI-Coding-Tools unterstützen das Format – entweder nativ oder als Fallback. Hier siehst du, welche Tools CLAUDE.md und andere Konfigurationsstandards unterstützen:

Tipp: Wenn du in einer Multi-Tool-Umgebung arbeitest, kann es sinnvoll sein, deine CLAUDE.md in AGENTS.md umzubenennen und einen Symlink für Claude Code zu erstellen:

# CLAUDE.md → AGENTS.md (Universell) + Symlink
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md