Wie migrieren Sie 2026 alten Code mit Claude Code? Von der isolierten Umgebung bis zur Abnahme

Der Build scheitert schon vor der ersten Änderung, und niemand kann sicher sagen, welche alten Geschäftsregeln noch gelten.

Die schnellste sichere Vorgehensweise: Legen Sie diese Woche eine isolierte Projektkopie an, erfassen Sie Build- und Testergebnisse und lassen Sie Claude Code zunächst erklären statt umschreiben. Ändern Sie danach kleine, einzeln prüfbare Bereiche. Für macOS-spezifische Builds oder Signaturen brauchen Sie eine passende macOS-Umgebung; sonst wählen Sie die Plattform, die Ihr Projekt tatsächlich voraussetzt.

Für wen ist dieser Leitfaden gedacht?
Für Entwicklerinnen und Entwickler, die ein gewachsenes System und seine Abhängigkeiten verstehen müssen.
Für technische Verantwortliche, die Umfang, Freigaben und Rückfallpunkte kontrollieren.
Für Teams, die einen wiederholbaren Ablauf von der Bestandsaufnahme bis zum Regressionstest brauchen.

Zuletzt aktualisiert am 24.09.2026. Geprüft anhand der Claude-Code-Unterlagen zur Installation, der offiziellen Veranstaltungsseite zur Modernisierung von Legacy-Code und des Code-Modernization-Playbooks.

Claude Code für die Migration von Legacy-Code: erst absichern, dann ändern

Eine Vorführung zur Code-Modernisierung zeigt einen möglichen Arbeitsablauf. Sie ist kein Nachweis dafür, dass ein Modell jede Sprache, jedes Repository oder jede verborgene Geschäftsregel automatisch migrieren kann. Die Veranstaltungsseite beschreibt Claude Code im Zusammenhang mit einer Modernisierungsdemo und einem Code-Modernization-Plugin. Verbindliche Details zu Verfügbarkeit und Installation müssen Sie den aktuellen offiziellen Unterlagen entnehmen. (Veranstaltungsseite)

Entscheidend ist deshalb nicht, ob Claude Code Änderungen erzeugen kann, sondern ob Sie vorab und nachher prüfen können, was sich geändert hat. Ein erfolgreicher Build allein belegt nicht, dass die Anwendung ihre bisherige Funktion beibehält. Umgekehrt ist ein fehlender automatisierter Test kein Freibrief: Wenn es keine Tests gibt, müssen Sie ausdrücklich festlegen, welche manuellen Prüfungen die bestehenden Abläufe absichern.

Behandeln Sie die Migration als kontrollierte Folge von Arbeitspaketen. Jedes Paket braucht einen begrenzten Zweck, eine nachvollziehbare Änderung und ein Ergebnis, das eine zuständige Person beurteilen kann. Damit verhindern Sie, dass eine plausible Erklärung des Modells unbemerkt zur neuen fachlichen Wahrheit wird.

Vor dem ersten Prompt: Arbeitskopie, Umfang und Ausgangslage

Was sollte vor der Migration eines alten Projekts bereitliegen?
Sie benötigen eine getrennte Arbeitskopie, eine Liste der betroffenen Komponenten, bekannte Start- und Build-Befehle, verfügbare Tests sowie eine Beschreibung der fachlich kritischen Abläufe. Halten Sie außerdem fest, welche Punkte ungeklärt sind. Wenn Sie diese Informationen nicht haben, starten Sie mit einer Bestandsaufnahme, nicht mit einem umfassenden Änderungsauftrag.

Legen Sie zunächst fest, was zur Migration gehört und was nicht. Ein Paket kann etwa eine klar abgegrenzte Bibliothek, einen Adapter oder eine einzeln prüfbare Schnittstelle betreffen. Schreiben Sie die Grenzen in die Projektaufgabe: Welche Verzeichnisse dürfen verändert werden? Welche Formate, APIs oder Datenbankstrukturen müssen unverändert bleiben? Welche Abhängigkeiten stehen außerhalb des Auftrags?

