Die perfekte CLAUDE.md: So gibst du Claude Code den richtigen Kontext

TL;DR

Die CLAUDE.md ist eine Textdatei im Projektverzeichnis, die Claude Code bei jedem Start liest. Sie enthält Kontext zu deinem Projekt: Befehle, Code-Konventionen, Architektur-Entscheidungen. Je präziser die CLAUDE.md, desto weniger Korrekturen brauchst du.

---

Was ist eine CLAUDE.md?

Claude Code liest beim Start automatisch eine Datei namens CLAUDE.md im aktuellen Verzeichnis. Diese Datei enthält alles, was Claude über dein Projekt wissen muss.

Stell dir die CLAUDE.md wie ein Briefing für einen neuen Entwickler vor -- falls du Claude Code noch nicht kennst, starte mit unserem Überblick Was ist Claude Code?. Du erklärst:

• Wie das Projekt aufgebaut ist
• Welche Befehle zum Bauen, Testen und Deployen nötig sind
• Welche Code-Konventionen gelten
• Was der Kontext des Projekts ist

Ohne CLAUDE.md startet Claude Code jedes Mal bei null. Es kennt weder dein Tech-Stack noch deine Namenskonventionen. Mit CLAUDE.md hat es von der ersten Interaktion an den richtigen Kontext.

/init: Automatisch starten

Claude Code bietet den Befehl /init, der eine Starter-CLAUDE.md generiert. Der Befehl analysiert dein Projekt und erstellt eine erste Version mit:

• Erkanntem Tech-Stack (z.B. Next.js, Python, Go)
• Vorhandenen Build-Befehlen aus package.json oder Makefile
• Projektstruktur-Übersicht
• Grundlegenden Konventionen aus bestehendem Code

Die generierte Datei ist ein Ausgangspunkt, kein fertiges Ergebnis. Du solltest sie nach der Generierung anpassen und erweitern.

Boris Chernys Ansatz: Fehler werden zur Regel

