Die perfekte CLAUDE.md für Enterprise Software Engineering

Das wirkungsvollste Artefakt in der agentenbasierten Entwicklung ist nicht Code — es ist die Spezifikation, die bestimmt, wie Code geschrieben wird. Im Claude-Code-Ökosystem ist dieses Artefakt die CLAUDE.md.

Nach 25 Jahren Entwicklung von Enterprise-Software und der Führung von Engineering-Teams habe ich beobachtet, wie Unternehmen immer wieder mit dem gleichen Problem kämpfen: Engineering-Standards existieren in Wikis, die niemand liest, Onboarding-Dokumenten, die veralten, und Stammwissen, das zur Tür hinausgeht, wenn Senior Engineers das Unternehmen verlassen. Code Reviews fangen manches ab, aber sie sind reaktiv — man behebt Probleme, nachdem sie geschrieben wurden.

CLAUDE.md ändert das grundlegend. Es ist keine Dokumentation über die Art, wie man Software baut. Es ist eine lebende Spezifikation, die aktiv jede Zeile Code formt, die im Repository geschrieben wird — ob von einem Menschen oder einem KI-Agenten.

Was eine großartige CLAUDE.md ausmacht

Die meisten CLAUDE.md-Dateien, die ich gesehen habe, sind dünn — ein paar Zeilen über den Tech Stack, vielleicht eine Notiz zur Formatierung. Das ist, als würde man einem neuen Engineer einen Laptop geben und sagen “viel Glück.” Eine großartige CLAUDE.md kodiert die volle Tiefe der Engineering-Kultur:

1. Architekturprinzipien, nicht nur Patterns

Sage nicht einfach “wir nutzen Microservices.” Spezifiziere warum Bounded Contexts so getrennt sind, wie die Inter-Service-Kommunikation funktioniert (synchron vs. asynchron, wann was nutzen), und wie die Anti-Corruption-Layer an jeder Grenze aussieht.

Für Enterprise SaaS bedeutet das, Multi-Tenancy-Regeln zu kodieren, die nicht verhandelbar sind: jede Query auf tenant_id gescoped, Row-Level Security als Sicherheitsnetz, Tenant-Kontext aus der Middleware injiziert — nie als Parameter übergeben.

2. Code-Standards, die ausführbar sind

“Sauberen Code schreiben” ist ambitioniert. “Maximal 20 Zeilen pro Funktion, maximal 3 Parameter, keine Boolean-Parameter, Guard Clauses statt tiefer Verschachtelung” ist ausführbar. Wenn Claude Code diese Regeln liest, befolgt es sie tatsächlich. Jede generierte Funktion bleibt im Rahmen.

Dasselbe gilt für Namenskonventionen, Error-Handling-Patterns und Dokumentationsstandards. Wenn man es präzise beschreiben kann, macht es die KI konsistent — ehrlich gesagt konsistenter als die meisten menschlichen Engineers.

3. Teststrategie mit konkreten Beispielen

Der Testing-Abschnitt ist dort, wo die meisten CLAUDE.md-Dateien zu kurz greifen. Man muss spezifizieren:

Die Testing-Pyramide-Proportionen (75 % Unit, 20 % Integration, 5 % E2E)
Coverage-Ziele pro Layer (85 % auf Domain-Logik, 95 % auf kritischen Berechnungen)
Test-Patterns (Arrange-Act-Assert, Factory-Funktionen statt roher Fixtures)
Was getestet werden muss (Edge Cases, Tenant-Isolation, Grenzwerte)
Welche Tools zu verwenden sind (Testcontainers für echte Datenbanken in Integrationstests)

Code-Beispiele einschließen. Wenn Claude Code ein konkretes Testbeispiel mit den exakten Patterns sieht, generiert es Tests, die in die Codebase passen.

4. CI/CD-Pipeline als Quality Gate

Die CLAUDE.md sollte die gesamte Pipeline beschreiben — von Pre-Commit-Hooks bis zum Canary-Deployment. Nicht weil die KI Code deployt, sondern weil das Verständnis der Pipeline beeinflusst, wie Code geschrieben wird. Wenn die KI weiß, dass Migrationen rückwärtskompatibel sein müssen, weil Blue-Green-Deployments gemacht werden, wird sie keine Migration generieren, die eine Spalte umbenennt.

5. Domain-Kontext

Das ist die Geheimwaffe. Wenn die CLAUDE.md die Geschäftsdomäne erklärt — was ein Validierungsmodul macht, warum Konfidenz-Schwellwerte existieren, wie Approval-Workflows verkettet sind — generiert die KI Code, der domänenlogisch sinnvoll ist, nicht nur syntaktisch korrekt. Sie benennt Variablen richtig, strukturiert Services entlang von Domain-Grenzen und schreibt Tests, die reale Geschäftsszenarien abdecken.

