Der komplette Leitfaden zum Schreiben von CLAUDE.md: Best Practices für die Projektkonfiguration

Was ist CLAUDE.md?

CLAUDE.md ist eine Kontextdatei, die Claude Code hilft, Ihr Projekt zu verstehen. Platzieren Sie sie im Stammverzeichnis Ihres Projekts, und Claude Code liest sie automatisch zu Beginn jeder Sitzung. Eine gut geschriebene CLAUDE.md kann die Qualität der Antworten von Claude Code dramatisch verbessern.

Dateispeicherorte und Priorität

Sie können CLAUDE.md-Dateien an mehreren Orten platzieren, und alle werden geladen:

~/.claude/CLAUDE.md          # Globale Einstellungen (projektübergreifend)
./CLAUDE.md                   # Projektstamm (im Team geteilt)
./CLAUDE.local.md             # Lokale Einstellungen (in .gitignore aufnehmen)
./src/CLAUDE.md               # Unterverzeichnis-Einstellungen

• Global: Ihre persönlichen Coding-Style-Präferenzen
• Projektstamm: Im Team geteilte Regeln und Tech-Stack
• Lokal: Persönliche Einstellungen, die nicht in Git committet werden
• Unterverzeichnis: Zusätzlicher Kontext für bestimmte Module

Einstiegsvorlage

Hier ist eine praktische CLAUDE.md-Vorlage:

# Projektübersicht

E-Commerce-Backend-API. Verwaltet Bestellungen, Inventar und Benutzerauthentifizierung.

## Tech-Stack

- Sprache: TypeScript 5.x
- Runtime: Node.js 22
- Framework: Fastify
- DB: PostgreSQL 16 + Prisma ORM
- Testing: Vitest
- CI: GitHub Actions

## Verzeichnisstruktur

src/
  routes/       # API-Endpunkt-Definitionen
  services/     # Geschäftslogik
  repositories/ # Datenzugriffsschicht
  middleware/   # Auth, Logging, Fehlerbehandlung
  utils/        # Hilfsfunktionen
  types/        # Typdefinitionen

## Coding-Konventionen

- Pfeilfunktionen verwenden
- Fehlerbehandlung immer mit try-catch und benutzerdefinierten Fehlerklassen
- Benennung: camelCase (Variablen/Funktionen), PascalCase (Typen/Klassen)
- Dateinamen: kebab-case
- Pfad-Alias `@/` statt relativer Imports verwenden

## Häufige Befehle

- Tests ausführen: `npm test`
- Typprüfung: `npx tsc --noEmit`
- Lint: `npm run lint`
- DB-Migration: `npx prisma migrate dev`
- Dev-Server: `npm run dev`

## Wichtige Regeln

- Nach Änderungen an prisma/schema.prisma immer eine Migration erstellen
- Jeder API-Endpunkt muss ein Zod-Validierungsschema haben
- Neue Routen in routes/index.ts registrieren

Tipps für effektive CLAUDE.md-Dateien

1. Halten Sie es kurz

CLAUDE.md verbraucht Kontextfenster-Tokens. Vermeiden Sie ausschweifende Erklärungen und halten Sie sich an Aufzählungspunkte.

# Schlechtes Beispiel
Dieses Projekt verwendet TypeScript. TypeScript ist eine von
Microsoft entwickelte Sprache, die JavaScript um Typen erweitert...

# Gutes Beispiel
- Sprache: TypeScript 5.x (Strict-Modus)

2. Dokumentieren Sie, was Sie nicht wollen

Das explizite Auflisten von Anti-Patterns ist überraschend wirkungsvoll.

## Verboten

- Keine `any`-Typen
- Keine Default-Exports (nur benannte Exports)
- Kein console.log zum Debuggen (den Logger verwenden)
- Bestehende Tests niemals löschen oder überspringen

3. Workflows definieren

Geben Sie Claude Code eine Anleitung, wie Aufgaben angegangen werden sollen.

## Neues Feature hinzufügen

1. Typdefinitionen in `src/types/` erstellen
2. Datenzugriffsschicht in `src/repositories/` implementieren
3. Geschäftslogik in `src/services/` implementieren
4. Endpunkte in `src/routes/` definieren
5. Unit-Tests für jede Schicht schreiben
6. Überprüfen, dass alle Tests mit `npm test` bestehen

4. Implizites Wissen festhalten

Dokumentieren Sie wichtige Informationen, die nirgendwo anders festgehalten sind.

## Projektspezifische Hinweise

- `user_id` verwendet UUID v7 (für zeitsortierbare Reihenfolge)
- Alle Preisberechnungen müssen `Decimal.js` verwenden (um Gleitkomma-Fehler zu vermeiden)
- Umgebungsvariablen sind in `src/config.ts` zentralisiert — niemals direkt auf process.env zugreifen

Team-Nutzung

.gitignore-Einrichtung

Halten Sie persönliche Einstellungen aus der Versionsverwaltung:

# .gitignore
CLAUDE.local.md

In Code-Reviews einbeziehen

Behandeln Sie CLAUDE.md als wichtiges Projektdokument. Beziehen Sie es in PR-Reviews ein und halten Sie es als Team aktuell.

Wann sollte CLAUDE.md aktualisiert werden

• Wenn eine neue Bibliothek hinzugefügt wird
• Wenn Coding-Konventionen geändert werden
• Wenn Verzeichnisse umstrukturiert werden
• Wenn Ihnen auffällt, dass Claude Code wiederholt denselben Fehler macht

Fazit

CLAUDE.md macht Claude Code zum Experten für Ihr spezifisches Projekt. Beginnen Sie damit, ein Gerüst mit /init zu generieren, und verfeinern Sie es während der Arbeit. Teilen Sie es mit Ihrem Team, damit alle von optimierten Claude-Code-Interaktionen profitieren.