Was ist eine CLAUDE.md — und warum du eine brauchst

Claude Code, Cursor, Windsurf – die neuen AI-Coding-Tools versprechen Produktivitätssprünge. Aber zwischen „installiert” und „wirklich nützlich” liegt ein Graben. Der Schlüssel liegt in der Konfiguration.

Bei Claude Code heißt sie CLAUDE.md. Eine Markdown-Datei, die Claude bei jeder Session liest. Klingt simpel – aber hier entscheidet sich, ob die KI dir hilft oder dich ausbremst.

Dieser Guide zeigt den goldenen Pfad: von der ersten Einrichtung bis zum produktiven Team-Workflow.

Schnellstart: Die ersten 5 Minuten

Mit /init starten

Nicht bei Null anfangen. Claude kann dein Projekt analysieren und eine initiale CLAUDE.md generieren:

claude
> /init

Das Ergebnis: Build-Kommandos, Test-Framework, Projektstruktur – automatisch erkannt. Danach anpassen, aber die Basis steht.

Kurz halten

Die wichtigste Regel: Weniger ist mehr. Anthropic selbst warnt: „Bloated CLAUDE.md files cause Claude to ignore your actual instructions.”

Für jede Zeile fragen: „Würde Claude ohne diese Zeile Fehler machen?” Wenn nein: raus damit.

## Code Style
- TypeScript strict mode
- Keine any-Types
- Funktionen unter 30 Zeilen
- Tests für jeden neuen Endpunkt

Nicht drei Absätze Prosa, warum TypeScript gut ist. Stichpunkte. Konkret. Fertig.

Ins Git committen

CLAUDE.md gehört ins Repository. Versioniert, für alle im Team sichtbar, gemeinsam gepflegt.

Für persönliche Präferenzen: CLAUDE.local.md anlegen und in .gitignore packen.

project/ ├── CLAUDE.md # Team-Standard, im Git ├── CLAUDE.local.md # Persönlich, in .gitignore └── src/

Die Datei strukturieren

Hierarchisch denken

Eine Datei für alles? Funktioniert bei kleinen Projekten. Bei größeren wird’s unübersichtlich – und Claude lädt bei jeder Session alles, auch wenn nur ein Bruchteil relevant ist.

Besser: Haupt-CLAUDE.md im Root, spezifische Dateien in Unterverzeichnissen.

project/ ├── CLAUDE.md # Globale Regeln ├── frontend/ │ └── CLAUDE.md # React-spezifisch ├── backend/ │ └── CLAUDE.md # API-spezifisch └── infrastructure/ └── CLAUDE.md # DevOps-spezifisch

Claude priorisiert automatisch die spezifischste Datei für den aktuellen Kontext.

Externe Docs verlinken

Architektur-Dokumentation nicht in die CLAUDE.md kopieren. Stattdessen verlinken:

## Architektur
Siehe @docs/architecture.md für Details.

## API-Konventionen
Siehe @docs/api-conventions.md

Die @-Syntax importiert Dateien nur bei Bedarf – nicht bei jeder Session. Spart Kontext, vermeidet doppelte Pflege.

Guardrails definieren

Nicht nur sagen, was Claude tun soll. Auch, was es lassen soll.

## WICHTIG: Nicht tun
- NIEMALS Dateien in /migrations/ ändern
- KEINE neuen Dependencies ohne Rückfrage
- NICHT auf main pushen
- KEINE console.log im Production-Code

Die Betonung („WICHTIG”, „NIEMALS”) verbessert die Befolgung nachweislich. Bei Anthropic nutzen Teams regelmäßig „YOU MUST” und „IMPORTANT” für kritische Regeln.

Persona und Qualität steuern

Eine Rolle definieren

Claude antwortet sonst generisch – mal Junior, mal Architekt, mal ausschweifend. Eine Persona schafft Konsistenz:

## Persona
Du bist ein Senior TypeScript-Entwickler mit Fokus auf:
- Clean Architecture
- Test-Driven Development
- Performance-Optimierung

Antworte präzise, nicht ausschweifend.
Wenn etwas unklar ist: nachfragen statt raten.

Keine Spielerei – sondern Qualitätssteuerung.

Mit Beispielen arbeiten

Abstrakte Regeln sind interpretierbar. Konkrete Beispiele nicht.

## Fehlerbehandlung
WICHTIG: Immer spezifische Error-Typen werfen.

✅ throw new ValidationError('Email ungültig')
❌ throw new Error('Fehler')

