Claude Code Masterkurs – KI-gestuetztes Programmieren lernen mit Anthropics Coding-Agent

CLAUDE.md Mastery

Level 1 | 45 Minuten

Dein Projekt richtig briefen — Von der Projekt-Identität bis zur vollständigen Kontext-Dokumentation

Lernziele

Das Mentale Modell — Wie Claude dein Projekt versteht

Bevor du eine CLAUDE.md schreibst, musst du verstehen wie Claude Code dein Projekt versteht. Claude baut bei jedem Start ein mentales Modell auf — eine interne Repräsentation deines Projekts basierend auf allem was es sehen und lesen kann. Je besser und vollständiger dieses Modell ist, desto besseren Code generiert Claude. Stell dir vor du gibst einem erfahrenen Freelance-Entwickler ein neues Projekt. Am ersten Tag hat er keine Ahnung: Welche Architektur? Welches Framework? Welche Konventionen? Welche Business-Logik? Ohne Einarbeitung wird sein Code nicht ins Projekt passen — auch wenn er technisch einwandfrei ist. Genau so funktioniert Claude Code. Beim Start liest es: Die Dateistruktur des Projekts, die CLAUDE.md (falls vorhanden), die package.json oder ähnliche Konfigurationsdateien, und optional weitere Dateien die du ihm gibst. Aus diesen Informationen baut es ein Verständnis auf — sein mentales Modell. Ohne CLAUDE.md basiert dieses Modell nur auf der Dateistruktur und dem Code selbst. Claude erkennt den Tech-Stack, die grobe Architektur und die Coding-Patterns. Aber es kennt nicht: Die Business-Logik und warum bestimmte Entscheidungen getroffen wurden. Die Konventionen die nicht im Code sichtbar sind. Die Performance-Anforderungen. Die Sicherheitsstandards. Die Team-Workflows. Mit einer guten CLAUDE.md hat Claude von Anfang an ein vollständiges Modell. Es weiß nicht nur WAS der Code tut, sondern WARUM er so geschrieben ist, WELCHE Standards gelten und WIE neue Features implementiert werden sollen. Der Unterschied ist dramatisch: Der gleiche Prompt 'Implementiere User-Authentifizierung' produziert mit CLAUDE.md Code der zu deinem Projekt passt, die richtigen Libraries nutzt, eure Konventionen einhält und die Security-Anforderungen erfüllt. Ohne CLAUDE.md bekommst du generischen Code der wahrscheinlich komplett refactored werden muss.

WIE CLAUDE DEIN PROJEKT "VERSTEHT"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Session-Start:
┌──────────────────────────────────────────┐
│  1. System Prompt (fest, von Anthropic)  │
│  2. CLAUDE.md wird geladen               │  ← DEIN Einfluss
│  3. Relevante Dateien werden gescannt    │
│  4. Projekt-Struktur wird analysiert     │
└──────────────────────────────────────────┘
              ↓
    Claude baut "mentales Modell" auf:
    • "Das ist ein Next.js Projekt..."
    • "Sie nutzen PostgreSQL..."
    • "Der Code-Style ist funktional..."
    • "Es gibt strikte TypeScript-Regeln..."
              ↓
    JEDE Antwort basiert auf DIESEM Modell

PROBLEM: Ohne CLAUDE.md fehlen 80% des Modells.
Claude RATET dann — und rät oft falsch.
💡 Die zentrale Erkenntnis CLAUDE.md ist KEIN optionales Nice-to-Have. Es ist das Fundament für alles was Claude Code tut. Stell dir vor, du stellst einen neuen Entwickler ein und gibst ihm KEINE Einarbeitung — keinen Zugang zur Doku, keine Erklärung der Architektur, keine Coding-Standards. Genau das passiert ohne CLAUDE.md.

CLAUDE.md erstellen

Jetzt wird es praktisch. Die CLAUDE.md ist die wichtigste Datei in deinem Claude Code Setup — sie ist Claudes permanentes Gedächtnis für dein Projekt. Eine gut geschriebene CLAUDE.md macht den Unterschied zwischen einem Tool das generischen Code generiert und einem das wie ein erfahrenes Teammitglied arbeitet. Die CLAUDE.md liegt im Root-Verzeichnis deines Projekts. Sie wird bei JEDER Session automatisch gelesen — du musst sie nicht manuell laden. Ihr Inhalt wird zum System-Prompt und beeinflusst ALLES was Claude in dieser Session tut. Die Struktur einer CLAUDE.md folgt einem bewährten Aufbau: Beginne mit der Projekt-Identität (was ist das Projekt, für wen, in welchem Stadium), dann technische Rahmenbedingungen (Tech-Stack, Constraints), dann Architektur und Konventionen (Patterns, Anti-Patterns), dann Domain-Wissen (Business-Logik, Compliance), und schließlich Workflow-Regeln (Definition of Done, Test-Strategie). Ein häufiger Fehler: Die CLAUDE.md wie eine README schreiben — allgemein, vage und beschreibend. Die CLAUDE.md sollte ANWEISUNGEN enthalten, nicht Beschreibungen. Statt 'Wir nutzen React' schreib 'React 18 mit TypeScript. Funktionale Komponenten mit Hooks, keine Klassen-Komponenten. Zustand mit Zustand statt Redux. Styling mit Tailwind CSS.' Die ideale Länge: 500-2000 Wörter. Kurz genug um das Context Window nicht zu überlasten, aber lang genug um alle wichtigen Informationen zu enthalten. Jedes Wort sollte Claude helfen bessere Entscheidungen zu treffen — alles was das nicht tut, streiche. Starte mit einer minimalen CLAUDE.md (Tech-Stack, Konventionen) und erweitere sie über Wochen wenn du merkst wo Claude Fehler macht. Jeder Fehler der auf fehlendem Kontext basiert, ist ein Hinweis dass deine CLAUDE.md erweitert werden sollte.

