# CLAUDE.md-Konfigurationsleitfaden

`CLAUDE.md` ist die **projektweite Konfigurationsdatei** von Claude Code. Jedes Mal, wenn Claude Code startet, liest es automatisch die `CLAUDE.md` des Projekts, um die Projektarchitektur, Codierungskonventionen und besondere Vereinbarungen kennenzulernen. So kann Claude Ihr Projekt genauer verstehen.

## Warum Sie CLAUDE.md benötigen

Ohne CLAUDE.md müssen Sie unter Umständen in jeder Konversation immer wieder erklären:
- „Dieses Projekt verwendet pnpm, nicht npm“
- „Der Testbefehl ist `yarn test:unit`, nicht `npm test`“
- „Alle Komponenten verwenden TypeScript — keine `any`-Typen“

Schreiben Sie diese Informationen in CLAUDE.md, und Claude liest sie bei jedem Start automatisch. Sie müssen sich dann nie wiederholen.

## Dateihierarchie

Claude Code liest CLAUDE.md-Dateien aus mehreren Ebenen und führt sie zusammen:

| Speicherort | Geltungsbereich |
|----------|-------|
| `~/.claude/CLAUDE.md` | Globale Konfiguration, gilt für alle Projekte |
| `<project root>/CLAUDE.md` | Projektkonfiguration, in Git committet für die Teamfreigabe |
| `.claude/CLAUDE.md` | Private Projektkonfiguration, kann zu `.gitignore` hinzugefügt werden |
| `CLAUDE.md` in einem Unterverzeichnis | Wird nur gelesen, wenn Claude in diesem Verzeichnis arbeitet |

## Schnelleinrichtung

Verwenden Sie den Befehl `/init`, um eine Datei automatisch zu generieren:

```
/init
```

Claude analysiert die aktuelle Projektstruktur und generiert automatisch eine CLAUDE.md mit Projektinformationen.

## Grundlegende Struktur

```markdown
# Project Name

## Overview
Brief description of the project's purpose and tech stack.

## Tech Stack
- Runtime: Node.js 20
- Framework: Next.js 15
- Styling: Tailwind CSS
- Database: PostgreSQL + Prisma

## Common Commands
- Start dev server: `npm run dev`
- Run tests: `npm test`
- Build for production: `npm run build`
- Lint code: `npm run lint`

## Coding Conventions
- Use TypeScript; no `any` types allowed
- Components use functional style
- Styling with Tailwind only — no inline styles
- Commit message format: `feat:` / `fix:` / `docs:` prefixes, etc.

## Project Structure
- `src/app/` — Next.js App Router pages
- `src/components/` — Reusable components
- `src/lib/` — Utility functions
- `prisma/` — Database schema and migrations

## Notes
- Do not modify `prisma/migrations/` — only create new migrations
- All API routes are under `src/app/api/`
- Image assets go in `public/images/`
```

## Praktische Tipps

### 1. Paketmanager angeben

```markdown
## Package Management
Use pnpm — do not use npm or yarn.
Install dependencies: `pnpm install`
Add a dependency: `pnpm add <package>`
```

### 2. Testkonventionen dokumentieren

```markdown
## Testing
- Unit tests: `vitest`, files end in `.test.ts`
- E2E tests: `playwright`, located in `tests/e2e/`
- Run unit tests: `pnpm test:unit`
- Run E2E: `pnpm test:e2e`
- New features must include tests
```

### 3. Verbotene Aktionen angeben

```markdown
## Prohibited Actions
- Do not use `console.log` — use the project's `logger` module instead
- Do not modify `package-lock.json` directly
- Do not commit directly to `main` — use feature branches
```

### 4. Architekturkontext bereitstellen

```markdown
## Architecture Overview
This project follows Hexagonal Architecture:
- `domain/` — Business logic, no external framework dependencies
- `application/` — Use cases, coordinating domain and infrastructure
- `infrastructure/` — External adapters for databases, HTTP, etc.
- `interfaces/` — Entry points such as web controllers and CLI

New features should follow this layering — do not introduce external dependencies in the domain layer.
```

### 5. Auf andere Dokumente verweisen

```markdown
## Further Reading
- API documentation: `docs/api.md`
- Deployment process: `docs/deploy.md`
- Database schema: `prisma/schema.prisma`
```
## CLAUDE.md und Kontextverwaltung