Claude lernt aus Beispielen schneller als aus Erklärungen.

Iterativ verbessern

CLAUDE.md ist kein Dokument – es ist ein Prompt. Und Prompts werden optimiert.

Bei Anthropic lassen Teams ihre Configs regelmäßig durch den Prompt Improver laufen. Auch ohne Tool gilt:

Wenn Claude eine Regel ignoriert: anders formulieren
Wenn Claude nachfragt, was in der Datei steht: klarer schreiben
Wenn etwas gut funktioniert: das Muster auf andere Regeln übertragen

Skills für wiederholbare Workflows

Was Skills sind

Manche Workflows wiederholen sich: Code-Review, Refactoring, Deployment-Checks. Die gehören nicht in die Haupt-CLAUDE.md – sondern in modulare Skills.

Skills sind SKILL.md-Dateien in .claude/skills/. Claude lädt sie bei Bedarf.

# .claude/skills/code-review/SKILL.md
---
name: code-review
description: Strukturiertes Code-Review mit Checkliste
---
Führe ein Code-Review durch:
1. Security-Checks (Injection, XSS, Auth)
2. Performance (N+1 Queries, unnötige Renders)
3. Lesbarkeit (Naming, Komplexität)
4. Tests (Coverage, Edge Cases)

Fasse die Ergebnisse am Ende zusammen.

Aufruf: /code-review – fertig.

Skills vs. CLAUDE.md

CLAUDE.md	Skills
Lädt bei jeder Session	Lädt nur bei Aufruf
Globale Regeln	Spezifische Workflows
Kurz halten	Darf detailliert sein
Team-Standard	Können persönlich sein

Faustregel: Was immer gilt → CLAUDE.md. Was nur manchmal relevant ist → Skill.

Den Workflow optimieren

Erst planen, dann coden

Direkt Code generieren lassen? Geht – führt aber oft zu Architektur-Entscheidungen, die du nicht wolltest.

Besser: Plan Mode nutzen.

1. "Erkläre mir, wie du Feature X umsetzen würdest"
2. Plan reviewen, Fragen klären
3. "Okay, implementiere nach diesem Plan"

Das kostet 2 Minuten extra – spart 20 Minuten Refactoring.

Verifikation einbauen

Claude ist gut im „sieht richtig aus”. Aber nicht unfehlbar. Tests und Typechecks gehören in den Workflow:

## Nach jeder Änderung
- `pnpm typecheck` ausführen
- `pnpm test` für betroffene Module
- Bei API-Änderungen: manueller Smoke-Test

Noch besser: Hooks, die das automatisch erzwingen.

# .husky/pre-commit
pnpm typecheck
pnpm test --bail
pnpm format
git add -u

Permissions bewusst setzen

Alle Sicherheitsabfragen abschalten? Verlockend, aber riskant. Ein Tippfehler, und Claude löscht das Build-Verzeichnis.

Permissions werden über .claude/settings.json konfiguriert – nicht in der CLAUDE.md. Dort lassen sich erlaubte Tools und Befehle als Allowlist definieren:

{
  "permissions": {
    "allow": [
      "Read",
      "Write(src/**)",
      "Bash(pnpm test)",
      "Bash(pnpm typecheck)"
    ]
  }
}

Teamweit abstimmen, nicht individuell ausschalten.

Kontext managen

Warum das wichtig ist

Die wichtigste Erkenntnis aus der Anthropic-Dokumentation: „Claude’s context window fills up fast, and performance degrades as it fills.”

Alles, was in den Kontext geht – CLAUDE.md, gelesene Dateien, Befehle, Diskussionen – muss seinen Platz verdienen.

/clear zwischen Tasks

Ein Feature, dann ein Bug, dann eine Frage, dann zurück zum Feature – alles in einer Session? Der Kontext wird zum Rauschen.

/clear zwischen unzusammenhängenden Tasks. Jede Aufgabe verdient frischen Kontext.

/compact für lange Sessions

Bei langen Sessions: /compact komprimiert den Kontext. Optional mit Fokus:

/compact Fokus auf die API-Änderungen

Claude behält das Wichtige, vergisst das Unwichtige.

Subagents für Recherche

Recherche füllt den Kontext schnell. Lösung: Subagents.

Nutze einen Subagent, um das Auth-System zu analysieren.
Berichte die Ergebnisse, ohne meinen Kontext zu füllen.

