Claude Code Tutorial: Setup, Refactoring und Debugging in der Praxis

Was ist Claude Code?

Claude Code ist ein Tool, das direkt in deinem Terminal läuft, deine Codebasis versteht und dich mit Sprachbefehlen bei Entwicklungstätigkeiten unterstützt. Es integriert sich mit minimalem Setup in deine Entwicklungsumgebung, sodass du dich auf das Schreiben und Verbessern von Code konzentrieren kannst.

Hier sind einige Kernfunktionen von Claude Code:

• Editieren und Refactoring: Code mit KI-Vorschlägen ändern, optimieren und verbessern.
• Bugfixes: Fehler, fehlende Abhängigkeiten und Performance-Engpässe erkennen und beheben.
• Code-Verständnis: Fragen zur Architektur, Logik und zu Abhängigkeiten deines Codes stellen.
• Automatisiertes Testing & Linting: Fehlgeschlagene Tests ausführen und reparieren, Linting laufen lassen und die Codequalität verbessern.
• Git-Integration: In der Git-Historie suchen, Merge-Konflikte lösen, Commits erstellen und Pull Requests generieren – mühelos.

Ob Open-Source-Projekt oder Enterprise-Codebasis: Claude Code unterstützt dich mit intelligenter Automatisierung, die sich an deinen Stil und deine Anforderungen anpasst. Zu den jüngsten Updates zählen Auto Mode (weniger Freigabeunterbrechungen), Plan Mode (Design-first-Workflows) und Routines (geplante Cloud-Agents, die durch Trigger laufen – ohne dass dein Rechner an sein muss).

Diese Zielgruppen profitieren besonders:

• Softwareentwickler*innen: Codequalität und Wartbarkeit verbessern.
• Open-Source-Beitragende: Unvertraute Codebasen verstehen und verbessern.
• DevOps Engineers: Code-Reviews und Linting-Aufgaben automatisieren.

Claude Code setzt auf Claude Opus 4.7 als Standard auf Max- und Team-Premium-Plänen. Pro-Nutzer starten mit Sonnet 4.6, können aber für anspruchsvolle Aufgaben auf Opus-Modelle wechseln. Du kannst Modelle in der Session via /model wechseln oder die Reasoning-Tiefe mit dem /effort-Slider anpassen. Außerdem kannst du eigenständige KI-Agenten mit dem Claude Agents SDK bauen.

Anthropic hat außerdem Cowork eingeführt – agentische Unterstützung für alltägliche Datei- und Dokumentaufgaben über das Coden hinaus. Verfügbar für alle zahlenden Abos (Pro, Max, Team, Enterprise) in der Claude Desktop-App.

Legen wir mit dem Praxisprojekt los.

Schritt 1: Claude Code einrichten

Zum Start mit Claude Code brauchst du ein Terminal, ein Codeprojekt und entweder ein Claude-Abo (Pro/Max/Teams/Enterprise) oder ein Claude-Console-Konto mit aktiver Abrechnung.

Installiere Claude Code je nach Betriebssystem und Terminal mit einem der folgenden Befehle.

macOS / Linux / WSL: 

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

Windows PowerShell: 

irm https://claude.ai/install.ps1 | iex

Windows CMD:  

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Hinweis: Die Installation via npm install -g @anthropic-ai/claude-code ist weiterhin möglich, aber veraltet. Bevorzuge die native Installation oben. Falls du zuvor über npm installiert hast, kannst du mit claude install migrieren.

Nach der Installation wechselst du in dein Projektverzeichnis und startest Claude mit:

cd your-project-directory
claude

Für die Anmeldung wirst du gefragt, ob du Claude Code über ein kostenpflichtiges Abo oder über API-Nutzungsabrechnung verwenden möchtest.

Anschließend erhältst du einen Login-Link zu einem Bestätigungscode, den du im Terminal mit Claude Code eingibst. Danach ist alles eingerichtet, und ein eigener „Claude Code“-Workspace wird automatisch für Nutzungs- und Kostenkontrolle erstellt.