Die Inhalte von CLAUDE.md beanspruchen Kontextplatz. Empfehlungen:
- Halten Sie CLAUDE.md knapp und konzentrieren Sie sich auf die wichtigsten Informationen
- Für detaillierte Architekturdokumentation verweisen Sie in CLAUDE.md auf Dateipfade, anstatt Inhalte direkt zu kopieren
- In langen Sitzungen bleibt CLAUDE.md stets sichtbar (er wird durch `/compact` nicht entfernt)

## Projektvorlagen

Die folgenden Strukturen sind praxiserprobte CLAUDE.md-Ausgangspunkte für gängige Projekttypen. Kopieren Sie die Vorlage, die Ihrem Tech-Stack entspricht, und passen Sie die Details an.

### Vorlage 1: React + TypeScript Frontend

```markdown
# MyApp Frontend

## Tech Stack
- React 19 + TypeScript 5.x
- Build tool: Vite 6
- Styling: Tailwind CSS v4 (utility-first, no inline styles)
- State management: Zustand (global), TanStack Query (server state)
- Routing: React Router v7
- Testing: Vitest + Testing Library + MSW

## Commands
- Dev: `pnpm dev` (port 3000)
- Test: `pnpm test` (Vitest watch mode)
- Single run: `pnpm test:run`
- Build: `pnpm build`
- Lint: `pnpm lint` (ESLint + Prettier)
- Type check: `pnpm typecheck`

## Coding Conventions
- Components: functional components + Hooks, no class components
- Props: define with `interface` (not `type`)
- File names: components in PascalCase (UserProfile.tsx), utilities in camelCase (formatDate.ts)
- Import order: React → third-party → internal → styles
- No `any` type; explicit type annotations are required
- Async work goes through TanStack Query, not direct `useEffect` + `fetch`

## Project Structure
- src/components/ — reusable UI components
- src/pages/ — route pages
- src/hooks/ — custom Hooks
- src/api/ — API request wrappers (TanStack Query queryFn)
- src/stores/ — Zustand stores
- src/lib/ — utility functions
- src/types/ — global type definitions

## Notes
- Package manager: pnpm (not npm or yarn)
- Node.js 22+
- All API requests go through src/api/client.ts (with interceptors)
- Images live in public/images/, referenced via the /images/ path
```

### Vorlage 2: Python + FastAPI Backend

```markdown
# MyApp Backend

## Tech Stack
- Python 3.12 + FastAPI
- ORM: SQLAlchemy 2.0 (async) + Alembic migrations
- Database: PostgreSQL 16
- Cache: Redis 7
- Testing: pytest + httpx + factory_boy

## Commands
- Dev: `uvicorn app.main:app --reload --port 8000`
- Test: `pytest -xvs`
- Migrate: `alembic upgrade head`
- New migration: `alembic revision --autogenerate -m "description"`
- Lint: `ruff check .`
- Format: `ruff format .`
- Type check: `mypy app/`

## Coding Conventions
- Type hints: all function parameters and return values must have type hints
- async/await: all I/O operations use async
- Pydantic v2: request/response schemas use Pydantic BaseModel
- Dependency injection: inject database connections, auth, etc. via FastAPI Depends()
- Error handling: business exceptions inherit from app.exceptions.AppError

## Project Structure
- app/main.py — application entry point
- app/api/ — routes (one file per resource)
- app/models/ — SQLAlchemy models
- app/schemas/ — Pydantic schemas
- app/services/ — business logic
- app/core/ — config, database, security, and other core modules
- tests/ — test files (mirror the app/ structure)
- alembic/ — database migrations

## Notes
- Do not modify existing migration files under alembic/versions/
- The .env file is not committed to Git; it is loaded via the Settings class in app/core/config.py
- Virtual environment: `python -m venv venv && source venv/bin/activate`
```

### Vorlage 3: Go-Microservice

```markdown
# MyService

## Tech Stack
- Go 1.23
- HTTP framework: Echo v4
- Database: PostgreSQL + sqlc (type-safe SQL)
- Message queue: NATS JetStream
- Containerization: Docker + docker-compose

## Commands
- Run: `go run ./cmd/server`
- Test: `go test ./...`
- Build: `go build -o bin/server ./cmd/server`
- Generate sqlc: `sqlc generate`
- Lint: `golangci-lint run`

## Coding Conventions
- Error handling: always check err, never ignore it with _
- Interface naming: single-method interfaces take the -er suffix (Reader, Writer)
- Package naming: lowercase words, no underscores
- Logging: use slog for structured logging
- Context: pass context.Context as the first parameter of every function

## Project Structure (standard Go layout)
- cmd/server/ — main program entry point
- internal/handler/ — HTTP handlers
- internal/service/ — business logic
- internal/repository/ — data access layer
- internal/model/ — data models
- sql/ — SQL query files (used by sqlc)
```

