CLAUDE.md – Project Instructions für KI-gestützte Entwicklung

CLAUDE.md ist eine spezielle Markdown-Datei, die im Root-Verzeichnis eines Projekts platziert wird und automatisch in jeden Claude Code Prompt eingebunden wird. Sie funktioniert wie eine erweiterte Projektbeschreibung für KI-Assistenten – eine strukturierte Sammlung von Regeln, Best Practices, Architektur-Dokumentation und Workflows, die Claude verstehen und befolgen soll.

Im Gegensatz zu generischer Dokumentation ist CLAUDE.md spezifisch darauf ausgelegt, dass KI-Assistenten diese Informationen aktiv nutzen. Die Datei enthält konkrete, nicht verhandelbare Regeln (mit Worten wie "NIEMALS", "IMMER", "PFLICHT"), anstatt vager Empfehlungen.

Was ist CLAUDE.md?

CLAUDE.md ist eine Projektdatei, die Claude Code automatisch einliest und in den Kontext jedes Prompts einbezieht. Sie funktioniert als "Gebrauchsanweisung für dieses Projekt" aus der Perspektive eines KI-Assistenten.

Kernfunktionen:

• Automatische Kontexteinbindung: Claude Code lädt CLAUDE.md automatisch und berücksichtigt die Inhalte bei jedem Prompt
• Persistente Regeln: Einmal definierte Regeln gelten konsistent über alle Sessions hinweg
• Teamkommunikation: Neue Entwickler (menschlich oder KI) verstehen sofort die Projektkonventionen
• Verbesserte Qualität: Strukturierte Guidelines führen zu konsistenterem, besseren Code
• Fehlerprävention: Anti-Patterns können explizit verboten werden, bevor sie entstehen

Warum ist CLAUDE.md wichtig?

Ohne CLAUDE.md muss der Mensch in jedem Prompt alle relevanten Informationen wiederholen. Mit CLAUDE.md:

• Claude versteht die Architektur des Projekts sofort
• Regeln zur Code-Qualität werden konsistent angewendet
• Sicherheitsrichtlinien (z.B. "keine hardcodierten Credentials") werden automatisch beachtet
• Deployment-Workflows sind dokumentiert und werden befolgt
• Die KI arbeitet wie ein erfahrenes Projektmitglied, nicht wie ein angelernter Praktikant

Aufbau einer CLAUDE.md

Eine professionelle CLAUDE.md hat typischerweise folgende Struktur:

1. Kritische Regeln (oben!)

Die wichtigsten, nicht verhandelbaren Regeln – oft mit Warnzeichen und NIEMALS/IMMER in Großbuchstaben:

## ⚠️ KRITISCHE REGELN - ABSOLUT BINDEND

- **NIEMALS etwas hardcodieren!** Es gibt klare Anweisungen: immer die API nutzen.
- **KEINE Fallbacks mit Daten** – nur leere "" Fallbacks erlaubt.
- **NIEMALS Credentials hardcoden** – IMMER Environment-Variablen nutzen.
- **Sprache:** Alles auf Deutsch mit korrekten Umlauten (äöüß).

2. Quick Start Commands

Die wichtigsten Befehle zum Starten des Projekts:

## Quick Start Commands

### Development Server
```bash
npm run dev              # Startet alle Services
npm run lint             # Code Style Check
npm run build            # Production Build
```

3. Server & Architektur

Tabelle mit Ports, URLs, und technischen Details:

## Server & Architektur

| Service | Port | URL |
|---------|------|-----|
| Frontend (Vite) | 5175 | http://localhost:5175 |
| Backend (Express) | 3030 | http://localhost:3030 |
| Production | - | https://elasticbrains.de |

4. Code Style Guidelines

Konkrete, umsetzbare Konventionen:

## Code Style Guidelines
- **Project:** Vue 3 with Vite, Composition API
- **Indentation:** 2 spaces
- **Components:** PascalCase naming (ComponentName.vue)
- **JavaScript Variables:** camelCase
- **CSS Classes:** kebab-case
- **State:** ref/computed for local state, provide/inject for global state

5. Sicherheits- und Testing-Anforderungen

Konkrete Sicherheitsmassnahmen und Testing-Checklisten:

## Sicherheit
- Helmet Security Headers nutzen
- Rate Limiting für API-Endpunkte
- JWT Authentication mit Access & Refresh Tokens
- Input Validation für alle User-Eingaben

## Testing
```bash
npm run test             # Unit Tests
npm run build            # Build-Check
npx tsc --noEmit        # TypeScript Check
npm run lint             # Linting
```

6. Dokumentation und Deployment

Wie man mit der bestehenden Dokumentation umgeht und wie Deployment funktioniert:

## Documentation Maintenance
- Nach neuen Seiten: npm run generate-sitemap
- Admin-Bereich: SEO Metadata aktualisieren
- Neuen Code: JSDoc-Kommentare hinzufügen

## Deployment
./deploy.sh             # Interaktives Deployment-Menü

CLAUDE.md vs. andere Project Instructions

Es gibt mehrere Formate für Project Instructions. CLAUDE.md ist spezifisch für Claude Code, aber es gibt Alternativen:

Format	Tool	Speicherort	Automatisches Laden
CLAUDE.md	Claude Code (Anthropic)	Project Root	Ja, automatisch in jeden Prompt
.cursorrules	Cursor IDE	Project Root	Ja, automatisch in jeden Prompt
.github/copilot-instructions.md	GitHub Copilot	GitHub Repository	Ja, für Copilot Chat
README.md	Allgemein	Project Root	Nur wenn manuell referenziert
MEMORY.md	Lokal	Projekt oder User-Config	Optional, manuelle Referenzierung

Warum CLAUDE.md über README.md?

• README.md: Ist für Menschen geschrieben – Projekt-Übersicht, Features, Installation
• CLAUDE.md: Ist für KI geschrieben – konkrete Regeln, Anti-Patterns, "Wie arbeite ich in diesem Projekt"

README.md sagt: "Das ist ein Vue 3 Frontend mit Express Backend." CLAUDE.md sagt: "Nutze IMMER den Logger aus @/core/Logger, niemals console.log. Alle Filter werden in localStorage persistiert. Admin-Views verwenden volle Breite ohne max-width."

Best Practices für CLAUDE.md

1. Konkrete Regeln statt vage Empfehlungen

Falsch:

- Logger sollte bevorzugt werden
- Code sollte TypeScript sein
- Components sollten modular sein

Richtig:

- **NIEMALS** console.log/warn/error verwenden. **IMMER** Logger aus @/core/Logger nutzen.
- **ALLE Dateien MÜSSEN TypeScript sein** (.ts oder .tsx)
- **IMMER Composition API** verwenden, Options API ist verboten

2. Beispiele geben

Nicht nur die Regel sagen, sondern zeigen, wie es richtig aussieht:

## Logging

// RICHTIG:
import { Logger } from '@/core/Logger'
Logger.debug('ADMIN', 'Loading users', { count: users.length })

// FALSCH - NIEMALS:
console.log('Loading users')
console.warn('Something happened')

3. Anti-Patterns explizit verbieten

Mit Warnzeichen, damit es wirklich ernst genommen wird:

## ⚠️ VERBOTENE PATTERNS