# Automatisch erstellen (empfohlen)
claude init
# → Analysiert dein Projekt und erstellt eine Basis-CLAUDE.md

# Oder manuell
touch CLAUDE.md

# Prüfe ob CLAUDE.md geladen wird
claude --verbose
# → Zeigt "Loading CLAUDE.md from ..."

Abschnitt 1: Projekt-Identität & Zweck

Der erste und wichtigste Abschnitt deiner CLAUDE.md definiert WAS dein Projekt ist. Das klingt trivial, aber diese Information bestimmt grundlegend wie Claude Code schreibt — von der Architektur-Komplexität über die Fehlerbehandlung bis zur Dokumentationstiefe. Stell dir vor, Claude bekommt den Auftrag 'Implementiere einen Login'. Ohne Projekt-Identität rät es: Ist das ein kleines Skript? Eine Enterprise-App? Ein Prototyp? Jedes Szenario erfordert fundamental anderen Code. Ein Prototyp braucht keine CSRF-Protection, eine Enterprise-App schon. Die vier Schlüsselinformationen: Erstens der Projekttyp — ist es ein einmaliges Skript, eine Automation, ein Service, eine Web-App, eine Mobile-App oder ein CLI-Tool? Zweitens die Zielgruppe — internes Tool für Entwickler, kundenorientierte Software für Endnutzer, oder B2B SaaS für Unternehmen? Drittens die Kernfunktionalität in maximal zwei Sätzen. Viertens das Entwicklungsstadium — POC, MVP oder Production? Das Entwicklungsstadium ist besonders wichtig: Bei einem POC optimiert Claude auf Geschwindigkeit — schneller Code, minimale Fehlerbehandlung, Shortcuts erlaubt. Bei einem MVP liegt der Fokus auf Funktionalität — ordentlicher Code, grundlegende Fehlerbehandlung, aber noch keine Enterprise-Features. Bei Production optimiert Claude auf Robustheit — umfassende Fehlerbehandlung, Security-Hardening, Monitoring, Logging und vollständige Tests. Ein konkretes Beispiel: 'SaaS-Plattform für Rechnungsverarbeitung (Production). Zielgruppe: Buchhaltungsabteilungen in DACH-Region. Kernfunktion: OCR-basierte automatische Rechnungserfassung mit DATEV-Export. DSGVO-konform, SOC2 in Vorbereitung.' Diese 35 Wörter geben Claude enormen Kontext: DACH-Region → deutsche Compliance-Anforderungen. Rechnungsverarbeitung → Finanzdaten, höchste Genauigkeit. DATEV-Export → spezifisches Format. DSGVO → Datenschutz, Löschfristen, Verschlüsselung.

# 🎯 Projekt: InvoiceFlow

## Was ist das?
Eine B2B SaaS-Plattform für automatisierte Rechnungsverarbeitung.
Kunden sind mittelständische Unternehmen im DACH-Raum (50-500 MA).

## Entwicklungsstadium
Production — Live seit März 2025, ~200 aktive Kunden.
→ Jede Änderung muss backward-compatible sein.
→ Breaking Changes nur mit Migration-Script.
→ Alle neuen Features hinter Feature Flags.

## Kern-Funktionalität
1. OCR-Erkennung eingehender Rechnungen (PDF/Bild → Daten)
2. Automatischer Abgleich mit Bestellungen
3. Freigabe-Workflow (4-Augen-Prinzip)
4. DATEV-Export für Buchhaltung
⚠️ Warum das Entwicklungsstadium entscheidend ist Claude behandelt Projekte FUNDAMENTAL unterschiedlich je nach Stadium: • POC / Prototyp → Darf experimentieren, Shortcuts sind OK, kein Error Handling nötig • MVP → Grundlegende Struktur wichtig, aber Perfektionismus vermeiden • Production → Error Handling, Input Validation, Logging, Tests sind PFLICHT • Enterprise → Compliance, Audit Trails, Security Reviews bei jeder Änderung Schreibe das Entwicklungsstadium EXPLIZIT in deine CLAUDE.md — sonst behandelt Claude jedes Projekt wie einen Prototypen.

Abschnitt 2: Technische Rahmenbedingungen

Die technischen Rahmenbedingungen definieren den Rahmen in dem Claude Code arbeiten darf. Sie unterscheiden zwischen harten Grenzen (Hard Constraints) die NIEMALS überschritten werden dürfen, und weichen Präferenzen (Soft Constraints) die bei guter Begründung abgewichen werden können. Hard Constraints sind nicht verhandelbar: Die Python-Version ist 3.11, nicht 3.12 (weil ein kritischer Dependency-Konflikt besteht). Die Datenbank ist PostgreSQL 15, kein Wechsel möglich (wegen bestehender Infrastruktur). Maximum 512MB RAM pro Container (Cloud-Provider-Limit). Offline-fähig, keine externen API-Calls zur Laufzeit (weil die Software in air-gapped Umgebungen läuft). Soft Constraints sind Präferenzen: Bevorzuge Standard-Libraries über Third-Party-Packages (weniger Dependencies). Nutze async/await statt Callbacks (bessere Lesbarkeit). Funktionen unter 30 Zeilen halten (Team-Konvention). Keine globalen Variablen (Code-Qualität). Der entscheidende Unterschied: Wenn Claude ein Hard Constraint verletzt, ist der Code FALSCH — egal wie gut er sonst ist. Wenn Claude ein Soft Constraint verletzt, ist der Code SUBOPTIMAL — aber möglicherweise aus gutem Grund (z.B. Performance-Optimierung die längere Funktionen erfordert). Erklärung WARUM ein Constraint existiert hilft Claude bessere Entscheidungen zu treffen: 'PostgreSQL statt MongoDB weil wir ACID-Transaktionen für Finanzdaten brauchen' ist besser als nur 'PostgreSQL'. Claude versteht dann WARUM es bei Datenbankentscheidungen immer ACID-Compliance berücksichtigen muss. Liste auch den vollständigen Tech-Stack: Frontend-Framework + Version, Backend-Framework + Version, Datenbank + Version, ORM, Test-Framework, Build-Tools, Package-Manager. Je präziser, desto besser passt der generierte Code.

