CLAUDE.md: Best Practices für Projekt-Konfiguration

CLAUDE.md ist die "Verfassung" Ihres Repositories. Die Datei, die Claude beim Start jeder Session liest und die bestimmt, wie Claude mit Ihrem Projekt arbeitet. Richtig eingesetzt spart sie unzählige Erklärungen.

Was ist CLAUDE.md?

CLAUDE.md ist eine automatisch geladene Konfigurationsdatei. Wenn Sie Claude Code in einem Projekt starten, liest Claude diese Datei und befolgt die Anweisungen.

Ohne CLAUDE.md:

User: Formatiere den Code
Claude: [nutzt Tabs statt Spaces]

User: Nein, wir nutzen 2 Spaces...
Claude: [korrigiert]

User: Und führe danach lint aus
Claude: [vergisst es beim nächsten Mal]

Mit CLAUDE.md:

# Code Style
- 2 Spaces, keine Tabs
- Nach Edit immer `npm run lint` ausführen

Claude erinnert sich - in jeder Session.

Datei-Locations

CLAUDE.md kann an verschiedenen Stellen liegen:

Wichtig: Die Datei muss exakt CLAUDE.md heissen (CLAUDE gross, .md klein).

Lade-Reihenfolge

Claude lädt alle relevanten Dateien und kombiniert sie:

1. ~/.claude/CLAUDE.md (User)
2. Parent-Directories (für Monorepos)
3. ./CLAUDE.md (Project)
4. CLAUDE.local.md (persönliche Overrides)
5. Child-Directories (on-demand)

Was gehört rein?

Ja, unbedingt

Nein, weglassen

Template: CLAUDE.md Struktur

# Projekt-Name

## Commands
npm run dev     # Dev Server auf :3000
npm run build   # Production Build
npm run test    # Vitest
npm run lint    # ESLint + Prettier

## Code Style
- TypeScript strict mode
- 2 Spaces, keine Tabs
- Imports: Named exports bevorzugen
- Keine default exports ausser für Pages

## Architecture
- State: Zustand (siehe src/stores/)
- API: React Query (siehe src/hooks/api/)
- Styling: Tailwind CSS, keine inline styles
- Forms: React Hook Form + Zod

## Testing
- Unit Tests: Vitest
- E2E: Playwright
- Test-Dateien neben Source: `Button.tsx` → `Button.test.tsx`

## Git
- Branch: feature/ABC-123-kurze-beschreibung
- Commits: Conventional Commits (feat, fix, docs...)
- PRs: Immer auf `develop`, nie direkt auf `main`

## Gotchas
- API-Calls NUR via /src/api/client.ts (Auth-Header!)
- .env.local für lokale Secrets (nicht committen)
- DB-Migrationen: `npm run db:migrate` vor Feature-Start

Imports und Referenzen

Sie können auf andere Dateien verweisen:

# Projekt-Kontext

Siehe @README.md für Projekt-Übersicht.
API-Dokumentation: @docs/api.md

## Zusätzliche Anweisungen
- Git Workflow: @docs/git-instructions.md
- Persönliche Overrides: @~/.claude/my-project.md

Claude lädt diese Dateien bei Bedarf.

Emphasis für kritische Regeln

Manche Regeln sind wichtiger als andere. Nutzen Sie Emphasis:

## Kritische Regeln

IMPORTANT: Niemals direkt auf main pushen!

YOU MUST: Tests ausführen vor jedem Commit.

NEVER: Hardcoded Credentials im Code.

ALWAYS: API-Calls über /src/api/client.ts

Diese Formulierungen erhöhen die Compliance signifikant.

/init nutzen

Der schnellste Start:

claude
> /init

Claude analysiert Ihr Projekt und erstellt ein CLAUDE.md Template basierend auf:

• package.json (Commands, Dependencies)
• Vorhandene Config-Files (.eslintrc, .prettierrc)
• Projekt-Struktur
• README.md

Passen Sie das generierte Template an Ihre Bedürfnisse an.

CLAUDE.md vs Hooks vs Skills

Faustregel:

• CLAUDE.md: "So arbeiten wir hier"
• Hooks: "Das muss immer passieren"
• Skills: "So machen wir diese spezifische Aufgabe"

Beispiel: Code Formatting

CLAUDE.md Ansatz (Advisory):

## Code Style
- Nach Edits bitte `npm run format` ausführen

Claude sollte es tun, vergisst es aber manchmal.

Hook Ansatz (Deterministisch):

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npm run format"
      }]
    }]
  }
}

Formatting passiert garantiert nach jedem Edit.

Empfehlung: Nutzen Sie CLAUDE.md für den Kontext ("wir nutzen Prettier") und Hooks für die Ausführung.