- **NIEMALS hardcodierte Credentials** (Passwörter, API Keys)
- **NICHT window.innerWidth in onMounted** – verursacht Layout Reflow
- **KEINE Mock-Daten in Production-Code** – nur echte API-Daten
- **NICHT /api/* Endpoints hardcoden** – verwende API-Service

4. Workflows dokumentieren

Nicht nur WAS, sondern auch WIE – mit genauen Befehlen:

## Deployment Workflow

### 1. Vor dem Deployment
```bash
npm run build           # Full build
npm run lint            # Code quality
npx tsc --noEmit       # Type check
```

### 2. Deployment
```bash
./deploy.sh             # Startet deployment.sh mit interaktivem Menü
./deploy.sh --dry-run   # Preview ohne Änderungen
./deploy.sh --force     # Deploy ohne Bestätigung
```

### 3. Nach dem Deployment
```bash
curl https://elasticbrains.de/api/health  # Health Check
```

5. Wichtiges visuell hervorheben

Nutze Markdown-Features, um Aufmerksamkeit zu lenken:

## ⚠️ KRITISCH: Production-Umgebung

**NIEMALS auf dem Production-Server:**
- Datenbank-Befehle ohne Backup
- rm -rf ohne explizite Pfadangabe
- Globale nginx-Konfiguration ändern
- Andere Services beeinflussen

6. Sicherheit nicht vergessen

Klare Regeln für Credentials und Umgebungsvariablen:

## ⚠️ NIEMALS HARDCODIERTE CREDENTIALS

- **NIEMALS** Passwörter, API Keys, Tokens im Code
- **IMMER** Environment-Variablen nutzen: process.env.VARIABLE_NAME
- **IMMER** Fehler werfen wenn required ENV-Variable fehlt:
  ```typescript
  if (!process.env.MONGODB_URI) {
    throw new Error('MONGODB_URI environment variable is required');
  }
  ```

Hierarchische Kontexte: Global → Projekt → Task

Es gibt mehrere Ebenen von Kontextinformationen, die eine KI berücksichtigen sollte:

Ebene 1: Globale CLAUDE.md (~/.claude/CLAUDE.md)

Für ALLE Projekte geltende Regeln:

• Coding-Standards (TypeScript, Composition API, German language)
• Sicherheits-Grundprinzipien (keine hardcodierten Credentials)
• Tool-Präferenzen (Logger statt console.log)
• Persönliche Arbeitsweise (deutsche Texte, Umlaute)

Ebene 2: Projekt-CLAUDE.md (PROJECT_ROOT/CLAUDE.md)

Spezifisch für das aktuelle Projekt:

• Architektur (Vue 3 + Express, Vite, tailwindcss)
• Tech-Stack Details (welche Libraries, welche Versionen)
• Projekt-spezifische Workflows (./deploy.sh, npm run generate-sitemap)
• Server-Konfiguration (Ports, Production URLs)
• Besonderheiten (Admin-Authentifizierung, Service Worker, etc.)

Ebene 3: Memory Files & Task-Context

Dynamischer Kontext für die aktuelle Aufgabe:

• MEMORY.md mit gelernten Lektionen und Known Issues
• Session-Handover-Dateien für lange Sessions
• Relevante Dateien für die aktuelle Task

Diese Hierarchie sorgt dafür, dass globale Prinzipien erhalten bleiben, während gleichzeitig projekt-spezifische Details beachtet werden.

CLAUDE.md als Onboarding-Tool

CLAUDE.md funktioniert auch perfekt als Onboarding-Material für neue Entwickler:

Für neue menschliche Entwickler:

• "Ich bin neu. Was muss ich über dieses Projekt wissen?" → CLAUDE.md lesen
• "Wie starte ich den Dev-Server?" → Quick Start Commands in CLAUDE.md
• "Was sind die Code-Style-Regeln?" → Code Style Guidelines in CLAUDE.md
• "Wie deploye ich?" → Deployment-Sektion in CLAUDE.md

Für KI-Assistenten:

• Claude Code lädt CLAUDE.md automatisch
• Neue KI-Assistenten verstehen sofort die Projektregeln
• Kein "kalter Start" – die KI kennt die Architektur von Anfang an
• Konsistentes Verhalten über Tage, Wochen, Monate hinweg

Knowledge Preservation:

• Wenn Entwickler das Projekt verlassen, bleibt ihr Wissen in CLAUDE.md
• Gelehrte Lektionen sind dokumentiert
• Vermeidung von "Silo-Wissen" bei einzelnen Personen
• Neue Entwickler (menschlich oder KI) profitieren von dieser Dokumentation

CLAUDE.md bei elasticbrains

Bei elasticbrains haben wir ein zweischichtiges System:

• Globale CLAUDE.md: (~/.claude/CLAUDE.md) Definiert unsere Standards über ALLE Projekte: deutsche Sprache mit Umlauten, TypeScript, keine hardcodierten Credentials, saubere Code-Architektur
• Projekt-CLAUDE.md: (/elasticbrains-website/CLAUDE.md) Spezifisch für elasticbrains-website: Vite, Vue 3, Express Backend, Admin-Dashboard mit JWT-Auth, SEO-Anforderungen, Deployment via ./deploy.sh

Das Ergebnis: Egal welcher Entwickler (menschlich oder KI) arbeitet am Projekt, die Qualität und Konsistenz sind garantiert.

Häufige Fehler bei CLAUDE.md

1. Zu allgemein ("Best Practices")

Falsch: "Code sollte gut strukturiert sein."

Richtig: "Verwende Composition API, niemals Options API. Components in src/components/, Views in src/views/. Logger statt console.log."

2. Zu viel auf einmal

CLAUDE.md wird in den Token-Kontext eingebunden. Eine 10-Seiten-CLAUDE.md verbraucht kostbare Tokens. Konzentriere dich auf das Wichtigste:

• Kritische Regeln (oben)
• Quick Start
• Server-Konfiguration
• Code Style
• Sicherheit
• Deployment

3. Regeln die niemand befolgt

Wenn eine Regel wirklich nicht befolgt wird, ist sie falsch. CLAUDE.md sollte realistisch sein:

• "Niemals debuggen" – unrealistisch
• "Alles in TypeScript" – wenn das Projekt teilweise JS hat, dann anpassen
• "Keine externen Dependencies" – wenn das Projekt 50 npm-Packages hat, dann anpassen

4. Zu selten aktualisiert

CLAUDE.md ist ein lebendes Dokument. Wenn sich die Architektur ändert, muss CLAUDE.md aktualisiert werden. Alte, veraltete CLAUDE.md ist schlimmer als keine CLAUDE.md.

Workshop-Verweis: Agentic Coding meistern

CLAUDE.md ist ein zentraler Bestandteil des Agentic Coding Workshops. In unserem Workshop lernen Sie:

• Wie man professionelle, wartbare CLAUDE.md Dateien schreibt
• Best Practices für Project Instructions aus 3 Jahren Erfahrung
• Wie man CLAUDE.md, Memory Files und Session-Handover kombiniert
• Praktische Übungen: Ihre eigene CLAUDE.md schreiben und testen
• Context Engineering: Wie man Kontextinformationen optimal nutzt
• Integration mit Claude Code, Cursor und anderen KI-Tools

Der Workshop zeigt, wie systematisches Context Engineering (davon CLAUDE.md ein Teil ist) die Qualität und Effizienz von KI-gestützter Entwicklung um ein Vielfaches verbessert.

Tools und Integration

Claude Code (Anthropic)

• CLAUDE.md wird automatisch erkannt und in jeden Prompt eingebunden
• Neueste Dateiversion wird immer verwendet
• Keine manuelle Konfiguration nötig
• Vollständige Unterstützung für Markdown-Formatierung

Cursor IDE

• .cursorrules Datei mit ähnlichem Zweck
• Automatisches Laden beim Start
• Integration mit Cursor Composer

GitHub Copilot

• .github/copilot-instructions.md
• Weniger ausgereift als CLAUDE.md oder .cursorrules
• Funktioniert mit GitHub Copilot Chat

Weiterführende Ressourcen

• Glossar: Context Engineering – Umfassender Leitfaden für strukturierten KI-Kontext
• Glossar: Agentic Coding – KI-gestützte Softwareentwicklung praktizieren
• Glossar: Prompt Engineering – Einzelne KI-Prompts optimal formulieren
• Workshop: Agentic Coding Workshop – Hands-on Erfahrung mit Project Instructions und Context Engineering
• Tools: Claude Code, Cursor IDE, GitHub Copilot
• Dokumentation: Anthropic Claude API Documentation, Cursor Documentation

Zusammenfassung

CLAUDE.md ist nicht nur ein Dokument – es ist eine Schnittstelle zwischen menschlichen Entwicklern und KI-Assistenten. Eine gut geschriebene CLAUDE.md:

• Macht Projekt-Wissen dauerhaft und teilbar
• Verbessert die Qualität von KI-generiertem Code
• Spart Zeit durch klare, wiederholte Regeln
• Ist ein Onboarding-Tool für neue Entwickler (menschlich und KI)
• Bewahrt Lessons Learned, auch wenn Entwickler gehen
• Ermöglicht professionelles, skalierbares Agentic Coding

Die beste CLAUDE.md ist eine, die regelmäßig gelesen und aktualisiert wird – ein lebendes Dokument, das mit dem Projekt wächst.