## ⚙️ Technische Rahmenbedingungen

### Hard Constraints (NICHT verhandelbar)
- Python 3.11 — Deployment-Server unterstützt kein 3.12+
- PostgreSQL 15 — Unternehmens-Standard, keine Alternativen
- Max 512 MB RAM — Container-Limit in Kubernetes Production
- Kein externer Netzwerkzugriff — Airgapped Environment (Finanzsektor)
- DSGVO-Konformität — Alle Nutzerdaten verschlüsselt, Löschfristen

### Soft Constraints (Präferenzen)
- Standard-Library bevorzugen → weniger Dependencies = einfacheres Audit
- Async/await für I/O → bessere Performance unter Last
- Type Hints überall → bessere IDE-Unterstützung, weniger Bugs
- Conventional Commits → automatisches Changelog
- Black Formatter → konsistenter Code-Style im gesamten Team

### Warum diese Constraints?
- RAM-Limit: Kubernetes Cluster mit festen Resource Quotas
- Airgapped: Finanzsektor-Anforderung, kein pip install zur Laufzeit
- PostgreSQL: Concurrent Access, JSONB für flexible Metadaten, Full-Text-Search
💡 Das WARUM dokumentieren Schreibe nie nur "Nutze PostgreSQL". Schreibe: "Nutze PostgreSQL weil: Concurrent Access für 50+ gleichzeitige User, JSONB-Columns für flexible Metadaten, Full-Text-Search ohne extra ElasticSearch." Das WARUM hilft Claude in NEUEN Situationen die richtige Entscheidung zu treffen — selbst wenn der genaue Fall nicht in der CLAUDE.md steht.

Abschnitt 3: Architektur-Entscheidungen & Anti-Patterns

Dieser Abschnitt dokumentiert die wichtigsten technischen Entscheidungen die in deinem Projekt getroffen wurden — und vor allem WARUM. Architecture Decision Records (ADRs) helfen Claude konsistent mit bestehenden Entscheidungen zu bleiben statt bei jeder Aufgabe einen neuen Ansatz zu wählen. Ohne diese Dokumentation trifft Claude eigene Entscheidungen: Vielleicht nutzt es Redux statt eurer gewählten Zustand-Library. Vielleicht erstellt es eine monolithische Datei statt eurer Microservice-Architektur zu folgen. Vielleicht implementiert es ein Pattern das ihr explizit vermeidet. Jede falsche Entscheidung kostet Refactoring-Zeit. Das Format für ADRs ist einfach: Was wurde entschieden? Warum? Welche Alternativen wurden erwogen? Beispiel: 'Zustand statt Redux für State Management — weil weniger Boilerplate, besser für unsere Teamgröße (3 Devs), und ausreichend für unsere State-Komplexität. Redux wäre Overkill.' Genauso wichtig wie Entscheidungen sind Anti-Patterns — Dinge die ihr explizit NICHT wollt. Ohne diese Liste wird Claude manchmal Patterns verwenden die technisch korrekt aber unerwünscht sind: 'KEINE verschachtelten Ternaries für Logik (nutze if/else). KEINE zirkulären Imports zwischen Modulen. KEINE Klassen-Komponenten in React. KEINE any-Types in TypeScript.' Die Begründung bei Anti-Patterns ist wichtig: 'Keine verschachtelten Ternaries weil das Team sie als schwer lesbar empfindet' gibt Claude den Kontext WAS stattdessen gewünscht ist und WARUM. Ohne Begründung könnte Claude in Edge Cases entscheiden dass ein verschachteltes Ternary hier ausnahmsweise sinnvoll wäre. Dokumentiere auch die Projekt-Struktur: Welcher Code gehört wohin? Welche Ordner haben welche Verantwortung? Das verhindert dass Claude neue Dateien an den falschen Stellen erstellt.

## 📐 Architektur-Entscheidungen

### ADR-001: Zustand statt Redux
Entscheidung: Zustand für State Management
Begründung: App hat ~15 kleine Stores, kein globaler komplexer State.
Zustand: 2KB Bundle, weniger Boilerplate, Team kennt es besser.
Konsequenz: Kein Redux, keine Redux Toolkit, keine Sagas.

### ADR-002: API Routes statt separatem Backend
Entscheidung: Next.js API Routes für Backend-Logik
Begründung: Ein Deployment, ein Repo, ein Team.
Separate Microservices erst ab >10 Entwicklern sinnvoll.
Konsequenz: Kein Express, kein Fastify, kein separates Backend-Repo.

### ADR-003: Result-Pattern statt try/catch
Entscheidung: Alle Funktionen returnieren Result<T, Error>
Begründung: Explizites Error Handling, keine silent failures.
`typescript
// ✅ SO machen wir es:
function getUser(id: string): Result<User, NotFoundError | DbError>

// ❌ NICHT so:
function getUser(id: string): Promise<User> // throws irgendwas
`

## 🚫 Anti-Patterns (Was wir NICHT wollen)
- Keine God-Objects → Klassen max 200 Zeilen, eine Verantwortung
- Keine zirkulären Imports → Module-Graph muss ein DAG sein
- Keine Barrel-Files → index.ts Dateien, die nur re-exportieren
- Keine über-komplexen Abstraktionen → Lieber Code duplizieren als
  eine fragile Abstraktion für 3 verschiedene Use Cases