Jetzt ist Claude Code startklar.

Schritt 2: Entwicklungsumgebung vorbereiten

Für diese Demo nutze ich die Supabase-Python-Bibliothek supabase-py – einen Open-Source-Python-Client für Supabase, ein Backend-as-a-Service auf Basis von PostgreSQL. Supabase bietet u. a. Authentifizierung, Realtime-Subscriptions, Storage und automatisch generierte APIs.

Beginnen wir damit, das Repository zu klonen und die Entwicklungsumgebung einzurichten.

1. Öffne dein Terminal, wechsle in das Verzeichnis, in das du das Supabase-py-Repository klonen willst (z. B. cd Desktop), und führe aus:

git clone https://github.com/supabase/supabase-py.git
cd  supabase-py

2. Erstelle als Nächstes eine virtuelle Umgebung und installiere die benötigten Abhängigkeiten – führe die folgenden Befehle nacheinander aus:

python3 -m venv env
source env/bin/activate  # On Windows, use ./env/Scripts/activate
pip install -e .

Deine Python-Umgebung ist nun mit allen erforderlichen Abhängigkeiten für die Supabase-Bibliothek eingerichtet, und das Repository ist bereit zur Erkundung. 

Schritt 3: Bereiche für Beiträge finden

Ein guter Einstieg ist der Issues-Tab auf GitHub. Im Supabase-Repository habe ich ein Issue in client.py gefunden – rund um Lesbarkeit, Struktur und fehlende aussagekräftige Kommentare.

Das werden wir mit Claude Code umsetzen:

• Refactoring zur Verbesserung von Lesbarkeit, Wartbarkeit und Struktur.
• Aussagekräftige Docstrings und Inline-Kommentare ergänzen, um Zwecke der Komponenten zu klären.
• Bugs identifizieren und beheben – anhand von Issues und potenziellen Fehlerquellen.

Schritt 4: Mit Claude Code experimentieren

Wir sind bereits im supabase-py-Ordner. Wechsle nun in das supabase-Verzeichnis mit der Datei client.py und starte Claude Code:

cd supabase
claude

Claude Code hat jetzt Zugriff auf alle Dateien und Ordner im supabase-py-Verzeichnis. Legen wir los.

Code refaktorieren

Als Teil der Verbesserungen am Supabase Python SDK refaktorieren wir die Datei client.py, um Lesbarkeit, Wartbarkeit und Struktur zu erhöhen. Gib dazu einfach folgenden Prompt in der Kommandozeile ein:

Prompt: Refaktoriere den Code in der Datei client.py im Supabase-Ordner.

Claude fragt vor dem Fortfahren nach Bestätigung. Drücke Enter, um die Änderungen zu genehmigen. Nach Abschluss aktualisiert Claude Code die Datei, zeigt die Änderungen im Terminal und gibt eine Zusammenfassung aus.

Mit Claude Code haben wir folgende Verbesserungen an client.py vorgenommen:

• Importe organisiert:  Claude Code hat thematisch verwandte Importe (Auth-Fehler, API-Typen, Function-Errors) gruppiert, für Klarheit umbenannt und redundante Aliasse entfernt.
• Lesbarkeit erhöht: Es wurden Abschnittskommentare ergänzt und Duplikate in der __all__-Liste entfernt.
• Client-Optionen vereinfacht: Ähnliche Importe wurden zu einer Anweisung zusammengeführt.

Hier siehst du einen Side-by-Side-Vergleich von Original- und Refactoring-Version.

Code dokumentieren

Neben dem Refactoring kann Claude Code Projekt-Dokumentation generieren, aktualisieren und vereinheitlichen. Es erkennt undokumentierte Bereiche, erzeugt strukturierte Docstrings oder Kommentare und prüft die Einhaltung deiner Dokumentationsstandards.

Wir haben mit Claude Code die Dokumentation in client.py verbessert. Ergebnis:

• Klare Modul-Docstrings, die den Zweck der Datei erklären.
• Detaillierte Abschnittskommentare zur Kategorisierung der Importe (Fehlertypen, Client-Implementierungen, Storage-Services).
• Inline-Kommentare zur Beschreibung von Fehlertypen, Client-Funktionen und wichtigen Komponenten.

