CLAUDE.md Template für Engineering-Teams: Aufbau, Struktur, Beispiele

Aufbau einer production-grade CLAUDE.md: Skeleton, projekttypspezifische Includes, repo-spezifische Overrides. Mit vollständigem Template.

Veröffentlicht: 2026-05-30. Aktualisiert: 2026-05-30.

Die CLAUDE.md macht aus einem generischen AI-Coding-Tool ein projektspezifisches Engineering-Werkzeug. Wenn sie gut ist. Eine schlechte CLAUDE.md wird nach zwei Wochen wieder vergessen. Aufbau, Pflichtsektionen, konkrete Beispiele für TypeScript, Python und Infrastructure-as-Code. Plus: Template-Library für Multi-Repo-Setups.

Was eine produktive CLAUDE.md ausmacht

Ich habe in Audits hunderte CLAUDE.md gesehen - von einer Zeile bis zu 2000 Zeilen. Was die guten von den unbenutzten unterscheidet:

• Konkret statt abstrakt. „Wir verwenden Clean Code" hilft niemandem. „Wir nutzen useQuery aus tanstack-query mit staleTime: 5 * 60 * 1000 als Default" schon.
• Fokussiert auf Friktion. Was bricht in eurem Projekt typisch? Was sind die häufigsten Fehler neuer Engineers? Genau das gehört rein.
• Wartbar. Wenn die CLAUDE.md nach 3 Monaten unkorrigiert ist, ist sie nicht nur unnütz - sie ist aktiv schädlich, weil Claude veraltete Anweisungen befolgt.

Drei Anti-Patterns, die ihr sofort erkennen werdet:

• CLAUDE.md als Marketing-Copy. „Wir bauen weltklasse Software mit Liebe zum Detail." Hilft niemandem.
• CLAUDE.md als API-Doku. Detaillierte Funktions-Signaturen gehören in Code-Kommentare, nicht in die CLAUDE.md.
• CLAUDE.md als persönliche Wunschliste. „Bitte schreibe Commit-Messages auf Deutsch." Das ist CLAUDE.local.md, nicht das Team-Dokument.

Die 5 Pflichtsektionen

Jede produktive CLAUDE.md hat diese 5 Sektionen - meist in dieser Reihenfolge:

1. Stack-Übersicht (≤30 Zeilen)

Tabelle oder kompakter Block mit Tech-Stack und Versionen.

## Tech Stack

| Layer | Tech | Version |
|---|---|---|
| Sprache | TypeScript | 5.4 |
| Framework | React + Vite | 19 / 7 |
| Styling | Tailwind CSS | 3.4 |
| State | React Query | v5 |
| Tests | Vitest + Testing Library | 1.x |
| Build | pnpm | 9 |
| Node | 22 (pinned in .nvmrc) | |

Warum wichtig: Claude weiß sofort, welche APIs und Patterns idiomatisch sind. Wer das auslässt, bekommt React-15-Patterns in einem React-19-Projekt.

2. Quick-Reference-Commands (≤20 Zeilen)

Die Befehle, die Engineer und Agent täglich brauchen.

## Quick Reference

```bash
pnpm install           # Dependencies
pnpm dev               # Dev-Server (localhost:3000)
pnpm build             # Production-Build
pnpm test              # Vitest watch
pnpm test:run          # Vitest single-run (CI-Modus)
pnpm lint              # ESLint
pnpm type-check        # tsc --noEmit
pnpm check             # lint + type-check + test

Warum wichtig: Claude probiert nicht mehr blind `npm test` (das in einem pnpm-Projekt fehlschlägt).

### 3. Coding-Konventionen mit Beispielen (≤80 Zeilen)

Hier liegt der größte Hebel. Konkret, mit Code-Snippets.

```markdown
## Conventions