Team-CLAUDE.md Strategien

Shared via Git

./CLAUDE.md committen für team-weite Konventionen:

# Team-Konventionen
[Alles was fürs ganze Team gilt]

Persönliche Overrides

CLAUDE.local.md für individuelle Präferenzen:

# Meine Overrides
- Ich bevorzuge verbose Commit Messages
- Bitte immer erklären bevor du editierst

Wichtig: CLAUDE.local.md in .gitignore eintragen!

Monorepo-Setup

monorepo/
├── CLAUDE.md           # Globale Konventionen
├── apps/
│   ├── frontend/
│   │   └── CLAUDE.md   # Frontend-spezifisch
│   └── backend/
│       └── CLAUDE.md   # Backend-spezifisch
└── packages/
    └── shared/
        └── CLAUDE.md   # Shared Package

Claude lädt die relevanten Dateien basierend auf dem Arbeitsverzeichnis.

Wartung und Pflege

Regelmässig reviewen

Behandeln Sie CLAUDE.md wie Code:

• Bei Fehlern: War die Anweisung unklar?
• Bei Projekt-Änderungen: CLAUDE.md aktualisieren
• Regelmässig prunen: Was ist obsolet?

Review-Checklist

Für jede Zeile in CLAUDE.md fragen Sie:

1. Würde Claude ohne diese Info Fehler machen?
2. Kann Claude diese Info aus dem Code lesen?
3. Ist die Anweisung noch aktuell?
4. Ist sie klar und eindeutig?

Wenn 1=Nein oder 2=Ja oder 3=Nein: Entfernen.

Anti-Patterns vermeiden

Zu lang

# Schlecht: 500+ Zeilen

## Detaillierte Code-Erklärung
Die Datei src/auth/login.ts implementiert...
[200 Zeilen Erklärung]

Besser: Maximal 100-200 Zeilen. Link zu Docs.

Zu vage

# Schlecht
Schreibe guten, sauberen Code.

Besser: Konkrete Regeln.

# Besser
- Funktionen maximal 30 Zeilen
- Keine nested ternaries
- Error handling mit try/catch

Veraltet

# Schlecht
Nutze npm run test:legacy  # Existiert nicht mehr

Lösung: Regelmässige Reviews, CI-Check für CLAUDE.md.

Redundant zum Code

# Schlecht
Die Funktion getUserById nimmt eine ID und gibt einen User zurück.

Besser: Nur dokumentieren was nicht offensichtlich ist.

Praktische Beispiele

Next.js Projekt

# Next.js Projekt

## Commands
npm run dev    # Dev Server :3000
npm run build  # Production Build
npm run lint   # ESLint

## Code Style
- App Router, keine Pages
- Server Components default
- 'use client' nur wenn nötig
- Imports: @/ für src/

## Architecture
- Data Fetching: Server Components oder React Query
- State: Zustand für Client State
- Forms: Server Actions bevorzugen

## Gotchas
- Metadata in layout.tsx, nicht in page.tsx
- Images immer via next/image
- API Routes in app/api/

Python/FastAPI Projekt

# FastAPI Backend

## Commands
uv run fastapi dev   # Dev Server
uv run pytest        # Tests
uv run ruff check    # Linting

## Code Style
- Python 3.12+
- Type Hints required
- Pydantic für Validation

## Architecture
- Routers in app/routers/
- Services in app/services/
- Models in app/models/

## Testing
- pytest + pytest-asyncio
- Fixtures in conftest.py
- Test DB: SQLite in-memory

Fazit

Eine gute CLAUDE.md ist kurz, präzise und aktuell. Sie dokumentiert, was Claude nicht aus dem Code lesen kann, und gibt klare Anweisungen für Ihre Projekt-Konventionen.

Starten Sie mit /init, passen Sie das Template an, und pflegen Sie die Datei wie Code. In Kombination mit Hooks für deterministische Aktionen und Skills für komplexe Workflows haben Sie ein vollständiges System für konsistente Claude Code Nutzung.

---

Weiterführende Artikel:

• Claude Code: Der komplette Überblick - Alle Features
• Claude Code MCP-Server einrichten - Externe Tools anbinden
• Claude Code Skills erstellen - Wiederverwendbare Workflows
• Claude Code Hooks konfigurieren - Event-Automatisierung
• Claude Code Agents verstehen - Sub-Agenten

Nächster Schritt: Sie möchten Claude Code optimal für Ihr Team konfigurieren? Wir helfen bei Setup, CLAUDE.md Erstellung und Best Practices. Mehr über unsere Entwicklungsdienstleistungen.