Refactoring 2. Mai 2026 12 min Lesezeit

Claude Code Legacy Code Refactoring: Alte Codebases systematisch modernisieren

Legacy Code ist nicht das Problem — fehlende Strategie ist das Problem. Mit Claude Code lässt sich selbst eine 10-Jahre-alte Codebase strukturiert analysieren, dokumentieren und schrittweise modernisieren, ohne den Betrieb zu gefährden.

Warum Legacy Code so schwer zu refaktorieren ist

Das klassische Legacy-Problem: du siehst Code der "irgendwie funktioniert" aber niemand mehr versteht. Keine Dokumentation, keine Tests, enge Kopplungen überall. Jede Änderung fühlt sich an wie Minen räumen — du weißt nie was als nächstes explodiert.

Claude Code ändert die Gleichung fundamental: es kann tausende Zeilen Code in Minuten analysieren, Abhängigkeiten kartieren, und systematische Refactoring-Pläne erstellen — ohne dass du die ganze Codebase im Kopf behalten musst.

Wichtige Grundregel: Legacy Code niemals "big bang" refaktorieren. Immer inkrementell, immer mit Tests, immer mit Rollback-Plan. Claude Code hilft dir dabei — aber die Strategie muss stimmen.

Phase 1: Verstehen — Bevor du eine Zeile änderst

Phase 1

Codebase-Analyse und Kartierung

Lass Claude Code zuerst verstehen was vorhanden ist — dann entscheidest du was geändert werden soll.

Analysiere diese Codebase und erstelle einen Überblick: 1. Hauptkomponenten: Was macht welches Modul/Verzeichnis? 2. Abhängigkeitsgraph: Welche Module hängen voneinander ab? (Zeige top 5 am stärksten gekoppelte Module) 3. Risiko-Assessment: Wo ist der Code am kritischsten/gefährlichsten zu ändern? 4. Quick Wins: Was könnte man in <2h refaktorieren ohne Risiko? 5. Technische Schulden: Was ist das Schlimmste (objektiv messbar)? Halte dich an Fakten. Keine Meinung ohne Beweis im Code.
Diesen Output als LEGACY_ANALYSIS.md speichern — er ist die Grundlage für alle folgenden Entscheidungen.
Phase 1b

Fehlende Dokumentation generieren

Bevor du refaktorierst, brauchst du Dokumentation die beschreibt was der Code JETZT tut. Nicht was er tun sollte.

Generiere Inline-Dokumentation für alle Public Functions in [Datei]. Regeln: - Beschreibe was die Funktion TATSÄCHLICH tut (nicht was der Name sagt) - Dokumentiere alle Side Effects (was ändert sie außerhalb ihrer Scope?) - Markiere mit // WARNING: wenn du verdächtige Patterns siehst - Keine Verschönerung: wenn der Code schlecht ist, sage es Format: JSDoc/TSDoc Kommentare direkt über jede Function.

Phase 2: Sichern — Tests bevor Änderungen

Phase 2

Charakterisierungs-Tests schreiben

Charakterisierungs-Tests dokumentieren das aktuelle Verhalten — nicht das gewünschte. Sie sind dein Sicherheitsnetz.

Schreibe Charakterisierungs-Tests für [Modul]. Ziel: Nicht testen was der Code tun SOLL, sondern dokumentieren was er TATSÄCHLICH tut. Wenn der Code komisch ist: teste das komische Verhalten. Für jede Public Function: 1. Happy Path Test (normaler Input) 2. Edge Case Tests (null, undefined, leere Arrays, sehr große Zahlen) 3. Error Case Tests (was passiert bei invaliden Inputs?) Framework: Jest (oder was im Projekt vorhanden ist) Kommentar: // CHARAKTERISIERUNGSTEST - dokumentiert IST-Verhalten, nicht SOLL
Wenn diese Tests nach dem Refactoring noch grün sind, hast du das Verhalten korrekt erhalten. Das ist der Wert dieser Tests.

Phase 3: Refaktorieren — Systematisch und sicher

Phase 3a

Totes Holz entfernen

Starte mit dem risikoärmsten Schritt: Code löschen der nie aufgerufen wird.