- Kein premature Optimization → Erst messen, dann optimieren

Abschnitt 4: Domain & Business-Logik

Dieser Abschnitt wird am häufigsten vergessen — und ist gleichzeitig der wertvollste. Domain-Wissen ist Information die Claude NICHT aus dem Code ableiten kann. Geschäftsregeln, Nutzer-Rollen, Compliance-Anforderungen und branchenspezifische Logik müssen explizit erklärt werden. Stell dir vor, du baust eine Rechnungssoftware. Claude sieht den Code der Rechnungen erstellt, aber es weiß nicht: Dass Rechnungen nach Versand nicht mehr geändert werden dürfen (rechtliche Anforderung). Dass Stornos eine neue Rechnungsnummer brauchen. Dass bestimmte Kunden Netto-Zahlungsziele von 60 statt 30 Tagen haben. Dass EU-Rechnungen eine Reverse-Charge-Zeile brauchen wenn der Kunde in einem anderen EU-Land sitzt. Ohne dieses Domain-Wissen generiert Claude Code der technisch funktioniert aber geschäftlich falsch ist. Und diese Fehler sind besonders teuer weil sie oft erst spät entdeckt werden — wenn der Kunde sich beschwert oder das Finanzamt nachfragt. Besonders im DACH-Raum sind Compliance-Anforderungen kritisch: DSGVO-Konformität mit expliziten Löschfristen (wann müssen welche Daten gelöscht werden?), Aufbewahrungspflichten (welche Daten müssen wie lange gespeichert werden?), Verschlüsselungsanforderungen (welche Daten at-rest und in-transit verschlüsselt?), Audit-Log-Pflichten (welche Aktionen müssen für die Nachvollziehbarkeit geloggt werden?). Nutzer-Rollen und Berechtigungen gehören ebenfalls in diesen Abschnitt: Welche Rollen gibt es? Was darf jede Rolle sehen und tun? Gibt es Daten die bestimmte Rollen NICHT sehen dürfen (z.B. Gehaltsdaten nur für HR)? Mein Tipp: Frage dich bei jedem Abschnitt: 'Wüsste ein neuer Entwickler der nur den Code sieht das bereits?' Wenn nicht, gehört es in die CLAUDE.md.

## 🏢 Domain & Business-Logik

### Nutzer-Rollen & Berechtigungen
| Rolle      | Rechnungen sehen | Freigeben | Einstellungen | Admin |
|------------|:---:|:---:|:---:|:---:|
| Viewer     | ✅ | ❌ | ❌ | ❌ |
| Approver   | ✅ | ✅ (bis 5.000€) | ❌ | ❌ |
| Manager    | ✅ | ✅ (bis 50.000€) | ✅ | ❌ |
| Admin      | ✅ | ✅ (unbegrenzt) | ✅ | ✅ |

### Geschäftsregeln
- Rechnungen über 10.000€: IMMER zwei Freigaben (4-Augen-Prinzip)
- Freigeber ≠ Rechnungsersteller (Segregation of Duties)
- Zahlungsziel: Default 30 Tage, konfigurierbar pro Kunde (14-90 Tage)
- Skonto: 2% bei Zahlung innerhalb 14 Tagen
- Mahnwesen: Automatisch nach 7/14/30 Tagen überfällig

### DSGVO & Compliance (DACH-Raum)
- Löschfristen: Personendaten nach 6 Monaten Inaktivität anonymisieren
- Aufbewahrungspflicht: Rechnungsdaten 10 Jahre (HGB §257)
- Verschlüsselung: AES-256 at rest, TLS 1.3 in transit
- Audit-Log: Jede Datenänderung mit Zeitstempel, User-ID, IP
- Recht auf Auskunft: Export-Endpoint für alle User-Daten (Art. 15)
💡 DACH-spezifisch: DSGVO & Datenschutz Bei Projekten im DACH-Raum: Dokumentiere ALLE Datenschutz-Anforderungen explizit. Claude kennt DSGVO nur allgemein aus dem Training — deine konkreten Löschfristen, Encryption-Requirements und Audit-Logging-Pflichten muss es aus der CLAUDE.md erfahren. Ohne diese Info generiert Claude Code der DSGVO-Anforderungen ignoriert.

Abschnitt 5: Development Workflow & Standards

Der Workflow-Abschnitt definiert wie in deinem Projekt entwickelt wird — von der Code-Style-Convention über die Git-Strategie bis zur Definition of Done. Ohne diese Informationen trifft Claude eigene Entscheidungen die möglicherweise nicht zu eurem Team-Workflow passen. Coding Standards im Detail: Dateinamen in kebab-case oder camelCase? Funktionen als Arrow Functions oder Regular Functions? Exports als Named oder Default? Maximale Funktionslänge? Kommentar-Sprache (Deutsch oder Englisch)? Import-Reihenfolge? Diese Konventionen sind im Code-Review wichtig und sollten automatisch eingehalten werden. Git-Workflow: Welches Branching-Modell nutzt ihr (Git Flow, Trunk-Based)? Welches Commit-Format (Conventional Commits, Ticket-Referenz)? Welche Branch-Naming-Convention? Wer reviewed PRs? Wie viele Approvals braucht ein Merge? Definition of Done: Was muss erfüllt sein damit ein Feature als 'fertig' gilt? Typischerweise: Code implementiert und reviewed, Unit Tests vorhanden und grün, Integration Tests bestehen, Dokumentation aktualisiert, Performance-Anforderungen erfüllt, Security-Check bestanden. Definiere das explizit — Claude wird es bei jeder Aufgabe berücksichtigen. Test-Standards: Welches Framework? Welche Mindest-Coverage? Welche Tests müssen vorhanden sein (Unit, Integration, E2E)? Wo liegen Test-Dateien? Wie werden Tests benannt? Welche Mocking-Strategie? Das sind die Regeln nach denen Claude Code schreiben soll. Je klarer du sie formulierst, desto konsistenter und qualitativ hochwertiger wird der Output — bei JEDER Session, nicht nur bei der nächsten.