Hier siehst du einen Side-by-Side-Vergleich von refaktoriertem und dokumentiertem Code.

Prompt: Dokumentiere den Code in client.py mit Kommentaren für besseres Verständnis.

Sobald die Dokumentation ergänzt ist, kannst du ihre Einhaltung eurer Projektstandards mit einem Prompt prüfen:

Prompt: Prüfe, ob die Dokumentation unseren Projektstandards folgt.

Bugs beheben

Debugging kann zeitaufwändig sein, aber Claude Code verkürzt den Zyklus, indem es Fehlermeldungen analysiert, Ursachen identifiziert und Fixes vorschlägt. Ob fehlende Importe, Laufzeitfehler oder Logikprobleme – es grenzt die Suche ein und liefert gezielte Korrekturen.

So nutzt du Claude Code fürs Debugging:

1. Problem benennen:  Teile die Fehlermeldung mit Claude.
2. Fix-Vorschläge einholen: Bitte Claude um mögliche Lösungen.
3. Fix anwenden und prüfen:  Setze die Vorschläge um und prüfe, ob das Problem behoben ist.

Zur Behebung von Import-Problemen in client.py hat Claude Code Folgendes umgesetzt: 

• Type-Ignore-Kommentare: # type: ignore ergänzt, um IDE- und Type-Checking-Warnungen bei nicht auflösbaren Importen zu unterdrücken.
• Konsistente Fehlerkategorien: Fehlerimporte aus Auth, Datenbank, Storage und Functions klar gruppiert.
• Lesbarkeit bewahrt: Kommentare hinzugefügt, warum bestimmte Importe ignoriert wurden, statt sie zu entfernen.

Hier siehst du einen Side-by-Side-Vergleich von Original- und gefixtem Code.

Prompt: Ich sehe Bugs wie „Import gotrue.errors konnte nicht aufgelöst werden“. Hilf mir, alle Fehler in client.py zu beheben.

Claude Code-Befehle

Hier sind ein paar Befehle, die du mit Claude ausprobieren kannst.

Ich empfehle außerdem die offiziellen Anthropic-Tutorials und unseren Leitfaden zu Best Practices mit Claude Code.

Erweiterte Claude-Code-Funktionen

Wenn du mit Refactoring und Debugging vertraut bist, kannst du Claude Code durch Anpassungen weiter ausreizen. Hooks und Plugins erlauben dir, Routineaufgaben zu automatisieren und externe Systeme anzubinden.

Claude Code Hooks

Claude Code Hooks sind automatische Trigger, die Shell-Befehle ausführen, wenn während deiner Claude-Code-Session bestimmte Ereignisse eintreten. Sie automatisieren Aufgaben wie Codeformatierung, Tests und Security-Checks, die Claude sonst überspringen könnte.

Hooks nutzen ein Event-Action-System, bei dem du drei Dinge definierst:

• Event: Wann wird der Hook ausgelöst?

• Matcher: Welche Aktionen sind betroffen?

• Command: Was wird ausgeführt, wenn der Hook triggert?

Beispielsweise kann ein Hook nach dem Schreiben einer Python-Datei black ausführen, um den Code zu formatieren. Hooks erhalten JSON-Kontext über das Ereignis und können so intelligent nach Dateitypen oder Pfaden entscheiden. Sie können in das Claude-Transkript schreiben oder Fehlermeldungen direkt an Claude senden, um Aktionen zu blockieren.

Typische Anwendungsfälle für Hooks:

• Codeformatierung: Linter und Formatter nach Schreibvorgängen automatisch ausführen

• Testing: Test-Suites nach Änderungen ausführen, um Bugs früh zu erkennen

• Sicherheit: Änderungen an sensiblen Dateien wie Produktionsconfigs oder API-Keys blockieren

• Dokumentation: API-Dokumentation automatisch generieren, wenn sich Quelldateien ändern