### Naming
- Components: PascalCase (`UserCard.tsx`)
- Hooks: camelCase mit `use`-Prefix (`useFormValidation.ts`)
- Utils: camelCase (`formatDate.ts`)
- Constants: UPPER_SNAKE_CASE (`MAX_RETRIES`)

### Imports
- Absolute via `@/` (`import { cn } from "@/lib/utils"`)
- Relative nur im selben Modul (`./helper`)
- Typ-Imports separat: `import type { User } from "@/types"`

### Error Handling
- Form-Validation: Zod-Schema in der Komponente
- API-Errors: React Query `onError` + Toast
- Niemals raw `catch (e) { console.log(e) }` - entweder loggen + re-throw oder strukturiert handhaben

Warum wichtig: Das ist der Unterschied zwischen „Claude erfindet Conventions" und „Claude folgt unseren Conventions".

4. Workflow-Patterns für wiederkehrende Aufgaben (≤50 Zeilen)

Wie löst ihr typische Engineering-Aufgaben?

## Workflows

### Neue Komponente
1. `src/components/[area]/MyComponent.tsx`
2. Test-File: `src/components/__tests__/MyComponent.test.tsx`
3. Storybook-Story (falls UI-Komponente): `MyComponent.stories.tsx`
4. Export via `components/index.ts` nur wenn extern-genutzt

### Neue API-Route
1. Route in `src/api/routes/[domain].ts`
2. Zod-Schema in `src/api/schemas/[domain].schema.ts`
3. Tests in `src/api/__tests__/[domain].test.ts`
4. README in `docs/api/[domain].md` updaten

### Bug-Fix
1. Reproduzierender Test ZUERST (RED)
2. Fix implementieren (GREEN)
3. Refactor falls sinnvoll
4. Test-Suite vollständig laufen lassen (`pnpm check`)

Warum wichtig: Engineer-Onboarding-Zeit halbiert sich. Der Agent macht auch ohne expliziten Prompt das Richtige.

5. Known Friction (≤30 Zeilen)

Was bricht typisch? Was sind die häufigsten Fehler?

## Known Friction

- **Type-Errors nach Multi-File-Edits:** nach jeder 2-3 Datei-Änderung
  `pnpm type-check` laufen lassen, nicht erst am Ende.
- **Pre-commit Hooks reverten Edits:** ESLint/Prettier können Änderungen
  umformatieren - nach jedem Commit `git diff` prüfen.
- **Test-Snapshots driften:** bei UI-Änderungen `pnpm test:update` nutzen,
  dann manuell reviewen.
- **HMR bricht bei Tailwind-Config-Änderungen:** Dev-Server neu starten.

Warum wichtig: Genau die Fragen, die Junior-Engineers nach 2 Tagen stellen. Steht hier - und Claude warnt proaktiv.

Optionale Sektionen je nach Projekt

Diese Sektionen sind nicht universell sinnvoll, aber in vielen Projekten wertvoll:

• Architektur-Übersicht (kurzes Diagramm oder Bullet-Liste der Hauptkomponenten)
• Externe Abhängigkeiten (welche APIs, welche Datenbanken)
• Deployment-Prozess (wie kommt Code in Production)
• Secret-Handling (wo liegen Secrets, wie werden sie injiziert)
• Performance-Anforderungen (kritische Pfade, Latenz-Budgets)

Faustregel: was ein neuer Engineer in den ersten 2 Wochen oft fragt, gehört rein.

Beispiel-Templates pro Projekttyp

Drei kompakte Templates zum Adaptieren:

TypeScript-Frontend-Projekt

# CLAUDE.md - [Projektname]

## Stack
| Layer | Tech |
|---|---|
| TypeScript | 5.4 |
| React + Vite | 19 / 7 |
| Tailwind | 3 |
| State | React Query v5, Zustand |
| Forms | react-hook-form + zod |
| Tests | Vitest + Testing Library |
| Routing | react-router-dom v7 |

## Quick Reference
pnpm dev, pnpm test, pnpm check, pnpm build