Arbeiten Sie nicht direkt auf dem Hauptzweig. Eine isolierte Kopie oder ein eigener Branch macht Änderungen prüfbar und erleichtert den Abbruch, wenn eine Annahme falsch war. Wenn Sie mehrere getrennte Arbeitsverzeichnisse benötigen, beschreibt das Git-Handbuch zu git worktree die dafür vorgesehene Funktion. Prüfen Sie dabei Ihre Repository-Konventionen; ein zusätzliches Arbeitsverzeichnis ersetzt weder eine Sicherung noch eine saubere Freigabe.

Erfassen Sie die Ausgangslage, bevor Claude Code Dateien bearbeitet:

[ ] Repository-Version und verwendeten Zweig dokumentieren.
[ ] Projektstart, Build und vorhandene Tests in der Arbeitskopie ausführen.
[ ] Ergebnisse, Fehlermeldungen und benötigte Umgebungsvariablen sichern.
[ ] Kritische Eingaben und erwartete Ausgaben für wichtige Abläufe notieren.
[ ] Bekannte Geschäftsregeln, Datenformate und externe Schnittstellen festhalten.
[ ] Fehlende Tests und ungeklärte fachliche Annahmen ausdrücklich markieren.
[ ] Verantwortliche Person und Rückfallmöglichkeit für das Arbeitspaket benennen.

Ein „grüner“ Ausgangsstatus ist nicht zwingend erreichbar. Ein altes Projekt kann schon vor der Migration fehlerhaft oder nicht mehr vollständig baubar sein. Wichtig ist dann, diese Einschränkung zu protokollieren und zwischen vorhandenen Fehlern und neuen Regressionen unterscheiden zu können. Bewerten Sie nicht nur, ob ein Befehl erfolgreich endet: Entscheidend ist auch, ob die wesentlichen Geschäftsabläufe die erwarteten Ergebnisse liefern.

Achtung: Lassen Sie Claude Code ungeklärte Regeln nicht durch plausibel klingende Annahmen ersetzen. Bitten Sie darum, Unsicherheiten als offene Fragen auszuweisen. Eine fachliche Entscheidung muss von einer zuständigen Person kommen.

Erste Analyse: Claude Code soll erklären, nicht sofort umschreiben

Richten Sie Claude Code nach der offiziellen Installationsdokumentation ein und folgen Sie den dort aktuellen Vorgaben für Installation und Anmeldung. Die verfügbaren Befehle und Optionen können sich ändern. Verwenden Sie deshalb für die konkrete CLI-Bedienung die offizielle CLI-Referenz, statt ältere Shell-Beispiele ungeprüft zu übernehmen.

Beginnen Sie mit einer Bestandsaufnahme in klar abgegrenzten Fragen. Lassen Sie die Verzeichnisstruktur, Einstiegspunkte, Build-Schritte, Abhängigkeiten und Verbindungen zwischen den Komponenten beschreiben. Bitten Sie nicht sofort um einen vollständigen Migrationspatch. Eine Erklärung ist leichter zu überprüfen als eine große Änderung, und Sie können fehlende oder falsche Zusammenhänge früher erkennen.

Geben Sie den Auftrag so, dass Beobachtung und Schlussfolgerung unterscheidbar bleiben. Zum Beispiel: „Fassen Sie die Aufrufkette für diesen Einstiegspunkt zusammen. Belegen Sie Aussagen mit Dateipfaden und Symbolnamen. Markieren Sie, was Sie aus dem Code ableiten und was unklar bleibt. Ändern Sie keine Dateien.“ Das ist eine Arbeitsanweisung, keine Garantie für fehlerfreie Analyse. Prüfen Sie wichtige Aussagen am Repository.

Teilen Sie Ihre Informationen passend zum Projekt auf. Kurzlebige Aufgaben gehören in den jeweiligen Arbeitsauftrag. Wiederkehrende Konventionen, bekannte Build-Hürden und bestätigte Architekturregeln können in einer gepflegten Projektdokumentation festgehalten werden. Die Dokumentation zu Claude-Code-Projektgedächtnis erklärt, wie Projekthinweise organisiert werden. Behandeln Sie solche Hinweise als unterstützende Dokumentation: Sie müssen fachlich geprüft und aktuell gehalten werden, damit veraltete Angaben nicht zur falschen Grundlage werden.