• Git-Automation: Intelligente Commits erstellen und Branch-Policies validieren

• Benachrichtigungen: Dein Team via Slack informieren, wenn wichtige Dateien geändert werden

• Compliance: Lizenzheader oder Coding-Standards vor Änderungen durchsetzen

Hooks richtest du mit dem /hooks-Befehl in Claude Code ein oder über ~/.claude/settings.json.

Claude Code Plugins

Plugins sind Erweiterungen, die Claude Code mit externen Tools, Services und APIs verbinden. Während Hooks lokale Shell-Kommandos automatisieren, binden Plugins dein größeres Ökosystem ein – etwa CI/CD-Pipelines, Projektmanagement-Tools und Teamkommunikation.

Plugins können mehrere Komponenten bündeln – Subagents (spezialisierte Claude-Assistenten), MCP-Server (standardisierte Tool-Integrationen) und Hooks – und sie gemeinsam orchestrieren.

Ein Plugin könnte Codeänderungen analysieren und automatisch Issues in Jira anlegen oder sich mit eurer internen Testinfrastruktur verbinden. Plugins reagieren auf dieselben Events wie Hooks, senden Daten aber an externe Services und verarbeiten Antworten, um den Workflow von Claude zu steuern.

Diese Aufgaben eignen sich besonders für Claude-Code-Plugins:

• CI/CD-Integration: Builds, Tests und Deployments bei Dateiänderungen anstoßen

• Projektmanagement: Issues in Jira, GitHub oder Linear automatisch erstellen oder aktualisieren

• Teamkommunikation: Updates bei Änderungen in Slack oder Teams posten

• Code Review: Pull Requests automatisch erstellen und Reviews auf GitHub/GitLab steuern

• Externe Analysen: SonarQube, CodeClimate oder Snyk für Enterprise-Code-Scans einbinden

• Custom Tools: Eigene Systeme und Workflows deines Unternehmens integrieren

• IDE-Erweiterungen: Eigene Befehle und Navigationshilfen hinzufügen

Installiere Plugins aus einem Registry oder entwickle sie intern für deine Organisation und konfiguriere, auf welche Events sie reagieren. Zusammen bilden Hooks und Plugins eine erweiterbare Plattform, die Claude Code an eure Infrastruktur anpasst.

Weitere Advanced-Features

Claude Code hat 2026 mehrere große Funktionen ergänzt, die den Einsatzbereich erweitern:

• Plan Mode: Ein Design-first-Workflow, bei dem Claude vor dem Schreiben einen detaillierten Umsetzungsplan erstellt. Ideal für nicht-triviale Aufgaben.
• Auto Mode: Eine Berechtigungslogik, die Claude mit weniger Unterbrechungen arbeiten lässt – praktisch bei längeren Tasks, ohne jede Dateischreibung freizugeben.
• Routines: Geplante Cloud-Agents, die per Cron, GitHub-Event (z. B. PR geöffnet) oder Webhook starten. Dein Rechner muss nicht laufen.
• IDE-Integration: Offizielle Erweiterungen für VS Code, Cursor und JetBrains IDEs – mit Inline-Diffs, Checkpoints und Multi-Session-Support.
• Remote Control und Channels: Claude-Code-Sessions starten und von Handy oder anderen Geräten darauf zugreifen.

Fazit

In diesem Tutorial habe ich mit Claude Code eine Datei im Supabase Python SDK refaktoriert, dokumentiert und debuggt. Wir haben die Lesbarkeit verbessert, strukturierte Dokumentation ergänzt und Import-Probleme gelöst.

Claude Code entwickelt sich mit Features wie Plan Mode, Auto Mode und Routines stetig weiter. Probiere es in deinen Projekten aus und finde heraus, wie es zu deinem Workflow passt.

Für den nächsten Schritt empfehle ich dir unser Tutorial Claude Code Best Practices, das zeigt, wie du das Kontextfenster optimal nutzt. Wenn du ein Projekt von Grund auf aufbauen willst, lies unser Tutorial zu Spec-driven Development mit Claude Code.