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 natürlichen Sprachbefehlen bei Entwicklungsaufgaben unterstützt. Es integriert sich mit minimalem Setup in deine Entwicklungsumgebung, damit du dich auf das Schreiben und Verbessern von Code konzentrieren kannst.

Hier sind einige zentrale Fähigkeiten von Claude Code:

• Bearbeiten und Refactoring: Modifiziere, optimiere und verbessere deine Codebasis mit KI-gestützten Vorschlägen.
• Bugfixing: Erkenne und behebe Fehler, fehlende Abhängigkeiten und Performance-Engpässe.
• Codeverständnis: Stelle Fragen zur Architektur, Logik und zu Abhängigkeiten deines Codes.
• Automatisiertes Testing & Linting: Führe Tests aus und behebe fehlschlagende Tests, starte Linting-Befehle und verbessere die Codequalität.
• Git-Integration: Durchsuche die Git-Historie, löse Merge-Konflikte, erstelle Commits und generiere Pull Requests mühelos.

Ob Open-Source-Projekt oder Enterprise-Codebasis: Claude Code unterstützt dich mit intelligenter Automatisierung, die sich an deinen Stil und deine Projektanforderungen anpasst. Aktuelle Updates brachten den Auto Mode (weniger Berechtigungsunterbrechungen), den Plan Mode (Design-first-Workflows) und Routines (geplante Cloud-Agents, die per Trigger laufen, ohne dass dein Rechner an sein muss).

Diese Zielgruppen profitieren besonders:

• Softwareentwickler: Höhere Codequalität und bessere Wartbarkeit.
• Open-Source-Contributor: Unbekannte Codebasen schneller verstehen und verbessern.
• DevOps Engineers: Code-Reviews und Linting-Aufgaben automatisieren.

Claude Code nutzt jetzt standardmäßig Claude Opus 4.7 auf Max- und Team-Premium-Plänen. Pro-User starten mit Sonnet 4.6, können aber für anspruchsvolle Aufgaben auf Opus-Modelle wechseln. Du kannst Modelle mit dem Befehl /model während der Sitzung wechseln oder die Reasoning-Tiefe mit dem /effort-Regler anpassen. Außerdem kannst du eigenständige KI-Agents mit dem Claude Agents SDK bauen.

Anthropic hat außerdem Cowork eingeführt, das dich agentenartig bei alltäglichen Aufgaben mit Dateien und Dokumenten jenseits des Codings unterstützt. Es ist für alle zahlenden Pläne (Pro, Max, Team, Enterprise) in der Claude-Desktop-App verfügbar.

Wenn du Claude Code gegen xAI's Terminal-Agent abwägst, testet unser Grok Build vs. Claude Code-Vergleich beide am selben Task.

Legen wir mit unserem Praxisprojekt los.

Schritt 1: Claude Code einrichten

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

Installiere Claude Code, indem du je nach Betriebssystem und Terminal einen der folgenden Befehle ausführst.

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 über npm install -g @anthropic-ai/claude-code ist weiterhin möglich, aber veraltet. Bevorzuge daher die oben genannte native Installation. Wenn du zuvor via npm installiert hast, kannst du mit claude install migrieren.

Nach der Installation wechsle in dein Projektverzeichnis und starte Claude mit:

cd your-project-directory
claude

Zur Authentifizierung wirst du gefragt, ob du Claude Code über ein kostenpflichtiges Abo oder über API-Abrechnung nutzen möchtest.

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

Jetzt ist Claude Code einsatzbereit.

Schritt 2: Entwicklungsumgebung aufsetzen

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

Beginnen wir mit dem Klonen des Repositories und dem Einrichten der Entwicklungsumgebung.

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

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

2. Erstelle anschließend eine virtuelle Umgebung und installiere die benötigten Abhängigkeiten mit folgenden Befehlen (nacheinander ausführen):

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

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

Schritt 3: Bereiche für Beiträge identifizieren

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

Das werden wir mit Claude Code tun:

• Den Code refaktorisieren, um Lesbarkeit, Wartbarkeit und Struktur zu verbessern.
• Aussagekräftige Docstrings und Inline-Kommentare hinzufügen, um den Zweck der Komponenten zu klären.
• Bugs identifizieren und beheben, indem wir Issues und potenzielle Fehler analysieren.

Schritt 4: Mit Claude Code experimentieren

Da wir bereits im supabase-py-Ordner sind, wechsle in das supabase-Verzeichnis mit der Datei client.py und starte Claude Code:

cd supabase
claude

Claude Code hat nun Zugriff auf alle Dateien und Ordner im Supabase-py-Ordner. Lass uns experimentieren.

Code refaktorisieren

Als Teil der Verbesserung des Supabase Python SDK refaktorisieren wir die Datei client.py, um Lesbarkeit, Wartbarkeit und Struktur zu erhöhen. Gib dafür einfach folgende Aufforderung in der Kommandozeile ein:

Prompt: Refactor the code in the client.py file located in the Supabase folder.

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

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

• Imports organisiert:  Claude Code hat verwandte Imports in logische Abschnitte (Auth-Fehler, API-Typen, Funktionsfehler) gruppiert, Imports für Klarheit umbenannt und redundante Aliase entfernt.
• Lesbarkeit erhöht: Es wurden Abschnittskommentare hinzugefügt und Duplikate in der __all__-Liste entfernt.
• Client-Optionen vereinfacht: Ähnliche Imports wurden in einer einzigen Anweisung zusammengefasst, um mehrere Zeilen zu sparen.

Hier siehst du den Vergleich von Original und Refactoring im Side-by-Side.

Code dokumentieren

