Claude Code einrichten: Setup, CLAUDE.md & die wichtigsten Best Practices

Was ist Claude Code?

Claude Code ist Anthropics CLI-Tool für Entwickler. Es läuft direkt im Terminal, hat Zugriff auf dein Dateisystem, kann Code lesen und schreiben, Git-Befehle ausführen und mit externen Tools über MCP-Server kommunizieren. Im Gegensatz zu einem einfachen Chat-Interface arbeitet Claude Code agentenbasiert — es plant, führt aus und verifiziert eigenständig.

Das macht es extrem leistungsfähig, aber auch konfigurationsabhängig. Ohne klare Projektregeln produziert es generischen Code. Mit dem richtigen Setup wird es zum Teamkollegen, der deine Konventionen kennt.

Installation und erster Start

Der empfohlene Weg ist der native Installer für macOS, Linux und WSL. Er bringt sein eigenes Update-System mit und aktualisiert sich selbst:

curl -fsSL https://claude.ai/install.sh | bash

Alternativ über Homebrew. Wichtig: Homebrew-Installationen aktualisieren sich nicht automatisch — du musst manuell nachziehen:

brew install --cask claude-code
brew upgrade claude-code

Es gibt auch eine npm-Variante (npm install -g @anthropic-ai/claude-code, benötigt Node.js 22 oder neuer). Sie funktioniert, wird aber gegenüber dem nativen Installer nicht mehr empfohlen und muss ebenfalls manuell aktualisiert werden.

Danach startest du Claude Code mit claude im Terminal — idealerweise im Root-Verzeichnis deines Projekts. Beim ersten Start verbindest du deinen Anthropic-Account. Claude Code erkennt automatisch, ob es sich in einem Git-Repository befindet, und nutzt diese Information für Kontext.

CLAUDE.md — das Herzstück der Konfiguration

Die CLAUDE.md ist die wichtigste Datei für Claude Code. Sie liegt im Root deines Projekts und definiert die Spielregeln: Welchen Tech-Stack du nutzt, welche Konventionen gelten, wie Commits aussehen sollen und was Claude Code niemals tun darf.

Claude Code liest diese Datei bei jeder Konversation automatisch ein. Das bedeutet: Was hier steht, gilt immer — ohne dass du es jedes Mal wiederholen musst.

Eine gute CLAUDE.md enthält mindestens:

• Tech-Stack: Framework, Sprache, Styling-Lösung, Deployment-Plattform
• Code-Konventionen: Commit-Präfixe, Namenskonventionen, Dateistruktur
• Verbote: Was Claude Code nicht tun soll (z. B. keine neuen Dependencies ohne Rücksprache)
• SEO-Regeln: URL-Struktur, Metadata-Anforderungen, Sitemap-Pflege
• Sicherheitsregeln: Wo Secrets liegen, welche Header Pflicht sind

Je spezifischer die CLAUDE.md, desto besser die Ergebnisse. Generische Regeln wie „Schreibe guten Code" bringen nichts. Konkrete Anweisungen wie „Verwende border-3 border-foreground für alle Rahmen" schon.

Die Ebenen der CLAUDE.md

Claude Code unterstützt mehrere Ebenen von Instruktionen, die zusammen geladen werden:

• Global (~/.claude/CLAUDE.md): Gilt für alle Projekte. Hier gehören übergreifende Regeln hin — z. B. Sprache, Sicherheitsstandards, Testing-Pflichten.
• Projektspezifisch (./CLAUDE.md oder ./.claude/CLAUDE.md): Gilt nur für dieses Projekt und wird ins Repository eingecheckt. Tech-Stack, Design-System, Datenstrukturen, Navigation.
• Persönlich & lokal (./CLAUDE.local.md): Deine privaten Notizen zum Projekt, per .gitignore ausgeschlossen — landen nicht im Team-Repo.
• Verwaltet/Enterprise: Organisationsweite Vorgaben, die die IT zentral ausrollt (z. B. /etc/claude-code/CLAUDE.md unter Linux). Für Teams mit verbindlichen Richtlinien.

Die projektspezifische CLAUDE.md überschreibt die globale nicht — beide werden zusammen geladen. Achte darauf, dass sie sich nicht widersprechen.

Kontextsparen mit .claude/rules/

Wenn die CLAUDE.md zu lang wird, lagerst du themenspezifische Regeln in das Verzeichnis .claude/rules/ aus. Jede Regel-Datei kann über ein YAML-Frontmatter an bestimmte Dateipfade gebunden werden und wird nur dann in den Kontext geladen, wenn Claude Code tatsächlich mit passenden Dateien arbeitet. So bleibt die CLAUDE.md schlank, und spezielle Vorgaben (z. B. für Migrations, Tests oder eine bestimmte App) tauchen genau dann auf, wenn sie gebraucht werden.

Skills: Wiederverwendbare Fähigkeiten

Skills sind Markdown-Dateien mit Frontmatter, die Claude Code spezielle Fähigkeiten geben. Sie liegen unter ~/.claude/skills/ (global) oder .claude/skills/ (projektspezifisch).