Die Engineering-Excellence-Referenz

Unten ist eine vollständige CLAUDE.md, die ich für eine Enterprise-SaaS-Plattform geschrieben habe. Sie deckt alles ab: Multi-Tenancy-Architektur, Clean-Code-Standards, Teststrategie, CI/CD-Pipeline-Design, Observability, Domain-Driven-Design-Struktur, Sicherheitspraktiken und Performance-Patterns.

Ich teile sie vollständig, weil der beste Weg zu verstehen, wie eine umfassende CLAUDE.md aussieht, ist, eine zu lesen. Nutze sie als Template — passe die Domänenspezifika an dein Produkt an, aber behalte die strukturelle Tiefe bei.

Die komplette Engineering Excellence CLAUDE.md ansehen (560 Zeilen)

```markdown

Engineering Excellence Standards — Enterprise SaaS Platform

Purpose

These standards define how we build enterprise-grade, scalable, maintainable software for our SaaS platform. Every engineer, every PR, every deployment follows these principles. They are non-negotiable for enterprise customers processing millions of transactions and managing complex business workflows.

1. Enterprise SaaS Architecture Principles

Multi-Tenancy

Tenant isolation is absolute. Every database query, every API call, every background job is scoped to a tenant_id. There is no code path that can access another tenant’s data.
Use PostgreSQL Row-Level Security (RLS) as a safety net on top of application-level filtering. RLS policies enforce tenant isolation even if application code has a bug.
Tenant context is set at the middleware/request level and propagated through the entire call chain. Never pass tenant_id as a function parameter — inject it from context.
Shared infrastructure (queues, caches, compute) uses logical isolation. Dedicated infrastructure available for Tier 1 customers if contractually required.
Data export and deletion must be tenant-scoped and auditable (GDPR Article 17 right to erasure).

Configuration Architecture

Per-tenant configuration stored in a dedicated config service, not in application code or environment variables.
Configuration hierarchy: Global defaults → Customer-level → Legal Entity-level → Override rules. Child inherits from parent unless explicitly overridden.
Configuration changes are versioned and auditable. Every change records: who, when, what changed, previous value.
Feature flags (LaunchDarkly or Unleash) for per-tenant feature rollout. New capabilities deploy dark, then activate per customer.
Configuration is cached with TTL and invalidation. Config changes take effect within 60 seconds without deployment.

API Design

RESTful APIs with consistent conventions. Resource-oriented URLs, standard HTTP methods, proper status codes.
API versioning via URL path (/v1/, /v2/). Breaking changes require new version. Old versions supported for minimum 12 months.
Pagination on all list endpoints (cursor-based, not offset-based — offset breaks with concurrent writes).
Rate limiting per tenant, per endpoint. Configurable limits for different customer tiers.
Every API response includes request_id for tracing. Every error response includes machine-readable error code + human-readable message.
OpenAPI 3.0 specification is the source of truth. Generated from code annotations. Client SDKs auto-generated.

Authentication & Authorization

SSO mandatory for enterprise: SAML 2.0 and OIDC support. Tested against Okta, Azure AD, OneLogin, Ping Identity.
SCIM 2.0 provisioning: Automated user lifecycle. User created/deactivated in IdP → reflected within minutes.
RBAC with custom roles: Pre-defined roles (Analyst, Team Lead, Department Manager, Admin) plus customer-configurable custom roles.
Permission model: Role → Permission Set → Resource Scope. Permissions are granular: documents:read, documents:approve, workflows:manage, config:admin.
API authentication via short-lived JWT tokens (15 min) with refresh token rotation.
Service-to-service auth via mTLS or signed JWTs with strict audience validation.

Data Residency & Encryption

Encryption at rest: AES-256 via AWS KMS. Per-tenant customer-managed keys (CMK) available for regulated customers.
Encryption in transit: TLS 1.2+ everywhere. Internal service mesh uses mTLS.
Data residency: Tenant data pinned to region (eu-west-1, us-east-1). Cross-region replication only with explicit customer consent.
PII handling: Customer data classified by sensitivity. PII fields encrypted at field level with separate key hierarchy.
Key rotation: Automated quarterly. Zero-downtime re-encryption of active data.

Compliance

SOC 2 Type II: Continuous compliance. Controls embedded in CI/CD, not manual checklists.
ISO 27001: Information security management system. Annual external audit.
GDPR: Data processing agreements per customer. Right to access, rectify, erase. Data retention policies configurable per tenant.
Penetration testing: Annual third-party pentest. Quarterly automated security scanning (SAST + DAST).
Audit trail: Immutable, append-only log of every data mutation, every configuration change, every AI decision. Retained for 7 years minimum.

2. Clean Code Standards

Principles

Readability over cleverness. Code is read 10x more than it’s written. Optimize for the reader.
Single Responsibility. Every function does one thing. Every class has one reason to change.
Explicit over implicit. No magic. No hidden side effects. Function names say what they do.
Fail loudly and early. Validate inputs at the boundary. Throw meaningful exceptions.
Domain-Driven Design. Code structure mirrors the business domain.

Naming Conventions

Files & directories: kebab-case Classes: PascalCase → DocumentValidationEngine Functions: camelCase → validateDocumentAgainstRules() Constants: UPPER_SNAKE → MAX_RETRY_ATTEMPTS Variables: camelCase → validatedDocumentCount Types/Interfaces: PascalCase → ValidationResult, DocumentStatus Database tables: snake_case → document_line_items API endpoints: kebab-case → /v1/documents/{id}/validation-results

Function Design

Maximum 20 lines per function. If longer, extract sub-functions.
Maximum 3 parameters. More than 3 → use an options/config object.
No boolean parameters. processDocument(document, true, false) is unreadable.
Pure functions where possible. Same input → same output. No side effects.
Guard clauses over deep nesting. Return early for error conditions.

Error Handling

Custom domain exceptions for every error category.
Never catch generic exceptions unless re-throwing with context.
Structured error responses with: error code, message, details, request_id.
Retry with backoff for transient failures. Exponential backoff with jitter. Max 3 retries with circuit breaker.
Dead letter queues for messages that fail after max retries.

3. Testing Strategy

Testing Pyramid

Unit Tests (~75%): Domain logic, validation engine, confidence checks. Run on every commit (< 2 min).
Integration Tests (~20%): Service boundaries, DB queries, backend system connectors. Run on every PR (< 10 min).
E2E Tests (< 5%): Full pipeline. Run nightly + before release (< 30 min).

Unit Tests

Coverage target: 85%+ on domain logic, 95%+ on validation engine and threshold calculations.
Factory functions for test data, not raw fixtures.
Test behavior, not implementation. Arrange-Act-Assert pattern.
Edge cases mandatory: null inputs, empty arrays, boundary values, currency rounding, timezone boundaries.
Mock external dependencies. Unit tests never touch the network.

Integration Tests

Test service boundaries: API endpoints, database queries, message queue producers/consumers.
Use testcontainers for PostgreSQL, Redis, and LocalStack — real services, not mocks.
Test tenant isolation: create data for tenant A, query as tenant B, verify zero results.
Test backend system connector against recorded API responses (VCR pattern).

AI/ML Model Testing

Golden set tests: 500+ documents with known correct results.
Regression tests on every model retrain.
Adversarial tests: near-duplicates, legitimate price changes.
Performance benchmarks: inference latency p95 must stay below threshold.

4. CI/CD Pipeline

Pipeline Flow

Pre-commit (local) → Build → Unit Test → Integration Test → Security Scan → Build Image → Staging Deploy → Production Canary

Branch Strategy

Trunk-based development. Main branch is always deployable.
Short-lived feature branches (< 2 days).
Conventional commits: feat:, fix:, refactor:, docs:, test:, chore:.
Squash merge to main. Clean, linear history.

Deployment Strategy

Canary deployments: 10% → 50% → 100%.
Automated rollback if error rate > 2% or latency > 2x baseline.
Blue-green for database migrations (expand-contract pattern).
Feature flags for per-tenant rollout.
Zero-downtime deployments. Rolling updates with health checks.

Database Migrations

Forward-only. Backward-compatible always.
New column? Add nullable first, deploy code, backfill, then add NOT NULL.
Migration review required from senior engineer.
Tested in CI against real PostgreSQL with representative data volume.

5. Observability

Structured Logging

Every log line is JSON with: timestamp, level, service, tenant_id, request_id, trace_id, event, duration_ms. Never log PII in plain text. Never log at DEBUG level in production.

Distributed Tracing

OpenTelemetry SDK in every service. Trace ID propagated through queues, workflows, and all service calls.

Alerting

Alert on symptoms, not causes. Every alert has a runbook. Three tiers: P1 (page, 15 min), P2 (Slack + ticket, 4 hours), P3 (daily digest).

SLOs

API availability: 99.9%
Document ingestion latency: p95 < 5s
Validation latency: p95 < 10s
Backend sync freshness: < 15 min
Pipeline STP rate: > 80%

6. Domain-Driven Design

Bounded Contexts

document-intake/ — Channel adapters, normalization document-intelligence/ — AI extraction, confidence scoring validation/ — Core validation engine, confidence engine exception-management/ — Exception types, routing, SLA approval/ — Approval matrix, delegation, thresholds backend-integration/ — Backend connector layer with per-system adaptors platform/ — Auth, config, audit, events, observability orchestration/ — Temporal workflow definitions

Inter-Context Communication

Synchronous (API) for queries needing immediate response.
Asynchronous (Events via SNS/SQS) for state changes.
Never share databases between bounded contexts.
Anti-corruption layer at each boundary.

7. Security

Automated CVE scanning on every build. No deploy with Critical/High CVEs.
Secrets in AWS Secrets Manager. Never in code or visible env vars.
Parameterized queries only. ORM with strict mode.
Input validation via schema (Zod/Joi) on every API endpoint.
SBOM generated on every build. License compliance automated.
Container scanning before push to registry.

8. Performance & Scalability

Read-through cache (Redis, 5 min TTL) for reference data.
Cache invalidation via events. Keys always include tenant_id.
SQS FIFO for document ingestion (dedup + ordering).
Dead letter queue on every queue. Max 3 receives before DLQ.
Connection pooling via PgBouncer. Read replicas for analytics.
Table partitioning by tenant_id + created_date for high-volume tables.

Quality Gate Summary

No code reaches production without passing ALL of these:

Lint + Format: Zero errors (pre-commit hook)
Type check: Zero errors (CI build)
Unit tests: All pass, coverage ≥ 85% on changed files
Integration tests: All pass
Security scan: No Critical/High CVEs
License check: All dependencies approved
Contract tests: All consumer contracts satisfied
PR review: 1 approval minimum
Staging E2E: Smoke tests pass
Canary health: Error rate < 2%, latency < 2x baseline ```