## Conventions
- Components: PascalCase, in components/[area]/
- Tests: __tests__ subfolder
- Tailwind: cn() helper aus lib/utils
- Forms: zod schema + react-hook-form

## Workflows
- Neue Komponente: siehe oben
- Form-Validierung: zod schema + useForm + Component-Integration

## Known Friction
- Vite-HMR bricht bei Tailwind-Config-Änderungen
- React-Query-Cache nicht zwischen Tests teilen

Python-Backend-Projekt

# CLAUDE.md - [Projektname]

## Stack
| Layer | Tech |
|---|---|
| Python | 3.12 |
| Framework | FastAPI + Pydantic v2 |
| DB | PostgreSQL + SQLAlchemy 2 |
| Tests | pytest + httpx |
| Format | ruff + black |
| Package | uv |

## Quick Reference
uv sync, uv run pytest, uv run uvicorn main:app --reload, uv run ruff check

## Conventions
- Endpoints: app/api/v1/[domain].py
- Models: app/models/[domain].py (SQLAlchemy) + app/schemas/[domain].py (Pydantic)
- Service-Layer: app/services/[domain]_service.py
- Dependency Injection via FastAPI Depends

## Workflows
- Neue Route: Schema → Model → Service → Endpoint → Test
- DB-Migration: alembic revision --autogenerate -m "msg", review, alembic upgrade head

## Known Friction
- Alembic-Autogenerate erkennt Type-Änderungen nicht - manuell anpassen
- Async DB-Sessions nicht zwischen Requests teilen

Infrastructure-as-Code-Projekt (AWS CDK)

# CLAUDE.md - [Projektname] Infrastructure

## Stack
| Layer | Tech |
|---|---|
| IaC | AWS CDK v2 (TypeScript) |
| Compute | ECS Fargate + Lambda |
| DB | RDS PostgreSQL |
| CI | GitHub Actions |
| Account | bojatschkin-prod (eu-central-1) |

## Quick Reference
npm run build, npm run synth, cdk diff, cdk deploy

## Conventions
- Eine Stack-Klasse pro Service, in lib/stacks/[service]-stack.ts
- Construct-IDs: PascalCase ohne Bindestriche
- Tags: Project, Environment, Owner auf jedem Resource
- Secrets: AWS Secrets Manager, niemals .env

## Workflows
- Neue Resource: Stack updaten → cdk diff → review → cdk deploy
- IAM-Änderungen: explizit synth diff prüfen, mit Security abstimmen
- Production-Deploy: nur via GitHub Actions, nie lokal

## Known Friction
- CDK-Bootstrap pro Account/Region einmalig
- Stack-Updates mit Resource-Replacement = Downtime, vorher prüfen
- IAM-Policy-Changes propagieren oft 5-10 Min - geduldig sein

Multi-Repo: Template-Library statt Copy-Paste

Wer 10+ Repos hat, kommt mit Copy-Paste der CLAUDE.md nicht weit. Nach 6 Monaten driftet die Konfiguration und niemand pflegt sie zentral.

Lösung: modulare Template-Library mit drei Schichten:

1. Skeleton - Sektionen, die in jeder CLAUDE.md gleich sind (Brand-Voice-Hinweise, allgemeine Konventionen).
2. Projekttyp-Includes, pro Projekttyp ein Include-Block (Frontend, Backend, Infra).
3. Repo-Override, repo-spezifische Anpassungen (Service-Name, spezielle Patterns).

Praktische Umsetzung: ein Bootstrap-Skript (init-claude-md) zieht das passende Template und legt es im neuen Repo an. Updates der Library propagieren per Pull-Skript zurück in alle Repos.

Wer das ohne fremde Hilfe baut: rechnet mit 2-3 Wochen für ein solides Setup. Mehr Details zum Service: CLAUDE.md, Hooks & Skills Engineering.

CLAUDE.md vs .cursorrules: Was übertragen?