Vor dem ersten Änderungsvorschlag sollte Ihr Team die Analyse gegen den Bestand abgleichen:

Sind die beschriebenen Einstiegspunkte tatsächlich vorhanden?
Stimmen Abhängigkeitsangaben mit Manifesten und Build-Dateien überein?
Sind Datenformate und Schnittstellen belegt oder nur vermutet?
Sind Geschäftsregeln in Code, Tests oder verlässlicher Dokumentation nachweisbar?
Welche Punkte benötigen eine Entscheidung durch Produktverantwortliche oder Fachbereiche?

So schaffen Sie eine prüfbare Karte des Systems. Sie ist besonders wertvoll, wenn Tests fehlen: Eine fachliche Anforderung, die niemand bestätigen kann, darf nicht allein deshalb als korrekt gelten, weil ein Modell eine konsistente Erklärung formuliert.

Kleine Änderungspakete statt umfassender Umschreibung

Kann Claude Code direkt auf dem Hauptzweig alten Code ändern?
Für eine kontrollierte Migration sollten Sie Änderungen zunächst in einer getrennten Arbeitskopie oder auf einem eigenen Zweig vorbereiten und prüfen. Direkte Änderungen am Hauptzweig erschweren den Vergleich mit dem Ausgangszustand und machen es riskanter, eine unvollständige Änderung zurückzunehmen. Eine Ausnahme ergibt sich nur aus Ihrem festgelegten Entwicklungsprozess, nicht aus einer besonderen Sicherheit des Modells.

Zerlegen Sie die Arbeit in Pakete, die sich unabhängig verstehen und bewerten lassen. Eine sinnvolle Einheit ist nicht „modernisiere das gesamte Modul“, sondern beispielsweise „ersetze in diesem Adapter die veraltete Bibliotheksnutzung, ohne das öffentliche Datenformat zu ändern“. Das konkrete Paket hängt vom Projekt ab. Es sollte eng genug sein, dass Sie die betroffenen Dateien und Verhaltensänderungen überblicken.

Lassen Sie Claude Code vor der Umsetzung den geplanten Eingriff und seinen Umfang beschreiben. Fordern Sie nach jeder Änderung eine Zusammenfassung der betroffenen Dateien, der geänderten Annahmen und der durchgeführten Prüfungen. Führen Sie die relevanten Tests selbst in der vorgesehenen Umgebung aus. Wenn das Ergebnis nicht zu Ihrer Aufgabenbeschreibung passt, stoppen Sie und klären Sie den Unterschied, bevor Sie weitere Arbeit darauf aufbauen.

Achten Sie besonders auf Stellen, an denen eine kleine technische Änderung weitreichende Folgen haben kann: öffentliche Schnittstellen, serialisierte Daten, Datenbankmigrationen, Zeitzonen, Rundung, Zeichencodierung und Fehlerbehandlung. Ein geänderter Rückgabewert kann den Build bestehen und dennoch einen nachgelagerten Prozess brechen. Bei Datenformaten sollten Sie alte und neue Beispiele direkt vergleichen und festhalten, ob Abwärtskompatibilität erforderlich ist.

Die Sicherheitsprüfung gehört in denselben Ablauf. Prüfen Sie, welche Projektdateien und Zugangsdaten im Arbeitskontext verfügbar sind, welche Änderungen freigegeben werden und welche Befehle ausgeführt werden dürfen. Die Sicherheitsdokumentation von Claude Code erläutert die entsprechenden Sicherheitsaspekte und Einstellungen. In einem Unternehmen sollten Sie diese Vorgaben mit internen Regeln zu Geheimnissen, Zugriffsrechten und Datenschutz abgleichen. Übergeben Sie keine produktiven Schlüssel oder personenbezogenen Daten, wenn das für die Aufgabe nicht ausdrücklich freigegeben ist.

Entscheidungsübersicht: lokale Umgebung, Cloud oder Mac?

