CLAUDE.md

Projekt-spezifische Anweisungen, die Claude Code bei jedem Start liest.

Speicherort

./project/CLAUDE.md      # Projekt-Root (empfohlen)
./project/.claude.md     # Alternative (hidden)

Claude Code sucht automatisch nach beiden Varianten.

Zweck

CLAUDE.md ist wie ein "Onboarding-Dokument" für Claude:

• Projekt-Kontext verstehen
• Coding-Standards einhalten
• Architektur-Entscheidungen kennen
• Häufige Fehler vermeiden

Beispiel

# CLAUDE.md

## Projekt

E-Commerce Platform (Node.js/TypeScript)

## Architektur

- Backend: Express.js + TypeORM
- Frontend: React + Zustand
- DB: PostgreSQL 15
- Cache: Redis

## Coding Standards

- TypeScript strict mode
- ESLint + Prettier (npm run lint)
- Tests: Jest (npm test)
- Keine `any` Types

## Wichtige Konventionen

- API Endpoints: `/api/v1/resource`
- Alle Responses: `{ data: T, error?: string }`
- Fehler-Handling: Custom AppError Klasse
- Logging: Winston Logger (nicht console.log)

## Nicht anfassen

- `src/legacy/` - Wird migriert, nicht ändern
- `config/prod.json` - Nur DevOps

## Build & Test

```bash
npm run build      # TypeScript kompilieren
npm test           # Jest Tests
npm run e2e        # Playwright E2E

Bekannte Issues

• Redis-Connection muss vor DB-Init stehen
• User-Service hat Race Condition bei Bulk-Updates

  ## Best Practices
  
  ### DO ✅
  
  - **Kurz halten** - Claude liest das bei jedem Start
  - **Konkret sein** - "Nutze Winston Logger" statt "Logging beachten"
  - **Pfade angeben** - "Siehe `docs/api.md` für API-Spec"
  - **Commands listen** - Build, Test, Lint Commands
  
  ### DON'T ❌
  
  - **Zu lang** - Keine 500 Zeilen
  - **Zu vage** - "Code sollte gut sein"
  - **Redundant** - Was offensichtlich ist weglassen
  - **Veraltet** - CLAUDE.md aktuell halten!
  
  ## Struktur-Template
  
  ```markdown
  # CLAUDE.md
  
  ## Projekt
  [1-2 Sätze: Was ist das?]
  
  ## Tech Stack
  [Bullet-Liste der Haupttechnologien]
  
  ## Wichtige Commands
  [Build, Test, Lint, Deploy]
  
  ## Coding Conventions
  [Die wichtigsten 3-5 Regeln]
  
  ## Architektur-Notizen
  [Nur was nicht offensichtlich ist]
  
  ## Off-Limits
  [Was Claude nicht anfassen soll]
  

CLAUDE.md vs Skills

Aspekt	CLAUDE.md	Skills
Geladen	Immer	On-demand
Scope	Projekt-Kontext	Spezifische Tasks
Länge	Kurz (< 100 Zeilen)	Kann lang sein
Inhalt	Kontext & Regeln	Workflows & Instructions

Kombination:

• CLAUDE.md: "Wir nutzen Jest für Tests"
• Skill /test-gen: "So generierst du Jest-Tests..."

Auto-Memory

Claude Code baut auch automatisch "Memory" auf:

~/.claude/memory/project-hash/
└── learnings.json

Hier speichert Claude Erkenntnisse wie: - Build-Commands die funktioniert haben - Debugging-Insights - Projekt-spezifische Patterns

Diese Auto-Memory ergänzt CLAUDE.md, ersetzt sie aber nicht.

Multi-Projekt Setup

Bei Monorepos:

/monorepo/
├── CLAUDE.md              # Root: Allgemeine Infos
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md      # Frontend-spezifisch
│   └── backend/
│       └── CLAUDE.md      # Backend-spezifisch

Claude lädt die CLAUDE.md basierend auf dem aktuellen Arbeitsverzeichnis.

Troubleshooting

CLAUDE.md wird nicht geladen

1. Dateiname prüfen: CLAUDE.md (case-sensitive)
2. Pfad prüfen: Muss im Projekt-Root sein
3. Encoding: UTF-8

Inhalt wird ignoriert

Claude hat Token-Limits. Wenn CLAUDE.md zu lang ist, wird evtl. gekürzt.

Fix: Kürzen, nur das Wichtigste behalten.