## 📋 Development Workflow

### Definition of Done (neues Feature)
- [ ] TypeScript-Typen definiert (kein any)
- [ ] Implementation mit Error Handling (Result-Pattern)
- [ ] Unit Tests (>80% Coverage für Business Logic)
- [ ] Integration Test für API-Endpoints
- [ ] API-Dokumentation aktualisiert
- [ ] Migration-Script falls DB-Schema geändert
- [ ] Feature Flag konfiguriert
- [ ] Code Review von mindestens 1 Person
- [ ] Keine neuen Linter-Warnings

### Coding Standards
- Dateibenennung: kebab-case (user-service.ts, NICHT UserService.ts)
- Exports: Named Exports, KEINE Default Exports
- Funktionen: Max 30 Zeilen, eine Aufgabe
- Kommentare: Nur WARUM, nie WAS (der Code erklärt das WAS)
- Error Messages: Deutsch für User-facing, Englisch für Logs

### Git Workflow
- Feature Branches: feature/INV-123-kurze-beschreibung
- Conventional Commits: feat:, fix:, refactor:, test:, docs:
- Squash Merge in main
- Kein Force Push auf main/develop

Abschnitt 6: Tool & Integration Kontext

Dieser Abschnitt dokumentiert alle externen Services, APIs und Tools die dein Projekt nutzt. Claude braucht diese Information um korrekte Integration-Code zu schreiben, richtige Error-Handling-Patterns zu verwenden und die richtigen API-Versionen und Formate zu nutzen. Für jede API dokumentiere: Die Base-URL und Version, das Authentifizierungsverfahren (API-Key, OAuth, JWT), die Rate-Limits (Anfragen pro Minute/Stunde), das Datenformat (JSON, XML, GraphQL), und das Error-Response-Format. Claude kann dann korrekte Retry-Logic und Error-Handling implementieren. Für Webhooks: Welches Format haben eingehende Webhooks? Welche Events werden verarbeitet? Wie wird die Signatur verifiziert? Welche Timeout-Limits gelten? Claude kann dann robuste Webhook-Handler schreiben die alle Edge Cases berücksichtigen. Umgebungsvariablen und Secrets: Welche Environment-Variablen werden genutzt? Welche Naming-Convention gilt (UPPER_SNAKE_CASE, PREFIX_SERVICE_KEY)? Welche Rotation-Policy gibt es für API-Keys? Claude soll keine Secrets hartcoden und die richtigen Variablen-Namen verwenden. Externe Dienste mit denen Claude häufig interagiert: Datenbank (Verbindungs-Details), Cache (Redis/Memcached Konfiguration), Queue (RabbitMQ/SQS Setup), Storage (S3/GCS Buckets), E-Mail (SendGrid/SES API), Payment (Stripe/Adyen Integration), Monitoring (Sentry/Datadog). Für jede Integration die spezifischen Gotchas: 'Die Stripe API hat ein Idempotency-Window von 24 Stunden — alle POST-Requests brauchen einen Idempotency-Key'. 'Die SendGrid API blockiert bei mehr als 100 E-Mails pro Sekunde — nutze Batch-Sending'. Solche Details verhindern teure Produktions-Fehler.

## 🔌 Externe Services & APIs

### DATEV API (Buchhaltungs-Export)
- Auth: OAuth2 Client Credentials
- Rate Limit: 100 Requests/Minute
- Timeout: 30 Sekunden
- Retry: 3x mit exponential Backoff (1s, 2s, 4s)
- Bei 429 (Rate Limit): Queue + Retry nach Retry-After Header

### AWS S3 (Dokument-Storage)
- Max Dateigröße: 25 MB
- Erlaubte Formate: PDF, PNG, JPG, TIFF
- Lifecycle: Nach 90 Tagen → Glacier (Kostenreduktion)

### Secrets & API Keys
- Naming: SERVICE_ENV_KEY (z.B. DATEV_PROD_CLIENT_ID)
- Storage: AWS Secrets Manager (NICHT .env in Production)
- Rotation: Alle 90 Tage
- NIEMALS in Logs, Fehler-Messages oder Responses ausgeben

Abschnitt 7: Performance & Security

Performance und Security sind die beiden Bereiche die am häufigsten vergessen werden — und die teuersten Konsequenzen haben wenn sie fehlen. Ohne explizite Anforderungen optimiert Claude weder für Geschwindigkeit noch für Sicherheit, weil es die spezifischen Anforderungen deines Projekts nicht kennt. Performance-Anforderungen sollten messbar sein: API-Response-Time unter 200ms für Standard-Endpoints, unter 1s für komplexe Queries. Seitenladung unter 3 Sekunden, First Contentful Paint unter 1.5s. Datenbank-Queries unter 50ms, keine N+1-Query-Patterns. Background-Jobs mit Timeout von 30 Sekunden. Diese konkreten Zahlen geben Claude klare Ziele. Graceful Degradation: Was passiert wenn ein externer Service nicht erreichbar ist? Was passiert bei Timeout? Was sieht der Nutzer bei einem 500-Error? Definiere Loading-States, Fallback-Verhalten und Error-Pages. Claude implementiert diese automatisch wenn sie dokumentiert sind. Security-Anforderungen: Welche Daten müssen verschlüsselt werden (at-rest, in-transit, end-to-end)? Welche HTTP-Security-Headers werden gesetzt? Wie wird Input validiert (Schema-Validierung, Sanitizing)? Welche Authentication-Methode wird verwendet? Wie werden Sessions gemanagt? Threat Model: Welche Angriffsvektoren werden berücksichtigt? SQL-Injection, XSS, CSRF, Rate-Limiting, Brute-Force — für jede Bedrohung sollte dokumentiert sein welche Gegenmaßnahme implementiert ist oder werden soll. Besonders für DSGVO-relevante Projekte: Verschlüsselung personenbezogener Daten in der Datenbank. Audit-Log für alle Zugriffe auf sensible Daten. Automatische Löschung nach definierten Fristen. Datenexport-Funktion für Betroffenenanfragen. Dokumentiere diese Anforderungen explizit.