Wer parallel Cursor nutzt: die Mehrheit der CLAUDE.md-Inhalte lässt sich 1:1 in .cursorrules übernehmen. Cursor parsed das Format etwas anders, aber die Pflichtsektionen (Stack, Commands, Conventions, Workflows, Known Friction) sind identisch wertvoll.

Workflow: CLAUDE.md als Single Source of Truth pflegen. .cursorrules als generierte Kopie behandeln (ggf. via Skript synchronisieren). So vermeidet ihr Vendor-Lock-In und Doppel-Pflege.

Wartung: was real funktioniert

Drei Patterns, die in Teams nachhaltig funktionieren:

• PR-Template-Frage: „Wurde CLAUDE.md angepasst?" - Reviewer fragen aktiv nach.
• Pre-Hook-Reminder: wenn Architektur-Files geändert werden, erinnert ein Hook an CLAUDE.md-Update (siehe Hooks Cookbook, Pattern 12).
• Quartalsweise Review-Session: 30 Minuten Team-Meeting, in dem die CLAUDE.md gegen die Realität gehalten wird.

Ohne mindestens einen dieser Mechanismen veraltet die CLAUDE.md innerhalb von 3 Monaten und wird unbenutzt.

Nächste Schritte

Wer eine neue CLAUDE.md schreibt: starte mit den 5 Pflichtsektionen aus einem der drei Templates oben. 60 Minuten Initial-Aufwand reichen für eine solide Basis. Iteriert nach 2 Wochen Praxis.

Wer eine Template-Library für 10+ Repos plant: das ist nicht in 2 Stunden gemacht. Service: CLAUDE.md, Hooks & Skills Engineering.

Verwandte Posts: Claude Code Setup-Guide, Claude Code Hooks Cookbook.

Häufige Fragen

Was gehört in eine CLAUDE.md unbedingt rein?

Fünf Pflichtsektionen: (1) Tech-Stack-Übersicht inkl. Versionen, (2) Quick-Reference-Commands für Build/Test/Deploy, (3) Coding-Konventionen mit konkreten Beispielen, (4) Workflow-Patterns für wiederkehrende Aufgaben, (5) Known-Friction-Liste mit den häufigsten Problemen und ihren Lösungen.

Wie lang sollte eine CLAUDE.md sein?

150-400 Zeilen für die meisten Projekte. Kürzer reicht oft nicht aus, um den Projektkontext sinnvoll zu vermitteln. Länger wird vom Coding-Agent oft nicht mehr vollständig geparst - und niemand pflegt es.

Was ist der Unterschied zwischen CLAUDE.md und CLAUDE.local.md?

CLAUDE.md wird ins Git committed und gilt für das gesamte Team. CLAUDE.local.md ist gitignored und enthält persönliche Präferenzen (z.B. bevorzugte Sprache für Commit-Messages, eigene Editor-Shortcuts). So bleiben Team-Standards sauber von persönlichen Vorlieben getrennt.

Wie strukturiere ich CLAUDE.md für Multi-Service-Repos?

Root-CLAUDE.md mit allgemeinen Konventionen plus pro Service eine eigene CLAUDE.md im Service-Verzeichnis. Claude Code lädt automatisch die nächst-höhere CLAUDE.md, sodass Engineers im Service-Kontext die spezifischen Anweisungen bekommen plus die Root-Standards.

Wie vermeide ich, dass CLAUDE.md veraltet?

Drei Maßnahmen: (1) Update-Pflicht im PR-Template ('Wurde CLAUDE.md angepasst?'), (2) automatisches Pre-Hook-Reminder bei Architektur-Änderungen, (3) quartalsweise Review-Session, in der das Team die CLAUDE.md auf Aktualität prüft.

• CLAUDE.md, Hooks & Skills Engineering
• Claude Code Hooks Cookbook
• Claude Code Setup-Guide
• Zur Blog-Uebersicht
• Leistungen & Use Cases