Wie man das für das eigene Projekt anpasst

Mit der Architektur beginnen. Multi-Tenancy-Regeln, API-Konventionen, Auth-Modell. Das sind die nicht verhandelbaren Leitplanken.
Konkrete Code-Standards ergänzen. Keine Prinzipien — Regeln. Zeilenlimits, Parameterlimits, Namenskonventionen mit Beispielen. Je spezifischer, desto konsistenter wird die KI (und das Team) sie befolgen.
Die Testkultur kodieren. Coverage-Ziele, Test-Patterns mit Code-Beispielen, die spezifischen Tools. Eine KI, die ein Testcontainers-Beispiel sieht, generiert Integrationstests mit Testcontainers.
Domain-Kontext einschließen. Erkläre, was das Produkt in Business-Begriffen macht. Die KI schreibt besseren Code, wenn sie versteht, warum ein Validierungsmodul Konfidenz-Schwellwerte hat.
Lebendig halten. Eine CLAUDE.md, die einmal geschrieben und dann vergessen wird, ist nur eine weitere veraltete Wiki-Seite. Aktualisieren, wenn sich Standards weiterentwickeln. Sie sollte widerspiegeln, wie man heute Software baut, nicht wie man es vor sechs Monaten geplant hat.

Der Multiplikator-Effekt

