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ürlichsprachigen Befehlen bei Entwicklungsaufgaben 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-gestützten Vorschlägen anpassen, optimieren und erweitern.
• Bugfixing: Fehler, fehlende Abhängigkeiten und Performance-Engpässe erkennen und beheben.
• Code-Verständnis: Fragen zur Architektur, Logik und den Abhängigkeiten deines Codes stellen.
• Automatisiertes Testing & Linting: Fehlgeschlagene Tests ausführen und beheben, Linting-Befehle starten und die Codequalität verbessern.
• Git-Integration: In der Git-Historie suchen, Merge-Konflikte lösen, Commits erstellen und Pull Requests mühelos generieren.

Ob Open-Source-Projekt oder Enterprise-Codebasis: Claude Code unterstützt dich mit intelligenter Automatisierung, die sich an deinen Stil und deine Projektanforderungen anpasst. Neuere Updates brachten den Auto Mode (weniger Zustimmungsabfragen), den Plan Mode (Design-first-Workflows) und Routines (geplante Cloud-Agenten, die auf Trigger laufen, ohne dass deine Maschine an ist).

Für wen eignet sich der Einsatz besonders:

• Softwareentwickler: Codequalität und Wartbarkeit verbessern.
• Open-Source-Contributor: Unbekannte Codebasen verstehen und verbessern.
• DevOps Engineers: Code-Reviews und Linting automatisieren.

Claude Code nutzt jetzt standardmäßig Claude Opus 4.7 in 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 das Modell während der Session mit dem Befehl /model wechseln oder die Reasoning-Tiefe über den /effort-Schieberegler anpassen. Mit dem Claude Agents SDK lassen sich auch eigenständige KI-Agenten bauen.

Anthropic hat außerdem Cowork eingeführt – für agentische Unterstützung bei alltäglichen Datei- und Dokumentaufgaben jenseits des Codings. Verfügbar für alle zahlenden Abonnenten (Pro, Max, Team, Enterprise) in der Claude-Desktop-App.

Starten wir mit dem Praxisprojekt.

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 einen Claude-Console-Account mit aktiver Abrechnung.

Installiere Claude Code einfach, indem du je nach Betriebssystem und Terminal einen der folgenden Befehle im Terminal 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 noch möglich, aber veraltet. Bevorzuge den oben beschriebenen nativen Installationsweg. Wenn 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

Bei der Anmeldung wirst du gefragt, ob du Claude Code über ein kostenpflichtiges Abo oder über API-basierte Abrechnung nutzen möchtest.

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

Jetzt ist Claude Code einsatzbereit.

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 liefert Tools wie Authentifizierung, Realtime-Subscriptions, Storage und automatisch generierte APIs.

Klonen wir das Repository und richten die Entwicklungsumgebung ein.

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 folgenden Befehl 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 im Terminal aus:

python3 -m venv env
source env/bin/activate  # Unter Windows: ./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: Beitragsmöglichkeiten identifizieren

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

Das wollen wir mit Claude Code angehen:

• Refactoring für bessere Lesbarkeit, Wartbarkeit und Struktur.
• Sinnvolle Docstrings und Inline-Kommentare hinzufügen, um die Bausteine zu erklären.
• Bugs identifizieren und beheben – anhand von Issues und weiteren potenziellen Fehlern.

Schritt 4: Mit Claude Code experimentieren

Wir befinden uns bereits im supabase-py-Ordner. 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 innerhalb des Supabase-py-Ordners. Legen wir los.

Code refaktorisieren

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

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

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 Modifikationen im Terminal an und liefert eine Zusammenfassung der Anpassungen.

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

• Importe strukturiert: Claude Code hat zusammengehörige Importe in logische Bereiche gruppiert (Auth-Fehler, API-Typen, Function-Fehler), Importe zur Klarheit umbenannt und redundante Aliasse für Konsistenz entfernt.
• Lesbarkeit verbessert: Es wurden Abschnittskommentare für die Importe hinzugefügt und Duplikate in der __all__-Liste entfernt.
• Client-Optionen vereinfacht: Mehrere Zeilen wurden reduziert, indem ähnliche Importe in einer Anweisung gebündelt wurden.

Hier siehst du einen Vergleich von originalem und refaktoriertem Code.

Code dokumentieren

Neben dem Refactoring kann Claude Code Projektdokumentation generieren, aktualisieren und standardisieren. Es erkennt undokumentierte Stellen, erzeugt strukturierte Docstrings oder Kommentare und prüft die Einhaltung deiner Dokumentationsstandards.

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

