Vibe Coding Kurs — Handout — macOS

Das CLAUDE.md File

Dein wichtigstes Steuerungsinstrument für Claude Code – was rein muss, was nicht, und wie du es richtig strukturierst.

Was ist CLAUDE.md?

CLAUDE.md ist eine Markdown-Datei, die Claude Code bei jedem Session-Start automatisch liest. Sie enthält persistente Instruktionen, die du nicht jedes Mal wiederholen musst – Build-Befehle, Coding-Standards, Architektur-Entscheidungen, Projekt-Konventionen. Sie ist die Brücke zwischen deinem Projekt und Claude.

Wichtig

Die CLAUDE.md verbraucht Context-Tokens. Je länger die Datei, desto weniger Platz bleibt für deinen eigentlichen Dialog. Halte sie darum unter 200 Zeilen.

Inhalt

  1. What – Why – How
  2. Wo CLAUDE.md ablegen?
  3. Lade-Hierarchie & Priorität
  4. Empfohlene Struktur
  5. Was rein muss
  6. Was NICHT rein gehört
  7. Do & Don’t
  8. Vollständiges Beispiel
  9. Schnellstart mit /init
  10. Checkliste

1. What – Why – How

What

Eine Markdown-Datei namens CLAUDE.md im Projekt-Root (oder an anderen Stellen). Sie wird automatisch als User-Nachricht an Claude gesendet – wie ein dauerhaftes Briefing.

Why

Claude kann nicht alles aus dem Code ableiten: welche Build-Befehle gelten, welche Konventionen das Team hat, welche Gotchas existieren. Ohne CLAUDE.md wiederholt man sich in jeder Session.

How

Erstelle eine CLAUDE.md im Projekt-Root, checke sie in Git ein, und halte sie gepflegt. Claude liest sie automatisch. Nutze /init für einen Schnellstart.

2. Wo CLAUDE.md ablegen?

CLAUDE.md Dateien können an verschiedenen Orten liegen, je nach Scope:

Scope Pfad Geteilt mit
Projekt Empfohlen ./CLAUDE.md Team via Git
Persönlich (Projekt) ./CLAUDE.local.md Nur du (in .gitignore)
User-Global ~/.claude/CLAUDE.md Nur du (alle Projekte)
Unterverzeichnis subdir/CLAUDE.md Team (lädt lazy on-demand)
Regeln (modular) .claude/rules/*.md Team via Git
Organisation System-Pfad Alle User auf der Maschine

3. Lade-Hierarchie & Priorität

Claude lädt beim Session-Start alle CLAUDE.md Dateien vom Working Directory aufwärts bis zum Repo-Root. Sie werden konkateniert (nicht überschrieben).

1
Organisation (Managed Policy) Kann nicht ausgeschlossen werden. IT/DevOps verwaltet.
2
User-Global ~/.claude/CLAUDE.md Deine persönlichen Präferenzen für alle Projekte.
3
Projekt ./CLAUDE.md + .claude/rules/ Team-geteilte Instruktionen. Höchste Priorität bei Konflikten.
4
Lokal ./CLAUDE.local.md Wird nach CLAUDE.md angehängt. Persönlich, nicht in Git.
5
Unterverzeichnis subdir/CLAUDE.md Lädt lazy, nur wenn Claude in diesem Verzeichnis arbeitet.

Konflikt-Regel

Bei widersprüchlichen Instruktionen gewinnt der spezifischere Pfad. CLAUDE.local.md überschreibt CLAUDE.md auf derselben Ebene. Tiefere Verzeichnisse überschreiben höhere.

4. Empfohlene Struktur

Eine gute CLAUDE.md folgt einem klaren Aufbau. Hier ist das empfohlene Template:

CLAUDE.md
# Projektname Kurzbeschreibung in 1–2 Sätzen. ## Tech Stack - Frontend: Next.js 14, TypeScript, Tailwind - Backend: FastAPI, PostgreSQL - Deploy: Vercel + Docker ## Code Style - 2-Space Indentation - ES Modules (import/export), kein CommonJS - Destructured Imports bevorzugen ## Workflow - Dev: `npm run dev` (Port 3000) - Build: `npm run build` - Test: `npm test` (vor jedem Commit) ## Architektur - API-Handler in `src/api/handlers/` - DB-Queries in `src/db/` - Keine Business-Logik in Controllern ## Gotchas - Session-Tokens laufen nach 1h ab - Cache muss manuell invalidiert werden ## Security - Keine .env Dateien committen - Input-Validierung mit Zod an API-Grenzen

5. Was rein muss

Alles, was Claude nicht aus dem Code ableiten kann und was zu Fehlern führt, wenn es fehlt:

Kategorie Beispiele
Build & Test Befehle npm run build, pytest, cargo test
Code-Style Abweichungen Indentation, Import-Style, Naming Conventions
Architektur-Entscheidungen Wo was hinkommt, Design-Patterns, Constraints
Git & Workflow Branch-Naming, Commit-Format, PR-Konventionen
Environment Setup Benötigte Env-Vars, Node-Version, DB-Setup
Gotchas & Fallen Nicht-offensichtliche Verhaltensweisen, häufige Fehler
Tech-Stack Präferenzen Welche Libs bevorzugt, welche verboten
Security-Regeln Keine Secrets committen, Input-Validation, Auth-Setup

Faustregel

Für jede Zeile fragen: «Würde Claude ohne diese Information Fehler machen?» – Wenn nein, raus damit.

6. Was NICHT rein gehört

Nicht in die CLAUDE.md

  • Standard-Konventionen – Claude kennt JavaScript/Python-Syntax bereits
  • Selbstverständlichkeiten – «Schreibe sauberen Code» bringt nichts
  • Detaillierte API-Docs – Zu lang, lieber verlinken
  • Code-Muster aus dem Projekt – Claude liest den Code selbst
  • File-für-File Beschreibungen – Zu viel Platz, veraltet schnell
  • Tutorials & lange Erklärungen – Blähen die Datei auf
  • Sich häufig ändernde Info – Veraltet und verwirrt
  • Secrets & Zugangsdaten – Niemals!

So ist es richtig

  • Nutze 2-Space Indentation
  • Tests vor Commit: npm test
  • API-Handler in src/api/
  • Kein axios – nur native fetch

So nicht

  • Schreibe guten, wartbaren Code
  • Nutze sinnvolle Variablennamen
  • Die Datei user.ts enthält...
  • JavaScript nutzt Semikolons...

7. Do & Don’t

Do Best Practices

Don’t Vermeiden

Compliance-Hinweis

CLAUDE.md Instruktionen sind advisory (~70% Compliance). Wenn Claude eine Regel konsequent ignoriert, ist die Datei wahrscheinlich zu lang. Kürze sie. Für 100% Durchsetzung nutze Hooks in settings.json.

8. Vollständiges Beispiel

Ein realistisches CLAUDE.md für ein Next.js SaaS-Projekt:

CLAUDE.md
# MeinSaaS – Kunden-Dashboard Next.js 14 App Router SaaS mit Stripe-Billing und Team-Management. ## Tech Stack - Next.js 14 (App Router), TypeScript strict - Tailwind CSS + shadcn/ui - PostgreSQL (Neon) + Drizzle ORM - Auth: NextAuth.js v5 - Payments: Stripe - Deploy: Vercel ## Commands - Dev: `npm run dev` (Port 3000) - Build: `npm run build` - Test: `npm test` (einzelne Dateien, nicht Full Suite) - Typecheck: `npm run typecheck` - Lint: `npm run lint` - DB Push: `npx drizzle-kit push` ## Code Style - ES Modules, kein CommonJS - Destructured Imports - Kein axios – nur native fetch - Server Components als Default - «use client» nur wo nötig ## Architektur - API Routes: `app/api/` - DB Queries: `lib/db/queries/` - UI Components: `components/ui/` (shadcn) - Business Logic: `lib/services/` - Input-Validierung mit Zod an API-Grenzen ## Git - Nie mit --no-verify committen - Kein Force-Push auf main - .env nie committen ## Gotchas - Stripe Webhooks brauchen Raw Body (kein JSON parse) - NextAuth Session nur in Server Components verfügbar - Drizzle: `eq()` importieren, nicht `=` in Queries

9. Schnellstart mit /init

Der schnellste Weg zu einer guten CLAUDE.md:

  1. Öffne Claude Code in deinem Projekt-Root
  2. Tippe /init – Claude analysiert den Code und generiert ein CLAUDE.md
  3. Prüfe und passe die generierte Datei an
  4. Checke sie in Git ein: git add CLAUDE.md
  5. Erstelle optional eine CLAUDE.local.md für deine persönlichen Präferenzen
Terminal
# Im Projekt-Root: $ claude > /init # Claude analysiert dein Projekt und erstellt CLAUDE.md # Danach prüfen und committen: $ git add CLAUDE.md $ git commit -m "Add CLAUDE.md project instructions"

Installation

Claude Code kannst du auf drei Wegen nutzen:

Claude Desktop App

Am einfachsten: Claude Code ist direkt in der Desktop App integriert. Download unter claude.ai/download – kein npm oder Node.js nötig.

VS Code Extension

Claude Code als Extension im VS Code Marketplace installieren. Ideal für alle, die bereits in VS Code arbeiten.

CLI via npm

Für Entwickler mit Node.js: npm install -g @anthropic-ai/claude-code im Terminal ausführen. Setzt Node.js voraus.

10. Checkliste

Quick Reference

Vor dem Erstellen fragen

  • ✓ Würde Claude ohne diese Info Fehler machen?
  • ✓ Ist es spezifisch genug zum Verifizieren?
  • ✓ Gilt es breit (nicht einmalig)?
  • ✓ Kann es NICHT aus dem Code abgeleitet werden?

Beim Review prüfen

  • ✓ Unter 200 Zeilen?
  • ✓ Klare Header-Struktur?
  • ✓ Konkrete, spezifische Regeln?
  • ✓ Keine Duplikate oder Veraltetes?
  • ✓ Keine Secrets enthalten?
  • ✓ In Git eingecheckt?

CLAUDE.md

Team-geteilte Instruktionen. In Git einchecken. Pflege wie Code.

CLAUDE.local.md

Persönliche Präferenzen. In .gitignore. Ergänzt die Projekt-Datei.

.claude/rules/

Modulare Regeln für grosse Projekte. Können pfad-basiert scoped werden.

~/.claude/CLAUDE.md

Globale Präferenzen über alle Projekte hinweg. Nur für dich.