Major-Version-Dependency-Upgrades mit Claude planen

1. Die Herausforderung bei Major-Version-Upgrades

Ein Major-Version-Sprung, etwa von Symfony 6 auf Symfony 7 oder von einer PHP-7-kompatiblen Bibliothek auf eine PHP-8-only-Version, bringt fast immer Breaking Changes mit sich, die sich nicht automatisch per Composer oder npm auflösen lassen. Die eigentliche Arbeit liegt selten im reinen Versionswechsel in der composer.json oder package.json, sondern im Aufspüren aller Stellen im eigenen Code, die von einer geänderten Signatur, einer entfernten Methode oder einem veränderten Standardverhalten betroffen sind.

Gerade bei gewachsenen Codebasen mit mehreren hundert Verwendungsstellen einer Bibliothek ist diese Suche manuell aufwendig und fehleranfällig. Claude kann hier als Recherche- und Analysewerkzeug unterstützen, das die Vorarbeit strukturiert, ersetzt aber nicht die abschließende fachliche Entscheidung und das Testen im eigenen Projekt.

2. Breaking Changes aus Changelogs und Migration-Guides extrahieren lassen

Der erste sinnvolle Schritt ist, den offiziellen Changelog oder Upgrade-Guide der Zielversion in den Kontext zu geben und Claude die relevanten Breaking Changes strukturiert extrahieren zu lassen, gegliedert nach betroffener Klasse, Methode oder Konfigurationsoption. Das ist deutlich schneller als das manuelle Durchlesen eines oft mehrere tausend Zeilen langen UPGRADE.md, besonders wenn nur ein Teilbereich der Bibliothek im eigenen Projekt überhaupt genutzt wird.

Wichtig ist, den vollständigen Text des offiziellen Guides als Quelle mitzugeben, statt sich auf das Wissen des Modells über die Bibliothek zu verlassen. Nur so lässt sich sicherstellen, dass die extrahierten Breaking Changes tatsächlich der offiziellen Dokumentation entsprechen und nicht auf veraltetem oder unvollständigem Trainingswissen beruhen.

# Offiziellen Upgrade-Guide als Kontext bereitstellen
curl -s https://raw.githubusercontent.com/symfony/symfony/7.0/UPGRADE-7.0.md \
  -o upgrade-guide.md

claude "Lies upgrade-guide.md und liste alle Breaking Changes auf, \
  die die Klassen Symfony\Component\HttpFoundation\Request und \
  Symfony\Component\Routing\Router betreffen. Gruppiere nach \
  Klasse und gib jeweils die konkrete Codeänderung an."

3. Betroffene Codestellen im eigenen Projekt identifizieren

Mit der Liste der Breaking Changes als Grundlage kann Claude Code das eigene Repository gezielt durchsuchen, um alle Verwendungsstellen der betroffenen Klassen, Methoden oder Konfigurationsschlüssel zu finden. Das geschieht über gezielte Suchanfragen im Code, kombiniert mit dem Verständnis, welche Verwendungsmuster tatsächlich von einer bestimmten Breaking Change betroffen sind und welche nur oberflächlich ähnlich aussehen, aber unproblematisch bleiben.

Dieser Schritt ist deutlich wertvoller als eine reine Textsuche mit grep, weil Claude den Kontext einer Fundstelle versteht: Ein Aufruf einer gleichnamigen, aber aus einer anderen Klasse stammenden Methode wird korrekt als nicht betroffen erkannt, während ein Aufruf mit tatsächlich geänderter Signatur markiert wird. Bei sehr großen Codebasen empfiehlt sich eine Aufteilung nach Modul oder Verzeichnis, um die Analyse in überschaubaren Schritten durchzuführen.

claude "Durchsuche src/app/code nach allen Aufrufen von \
  Request::getContent() mit dem zweiten Parameter true. \
  Diese Signatur wurde in Symfony 7 entfernt. Liste jede \
  Fundstelle mit Datei, Zeile und vorgeschlagener Ersetzung auf."

4. Einen schrittweisen Migrationsplan erstellen lassen

Sobald die betroffenen Codestellen bekannt sind, kann Claude daraus einen konkreten, priorisierten Migrationsplan formulieren, der die Änderungen in sinnvolle, unabhängig testbare Schritte gliedert. Sinnvoll ist eine Reihenfolge, die mit den risikoärmsten, isolierten Änderungen beginnt und sich zu den Stellen mit den meisten Abhängigkeiten vorarbeitet, damit ein Fehlschlag früh erkannt wird und nicht erst am Ende einer großen, monolithischen Migrations-Pull-Request.

Ein guter Migrationsplan enthält für jeden Schritt nicht nur die Codeänderung selbst, sondern auch, welche Tests danach laufen müssen und welches Verhalten sich beobachtbar ändert. Das erleichtert es dem Team, den Fortschritt zu verfolgen und die Migration bei Bedarf zu unterbrechen, ohne den Überblick über bereits erledigte und noch offene Schritte zu verlieren.

claude "Erstelle aus der Liste der 23 Fundstellen einen \
  Migrationsplan in maximal 6 Schritten. Beginne mit \
  isolierten Stellen ohne Abhängigkeiten zu anderen \
  Modulen. Nenne pro Schritt die betroffenen Dateien und \
  die zu erwartenden Testfälle."

5. Praxisbeispiel: Major-Upgrade einer PHP-Bibliothek