Neben Refactoring kann Claude Code Projektdokumentation erzeugen, aktualisieren und standardisieren. Es erkennt undokumentierte Abschnitte, generiert strukturierte Docstrings oder Kommentare und prüft die Einhaltung deiner Dokumentationsstandards.

Wir haben Claude Code eingesetzt, um die Dokumentation in client.py zu verbessern. Ergebnis:

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

Hier siehst du den Vergleich von refaktoriertem und dokumentiertem Code.

Prompt: Document the client.py code by adding comments to improve understanding.

Sobald die Dokumentation ergänzt ist, kannst du ihre Konformität mit deinen Projektstandards prüfen, indem du Claude folgendermaßen aufforderst:

Prompt: Check if the documentation follows our project standards.

Bugs fixen

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

So nutzt du Claude Code fürs Debugging:

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

Claude Code hat folgende Maßnahmen ergriffen, um Import-bezogene Probleme in client.py zu lösen: 

• Type-Ignore-Kommentare: # type: ignore hinzugefügt, um IDE- und Typprüfungs-Warnungen bei nicht auflösbaren Imports zu unterdrücken.
• Konsistente Fehlerkategorisierung: Fehler-Imports aus Authentifizierung, Datenbank, Storage und Functions wurden klar gruppiert.
• Lesbarkeit erhalten: Kommentare erklären, warum bestimmte Imports ignoriert statt entfernt wurden.

Hier siehst du den Vergleich von Original und Fix.

Prompt: I see some bugs, such as 'Import gotrue.errors' could not be resolved. Help me fix all errors in client.py.

Claude Code Befehle

Hier sind einige Befehle, die du mit Claude ausprobieren kannst.

Für mehr Tiefe empfehle ich unseren Guide zu Claude-Code-Slash-Befehlen.

Erweiterte Claude-Code-Features

Sobald du mit Refactoring und Debugging sicher bist, kannst du Claude Code durch individuelles Verhalten erweitern. Hooks und Plugins ermöglichen dir, repetitive Aufgaben zu automatisieren und externe Systeme zu integrieren.

Claude-Code-Hooks

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

Hooks folgen einem Event-Action-System, in dem du drei Dinge definierst:

• Event: Wann wird der Hook ausgelöst?

• Matcher: Welche Aktionen sind betroffen?

• Command: Was wird beim Auslösen ausgeführt?

Beispielsweise kann ein Hook nach dem Schreiben einer Python-Datei triggern und automatisch black zur Formatierung ausführen. Hooks erhalten JSON-Kontext zu den Vorgängen, wodurch intelligente Entscheidungen anhand von Dateitypen oder Pfaden möglich sind. Sie können in Claude's Transkript ausgeben oder Fehlermeldungen direkt an Claude senden, um Aktionen zu blockieren.

Häufige Einsatzszenarien für Hooks:

• Codeformatierung: Nach dem Schreiben automatisch Linter und Formatter ausführen

• Testing: Testsuiten nach Änderungen ausführen, um Bugs früh zu fangen

• Security: Änderungen an sensiblen Dateien wie Produktions-Configs oder API-Keys blockieren

• Dokumentation: API-Dokumentation erzeugen, wenn sich Quellfiles ändern

• Git-Automation: Smart Commits erstellen und Branch-Protection-Policies prüfen

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

• Compliance: License-Header oder Coding-Standards vor Änderungen durchsetzen

Richte Hooks mit dem /hooks-Befehl in Claude Code ein oder bearbeite ~/.claude/settings.json direkt.

Claude-Code-Plugins

Plugins sind Erweiterungen, die Claude Code mit externen Tools, Services und APIs verbinden. Während Hooks lokale Shell-Befehle automatisieren, integrieren Plugins dein weiteres Entwicklungsökosystem wie 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 – in einem Paket, das sie orchestriert.

Ein Plugin kann Codeänderungen analysieren und automatisch Issues in Jira anlegen oder sich mit deiner internen Testinfrastruktur verbinden. Plugins reagieren auf dieselben Events wie Hooks, senden Daten jedoch an externe Services und verarbeiten Antworten, um Claudes Workflow zu steuern.

Dafür eignen sich Claude-Code-Plugins besonders:

• CI/CD-Integration: Builds, Tests und Deployments bei Änderungen auslösen

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

• Teamkommunikation: Updates an Slack oder Teams posten, wenn Änderungen auftreten

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

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

• Custom-Tools: Proprietäre Unternehmenssysteme und -workflows integrieren

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

Installiere Plugins aus einem Registry oder baue 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 deine bestehende Infrastruktur anpasst.

Weitere Advanced-Features

Claude Code hat 2026 mehrere große Neuerungen erhalten, die den Einsatzbereich erweitern:

• Plan Mode: Ein Design-first-Workflow, bei dem Claude vor dem Schreiben einen detaillierten Implementierungsplan erstellt. Ich nutze das für alle nicht-trivialen Tasks.
• Auto Mode: Ein Berechtigungs-Classifier, der Claude mit weniger Unterbrechungen arbeiten lässt – ideal für längere Tasks, bei denen du nicht jeden Schreibvorgang freigeben willst.
• 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 steuern.

Fazit

In diesem Tutorial habe ich Claude Code genutzt, um eine Datei im Supabase Python SDK zu refaktorisieren, zu dokumentieren und zu debuggen. Wir haben die Lesbarkeit verbessert, strukturierte Doku ergänzt und Import-Probleme gelöst.

Claude Code entwickelt sich mit Features wie Plan Mode, Auto Mode und Routines laufend weiter – probiere es in deinen Projekten aus und finde heraus, wie es in deinen Workflow passt.

Für den nächsten Schritt empfehle ich 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.