Option	Geeignet, wenn …	Prüfen Sie besonders …	Eher ungeeignet, wenn …
Bestehende lokale Entwicklungsumgebung	Toolchain und Abhängigkeiten des Projekts bereits verfügbar sind	Reproduzierbarkeit, lokale Berechtigungen und Abstand zur Produktivumgebung	Ihr Rechner den Ziel-Build nicht unterstützt oder gemeinsam genutzte Einstellungen die Isolation aufheben
Isolierte virtuelle oder entfernte Umgebung	Das Projekt auf einer klar definierten Plattform gebaut und getestet werden kann	Systembibliotheken, Netzwerkzugriffe, persistente Daten und Geheimnisverwaltung	Hardware- oder Betriebssystemfunktionen fehlen, die der Build voraussetzt
macOS-Entwicklungsumgebung oder gemieteter Mac	Sie macOS-spezifische Builds, Tests oder Signierung ausführen müssen	Verfügbarkeit der erforderlichen Werkzeuge, Umgang mit Zertifikaten, Zugriff und Rückgabe von Daten	Das Projekt keine macOS-Abhängigkeit hat oder physische Schnittstellen erforderlich sind, die nicht verfügbar sind

Die Wahl folgt dem Build-Ziel, nicht dem Einsatz von Claude Code. Ein Java-, Python- oder plattformübergreifendes Projekt benötigt nicht automatisch einen Mac. Prüfen Sie stattdessen die deklarierte Toolchain, Systembibliotheken, Build-Skripte und benötigten Dienste. Erst wenn ein notwendiger Schritt an macOS gebunden ist, wird eine passende Mac-Umgebung zur sachlichen Voraussetzung.

Wann benötigt die Migration alter Software eine macOS-Umgebung?
Dann, wenn Sie macOS-spezifische Projekte bauen oder testen müssen, Apple-Plattformen als Ziel haben oder ein macOS-abhängiges Signierungsverfahren durchführen. Für die Verteilung signierter macOS-Software beschreibt Apple die Anforderungen in der Dokumentation zur Erstellung signierten Codes. Prüfen Sie dort die Anforderungen für Ihren konkreten Verteilungsweg. Eine Mac-Umgebung ist dagegen keine allgemeine Voraussetzung für die Analyse oder Modernisierung von Legacy-Code.

Bei einem gemieteten Mac sollten Sie zusätzlich klären, wer Zugriff auf Quellcode, Build-Artefakte und Zertifikate hat, wie Sitzungen beendet werden und welche Daten nach der Nutzung erhalten bleiben. Berücksichtigen Sie interne Datenschutzvorgaben und die DSGVO. Dauerhafte Geheimnisse gehören nicht in beiläufige Testdateien oder ungeschützte Umgebungsvariablen; richten Sie Zugriffe nach dem kleinsten erforderlichen Berechtigungsumfang aus. Wenn Sie vorab Vertrags- und Nutzungsbedingungen prüfen müssen, finden Sie sie in den Servicebedingungen von Hashvps.

Abnahme: alte Verhaltensweisen gegen neue Ergebnisse prüfen

Wie stellen Sie fest, ob eine KI-Änderung das Verhalten des Altsystems verändert hat?
Vergleichen Sie nicht nur den Quellcode. Führen Sie Tests aus und prüfen Sie wichtige Eingaben, Ausgaben und Geschäftsbedingungen gegen die dokumentierte Ausgangslage. Wenn automatisierte Tests fehlen, vereinbaren Sie vor der Änderung konkrete manuelle Prüfschritte und lassen Sie diese von den fachlich Verantwortlichen bestätigen.

Die Abnahme sollte mehrere Ebenen verbinden. Ein Unit-Test kann eine lokale Funktion absichern, aber keinen vollständigen Ablauf über Schnittstellen und Datenspeicher belegen. Integrationstests prüfen Verbindungen zwischen Komponenten. Regressionstests decken bekannte frühere Fehler und wichtige Anwendungsfälle ab. Manuelle Prüfungen bleiben nötig, wenn eine Regel nicht zuverlässig automatisiert geprüft werden kann.

Nutzen Sie für jedes Paket eine kleine Abnahmeliste:

[ ] Geänderte Dateien und Abweichungen vom Auftrag sind nachvollziehbar.
[ ] Build und relevante Tests wurden in einer passenden Umgebung ausgeführt.
[ ] Kritische Eingaben und Ausgaben stimmen mit den vereinbarten Erwartungen überein.
[ ] Datenformate, Schnittstellen und fachliche Invarianten wurden geprüft.
[ ] Neue und entfernte Abhängigkeiten sind begründet und freigegeben.
[ ] Sicherheitsauswirkungen und Berechtigungen wurden geprüft.
[ ] Nicht abgedeckte Szenarien und offene Fragen sind dokumentiert.
[ ] Verantwortliche Person, Freigabe und Rückfallweg sind festgehalten.

Bei Migrationen mit Datenbank- oder Dateiformatänderungen brauchen Sie außerdem einen expliziten Umgang mit bereits gespeicherten Daten. Prüfen Sie, ob sich ein Schritt wiederholen lässt, ob eine Unterbrechung einen Zwischenzustand hinterlässt und wie Sie auf die vorherige Version zurückgehen. Ein Rückfallplan, der nur „bei Problemen zurückrollen“ sagt, reicht nicht: Er muss die betroffenen Änderungen und die Bedingungen für eine sichere Rückkehr benennen.

Erklären Sie ein Paket erst dann für abgenommen, wenn die Prüfergebnisse und verbleibenden Einschränkungen nachvollziehbar sind. „Der Agent meldet Erfolg“ ist kein Abnahmekriterium. Auch ein bestandener Testlauf gilt nur für die geprüfte Testbasis und Umgebung. Wenn Testdaten, Abdeckung oder Produktionsbedingungen davon abweichen, halten Sie diese Lücke offen, statt sie stillschweigend als erledigt zu behandeln.

Nach dem Go-live: Nachweise sichern und Rückfälle einarbeiten

Dokumentieren Sie, was tatsächlich freigegeben wurde: Änderungen, Testberichte, manuelle Prüfungen, offene Risiken, zuständige Personen und den vereinbarten Rückfallweg. Bewahren Sie diese Nachweise an einem Ort auf, an dem das Team sie später dem jeweiligen Paket zuordnen kann. Das hilft bei der Fehlersuche und verhindert, dass spätere Arbeiten auf eine ungeprüfte Annahme aufbauen.

Beobachten Sie nach der Bereitstellung die für das Projekt relevanten Fehlermeldungen und fachlichen Kennzahlen. Welche Signale geeignet sind, hängt vom System ab. Legen Sie vor dem Start fest, wer eine Abweichung bewertet und wie sie zurück in die Entwicklungsarbeit gelangt. Wird ein neuer Fehler gefunden, ergänzen Sie nach Möglichkeit einen reproduzierbaren Test oder eine dokumentierte manuelle Prüfung, bevor Sie dieselbe Art von Änderung erneut vornehmen.

Übernehmen Sie nicht die gesamte einmalige Unterhaltung mit Claude Code als dauerhaftes Prozesswissen. Extrahieren Sie nur bestätigte Regeln, wiederverwendbare Prüfungen und bekannte Grenzen. Prüfen Sie diese Einträge bei späteren Projektänderungen erneut. So bleibt das Projektgedächtnis eine gepflegte Hilfe und wird nicht zur Ablage unbestätigter Modellvorschläge.

Wenn Sie für einen Teil der Arbeit eine separate Mac-Umgebung brauchen, vergleichen Sie Ihren bisherigen Weg mit einer passenden Mac-Entwicklungsumgebung: Ein ungeeigneter lokaler Rechner kann macOS-Builds blockieren, gemeinsam genutzte Geräte erschweren die Isolation, und ein einmalig eingerichteter Rechner verursacht Pflegeaufwand. Ein Mac ist trotzdem nicht die richtige Wahl, wenn Ihr Projekt keine macOS-spezifischen Schritte benötigt oder dauerhafte lokale Hardware voraussetzt. Prüfen Sie zunächst die Paketdetails von Hashvps und klären Sie, ob die angebotene Umgebung zu Ihren Build- und Sicherheitsanforderungen passt. Für einen zeitlich begrenzten macOS-Test oder eine gezielte Signierungsprüfung kann das Mieten eines Mac den passenden Weg bieten; für dauerhaft hohe Last oder zwingend benötigte physische Schnittstellen ist eine eigene, kontrollierte Maschine oft die bessere Entscheidung.