Best Practices

Wissen

Was in die CLAUDE.md gehört

Eine gute CLAUDE.md enthält genau die Informationen, die Claude nicht aus dem Code selbst erschließen kann. Denk daran wie an das Briefing für einen erfahrenen Entwickler, der neu ins Team kommt: Du erklärst nicht, was eine for-Schleife ist, aber du erklärst die Eigenheiten eures Projekts.

Bash-Befehle, die Claude nicht erraten kann:

## Befehle
npm run dev          # Dev-Server (Port 3000)
npm run build        # Production Build (standalone)
npm run db:migrate   # Prisma Migrationen anwenden
npm run seed         # Testdaten laden

Code-Style-Regeln, die von Defaults abweichen:

## Code Style
- Keine Semikolons (Prettier-Config)
- Single Quotes statt Double Quotes
- Max 100 Zeichen pro Zeile
- Imports sortiert: externe zuerst, dann interne mit @/ Alias

Test-Anweisungen und bevorzugte Runner:

## Tests
- Unit Tests: `vitest run`
- E2E Tests: `playwright test`
- Vor jedem Commit: `npm run typecheck && npm run test`
- Snapshot-Tests nur für UI-Komponenten, nie für Logic

Repository-Etikette:

## Git-Konventionen
- Branch-Naming: feature/TICKET-123-kurze-beschreibung
- Conventional Commits: feat:, fix:, chore:, docs:
- PRs immer gegen `develop` branch, nie direkt gegen `main`
- Squash-Merge bevorzugt

Architektur-Entscheidungen:

## Architektur
- App Router mit [locale] Segment (de/en)
- Zustand für Client State, kein Redux
- MDX für Content, nicht Markdown
- Neue Komponenten MÜSSEN in zwei Dateien registriert werden:
  1. src/mdx-components.tsx
  2. src/app/.../page.tsx mdxComponents

Verstehen

Was NICHT in die CLAUDE.md gehört

Genauso wichtig wie der Inhalt ist das, was du weglässt. Eine zu lange CLAUDE.md wird von Claude zunehmend ignoriert -- ähnlich wie Menschen, die zu lange Emails überfliegen.

Was Claude aus dem Code selbst erschließen kann:

• Die Programmiersprache des Projekts
• Die Struktur der Verzeichnisse
• Welche Abhängigkeiten installiert sind
• Die Syntax der verwendeten Frameworks

Standard-Sprachkonventionen:

• "Variablen sollen beschreibende Namen haben" -- Das weiß Claude
• "Nutze async/await statt Callbacks" -- Standard in modernem JavaScript
• "Schreibe Typen für Funktionsparameter" -- TypeScript-Standard

Lange API-Dokumentation:

# Schlecht: Gesamte API-Docs kopiert
## User Endpoint
POST /api/users - Erstellt einen User
  Body: { name: string, email: string, ... }
  Response: { id: number, ... }
  ...50 weitere Zeilen...

# Besser: Link zur Doku
## API
Siehe @docs/api-reference.md oder https://api.example.com/docs

Häufig wechselnde Informationen:

• Aktuelle Ticket-Nummern
• Sprint-Ziele
• Temporäre Workarounds (lieber als Code-Kommentar)

Selbstverständlichkeiten:

• "Schreibe sauberen Code"
• "Teste deine Änderungen"
• "Verwende aussagekräftige Variablennamen"

Anwenden

## Commands
npm run dev    # Dev-Server
npm run build  # Production-Build
npm run lint   # Linting

Das 200-Zeilen-Ziel

Halte jede einzelne CLAUDE.md-Datei unter 200 Zeilen. Das ist kein hartes Limit, sondern eine Faustregel für maximale Wirksamkeit. Bei längeren Dateien passiert Folgendes:

1. Claude priorisiert Regeln am Anfang der Datei stärker
2. Regeln am Ende werden manchmal übersehen
3. Das Context-Budget wird unnötig belastet

Regelmäßig prunen: Überprüfe deine CLAUDE.md alle paar Wochen. Entferne Regeln, die Claude ohnehin befolgt (weil sie Standard sind), und aktualisiere veraltete Informationen.

Pro-Tipp: Interaktiver Init-Flow

Der Standard-/init-Befehl analysiert dein Projekt und generiert eine CLAUDE.md. Für einen noch detaillierteren, interaktiven Ablauf kannst du die Umgebungsvariable setzen:

CLAUDE_CODE_NEW_INIT=true claude

Damit stellt Claude dir gezielt Fragen zu deinem Projekt und erstellt eine maßgeschneiderte CLAUDE.md basierend auf deinen Antworten.