### Vorlage 4: Monorepo (Turborepo)

```markdown
# MyPlatform Monorepo

## Tech Stack
- Package management: pnpm workspace
- Build system: Turborepo
- Language: TypeScript across the stack

## Commands
- Global dev: `pnpm dev`
- Global test: `pnpm test`
- Global build: `pnpm build`
- Single-package dev: `pnpm --filter @myplatform/web dev`
- Add a dependency: `pnpm --filter @myplatform/api add express`

## Package Structure
- apps/web/ — Next.js frontend
- apps/api/ — Express backend
- apps/admin/ — admin dashboard
- packages/ui/ — shared UI component library
- packages/config/ — shared config (eslint, tsconfig)
- packages/types/ — shared type definitions

## Notes
- Shared code goes in packages/; do not import directly between apps
- When creating a new package, follow the format of packages/ui/package.json
- Turborepo cache: build artifacts are cached in node_modules/.cache/turbo
```

### Vorlage 5: Data-Science-/ML-Projekt

```markdown
# ML Pipeline

## Tech Stack
- Python 3.12
- Framework: PyTorch 2.5 + Lightning
- Data processing: Polars (not Pandas)
- Experiment tracking: MLflow
- Dependency management: uv

## Commands
- Train: `python -m src.train --config configs/experiment.yaml`
- Evaluate: `python -m src.evaluate --checkpoint runs/latest`
- Preprocess data: `python -m src.preprocess --data-dir data/raw`
- Jupyter: `jupyter lab`
- Test: `pytest tests/`

## Coding Conventions
- Use YAML for configuration (do not hard-code hyperparameters)
- Use Polars for data processing (faster than Pandas, type-safe)
- All experiments must be logged to MLflow
- Notebooks are for exploration only; production code must live in src/

## Project Structure
- configs/ — experiment configuration YAML
- data/raw/ — raw data (not committed to Git, managed with DVC)
- data/processed/ — processed data
- src/ — core code (model, data, train, evaluate)
- notebooks/ — exploratory analysis
- runs/ — training outputs (checkpoints, logs)
```
## Best Practices für Teamzusammenarbeit

### Git-Strategie

```
CLAUDE.md          → commit to Git (shared by the team)
.claude/CLAUDE.md  → add to .gitignore (personal configuration)
```

Fügen Sie dies zur `.gitignore` hinzu:

```gitignore
# Personal Claude Code configuration
.claude/CLAUDE.md
.claude/settings.local.json
```

### Code-Review-Checkliste

Prüfen Sie bei jedem PR-Review:
- Wurde CLAUDE.md aktualisiert, als eine neue Technologie eingeführt wurde?
- Wurde der Abschnitt „Projektstruktur“ aktualisiert, wenn sich das Layout geändert hat?
- Wurde der Abschnitt „Befehle“ aktualisiert, als ein wichtiger Befehl hinzukam?

### Onboarding-Anleitung

CLAUDE.md dient gleichzeitig als beste Onboarding-Dokumentation für ein Projekt:
1. Nach dem Klonen liest ein neuer Entwickler CLAUDE.md, um einen Gesamtüberblick zu erhalten
2. Er führt `claude` aus → Claude kennt bereits alle Projektkonventionen
3. Er beginnt mit `> help me understand this project`

---

## Fortgeschrittene Tipps

### Verweisen statt einbetten

CLAUDE.md sollte nicht zu lang werden. Für detaillierte Dokumente sollten Sie den Pfad referenzieren statt den Inhalt einzubetten:

```markdown
## Architecture
Detailed architecture doc: `docs/architecture.md`.
API design conventions: `docs/api-design.md`.
Database schema: `prisma/schema.prisma`.
```

Claude liest diese Dateien automatisch, wenn es sie benötigt.

### Verhältnis zu AGENTS.md

| | CLAUDE.md | AGENTS.md |
|---|---|---|
| Tool | Claude Code | Codex CLI |
| Format | Markdown | Markdown |
| Inhalt | 80 %+ wiederverwendbar | 80 %+ wiederverwendbar |