Identifiziere sicheren Dead Code in [Verzeichnis]. Kriterien für "sicher zu löschen": - Nie importiert/aufgerufen (statische Analyse) - Auskommentiert seit >6 Monaten (git blame) - Feature-Flag der permanent false ist Für jeden Fund: - Datei + Zeile - Beweis dass er nie aufgerufen wird - Risiko-Level: [niedrig/mittel/hoch] Lösche NUR was Risiko-Level "niedrig" hat. Alles andere: in TODO.md für manuelles Review.
Phase 3b

God Objects aufbrechen

Das häufigste Legacy-Problem: eine Klasse/Datei die zu viel macht. Claude Code hilft beim Aufbrechen.

❌ Vorher UserManager.js — 2.400 Zeilen Verantwortlich für: Auth, Profile, Billing, Email, Sessions, Permissions
✅ Nachher UserAuth.js — 280 Zeilen UserProfile.js — 190 Zeilen UserBilling.js — 340 Zeilen UserPermissions.js — 160 Zeilen
Analysiere UserManager.js auf Single Responsibility Violations. Identifiziere: Welche verschiedenen "Verantwortlichkeiten" hat diese Datei? Erstelle einen Splitting-Plan: - Wie würdest du sie aufteilen? (neue Dateinamen) - Welche Funktionen kommen wohin? - Welche Abhängigkeiten entstehen zwischen den neuen Modulen? NOCH NICHT IMPLEMENTIEREN — erst Plan zeigen, ich reviewe.
Phase 3c

Hardcoded Values externalisieren

Finde alle hardcodierten Werte in src/ die in Konfiguration oder Environment Variables gehören. Kategorien: - Credentials/Secrets (KRITISCH — sofort in .env!) - URLs/Endpoints (in config.js) - Timeouts/Limits (in constants.js) - Feature-Flags (in feature-flags.js) - Business-Konstanten (Preise, Schwellwerte — in business-constants.js) Erstelle für jede Kategorie die entsprechende Config-Datei mit den extrahierten Werten. Ersetze im Code durch Import der Konstante.

Risiko-Matrix: Was du wann anfassen solltest

Refactoring-TypRisikoVoraussetzungEmpfehlung
Dead Code entfernenNIEDRIGStatic AnalysisSofort
Kommentare + DocsNIEDRIGKeineSofort
Rename (aussagekräftigere Namen)NIEDRIGIDE RefactoringWoche 1
Hardcoded Values extrahierenMITTELTests vorhandenWoche 2
God Objects aufbrechenMITTELCharakterisierungs-TestsMonat 1
Framework/Library UpdateHOCHVollständige Test-SuiteMonat 2+
Architektur-ÄnderungHOCHStrangler Fig PatternQuartal 2+

Das Strangler Fig Pattern mit Claude Code

Bei tiefgreifenden Architektur-Änderungen ist das Strangler Fig Pattern die sicherste Strategie: Du baust das neue System neben dem alten, leitest Traffic schrittweise um, und strangulierst das alte System bis es komplett ersetzt ist.

Ich möchte [alten Code] schrittweise durch [neue Architektur] ersetzen. Strangler Fig Strategie: 1. Erstelle einen Adapter/Facade der die alte API für den Rest des Systems beibehält 2. Implementiere die neue Logik dahinter 3. Definiere Feature-Flag der steuert welche Implementierung aktiv ist 4. Schreibe Tests für BEIDE Implementierungen (sollen identisch antworten) Starte mit: [spezifische Funktion/Endpoint] Lass den Rest komplett unverändert.

Realistische Erwartungen

Claude Code beschleunigt Legacy-Refactoring erheblich — aber es gibt Grenzen:

  • Business-Logik die nicht im Code steht: Wenn eine Funktion eine Sonderregel implementiert die nur in den Köpfen der Original-Entwickler existiert, kann Claude Code sie nicht wissen
  • Externe Abhängigkeiten: Datenbankschema, externe APIs, deployte Binaries — die muss Claude Code kennen um sie zu berücksichtigen
  • Performance-Charakteristika: Manche Legacy-Code-Muster existieren aus Performance-Gründen die nicht offensichtlich sind

Faustregel: Claude Code kann 60-80% der mechanischen Refactoring-Arbeit übernehmen. Die verbleibenden 20-40% sind Entscheidungen die menschliches Kontext-Wissen brauchen.

Legacy Code Refactoring im Kurs

Im Claude Code Mastery Kurs gibt es ein dediziertes Modul zu Legacy Code — inklusive CLAUDE.md-Templates für alle 3 Phasen und einem Live-Beispiel mit echter Legacy-Codebase.

14 Tage kostenlos testen →