• Klare Modul-Docstrings, die den Zweck der Datei erläutern.
• Detaillierte Abschnittskommentare zur Kategorisierung der Importe (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: Dokumentiere den Code in client.py mit Kommentaren für besseres Verständnis.

Sobald die Dokumentation steht, kannst du mit folgendem Prompt prüfen, ob sie deinen Projektstandards entspricht:

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

Bugs beheben

Debugging kostet Zeit. Claude Code verkürzt den Zyklus, indem es Fehlermeldungen analysiert, Ursachen identifiziert und Fixes vorschlägt. Ob fehlende Importe, Laufzeitfehler oder Logikprobleme – es verengt den Suchraum und liefert gezielte Korrekturen.

So nutzt du Claude Code zum Debuggen:

1. Problem identifizieren: Teile die Fehlermeldung mit Claude.
2. Fix-Vorschläge holen: Bitte Claude um Lösungsansätze.
3. Fix anwenden und prüfen: Setze die Vorschläge um und kontrolliere, ob das Problem behoben ist.

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

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

Hier siehst du den Vergleich von Originalcode 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.

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

Erweiterte Funktionen von Claude Code

Sobald du mit Refactoring und Debugging vertraut bist, kannst du das Verhalten von Claude Code anpassen. Hooks und Plugins ermöglichen es dir, wiederkehrende Aufgaben zu automatisieren und externe Systeme zu integrieren.

Claude-Code-Hooks

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

Hooks folgen einem Event-Action-Prinzip. Du definierst drei Dinge:

• Event: Wann wird der Hook ausgelöst?

• Matcher: Welche Aktionen sind betroffen?

• Kommando: Was soll ausgeführt werden, wenn der Hook triggert?

Beispiel: Ein Hook läuft nach dem Schreiben einer Python-Datei und startet automatisch black zur Formatierung. Hooks erhalten JSON-Kontext zum Geschehen und können dadurch intelligent nach Dateitypen oder Pfaden entscheiden. Sie können Ausgaben ins Claude-Transkript schreiben oder Fehlermeldungen direkt an Claude senden, um Operationen zu blockieren.

Häufige Anwendungsfälle für Hooks:

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

• Testing: Nach Änderungen Testsuiten ausführen, um Bugs früh zu finden

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

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

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

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

• Compliance: Lizenzheader oder Coding-Standards erzwingen, bevor Änderungen erlaubt werden

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

Claude-Code-Plugins

Plugins erweitern Claude Code um Verbindungen zu externen Tools, Services und APIs. Während Hooks lokale Shell-Befehle automatisieren, integrieren Plugins dein weiteres Ö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 – zu einem Paket, das alles orchestriert.

Ein Plugin kann z. B. 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 aber an externe Dienste und verarbeiten Antworten, um den Workflow von Claude zu steuern.

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

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

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

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

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

• Externe Analyse: SonarQube, CodeClimate oder Snyk für Enterprise-Code-Scanning aufrufen

• Eigene Tools: Proprietäre Unternehmenssysteme und Workflows integrieren

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

Plugins kannst du aus einem Registry installieren oder intern für deine Organisation bauen und dann konfigurieren, auf welche Events sie reagieren. Zusammen bilden Hooks und Plugins eine erweiterbare Plattform, die Claude Code an deine Infrastruktur anpasst.

Weitere Advanced-Features

Claude Code hat 2026 mehrere große Fähigkeiten hinzugewonnen, 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 Berechtigungsstufe, die Claude mit weniger Unterbrechungen arbeiten lässt – praktisch für längere Tasks, bei denen du nicht jeden Schreibvorgang genehmigen willst.
• Routines: Geplante Cloud-Agenten, die über Cron, GitHub-Events (z. B. PR geöffnet) oder Webhooks ausgelöst werden. Deine Maschine muss dazu 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 von deinem Handy oder anderen Geräten aus steuern.

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 Doku hinzugefügt und Importprobleme gelöst.

Claude Code entwickelt sich mit Features wie Plan Mode, Auto Mode und Routines laufend weiter. Probier es in deinen eigenen Projekten aus und schau, wie es in deinen Workflow passt.

Für den nächsten Schritt empfehle ich unser Tutorial zu Best Practices für Claude Code – damit nutzt du das Kontextfenster optimal. Wenn du ein Projekt von Grund auf bauen willst, lies unser Tutorial zu Spec-Driven Development mit Claude Code.