Wenn Sie sowohl Claude Code als auch Codex nutzen, können die beiden Dateien koexistieren:
- **Gemeinsame Inhalte**: Tech-Stack, Befehle, Coding-Standards, Projektstruktur
- **Toolspezifisch**: Claudes `/model`- und `/plan`-Hinweise gehören in CLAUDE.md; die Konfiguration des Genehmigungsmodus von Codex gehört in AGENTS.md

> Siehe den [AGENTS.md-Leitfaden](/docs/usage/agents-md).

### Kontextnutzung steuern

Der Inhalt von CLAUDE.md ist immer im Kontext (`/compact` entfernt ihn niemals). Empfehlungen:

- **Gesamtlänge unter 500 Zeilen halten**
- Pfade referenzieren statt detaillierte Dokumente einzubetten
- Keine häufig wechselnden Informationen dort ablegen (wie den aktuellen Fortschritt)
- Keine Code-Beispiele dort ablegen (Claude kann den Quellcode selbst lesen)

---

## Häufige Fehler und Debugging

### CLAUDE.md wird nicht gelesen

```bash
# Confirm the file is in the project root
ls -la CLAUDE.md

# Confirm Claude sees it
claude
> Do you see CLAUDE.md? What tech stack does it describe?
```

### Zu lang – der Kontext wird überladen

```bash
# Check the line count
wc -l CLAUDE.md
# Over 500 lines: trim it

# Check context usage
/cost
```

### Teammitglieder verhalten sich unterschiedlich

Die globale `~/.claude/CLAUDE.md` unterscheidet sich von Person zu Person. Wenn das Team inkonsistentes Verhalten feststellt, prüfen Sie:
1. Ist die CLAUDE.md im Projektstamm spezifisch genug?
2. Hat jemand in `.claude/CLAUDE.md` die Teamregeln überschrieben?

---

## CLAUDE.md vs. AGENTS.md – So wählen Sie

Claude Code liest `CLAUDE.md` nativ (zusammen mit seinen Speicherdateien und pfadbezogenen Regeln). Die meisten **anderen** Tools – Cursor, Codex, GitHub Copilot, Cline, Gemini / Antigravity, Aider, Zed und weitere – lesen stattdessen `AGENTS.md`. Welche Datei Sie pflegen, hängt davon ab, wie viele Tools Ihr Team nutzt.

| Szenario | Empfehlung |
|----------|------------|
| **Einzelnes Tool (nur Claude Code)** | `CLAUDE.md` genügt – AGENTS.md wird nicht benötigt |
| **Multi-Tool-Team** | `AGENTS.md` als gemeinsame Referenzquelle pflegen, plus eine schlanke `CLAUDE.md`, die sie importiert |

### Einzelnes Tool: nur CLAUDE.md

Wenn alle im Team Claude Code nutzen, legen Sie alles in `CLAUDE.md` ab. Eine zweite Datei bringt keinen Vorteil.

### Multi-Tool: AGENTS.md als Referenzquelle

Wenn das Team Claude Code mit Cursor, Codex, Copilot oder anderen mischt, bewahren Sie die gemeinsamen Regeln – Tech-Stack, Befehle, Coding-Konventionen, Projektstruktur – in `AGENTS.md` auf und machen Sie `CLAUDE.md` zu einer schlanken Datei, die sie importiert und claude-spezifische Ergänzungen hinzufügt:

```markdown
# Project Rules

@AGENTS.md

## Claude Code specifics
- Use /model to switch to Opus 4.8 for large refactors
- Reference docs/architecture.md instead of pasting it
```

Die Zeile `@AGENTS.md` zieht die gemeinsamen Inhalte in den Claude-Kontext, sodass Claude die Teamregeln **plus** seine claude-spezifischen Ergänzungen erhält. **Vermeiden Sie zwei divergierende Kopien** derselben Regeln – das ist die Hauptfalle, weil die beiden Dateien unweigerlich auseinanderdriften.

> Weitere Details zum AGENTS.md-Format und den zugehörigen Tools finden Sie im [AGENTS.md-Konfigurationsleitfaden](/docs/usage/agents-md).

## Nächste Schritte

- Erfahren Sie mehr über [Kontextverwaltung](/docs/usage/context-management) – Techniken zur Verwaltung des Kontextfensters
- Erfahren Sie mehr über [Berechtigungs-Konfiguration](/docs/usage/permissions) – steuern, welche Operationen Claude ausführen darf
- Erfahren Sie mehr über [Workflow-Tipps](/docs/usage/workflow-tips) – einen effizienten Claude-Code-Workflow etablieren