CLAUDE.md schreiben

Die CLAUDE.md ist eine Markdown-Datei, die Claude Code automatisch beim Start einer Session liest. Sie enthält alles, was Claude über dein Projekt wissen muss: Tech-Stack, Konventionen, Build-Befehle und Regeln. Einmal geschrieben, sorgt sie dafür, dass Claude Code sofort produktiv arbeitet — ohne dass du jedes Mal erklären musst, wie dein Projekt aufgebaut ist.

Für wen ist das?

Für Entwickler, die Claude Code regelmäßig in einem Projekt einsetzen. Sobald du merkst, dass du Claude immer wieder die gleichen Dinge erklärst (“Wir nutzen TypeScript”, “Tests liegen in /tests”, “Verwende keine Semicolons”), lohnt sich eine CLAUDE.md.

Was lernst du?

Was eine CLAUDE.md ist und wie Claude Code sie verwendet
Wo die Datei liegt und welche Hierarchie-Ebenen es gibt
Welche Inhalte in eine gute CLAUDE.md gehören
Wie du deine erste CLAUDE.md Schritt für Schritt schreibst
Ein konkretes Beispiel zum Anpassen

Wann nutzen?

Du arbeitest wiederholt mit Claude Code im gleichen Projekt
Claude Code trifft Entscheidungen, die nicht zu deinem Projekt passen (falscher Stil, falsche Tools)
Du willst, dass neue Teammitglieder (und Claude) sofort wissen, wie das Projekt funktioniert

Wann nicht?

Für einmalige Aufgaben in einem fremden Ordner — da lohnt sich der Aufwand nicht
Wenn dein Projekt so klein ist, dass ein kurzer Prompt alles erklärt

Was ist eine CLAUDE.md?

Eine CLAUDE.md ist eine Markdown-Datei im Root deines Projekts. Wenn du claude im Terminal startest, sucht Claude Code automatisch nach dieser Datei und liest sie. Der Inhalt wird zum Kontext der Session — wie eine permanente Anweisung, die Claude Code bei jeder Aufgabe berücksichtigt.

Die vier Ebenen

Claude Code sucht an mehreren Orten nach CLAUDE.md-Dateien. Sie werden in dieser Reihenfolge geladen und ergänzen sich:

Global (~/.claude/CLAUDE.md) — Regeln, die für alle deine Projekte gelten (z.B. bevorzugte Sprache, allgemeine Konventionen)
Projekt-Root (CLAUDE.md im Projektverzeichnis) — Die wichtigste Datei. Enthält alles Projektspezifische.
Unterverzeichnisse (CLAUDE.md in Subdirectories) — Für spezielle Regeln in bestimmten Ordnern (z.B. andere Konventionen im Frontend vs. Backend)
Persönlich (.claude/CLAUDE.local.md) — Deine persönlichen Regeln, die nicht ins Repository committed werden

Die Projekt-Root CLAUDE.md ist die Datei, die du fast immer brauchst. Die anderen Ebenen sind optional und für fortgeschrittene Setups gedacht.

Wo gehört die Regel 'Verwende Vitest statt Jest' hin, wenn sie nur für ein bestimmtes Projekt gilt?

Was gehört in eine CLAUDE.md?

Eine gute CLAUDE.md beantwortet fünf Fragen:

Was ist das Projekt? — Kurze Beschreibung, Zweck, Zielgruppe
Welchen Tech-Stack nutzt es? — Sprachen, Frameworks, Tools, Versionen
Wie baue und teste ich? — Build-Befehle, Test-Befehle, Lint-Befehle
Wie ist es strukturiert? — Wichtige Verzeichnisse und ihre Bedeutung
Was sind die Regeln? — Do’s und Don’ts, Coding-Konventionen, Styleguide

Wenn es eine tsconfig.json, .eslintrc oder .prettierrc gibt, muss die CLAUDE.md deren Regeln nicht wiederholen. Claude Code liest diese Dateien selbst. Die CLAUDE.md ergänzt, was in Konfigurationsdateien nicht steht: Architekturentscheidungen, Konventionen und Verbote.

Deine erste CLAUDE.md schreiben

1

Datei erstellen

Erstelle eine Datei namens CLAUDE.md im Root-Verzeichnis deines Projekts. Öffne sie in einem Editor deiner Wahl.

2

Projekt beschreiben

Starte mit einer kurzen Beschreibung: Was ist das Projekt? Welche Sprache, welches Framework? Beispiel: '# Projekt-Name E-Commerce-API mit Node.js 20, Express und PostgreSQL.'

3

Build-Befehle dokumentieren

Liste die wichtigsten Befehle auf: Wie startet man die App? Wie laufen Tests? Wie wird gebaut? Claude Code nutzt diese Befehle aktiv.