Boris Cherny, Autor von "Programming TypeScript" (O'Reilly), beschreibt seinen Workflow so:

"Jedes Mal wenn Claude etwas falsch macht, wird es zur CLAUDE.md hinzugefügt."

Das klingt simpel, ist aber der effektivste Weg, eine gute CLAUDE.md aufzubauen. Beispiel:

1. Claude erstellt eine Komponente mit className statt deiner eigenen cn()-Utility.
2. Du korrigierst es.
3. Du fügst zur CLAUDE.md hinzu: "Verwende immer cn() aus @/lib/utils für Klassen, nie className direkt."

Nach einigen Wochen deckt die CLAUDE.md alle typischen Fehler ab. Claude macht sie nicht mehr.

Aufbau einer guten CLAUDE.md

1. Projektübersicht

E-Commerce-Plattform für nachhaltige Produkte.
Tech-Stack: Next.js 15, TypeScript, Prisma, PostgreSQL, Tailwind CSS.
Monorepo mit Turborepo.

Zwei bis drei Sätze reichen. Claude braucht den Kontext, keine Marketingbeschreibung.

2. Befehle

## Befehle

- Build: `pnpm build`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`
- DB Migration: `pnpm prisma migrate dev`
- DB Seed: `pnpm prisma db seed`

Konkrete Befehle, die Claude direkt ausführen kann. Kein "Nutze den üblichen Build-Prozess." Eine vollständige Liste aller Befehle findest du im Claude Code Befehle Cheatsheet.

3. Code-Konventionen

## Code-Stil

- Funktionale Komponenten mit Arrow Functions
- Named Exports, keine Default Exports
- Zod für alle Validierungen
- Server Actions statt API Routes wo möglich
- Fehler mit `AppError`-Klasse werfen, nie mit `Error`
- Alle DB-Queries in `/lib/db/`-Dateien, nie direkt in Komponenten

Hier liegt der größte Hebel. Je klarer die Regeln, desto konsistenter der Output. Weitere Tipps dazu findest du in unseren Claude Code Best Practices.

4. Architektur-Entscheidungen

## Architektur

- Alle Seiten sind Server Components (RSC), Client Components nur wenn nötig
- State Management: Zustand (kein Redux)
- Auth: NextAuth v5 mit Prisma Adapter
- Payments: Stripe Checkout Sessions, Webhooks in `/app/api/webhooks/stripe`

5. Projektspezifische Regeln

## Regeln

- KEINE neuen Dependencies ohne Rückfrage
- Tests für jede neue API-Route schreiben
- Commits in Conventional Commits Format
- Alle Preise in Cent speichern, erst im Frontend formatieren
- E-Mails nur über den EmailService, nie direkt über Resend

Beispiele für verschiedene Projekttypen

Python-Projekt

# Data Pipeline

ETL-Pipeline für Kundendaten. Python 3.12, Poetry, SQLAlchemy 2.0, Polars.

## Befehle

- Install: `poetry install`
- Test: `poetry run pytest`
- Lint: `poetry run ruff check .`
- Type Check: `poetry run mypy .`

## Code-Stil

- Type Hints überall, keine `Any`-Types
- Pydantic Models für alle Datenstrukturen
- async/await für I/O-Operationen
- Logging mit structlog, nie print()
- Alle SQL-Queries als SQLAlchemy ORM, kein Raw SQL

Go-Projekt

# API Server

REST API für Mobile App. Go 1.23, Chi Router, pgx, sqlc.

## Befehle

- Build: `go build ./cmd/server`
- Test: `go test ./...`
- Generate: `go generate ./...`
- Migrate: `goose -dir migrations up`

## Code-Stil

- Error Wrapping mit fmt.Errorf("context: %w", err)
- Interfaces im Consumer-Package definieren
- Table-driven Tests
- Context als erster Parameter
- Keine globalen Variablen

CLAUDE.md als Team-Gedächtnis

Die CLAUDE.md gehört ins Git-Repository. Jeder im Team kann sie bearbeiten. Das hat drei Vorteile:

1. Konsistenz: Alle Teammitglieder arbeiten mit denselben Regeln. Wenn ein Entwickler eine Konvention entdeckt, die Claude falsch macht, profitiert das ganze Team von der Korrektur.

2. Onboarding: Neue Teammitglieder lesen die CLAUDE.md und verstehen sofort die Projekt-Konventionen. Die Datei ist gleichzeitig Dokumentation für Menschen und Konfiguration für Claude. Wie du Claude Code im Team effektiv einsetzt, beschreibt unser Artikel Claude Code für Teams.

3. Versionierung: Über Git siehst du, wie sich die Konventionen über die Zeit entwickelt haben. Jede Änderung ist nachvollziehbar. Die CLAUDE.md lässt sich auch in CI/CD-Pipelines nutzen, damit automatisierte Claude-Code-Läufe denselben Kontext haben.

Hierarchie von CLAUDE.md-Dateien

Claude Code unterstützt mehrere CLAUDE.md-Dateien:

• ~/.claude/CLAUDE.md: Globale Einstellungen, gelten für alle Projekte.
• /projekt/CLAUDE.md: Projektspezifische Regeln, eingecheckt in Git.
• /projekt/CLAUDE.local.md: Persönliche Einstellungen, nicht in Git (in .gitignore).
• /projekt/src/CLAUDE.md: Verzeichnisspezifische Regeln für Unterordner.

Claude liest alle relevanten Dateien und kombiniert sie. Die spezifischere Datei gewinnt bei Konflikten.

Häufige Fehler vermeiden

Fehler 1: Zu vage formulieren

Schlecht: "Schreibe guten Code."

Gut: "Alle Funktionen mit mehr als 3 Parametern bekommen ein Options-Objekt als einzigen Parameter."

Fehler 2: Zu viel auf einmal

Eine CLAUDE.md mit 500 Zeilen überfordert den Kontext. Beginne mit den 10 wichtigsten Regeln. Erweitere nur, wenn Claude tatsächlich Fehler macht. Jede Regel sollte sich auf ein konkretes Problem beziehen.

Fehler 3: Veraltete Informationen

Wenn du von Express auf Hono migrierst, aber die CLAUDE.md noch Express-Patterns beschreibt, produziert Claude inkonsistenten Code. Halte die Datei aktuell. Behandle sie wie Code, nicht wie Dokumentation.

Fehler 4: Keine Befehle angeben

Claude kann Befehle ausführen. Wenn es nicht weiß, wie es dein Projekt baut oder testet, muss es raten. pnpm build vs. npm run build vs. yarn build macht einen Unterschied.

Fehler 5: Nur positive Regeln

"Verwende Tailwind" ist gut. "Verwende KEIN inline CSS" ist genauso wichtig. Claude braucht sowohl die Do's als auch die Don'ts.

Erste CLAUDE.md in 5 Minuten

1. Öffne das Projekt in Claude Code.
2. Führe /init aus.
3. Prüfe die generierte Datei.
4. Ergänze die fünf wichtigsten Code-Konventionen deines Teams.
5. Füge die Build- und Test-Befehle hinzu.
6. Committe die Datei.

Ab jetzt wird jede Interaktion mit Claude Code präziser.

---

FAQ

Muss die Datei CLAUDE.md heißen?

Ja. Claude Code sucht spezifisch nach dem Dateinamen CLAUDE.md (Großbuchstaben). Andere Namen wie ai-instructions.md werden ignoriert.

Wie lang sollte eine CLAUDE.md sein?

50 bis 200 Zeilen sind ein guter Richtwert. Kurz genug, um den Kontext nicht zu überlasten. Lang genug, um alle wichtigen Regeln abzudecken.

Wird die CLAUDE.md bei jedem Prompt gelesen?

Ja. Claude Code liest die CLAUDE.md bei jedem Start einer neuen Session. Sie fließt in den System-Prompt ein und steht damit für alle Interaktionen zur Verfügung.

Kann ich mehrere CLAUDE.md-Dateien haben?

Ja. Claude Code unterstützt eine Hierarchie: global (~/.claude/CLAUDE.md), projekt-weit, lokal (.local.md) und verzeichnisspezifisch. Alle werden kombiniert.

Was ist der Unterschied zwischen CLAUDE.md und .cursorrules?

CLAUDE.md ist für Claude Code, .cursorrules für Cursor. Das Konzept ist identisch: dem KI-Tool Projektkontext geben. Die Syntax und Features unterscheiden sich leicht.

Soll ich die CLAUDE.md in Git einchecken?

Ja. Die projektweite CLAUDE.md gehört ins Repository. Persönliche Einstellungen kommen in CLAUDE.local.md, die du in .gitignore einträgst.

Was bringt /init genau?

Der Befehl /init analysiert dein Projekt (Tech-Stack, Struktur, vorhandene Config-Dateien) und generiert eine Starter-CLAUDE.md. Das Ergebnis ist brauchbar, aber du solltest es anpassen.

Funktioniert CLAUDE.md auch mit anderen KI-Tools?

Nein. CLAUDE.md ist spezifisch für Claude Code. Cursor nutzt .cursorrules, GitHub Copilot nutzt .github/copilot-instructions.md. Das Konzept überträgt sich, aber die Dateien sind nicht austauschbar.