CLAUDE.md Template für Engineering-Teams: Aufbau, Struktur, Beispiele
Wie eine production-grade CLAUDE.md für Engineering-Teams aufgebaut ist: Skeleton, projekttypspezifische Includes, repo-spezifische Overrides. Mit vollständigem Template und Beispielen für TypeScript, Python, Infrastructure-as-Code.
import BlogFAQ from '../../src/components/BlogFAQ'; import KeyTakeaways from '../../src/components/KeyTakeaways';
<KeyTakeaways items= /
<p data speakable Die CLAUDE.md ist der wichtigste Hebel, um aus einem generischen AI Coding Tool ein projektspezifisches Engineering Werkzeug zu machen. Eine gut geschriebene CLAUDE.md macht Claude Code (und auch Cursor mit angepasstem Mapping) reproduzierbar produktiv. Eine schlechte führt dazu, dass das Setup nach 2 Wochen wieder vergessen wird. Dieser Post zeigt Aufbau, Pflichtsektionen, konkrete Beispiele für TypeScript, Python und Infrastructure as Code — plus wie ihr eine Template Library für 10+ Repos baut. </p
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.
```markdown 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.
```markdown Quick Reference
```
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 from "@/lib/utils") Relative nur im selben Modul (./helper) Typ Imports separat: import type from "@/types"
Error Handling Form Validation: Zod Schema in der Komponente API Errors: React Query onError + Toast Niemals raw catch (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?
```markdown 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?
```markdown 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
```markdown 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