Ein realistisches Szenario: Ein Team plant den Wechsel von guzzlehttp/guzzle 6 auf Version 7, weil eine neue Symfony-Version diese als Mindestanforderung vorschreibt. Der offizielle Upgrade-Guide listet unter anderem geänderte Exception-Klassen und ein verändertes Standardverhalten bei Redirects. Claude extrahiert diese Punkte aus dem Guide, durchsucht anschließend das Projekt nach catch-Blöcken, die die alte Exception-Klasse referenzieren, und nach expliziten Redirect-Konfigurationen in HTTP-Client-Aufrufen.

Aus diesen Fundstellen entsteht ein Migrationsplan mit typischerweise drei bis fünf Schritten: zuerst die Exception-Handhabung anpassen, dann die Redirect-Konfiguration explizit setzen statt sich auf das alte Standardverhalten zu verlassen, und zuletzt die Composer-Version anheben, begleitet von einem vollständigen Testlauf. Diese Reihenfolge minimiert das Risiko, dass ein einzelner großer Commit mehrere unabhängige Fehlerquellen gleichzeitig einführt.

6. Grenzen: Claude kennt nicht jede Bibliotheksversion aktuell

Ein zentraler Vorbehalt gilt uneingeschränkt: Das Trainingswissen von Claude hat einen Stichtag, und gerade sehr neue Bibliotheksversionen oder kürzlich veröffentlichte Patch-Releases mit nachträglichen Breaking-Change-Korrekturen sind dem Modell möglicherweise nicht bekannt. Wer sich ausschließlich auf das interne Wissen des Modells verlässt, statt den aktuellen offiziellen Changelog explizit bereitzustellen, riskiert veraltete oder unvollständige Informationen.

Deshalb ist die in diesem Artikel beschriebene Vorgehensweise, den Migration-Guide aktiv als Kontext mitzugeben, kein optionaler Komfortschritt, sondern die Grundvoraussetzung für belastbare Ergebnisse. Ohne diesen aktuellen Kontext arbeitet Claude im schlechtesten Fall mit einem veralteten mentalen Modell einer Bibliotheksversion, das plausibel klingt, aber sachlich falsch sein kann.

7. Warum Verifikation zwingend nötig bleibt

Selbst mit aktuellem Kontext bleibt jede von Claude vorgeschlagene Codeänderung ein Vorschlag, der gegen die tatsächliche Testsuite des Projekts verifiziert werden muss. Gerade bei Verhaltensänderungen, die sich nicht in einem Compile- oder Lint-Fehler äußern, sondern erst zur Laufzeit sichtbar werden, etwa ein verändertes Standardverhalten bei Zeitzonen oder Zeichenkodierung, reicht eine rein statische Analyse nicht aus.

Ein verlässlicher Migrationsprozess kombiniert deshalb die von Claude vorgeschlagenen Änderungen immer mit einem vollständigen Testlauf, idealerweise ergänzt um gezielte manuelle Stichproben an kritischen Stellen wie Zahlungsabwicklung oder Authentifizierung, bei denen ein unentdeckter Fehler besonders teuer würde. Automatisierte Tests allein decken selten jede Verhaltensänderung ab, die ein Major-Upgrade mit sich bringt.

8. Automatisierung versus menschliche Kontrolle im Upgrade-Prozess

Die sinnvolle Aufgabenteilung sieht vor, dass Claude die zeitaufwendige, aber mechanische Recherche- und Suchtätigkeit übernimmt, während die fachliche Bewertung, ob eine vorgeschlagene Änderung im spezifischen Kontext des Projekts korrekt ist, bei einem erfahrenen Entwickler bleibt. Diese Aufteilung nutzt die Stärke des Modells, große Textmengen schnell zu durchsuchen und zu strukturieren, ohne die Verantwortung für die letztendliche Korrektheit an das Modell abzugeben.

Besonders bei sicherheitsrelevanten oder finanziell kritischen Codestellen sollte kein Vorschlag ungeprüft übernommen werden, unabhängig davon, wie plausibel er formuliert ist. Ein Migrationsprozess, der diese Grenze konsequent einhält, profitiert von der Geschwindigkeit der KI-gestützten Recherche, ohne die Kontrolle über kritische Entscheidungen aufzugeben.

9. Ein praktischer Workflow für ein Entwicklerteam

Für den Teameinsatz hat sich ein vierstufiger Ablauf bewährt: Erstens den offiziellen Migration-Guide als Kontext bereitstellen und Breaking Changes extrahieren lassen. Zweitens das Projekt gezielt nach betroffenen Codestellen durchsuchen lassen. Drittens einen priorisierten, in kleine Schritte gegliederten Migrationsplan erstellen lassen. Viertens jeden Schritt einzeln umsetzen, testen und erst danach den nächsten Schritt beginnen, statt die gesamte Migration in einem einzigen, schwer überprüfbaren Commit zu bündeln.

Dieser Ablauf lässt sich gut in bestehende Pull-Request-Konventionen integrieren, indem jeder Migrationsschritt als eigener, klein gehaltener Pull Request eingereicht wird. Das erleichtert nicht nur das Code-Review, sondern auch einen gezielten Rollback einzelner Schritte, falls sich nach der Umsetzung doch ein unerwartetes Problem zeigt.

10. Zusammenfassung

11. FAQ: Dependency-Upgrades planen: Das Wichtigste auf einen Blick