Tipp Claude Code führt Build- und Test-Befehle aus. Wenn sie fehlen, rät Claude — und rät manchmal falsch.

4

Dateistruktur erklären

Beschreibe die wichtigsten Verzeichnisse. Claude Code muss wissen, wo Source-Code, Tests, Konfiguration und Assets liegen.

5

Regeln definieren

Definiere Do's und Don'ts: Welchen Code-Stil nutzt ihr? Welche Patterns sind erwünscht, welche verboten? Gibt es Namenskonventionen?

6

Testen

Starte Claude Code in deinem Projekt und stelle eine Aufgabe. Prüfe, ob Claude die Regeln aus der CLAUDE.md befolgt. Passe die Datei an, wenn nötig.

Konkretes Beispiel

# MeinShop API

E-Commerce-Backend mit Node.js 20, Express 4 und PostgreSQL 16.

## Tech-Stack
- Runtime: Node.js 20 LTS
- Framework: Express 4 mit TypeScript 5.4
- Datenbank: PostgreSQL 16 mit Prisma ORM
- Tests: Vitest + Supertest
- Linting: ESLint + Prettier

## Befehle
- `npm run dev` — Entwicklungsserver starten
- `npm test` — Alle Tests ausführen
- `npm run test:watch` — Tests im Watch-Mode
- `npm run build` — TypeScript kompilieren
- `npm run lint` — Linting ausführen

## Verzeichnisstruktur
- `src/routes/` — API-Endpunkte (eine Datei pro Ressource)
- `src/services/` — Business-Logik
- `src/middleware/` — Express Middleware
- `src/prisma/` — Datenbankschema und Migrationen
- `tests/` — Unit- und Integrationstests

## Regeln
- Kein `any` in TypeScript — verwende konkrete Typen
- Fehlerbehandlung immer mit Custom Error Classes aus `src/errors/`
- Neue Endpunkte brauchen mindestens einen Integrationstest
- Commit Messages auf Englisch, Conventional Commits Format
- Keine console.log — verwende den Logger aus `src/utils/logger.ts`

✗

Bitte schreibe guten Code und halte dich an Best Practices.

✓

Kein `any` in TypeScript. Fehler mit Custom Error Classes aus src/errors/. Neue Endpunkte brauchen mindestens einen Integrationstest.

Vage Anweisungen wie 'Best Practices' sagen Claude nichts Neues. Konkrete, testbare Regeln wirken sofort.

Typische Fehler

Zu lang: Eine CLAUDE.md mit 300 Zeilen überfrachtet den Kontext. Halte dich unter 150 Zeilen. Wenn du mehr brauchst, nutze CLAUDE.md-Dateien in Unterverzeichnissen.
Veraltete Informationen: Wenn sich der Tech-Stack oder die Befehle ändern, muss die CLAUDE.md aktualisiert werden. Veraltete Build-Befehle führen zu Fehlern.
Fehlende Build-Befehle: Ohne npm test oder npm run build rät Claude Code — und das geht oft schief.
Widersprüchliche Regeln: “Verwende Semicolons” in der globalen und “Keine Semicolons” in der Projekt-CLAUDE.md verwirrt Claude.
Alles doppelt erklären: Wenn es eine tsconfig.json, .eslintrc oder .prettierrc gibt, muss die CLAUDE.md deren Regeln nicht wiederholen. Claude Code liest diese Dateien selbst.

Mini-Übung

Schreibe eine CLAUDE.md für ein bestehendes Projekt auf deinem Rechner:

Öffne dein Projekt im Terminal
Erstelle eine CLAUDE.md im Root-Verzeichnis
Beschreibe: Tech-Stack, Build-Befehle, Verzeichnisstruktur, 3-5 Regeln
Starte Claude Code und frage: “Was weißt du über dieses Projekt?”
Prüfe, ob Claude die Informationen aus der CLAUDE.md korrekt wiedergibt

Mehr zum Unterschied zwischen CLAUDE.md und Projects findest du im Vergleich Projects vs. CLAUDE.md.

Nächster Schritt

Du hast jetzt eine CLAUDE.md, die Claude Code über dein Projekt informiert. Als Nächstes lernst du den Plan Mode kennen — damit analysiert Claude Code dein Projekt, bevor es Änderungen vornimmt.

Damit kannst du jetzt: Eine CLAUDE.md schreiben, die Claude Code über Tech-Stack, Build-Befehle und Coding-Regeln deines Projekts informiert.

Nächster Guide Plan Mode nutzen →

Neu → In Arbeit → Verstanden → Praxis

← Vorheriger Guide Artifacts teilen & exportieren Nächster Guide → Plan Mode nutzen

Erste Website mit Claude Code

Vom leeren Ordner zur fertigen Website. Claude Code Schritt für Schritt — auch ohne Programmiererfahrung.