Hier ist, was sich geändert hat, als wir anfingen, umfassende CLAUDE.md-Dateien zu nutzen:

PR-Review-Zeit sank um ~40 %. Der KI-generierte Code befolgt bereits Standards, sodass Reviews sich auf Logik und Architektur konzentrieren, nicht auf Formatierung und Patterns.
Onboarding beschleunigte sich. Neue Engineers lesen die CLAUDE.md und verstehen sofort, wie das Team Software baut. Die KI hilft ihnen, von Tag eins Code zu schreiben, der passt.
Konsistenz über die gesamte Codebase. Ob Code von einem Senior Architect oder einem Junior Engineer mit Claude Code geschrieben wurde, er folgt den gleichen Patterns. Die CLAUDE.md ist der große Gleichmacher.
Standards werden durchsetzbar. Eine Wiki-Seite ist ambitioniert. Eine CLAUDE.md ist operativ — sie formt jede Code-Generierung in Echtzeit.

Die CLAUDE.md dient nicht dazu, die KI zu kontrollieren. Es geht darum, die Engineering-Kultur in ein Format zu kodieren, das skaliert — für mehr Engineers, mehr Agenten, mehr Repositories. Es ist die fehlende Schicht zwischen “wir haben Standards” und “unsere Standards werden tatsächlich befolgt.”