Claude Code installieren und einrichten

1. Was ist Claude Code und für wen lohnt sich der Einstieg

Claude Code ist ein agentischer Kommandozeilen-Assistent von Anthropic, der direkt im Terminal arbeitet und im Gegensatz zu klassischen Autocomplete-Tools nicht nur einzelne Codezeilen vorschlägt, sondern eigenständig Dateien liest, Änderungen vornimmt, Shell-Befehle ausführt und mehrstufige Aufgaben plant. Für PHP- und Magento-Entwickler bedeutet das einen fundamentalen Unterschied zur bisherigen IDE-Integration: Statt einzelner Vorschläge im Editor übernimmt Claude Code komplette Arbeitsschritte, etwa das Anlegen eines neuen Moduls mit Interfaces, ViewModels und Layout-XML in einem Durchgang, wenn die Aufgabe klar formuliert ist.

Der Einstieg lohnt sich besonders für Entwickler, die repetitive, aber kontextreiche Aufgaben automatisieren wollen, etwa das Anlegen von Boilerplate-Code nach Projektkonventionen, das Debuggen über mehrere Dateien hinweg oder das Schreiben PHPStan-konformer Klassen mit vollständiger PHPDoc-Dokumentation. Wichtig ist ein realistischer Blick: Claude Code ersetzt kein Codereview, keine Testabdeckung und kein Verständnis der eigenen Architektur. Wer die Installation und Erstkonfiguration sorgfältig angeht, vermeidet spätere Überraschungen bei Berechtigungen, Kosten und Modellwahl, die in den folgenden Abschnitten im Detail behandelt werden.

2. Systemvoraussetzungen: Node.js, npm und Terminal

Claude Code benötigt eine aktuelle Node.js-Installation ab Version 18, da die CLI als npm-Paket ausgeliefert wird und intern auf der Node-Runtime läuft. Auf Entwicklungsmaschinen, die bereits für Hyvä-Themes mit Tailwind CSS und dem zugehörigen Build-Prozess eingerichtet sind, ist diese Voraussetzung in der Regel bereits erfüllt, da bin/npm und bin/node im Docker-Setup ohnehin vorhanden sind. Vor der Installation lohnt sich ein kurzer Check der vorhandenen Versionen, um Kompatibilitätsprobleme von vornherein auszuschließen.

Unterstützt werden macOS, Linux und Windows, wobei unter Windows der Einsatz über WSL (Windows Subsystem for Linux) empfohlen wird, weil die Shell-Integration und Dateisystem-Operationen dort deutlich zuverlässiger funktionieren als in der nativen PowerShell. Ein funktionierendes Terminal mit bash oder zsh ist Voraussetzung, ebenso ein Nutzerkonto ohne root-Rechte für die npm-Installation, da ein global mit sudo installiertes Paket später zu Berechtigungsproblemen bei Updates führen kann. Git sollte ebenfalls installiert sein, da Claude Code viele Operationen über die vorhandene Git-Historie und den Arbeitsbaum ausführt.

3. Installation per npm: Schritt für Schritt

Die Installation erfolgt über npm mit einem einzigen globalen Befehl. Nach Abschluss steht der Befehl claude systemweit im Terminal zur Verfügung, unabhängig vom aktuellen Arbeitsverzeichnis. Ein anschließender Versionscheck bestätigt, dass die Installation erfolgreich war und welche Version aktiv ist, was insbesondere bei späteren Update-Problemen als erster Diagnoseschritt dient.

# Install Claude Code globally via npm
npm install -g @anthropic-ai/claude-code

# Verify the installation and check the active version
claude --version

# If npm's global bin directory is not writable, configure a
# user-owned prefix instead of using sudo
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"

Bei Problemen mit globalen npm-Berechtigungen empfiehlt sich die Konfiguration eines eigenen npm-Präfix-Verzeichnisses im Home-Ordner, statt die Installation mit erhöhten Rechten zu erzwingen. Das vermeidet dauerhaft Berechtigungskonflikte und macht spätere Updates über npm update -g deutlich unkomplizierter. Alternative Installationswege wie ein natives Installationsskript existieren ebenfalls, sind für bereits vorhandene Node-Umgebungen im Magento-Kontext aber meist unnötig, da der npm-Weg sich nahtlos in bestehende Tool-Ketten einfügt.

4. Erste Anmeldung: Account-Login oder API-Key

Beim ersten Start fordert Claude Code eine Authentifizierung an. Zwei Wege stehen zur Auswahl: Anmeldung über ein bestehendes Claude-Konto (Pro- oder Max-Abonnement) per OAuth-Flow im Browser, oder die Verwendung eines Anthropic-API-Keys aus der Developer Console mit nutzungsbasierter Abrechnung. Der Account-Login ist für Einzelentwickler mit planbarem Nutzungsumfang meist die einfachere und günstigere Option, während der API-Key sich für Teams eignet, die Nutzung zentral über die Console abrechnen und pro Projekt oder Kunde trennen wollen.

# Option 1: interactive login via browser (OAuth), tied to a
# Claude Pro or Max subscription
claude login