## ⚡ Performance-Ziele (P95)
- API Endpoints: < 200ms
- Dashboard-Seite: < 1s (First Contentful Paint)
- Rechnungs-Upload + OCR: < 10s
- DATEV-Export (1000 Rechnungen): < 30s
- DB Queries: < 50ms (Index-Nutzung prüfen!)

### Bei Überschreitung
- API > 500ms → Alert an #monitoring Slack Channel
- Dashboard > 3s → Loading Skeleton anzeigen
- OCR > 15s → Progress-Bar + Hinweis "Dauert länger als üblich"
- Export > 60s → Background Job + Email-Benachrichtigung

## 🔒 Security
### Input Validation
- ALLE User-Inputs mit Zod validieren
- SQL: Prepared Statements (Prisma macht das automatisch)
- XSS: React escaped standardmäßig, dangerouslySetInnerHTML VERBOTEN
- CSRF: Double-Submit Cookie Pattern
- Rate Limiting: 100 req/min pro User, 1000 req/min pro IP

### Security Headers (ALLE Responses)
- Content-Security-Policy: strict
- X-Content-Type-Options: nosniff
- X-Frame-Options: DENY
- Strict-Transport-Security: max-age=31536000

Abschnitt 8: Test-Strategie

Eine klar definierte Test-Strategie in der CLAUDE.md sorgt dafür, dass Claude konsistent hochwertige Tests schreibt — nicht zu viele, nicht zu wenige, und an den richtigen Stellen. Ohne Strategie schreibt Claude manchmal triviale Tests die nichts prüfen, und manchmal überkomplexe Tests die schwer zu warten sind. Definiere die Test-Pyramide für dein Projekt: Wie viele Unit Tests, Integration Tests und E2E Tests erwartest du? Typische Verteilung: 70% Unit, 20% Integration, 10% E2E. Aber das variiert je nach Projekt — eine API-lastige Anwendung braucht mehr Integration Tests, eine UI-lastige mehr E2E Tests. Für jede Test-Ebene: Welches Framework? Wo liegen die Test-Dateien? Wie werden sie benannt? Welche Patterns werden verwendet (AAA — Arrange/Act/Assert, Given/When/Then)? Welche Mocking-Strategie (Manual Mocks, jest.mock, Testing Library)? Was wird getestet und was NICHT: Business-Logik immer testen. API-Endpoints mit Integration Tests abdecken. Kritische User-Flows mit E2E Tests sichern. NICHT testen: Triviale Getter/Setter, Framework-internes Verhalten, rein visuelle Dinge (außer Screenshot-Tests existieren). Test-Data-Strategie: Nutzt ihr Fixtures (feste Testdaten), Factories (generierte Testdaten), oder Mocks für externe Dependencies? Wo liegen die Testdaten-Definitionen? Gibt es eine Seeding-Strategie für die Testdatenbank? Die Mindest-Test-Coverage definieren: 80% für Business-Logik? 90% für Security-relevanten Code? 50% für UI-Komponenten? Claude orientiert sich an diesen Zahlen und schreibt entsprechend viele Tests.

## 🧪 Test-Strategie

### Was wird getestet
- Unit Tests: Business Logic, Berechnungen, Validierungen
  → Vitest, Coverage-Ziel: >80%
- Integration Tests: API Endpoints, DB-Queries
  → Vitest + Supertest, echte Test-DB (Docker)
- E2E Tests: Login, Rechnung hochladen, Freigabe, Export
  → Playwright, 5 Core Flows

### Was wird NICHT getestet
- Triviale Getter/Setter
- Reine UI-Darstellung (Farben, Abstände)
- Third-Party Libraries
- Generated Code (Prisma Client, GraphQL Types)

### Test Data Strategy
- Fixtures: tests/fixtures/ (statische JSON-Dateien)
- Factories: tests/factories/ (dynamische Test-Daten mit Faker)
- Mocking: Externe APIs (DATEV, S3) IMMER mocken
- DB: Separate Test-DB, Reset vor jedem Test-Run

### Namenskonvention
describe('InvoiceApprovalService', () => {
  it('should reject when amount exceeds user limit', ...)
  it('should require second approval for invoices over 10k', ...)
  it('should prevent self-approval', ...)
})

Abschnitt 9: Feature Development Template