Ein Skill wird automatisch verfügbar, wenn die Datei SKILL.md im entsprechenden Ordner liegt. Beispiele für nützliche Skills:

• Code Review: Prüft geänderten Code auf Qualität, Sicherheit und Konventionen
• SEO Check: Prüft Metadata, JSON-LD, Sitemap und Bildoptimierung
• Security Audit: Scannt nach OWASP-Top-10-Schwachstellen
• Deployment Checklist: Pre-Deploy-Prüfung für Vercel/Next.js

Der Vorteil gegenüber einfachen Prompts: Skills sind persistent und können von anderen Teammitgliedern genutzt werden. Einmal erstellt, immer verfügbar.

Commands: Slash-Befehle für wiederkehrende Aufgaben

Commands sind Markdown-Dateien unter .claude/commands/, die als Slash-Befehle verfügbar werden. Eine Datei unter .claude/commands/deploy.md und ein Skill unter .claude/skills/deploy/SKILL.md erzeugen beide den Befehl /deploy und verhalten sich identisch — es sind zwei Wege zum selben Ergebnis, nicht ein zusammengeführter. Bestehende Commands bleiben voll kompatibel. Für neue Workflows lohnt sich der Skill-Weg, weil Skills zusätzliche Möglichkeiten bieten: ein eigenes Verzeichnis für Hilfsdateien und Frontmatter zur Steuerung, wann der Skill greift.

Zwei besonders nützliche Commands für jedes Projekt:

• /deploy — TypeScript prüfen, Lint laufen lassen, Build ausführen, committen und pushen
• /check — Qualitätsprüfung: TypeScript, ESLint, Build, SEO-Metadata, Security Headers, Sitemap

Commands sparen nicht nur Zeit — sie sorgen auch dafür, dass vor jedem Deploy die gleichen Prüfungen laufen. Kein „Hab ich vergessen" mehr.

Settings: Berechtigungen steuern

Die .claude/settings.json steuert, welche Aktionen Claude Code ohne Nachfrage ausführen darf. Standardmäßig fragt Claude Code bei jedem Shell-Befehl nach Erlaubnis.

Für ein typisches Next.js-Projekt empfiehlt sich:

{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(git push:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ]
  }
}

Das erlaubt alle npm-Scripts und grundlegende Git-Operationen. Destruktive Befehle wie rm -rf oder git reset --hard bleiben bewusst ausgeschlossen — dafür fragt Claude Code weiterhin nach.

Memory: Kontext über Konversationen hinweg

Claude Code hat ein Memory-System, das Informationen zwischen Konversationen speichert — ohne dass du alles wiederholen musst. Es gibt zwei getrennte Mechanismen:

• CLAUDE.md-Dateien: Deine Anweisungen. Von dir manuell gepflegt, ins Repo eingecheckt und bei jeder Session in den Kontext geladen. Hier stehen Projektregeln, Konventionen und Entscheidungen, die dauerhaft gelten sollen.
• Auto-Memory: Claudes eigene Notizen. Claude Code schreibt hier automatisch fest, was es im Arbeitsalltag über dein Projekt lernt — Vorgehensweisen, Korrekturen, wiederkehrende Muster.

Die Auto-Memory ist maschinenlokal und liegt unter ~/.claude/projects/<projekt>/memory/. Eine Index-Datei MEMORY.md wird zu Session-Beginn geladen (die ersten Zeilen bzw. bis zu einer Größengrenze), ergänzt um thematische Notizdateien. Mit dem Befehl /memory siehst du diese Dateien ein und bearbeitest sie — auch die CLAUDE.md lässt sich darüber öffnen.

In der Praxis ergänzen sich beide: Die CLAUDE.md enthält die stabilen Spielregeln, die du vorgibst; das Auto-Memory fängt die Nuancen auf, die Claude Code selbst im Projektverlauf aufschnappt.

MCP-Server: Externe Tools anbinden

MCP (Model Context Protocol) erlaubt es Claude Code, mit externen Diensten zu kommunizieren — z. B. Airtable, Ahrefs, Vercel, Canva oder Browser-Automatisierung. Jeder MCP-Server stellt bestimmte Tools bereit, die Claude Code dann wie native Fähigkeiten nutzen kann.

Am schnellsten fügst du einen Server über die CLI hinzu: claude mcp add (mit --scope steuerst du die Reichweite). Projektbezogene Server, die das ganze Team nutzen soll, gehören in eine .mcp.json im Repo-Root — sie wird eingecheckt und ist damit für alle verfügbar. Nutzerweite oder rein lokale Server landen dagegen in deiner persönlichen ~/.claude.json. Die Einrichtung variiert je nach Server — manche brauchen API-Keys, andere laufen lokal.

Für den Einstieg sind besonders nützlich:

• Vercel MCP: Deployments verwalten, Logs lesen, Preview-URLs erstellen
• Browser MCP: Websites automatisiert testen und Screenshots machen
• Ahrefs MCP: SEO-Daten direkt in den Workflow einbinden