Der Subagent arbeitet in separatem Kontext und liefert nur die Zusammenfassung.

Nach zwei Korrekturen: neu starten

Claude macht etwas falsch. Du korrigierst. Immer noch falsch. Du korrigierst wieder.

Stop. Nach zwei Korrekturen ist der Kontext das Problem, nicht Claude. /clear, besserer Prompt, neu starten.

Git als Sicherheitsnetz

Immer auf Feature-Branches

Nie direkt auf main arbeiten lassen. Claude kann das selbst managen:

Erstelle einen Branch 'feature/user-auth', implementiere
das Feature, committe mit aussagekräftiger Message.

Checkpoints nutzen

Claude macht etwas kaputt? Nicht manuell reparieren. Esc + Esc oder /rewind öffnet das Checkpoint-Menü:

Nur Konversation zurücksetzen (Code behalten)
Nur Code zurücksetzen (Konversation behalten)
Beides zurücksetzen

Checkpoints persistieren über Sessions hinweg.

Sessions fortsetzen

Am nächsten Tag alles neu erklären? Nicht nötig.

claude --continue      # Letzte Session fortsetzen
claude --resume        # Aus Liste wählen

Mit /rename oauth-migration bekommen Sessions sprechende Namen.

Im Team arbeiten

Eine gemeinsame Basis

Die Team-CLAUDE.md wird wie Code behandelt:

Versioniert im Git
Änderungen per PR
Review durch Kollegen
Regelmäßige Updates (alle 2 Wochen prüfen)

Lokale Overrides erlauben

Persönliche Präferenzen gehören in CLAUDE.local.md:

# CLAUDE.local.md
## Meine Präferenzen
- Ausführlichere Erklärungen
- Immer deutsche Kommentare
- Bevorzugt funktionaler Stil

In .gitignore packen. Team-Standard bleibt verbindlich, persönlicher Stil bleibt möglich.

Learnings einpflegen

Nach jedem größeren PR kurz fragen:

Hat Claude etwas falsch gemacht, das in die Guardrails gehört?
Gibt es ein neues Pattern, das dokumentiert werden sollte?
Ist eine Regel veraltet?

5 Minuten pro Sprint-Review. Die CLAUDE.md wächst mit dem Projekt.

Checkliste

Schnellstart:

Mit /init generiert
Unter 500 Wörter
Im Git committet

Struktur:

Hierarchisch (Root + Unterverzeichnisse)
Externe Docs verlinkt
Guardrails definiert
Skills für Workflows

Qualität:

Persona definiert
Beispiele für richtig/falsch
Regelmäßig optimiert

Workflow:

Plan Mode für Features
Verifikation automatisiert
Permissions abgestuft
Format-Hooks aktiv

Team:

Gemeinsame Basis im Git
Lokale Overrides möglich
Regelmäßige Updates

Auf den Punkt

CLAUDE.md ist kein Dokument zum Ablegen. Es ist ein Steuerungsinstrument. Je besser gepflegt, desto produktiver die Zusammenarbeit mit Claude.

In fünf Schritten:

Starten: /init, kürzen, committen
Strukturieren: Hierarchie, Links, Guardrails
Optimieren: Persona, Beispiele, iterieren
Arbeiten: Plan Mode, Verifikation, Context-Management
Teilen: Git, Reviews, Learnings

Keine Raketenwissenschaft. Aber konsequent umgesetzt macht es den Unterschied zwischen „KI-Tool installiert” und „KI-Tool produktiv”.

Weiterlesen

Wer tiefer einsteigen will – drei Artikel, die das Thema ergänzen:

Prompt Engineering ist tot – Context Engineering lebt Warum das Schreiben “perfekter Prompts” der falsche Ansatz ist. Die Prinzipien aus diesem Artikel – kurz halten, Kontext managen, iterieren – gelten nicht nur für CLAUDE.md, sondern für jede KI-Interaktion.

Von der Frage zur Strategie: KI in Workflows einbauen Der nächste Schritt nach der Config: Wie du KI nicht als Chat-Tool, sondern als System integrierst. Skills, Automatisierung, wiederkehrende Workflows.

KI-Strategie: Von PowerPoint zum Werkstattboden Für alle, die nicht in Tech-Teams arbeiten: Wie KMU und Handwerk das Thema pragmatisch angehen – ohne Buzzword-Bingo, mit klaren Leitplanken.

Quellen

Claude Code Best Practices – Anthropic
Claude Code Tips Repository – Community