Das Feature Development Template gibt Claude eine feste Struktur vor wie neue Features spezifiziert und implementiert werden sollen. Es fungiert als Checkliste die sicherstellt, dass nichts vergessen wird — von der User Story über den technischen Ansatz bis zu den Acceptance Criteria. Das Template besteht aus sechs Teilen: Erstens die User Story ('Als [Rolle] möchte ich [Funktionalität] damit [Nutzen]'). Zweitens die Acceptance Criteria — konkrete, testbare Bedingungen die erfüllt sein müssen. Drittens der Technical Approach — wie soll das Feature implementiert werden. Viertens die Dependencies — welche anderen Features, Services oder Daten werden benötigt. Fünftens die Open Questions — ungeklärte Punkte die vor der Implementierung entschieden werden müssen. Sechstens der Test-Plan — welche Tests müssen geschrieben werden. Warum ist das nützlich? Weil es Claude strukturiertes Denken aufzwingt. Statt direkt in die Implementierung zu springen, geht Claude die Checkliste durch und identifiziert potenzielle Probleme bevor die erste Zeile Code geschrieben wird. Das Template lehrt auch dich als Nutzer strukturierter zu denken: Wenn du ein Feature Request als User Story formulierst, zwingst du dich die Nutzer-Perspektive einzunehmen. Wenn du Acceptance Criteria schreibst, definierst du was 'fertig' bedeutet. Wenn du Dependencies listst, entdeckst du Blocker frühzeitig. In der Praxis kannst du das Template als Slash-Command umsetzen: /project:feature startet einen interaktiven Workflow in dem Claude die Template-Felder mit dir zusammen ausfüllt. Das Ergebnis ist eine vollständige Feature-Spezifikation die als Grundlage für die Implementierung dient. Mein Tipp: Starte mit einem einfachen Template und erweitere es über Zeit. Ein Template das nie genutzt wird weil es zu kompliziert ist, hilft niemandem.

## 📝 Feature-Spezifikation Template

User Story:
Als [Rolle] möchte ich [Funktion], damit [Nutzen].

Acceptance Criteria:
- [ ] Kriterium 1 (messbar, testbar)
- [ ] Kriterium 2
- [ ] Edge Cases definiert

Technical Approach:
- Welche Dateien werden geändert?
- Welche neuen Dateien?
- DB-Migration nötig?
- API-Änderungen? Breaking/Non-Breaking?

Dependencies:
- Welche bestehenden Features betrifft das?
- Welche externen Services?

Open Questions:
- Ungeklärte Punkte VOR der Umsetzung

---
### Beispiel:

User Story:
Als Approver möchte ich Rechnungen per E-Mail freigeben,
damit ich nicht für jede Freigabe die App öffnen muss.

Acceptance Criteria:
- [ ] Approver erhält E-Mail mit Rechnungszusammenfassung
- [ ] E-Mail enthält "Freigeben"- und "Ablehnen"-Buttons
- [ ] Token in URL läuft nach 24h ab
- [ ] Doppelklick-Schutz (Idempotenz)

Technical Approach:
- Neuer Service: src/services/email-approval.ts
- Neuer API Route: POST /api/approvals/email-action
- DB: Token-Tabelle für Email-Links
- Bestehend: approval-service.ts erweitern

Context-Hierarchie: Mehrere CLAUDE.md Ebenen

Claude Code unterstützt CLAUDE.md Dateien auf mehreren Ebenen — eine mächtige Funktion die du kennen solltest wenn du in größeren Projekten oder Monorepos arbeitest. Die Hierarchie ermöglicht es, allgemeine Regeln global zu definieren und spezifische Regeln für Unterverzeichnisse zu überschreiben. Die drei Ebenen: Die ENTERPRISE-Ebene (zentral verwaltet, gilt für das gesamte Unternehmen) definiert unternehmensweite Standards wie Security-Anforderungen und Compliance-Regeln. Die USER-Ebene (~/.claude/CLAUDE.md) enthält persönliche Präferenzen die in allen Projekten gelten. Die PROJEKT-Ebene (CLAUDE.md im Projekt-Root) enthält projektspezifische Regeln. In Monorepos kannst du zusätzliche CLAUDE.md Dateien in Unterverzeichnissen platzieren. Wenn du in packages/frontend/ arbeitest, wird sowohl die Root-CLAUDE.md als auch die packages/frontend/CLAUDE.md gelesen. Die spezifischere Datei ergänzt oder überschreibt die allgemeinere. Praktisches Beispiel: Die Root-CLAUDE.md definiert den allgemeinen Tech-Stack und die Unternehmens-Standards. Die packages/frontend/CLAUDE.md definiert React-spezifische Konventionen und Komponenten-Patterns. Die packages/backend/CLAUDE.md definiert API-Standards und Datenbank-Regeln. So hat Claude in jedem Kontext die relevanten Informationen. Die Merge-Strategie: CLAUDE.md Dateien werden ZUSAMMENGEFÜHRT, nicht überschrieben. Die allgemeinen Regeln gelten weiterhin, und die spezifischen Regeln kommen hinzu. Bei Konflikten hat die spezifischere Ebene Vorrang. Ein häufiger Fehler: Zu viele verschachtelte CLAUDE.md Dateien die sich widersprechen. Halte die Hierarchie flach — Root-Level plus maximal eine Ebene für Monorepo-Packages. Mehr als zwei Ebenen werden unübersichtlich.

PRIORITÄT (höher überschreibt niedriger)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. 📁 Ordner-CLAUDE.md (höchste Priorität)
   src/components/CLAUDE.md
   → Spezifische Regeln NUR für diesen Ordner
   → Wird NUR geladen wenn in diesem Ordner gearbeitet wird

2. 📁 Projekt-CLAUDE.md
   /projekt/CLAUDE.md
   → Projekt-weite Standards (das meiste steht hier)
   → Wird IMMER geladen

3. 🌍 Global CLAUDE.md (niedrigste Priorität)
   ~/.claude/CLAUDE.md
   → Persönliche Preferences für ALLE Projekte
   → z.B. "Antworte auf Deutsch", "Bevorzuge TypeScript"

BEISPIEL:
━━━━━━━━━
~/.claude/CLAUDE.md         → "Antworte auf Deutsch"
/projekt/CLAUDE.md          → "React + Zustand, Result-Pattern"
/projekt/src/api/CLAUDE.md  → "REST API, Express Middleware Patterns"

Vorher/Nachher — Der Unterschied in der Praxis