Hooks: Automatisierung an festen Punkten

Hooks sind der Weg, Claude Code deterministisch zu automatisieren. Statt darauf zu hoffen, dass das Modell an eine Regel denkt, hängst du eigene Aktionen an feste Ereignisse im Ablauf — der Hook läuft dann garantiert. Konfiguriert werden sie in der settings.json.

Zu den wichtigsten Ereignissen gehören:

• SessionStart / SessionEnd: beim Start oder Ende einer Session — z. B. Abhängigkeiten installieren oder Aufräumen
• PreToolUse / PostToolUse: vor oder nach einem Tool-Aufruf — z. B. nach jeder Dateiänderung automatisch Prettier oder ESLint laufen lassen
• UserPromptSubmit: wenn du eine Nachricht abschickst — z. B. zusätzlichen Kontext einspeisen

Typischer Anwendungsfall: Nach jedem Edit automatisch formatieren und typprüfen — so bleibt der Code konsistent, ohne dass du es jedes Mal anstoßen musst.

Checkpointing: Sicher experimentieren mit /rewind

Claude Code legt automatisch Checkpoints an, bevor es Änderungen vornimmt. Läuft ein Versuch aus dem Ruder, springst du mit /rewind zu einem früheren Stand zurück — wahlweise nur den Code, nur den Gesprächsverlauf oder beides. Das nimmt größeren, mutigeren Änderungen den Schrecken: Du kannst Claude Code etwas ausprobieren lassen und den Stand jederzeit sauber wiederherstellen, ohne manuell Git-Stashes zu jonglieren.

Output Styles: Wie Claude Code antwortet

Mit Output Styles steuerst du den Antwortstil. Neben dem Standard gibt es eingebaute Stile wie Explanatory (erklärt Entscheidungen mit) und Learning (bezieht dich stärker ein) — ideal, wenn du nebenbei nachvollziehen willst, warum Claude Code etwas so macht. Eigene Stile legst du unter .claude/output-styles/ ab, umgeschaltet wird über /config.

Subagenten und parallele Ausführung

Subagenten sind eigenständige Agenten mit eigenem Systemprompt, eigenem Kontext und ggf. eigenem Modell. Claude Code kann Teilaufgaben an sie delegieren und mehrere parallel laufen lassen — etwa eine breite Codebase-Recherche auf mehrere Agenten aufteilen. Der Vorteil: Der Hauptkontext bleibt schlank, und unabhängige Arbeit läuft gleichzeitig statt nacheinander.

Plugins und Marketplaces

Plugins bündeln Skills, Hooks, MCP-Server und Output Styles zu einem installierbaren Paket. Über einen Marketplace lässt sich ein fertiges Setup per /plugin install einspielen — praktisch, um ein bewährtes Team-Setup oder ein Framework-spezifisches Paket auf einen Schlag in ein neues Projekt zu holen, statt jede Datei einzeln anzulegen.

Empfohlene Projektstruktur

Nach der Einrichtung sollte jedes Projekt diese Struktur haben:

projekt/
├── CLAUDE.md              ← Projektregeln
├── .mcp.json             ← geteilte MCP-Server (optional)
└── .claude/
    ├── settings.json      ← Berechtigungen & Hooks
    ├── commands/
    │   ├── deploy.md      ← /deploy Befehl
    │   └── check.md       ← /check Befehl
    ├── skills/            ← projektspezifische Skills
    └── rules/             ← pfadgebundene Regeln (optional)

Optional dazu: .claude/output-styles/ für eigene Antwortstile. Die Auto-Memory verwaltet Claude Code selbst unter ~/.claude/projects/ — die gehört nicht ins Projekt-Repo.

Die wichtigsten Best Practices

• 1. CLAUDE.md pflegen: Je detaillierter, desto besser. Aktualisiere sie regelmäßig, wenn sich Konventionen ändern — und lagere lange Spezialregeln nach .claude/rules/ aus.
• 2. Skills & Commands für Standards nutzen: Alles, was vor jedem Deploy passieren muss, gehört in einen Skill oder Command — nicht in deinen Kopf.
• 3. Wiederkehrendes per Hook erzwingen: Formatierung, Linting oder Typprüfung nach jeder Änderung gehören in einen Hook statt in eine Bitte ans Modell — so laufen sie garantiert.
• 4. Berechtigungen bewusst setzen: Erlaube nur, was sicher ist. Lieber einmal mehr bestätigen als einmal zu wenig.
• 5. Checkpoints nutzen: Trau dich an größere Änderungen — mit /rewind kommst du jederzeit sauber zum vorherigen Stand zurück.
• 6. Feedback geben: Wenn Claude Code etwas falsch macht, sag es direkt. Es hält die Korrektur in seiner Auto-Memory fest.
• 7. Nicht blind vertrauen: Claude Code ist mächtig, aber nicht unfehlbar. Prüfe Änderungen — besonders bei Sicherheits- und SEO-relevantem Code.