# Option 2: authenticate with an Anthropic API key instead,
# billed per token usage via the developer console
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"
claude

# Reset the current session and switch authentication method
claude logout

Für Agenturen mit mehreren Kundenprojekten ist die Entscheidung nicht trivial: Ein API-Key erlaubt granulare Kostenkontrolle über separate Keys pro Projekt, erfordert aber eigenes Monitoring der Ausgaben, da die Abrechnung nach Tokenverbrauch erfolgt und bei umfangreichen Refactorings schnell steigen kann. Der Account-Login mit Abonnement bietet planbare Fixkosten, ist aber an eine Nutzungsobergrenze pro Zeitfenster gebunden. Beide Methoden lassen sich mit claude logout jederzeit zurücksetzen, falls ein Wechsel zwischen Konto und API-Key nötig wird.

5. Berechtigungsmodi verstehen und konfigurieren

Der Berechtigungsmodus bestimmt, wie eigenständig Claude Code Datei-Änderungen und Shell-Befehle ausführen darf, bevor eine Bestätigung eingeholt wird. Im Standardmodus fragt die CLI vor jeder Datei-Änderung und jedem Terminal-Befehl einzeln nach, was maximale Kontrolle bietet, aber bei größeren Aufgaben zu ständigen Unterbrechungen führt. Der Modus acceptEdits übernimmt Datei-Änderungen automatisch, fragt aber weiterhin vor potenziell gefährlichen Shell-Befehlen nach. Der Plan-Modus lässt Claude Code zunächst nur lesend agieren und einen Plan erstellen, der explizit bestätigt werden muss, bevor tatsächliche Änderungen erfolgen.

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(bin/magento:*)",
      "Bash(bin/composer:*)",
      "Edit(src/app/code/**)"
    ],
    "deny": [
      "Bash(git push --force:*)",
      "Bash(git reset --hard:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

Für die Arbeit an produktiven Magento-Shops ist von einem vollständigen Bypass-Modus, der alle Bestätigungen überspringt, klar abzuraten, da destruktive Befehle wie git reset --hard oder das Löschen von Konfigurationsdateien ohne Rückfrage ausgeführt würden. Sinnvoller ist eine granulare Konfiguration in settings.json mit expliziten allow- und deny-Listen für bestimmte Befehlsmuster, etwa das Erlauben von bin/magento-Befehlen bei gleichzeitigem Verbot von git push --force. Diese Konfiguration lässt sich projektspezifisch in .claude/settings.json ablegen und greift automatisch bei jedem Start im jeweiligen Repository.

6. Standardmodell wählen: Sonnet, Opus und Haiku

Claude Code unterstützt mehrere Modelle mit unterschiedlichem Verhältnis aus Geschwindigkeit, Kosten und Fähigkeiten. Für alltägliche Magento- und PHP-Aufgaben wie das Schreiben von ViewModels, Plugins oder PHPStan-konformen Klassen reicht in der Regel das Standardmodell aus der Sonnet-Reihe aus, das eine gute Balance zwischen Antwortqualität und Geschwindigkeit bietet. Für komplexe Architekturentscheidungen, etwa die Planung eines neuen Moduls mit mehreren Abhängigkeiten oder die Analyse eines schwer nachvollziehbaren Bugs über viele Dateien hinweg, kann ein Wechsel zum leistungsfähigeren Opus-Modell sinnvoll sein.

{
  "model": "claude-sonnet-5",
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Das Standardmodell lässt sich sowohl temporär über den Befehl /model innerhalb einer laufenden Sitzung wechseln als auch dauerhaft in der Konfigurationsdatei festlegen, sodass jede neue Sitzung automatisch mit dem gewünschten Modell startet. Wichtig für die Budgetplanung: Leistungsfähigere Modelle verbrauchen bei gleicher Aufgabe in der Regel mehr Tokens und damit mehr Kosten oder Nutzungskontingent, weshalb sich eine bewusste Modellwahl je nach Aufgabentyp langfristig auszahlt, statt durchgehend das leistungsstärkste Modell für einfache Aufgaben zu verwenden.

7. CLAUDE.md und Projektkontext einrichten

Eine CLAUDE.md-Datei im Projekt-Root wird von Claude Code automatisch bei jedem Sitzungsstart eingelesen und dient als projektspezifischer Kontext für Coding-Standards, Verzeichnisstruktur, bevorzugte Patterns und Team-Konventionen. Für Magento-Projekte bietet es sich an, dort Vorgaben wie die Nutzung von ViewModels statt Block-Klassen, Constructor Property Promotion, den Pfad zu den Docker-Wrapper-Skripten und PHPStan-Ausnahmen zu dokumentieren, damit jede Sitzung dieselben Grundregeln kennt, ohne sie erneut erklären zu müssen. Der Befehl /init innerhalb einer laufenden Sitzung analysiert ein bestehendes Repository und schlägt automatisch eine erste CLAUDE.md auf Basis der erkannten Struktur vor.

Neben CLAUDE.md lohnt sich früh ein Blick auf .claudeignore, mit dem sich Verzeichnisse wie vendor, node_modules oder generierte Static-Content-Ordner von der Analyse ausschließen lassen, um Kontextfenster und Antwortzeiten nicht unnötig zu belasten. Bei Monorepos oder Projekten mit mehreren Vendor-Varianten, wie dem in diesem Projekt üblichen Dual-Vendor-Workflow zwischen Mironsoft und Abrams, hilft eine klar strukturierte CLAUDE.md dabei, dass Änderungen zuverlässig in beiden Codebasen synchron nachvollzogen werden, statt bei jeder Anfrage erneut manuell darauf hinweisen zu müssen.

8. Setup verifizieren: der erste Task

Nach Installation, Authentifizierung und Grundkonfiguration lohnt sich ein bewusst einfacher erster Test, bevor Claude Code an produktivem Code arbeitet. Ein sinnvoller Einstieg ist eine rein lesende Aufgabe, etwa die Bitte, die Struktur eines bestehenden Moduls zusammenzufassen oder eine einzelne Methode zu erklären. Das prüft, ob Authentifizierung, Modellzugriff und Dateizugriff korrekt funktionieren, ohne dass dabei Änderungen am Code riskiert werden.

Der nächste Schritt ist ein kleiner, klar abgegrenzter Schreibzugriff, etwa das Hinzufügen eines fehlenden PHPDoc-Blocks zu einer einzelnen Methode oder das Beheben eines offensichtlichen Tippfehlers. So lässt sich beobachten, wie der gewählte Berechtigungsmodus in der Praxis reagiert, welche Bestätigungen eingeholt werden und wie der vorgeschlagene Diff aussieht, bevor er übernommen wird. Diese schrittweise Herangehensweise, am besten in einem separaten Git-Branch oder einer Testkopie des Projekts, schafft Vertrauen in das Werkzeug, bevor es an komplexeren, produktionsrelevanten Aufgaben eingesetzt wird.

9. Typische Fehler beim ersten Start

Auch bei sorgfältiger Installation treten beim ersten Start typische Probleme auf, die sich meist schnell eingrenzen lassen. Die häufigste Fehlermeldung command not found: claude deutet fast immer darauf hin, dass das globale npm-Binärverzeichnis nicht im PATH des Terminals eingetragen ist, was besonders nach einer frischen Node-Installation über einen Versionsmanager wie nvm vorkommt. Authentifizierungsfehler entstehen häufig durch abgelaufene OAuth-Tokens nach längerer Inaktivität oder durch einen ungültigen API-Key, der beim Kopieren versehentlich Leerzeichen oder Zeilenumbrüche enthält.

# Check Node.js and npm versions
node --version
npm --version

# Confirm the global npm bin directory is on PATH
npm config get prefix
echo $PATH | tr ':' '\n' | grep npm

# Re-authenticate after a token or API key issue
claude logout
claude login

# Test connectivity to the Anthropic API through a proxy
curl -I https://api.anthropic.com

Ein weiteres verbreitetes Problem in Unternehmensumgebungen ist eine Firewall oder ein Proxy, der Verbindungen zu api.anthropic.com blockiert, was sich meist über Zeitüberschreitungen ohne konkrete Fehlermeldung äußert. Die folgende Übersicht fasst die häufigsten Startprobleme, ihre Ursachen und die jeweils empfohlene Lösung zusammen.

Die Diagnose folgt meist demselben Muster: zuerst Node- und npm-Version prüfen, dann die Umgebungsvariablen für Proxy und API-Key kontrollieren, und erst danach die Anmeldung erneut durchführen. Wer diese Reihenfolge einhält, löst die überwiegende Mehrheit der Erstinstallationsprobleme innerhalb weniger Minuten, ohne die gesamte Installation neu aufsetzen zu müssen.

10. Zusammenfassung

Die Installation und Einrichtung von Claude Code ist technisch unkompliziert, entscheidend sind aber die bewussten Konfigurationsentscheidungen direkt danach. Node.js 18 oder neuer, ein einziger npm-Befehl und ein Versionscheck reichen für die reine Installation aus. Die Wahl zwischen Account-Login und API-Key bestimmt das Abrechnungsmodell, während der Berechtigungsmodus darüber entscheidet, wie viel Kontrolle über Datei-Änderungen und Shell-Befehle beim Nutzer verbleibt. Ein produktionstauglicher Berechtigungsmodus mit expliziten allow- und deny-Listen ist für Magento-Projekte Pflicht, nicht optional.

Eine sauber gepflegte CLAUDE.md-Datei und ein bewusst gewähltes Standardmodell sparen langfristig Zeit und Kosten, weil jede Sitzung mit demselben Projektkontext startet, statt Konventionen wiederholt erklären zu müssen. Ein einfacher erster Test mit einer lesenden und anschließend einer kleinen schreibenden Aufgabe bestätigt, dass Authentifizierung, Modellzugriff und Berechtigungen korrekt zusammenspielen, bevor Claude Code an produktionsrelevantem Code eingesetzt wird. Die häufigsten Startprobleme lassen sich meist innerhalb weniger Minuten über PATH-, Token- und Netzwerkprüfung lösen.

11. FAQ: Claude Code installieren und einrichten