Theorie ist schön, aber der wahre Wert einer guten CLAUDE.md zeigt sich im direkten Vergleich. Dieselbe Aufgabe, einmal ohne und einmal mit CLAUDE.md — der Unterschied in Codequalität, Stil-Konsistenz und Architektur-Treue ist dramatisch. OHNE CLAUDE.md fragst du: 'Implementiere einen API-Endpoint für User-Registrierung.' Claude generiert: Einen generischen Express-Handler mit Basis-Validierung, speichert das Passwort als einfachen Hash, gibt eine JSON-Response zurück. Funktioniert technisch, aber: Keine Input-Sanitierung, kein Rate-Limiting, Fehlerbehandlung mit generischen 500-Fehlern, Tests fehlen, Naming passt nicht zum Projekt. MIT CLAUDE.md fragst du das Gleiche. Claude generiert: Einen Handler der eure Express-Middleware-Chain nutzt, Input mit eurer Zod-Schema-Validierung prüft, bcrypt mit dem konfigurierten Cost-Factor für Passwort-Hashing nutzt, Rate-Limiting nach eurer Konfiguration implementiert, strukturierte Fehler-Responses im projektspezifischen Format zurückgibt, Conventional-Commit-konforme Änderungen committet und Unit + Integration Tests nach eurem Pattern erstellt. Der Unterschied: Statt 30 Minuten Nacharbeit für Anpassung an Projekt-Standards brauchst du 0 Minuten. Der Code passt von Anfang an. Das ist der ROI einer guten CLAUDE.md — sie kostet einmalig 30-60 Minuten Arbeit und spart dir täglich vielfach mehr. Im Code-Beispiel unten siehst du den konkreten Vorher/Nachher-Vergleich. Achte besonders auf: Die richtige Error-Response-Struktur, die Nutzung der projektspezifischen Utilities, und die Einhaltung der Naming-Convention.

AUFGABE: "Erstelle einen Endpoint für Rechnungsfreigabe"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ OHNE CLAUDE.md — Claude rät und macht Annahmen:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
→ Erstellt Express.js Route (falsch — wir nutzen Next.js API Routes)
→ Nutzt try/catch (falsch — wir nutzen Result-Pattern)
→ Keine Berechtigungsprüfung (kritisch! Sicherheitslücke!)
→ Keine Betrags-Limits (Geschäftsregel ignoriert)
→ Default Export (gegen unsere Konvention)
→ Englische Fehlermeldungen (User sehen Deutsch)
→ Keine Tests
→ Kein Audit-Log (DSGVO-Verstoß!)

Ergebnis: 70% muss manuell korrigiert werden.
Zeitersparnis: ~10 Minuten (von 2 Stunden Arbeit)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ MIT vollständiger CLAUDE.md:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
→ Next.js API Route in /app/api/approvals/route.ts ✓
→ Result-Pattern mit typisiertem Error Handling ✓
→ Rollenprüfung: Nur Approver/Manager/Admin ✓
→ Betrags-Limit pro Rolle geprüft ✓
→ 4-Augen-Prinzip für Beträge >10.000€ ✓
→ Named Export ✓
→ Deutsche User-Fehlermeldungen, englische Logs ✓
→ Unit Test mit 5 Test Cases ✓
→ Audit-Log Entry mit User-ID, Zeitstempel, IP ✓
→ Zod-Validation für Request Body ✓

Ergebnis: Direkt verwendbar, Production-ready.
Zeitersparnis: ~1.5 Stunden (von 2 Stunden)
🔑 Die Lektion Der Unterschied ist nicht "etwas besser". Es ist der Unterschied zwischen "Code den ich wegwerfen muss" und "Code den ich direkt deployen kann". 30 Minuten Investment in die CLAUDE.md sparen dir STUNDEN bei jeder einzelnen Aufgabe danach.

Progressive Disclosure — Nicht alles auf einmal

Progressive Disclosure bedeutet: Starte mit minimalem Kontext und erweitere ihn nach Bedarf. Nicht jedes Projekt braucht eine 2000-Wörter CLAUDE.md. Bei einem kleinen Skript reichen 5 Zeilen. Bei einer Enterprise-App brauchst du alles. Die Kunst ist, den Kontext organisch wachsen zu lassen. Die Faustregel: Starte mit dem was Claude am häufigsten falsch macht. Wenn Claude den falschen Code-Style nutzt, ergänze Coding-Standards. Wenn Claude die falsche Library wählt, dokumentiere den Tech-Stack. Wenn Claude Security-Anforderungen ignoriert, füge den Compliance-Abschnitt hinzu. Jeder Fehler ist ein Signal dass die CLAUDE.md erweitert werden muss. Die Progressive-Disclosure-Stufen: Stufe 1 (Minimal) — Projektbeschreibung in einem Satz, Tech-Stack, 3-5 wichtigste Konventionen. Reicht für kleine Projekte und Skripte. Stufe 2 (Standard) — Alles aus Stufe 1 plus: Architektur-Entscheidungen, Anti-Patterns, Git-Workflow, Test-Strategie. Reicht für die meisten Web-Projekte. Stufe 3 (Vollständig) — Alles aus Stufe 2 plus: Domain-Logik, Performance-Anforderungen, Security-Standards, Compliance-Regeln, Feature-Template, Tool-Integrationen. Nötig für Production-Apps mit hohen Anforderungen. Stufe 4 (Enterprise) — Alles aus Stufe 3 plus: Multi-CLAUDE.md-Hierarchie, Team-spezifische Workflows, ADRs, Monitoring-Anforderungen, Deployment-Pipelines. Nötig für Enterprise-Monorepos mit mehreren Teams. Der Wachstumsprozess: Nutze Claude Code eine Woche mit einer Stufe-1 CLAUDE.md. Notiere jeden Fehler der auf fehlendem Kontext basiert. Ergänze den fehlenden Kontext. Wiederhole. Nach 3-4 Wochen hast du eine CLAUDE.md die perfekt zu deinem Projekt passt.

Zusammenfassung & Checkliste