Erste Erfahrungen mit einer explorativen, nicht spezifikationsgetriebenen Vaadin–Angular-Migration mit Claude Code Opus

Dieser Blogpost ist der erste Teil einer dreiteiligen Serie. In dieser Folge teile ich meine ersten Erfahrungen mit der technischen Modernisierung eines Vaadin-Frontends zu Angular, wobei ich noch keine Spec-driven Development verwende.

In mehreren Kundenprojekten sehen wir aktuell einen wachsenden Bedarf, bestehende Frontends zu modernisieren – nicht nur bei Vaadin-Anwendungen, sondern auch bei anderen, teilweise stark gewachsenen oder legacybehafteten Systemen. Frameworks wie Angular bieten hier mehr Flexibilität, eine klare Trennung von Frontend und Backend sowie eine gute Integration in etablierte Web-Ökosysteme.

Für Kunden bedeutet das vor allem Zukunftssicherheit, leichtere Wartbarkeit und eine effizientere Weiterentwicklung ihrer Anwendungen. Gleichzeitig kann eine gezielt unterstützte Migration die Umsetzung deutlich effizienter machen, Entwicklungsaufwände reduzieren und damit Kosten senken, ohne dabei Abstriche bei der Qualität der Lösung in Kauf nehmen zu müssen. Vor diesem Hintergrund stellt sich weniger die Frage, ob solche Migrationen sinnvoll sind, sondern vielmehr, wie sie effizient und kontrolliert umgesetzt werden können.

Ziel dieses Artikels ist es, aufzuzeigen, wie ein modernes Sprachmodell – in diesem Fall Claude Code Opus 4.5 – eine Frontend-Migration von Vaadin zu Angular auf Basis einfacher Prompts unterstützen kann, wo sich dadurch Zeit sparen lässt und was Claude Code „out-of-the-box“ zu bieten hat. Die folgenden Blogposts bauen auf diesen ersten Erfahrungen auf und stellen einen klar strukturierten, spezifikationsgetriebenen Ansatz vor, der den Einsatz des Sprachmodells weiter präzisiert und die Migration noch effizienter und kontrollierter macht.

Der im folgenden beschriebene erste Ansatz zur Migration war bewusst einfach gehalten. Wir wollten untersuchen, wie Claude Code mit einer Anwendung geringer Komplexität umgeht, wenn er den kompletten Quellcode auf einmal erhält – ohne zusätzliche Spezifikationen – und die Migration selbstständig durchführen soll.

Die Anwendung ist eine einfach gehaltene Beispielanwendung auf Basis von Vaadin Flow und Java EE. Es bietet eine klassische CRUD-Funktionalität für einen Buchladen, wobei die Stärke in der klaren Trennung von UI, Backend und Komponenten liegt. Diese Einfachheit macht es besonders überschaubar und gut nachvollziehbar, gleichzeitig aber realistisch genug, um als Referenz für eine Vaadin-zu-Angular-Migration zu dienen. Die Backend-Logik kann weitgehend unverändert weiterverwendet werden, während die Vaadin-Views schrittweise durch Angular-Komponenten ersetzt werden können – ideal für Lernzwecke.

Der in diesem Fall verwendete Prompt war:

Analysiere den aktuellen Frontend-Code und migriere ihn sinnvoll nach Angular
unter Berücksichtigung der neuesten Best Practices. Verwende überprüfbare 
Quellen, recherchiere Vaadin–Angular-Migrationsmuster 
und migriere basierend darauf. Befolge die Clean-Code-Prinzipien. 
Schreibe testbaren Code.

Aus diesem Prompt hat Claude Code die folgenden Anforderungen und Rückfragen abgeleitet:

Hauptanforderungen:
- Analyse des aktuellen Vaadin-Frontends

- Migration zu Angular nach den neuesten Best Practices

- Einhaltung der Clean-Code-Prinzipien

- Testbarer Code

- Überprüfbare Quellen für Vaadin–Angular-Migrationsmuster


Gewählte Optionen (Antworten auf Fragen):
- JWT-Authentifizierung

- Tests werden später hinzugefügt

So ein Vorgehen ist natürlich nicht realistisch. Aus Entwicklersicht würde man eine solche Aufgabe immer in kleinere, klar abgegrenzte Teilaufgaben zerlegen. Dadurch lässt sich der Aufwand deutlich besser einschätzen.

Trotzdem ist das Ergebnis bemerkenswert: Das Modell hat in etwa 30 Minuten die gesamte Migration durchgeführt und dieses über eine REST-API mit der bestehenden Backend-Logik verbunden – ein deutlicher Zeitvorteil im Vergleich zu einer manuellen Umsetzung durch einen Entwickler.

Mehr über die bestehende und die neue Architektur

Die Architektur der bestehenden Anwendung folgt einem modularen Monolith-Prinzip. Das Backend, bestehend aus Services und Domain-Modellen, ist klar von der Benutzeroberfläche getrennt, doch alle Module werden gemeinsam als EAR-Paket bereitgestellt. Die UI wird vollständig mit Vaadin Flow serverseitig umgesetzt, das heißt, die Views, Formulare und Grids existieren als Java-Komponenten und kommunizieren direkt mit den Backend-Services über CDI (Context and Dependency Injection). Zusätzliche Module enthalten Custom Components für wiederverwendbare UI-Elemente und Integrationstests, die die gesamte Funktionalität validieren. Diese Struktur erlaubt einerseits eine saubere Trennung von Logik und Darstellung, andererseits bleibt alles innerhalb eines einheitlichen Monolithen, was Experimente, wie z. B. eine schrittweise Migration zu Angular, erleichtert.

Im Rahmen der Migration zum Angular-Frontend wurde die Architektur erweitert: Die bestehende Backend-Logik bleibt erhalten, wird jedoch über REST-APIs für das neue Angular-Frontend verfügbar gemacht. Während die Vaadin-Version serverseitige UI-Komponenten direkt auf die Services zugreifen ließ, trennt die Angular-Variante nun klar Frontend und Backend als eigenständige Schichten. Das Angular-Frontend kommuniziert asynchron über HTTP mit den REST-Endpunkten des Backends, wodurch die UI vollständig clientseitig gerendert und die Business-Logik unverändert wiederverwendet werden kann. Diese Umstellung demonstriert, wie ein bestehender Monolith schrittweise zu einer SPA-Architektur migriert werden kann, ohne das Backend neu schreiben zu müssen, und erlaubt gleichzeitig die Einführung moderner Frontend-Technologien wie Angular.

Wichtig ist dabei, dass Claude Code nur sehr wenige Informationen bekommen hat. Es hatte Zugriff auf den bestehenden Quellcode und lediglich die Anweisung, die Migration anhand bekannter Vaadin–Angular-Migrationsmuster und aktueller Best Practices umzusetzen. Detaillierte Spezifikationen, UI-Designs oder technische Regeln gab es nicht.

Über die Dokumentation

Abbildung 1 zeigt einen Ausschnitt der generierten Dokumentation. Sie ist in Teilen eher oberflächlich, etwa wenn Schritte nur grob beschrieben wurden, ohne auf Hintergründe oder konkrete Entscheidungen einzugehen.

Abbildung 1:

Gleichzeitig gab es jedoch auch gut verwertbare Abschnitte, zum Beispiel strukturierte Übersichten über den aktuellen Stand oder Zusammenfassungen der bereits umgesetzten Änderungen, die als solide Grundlage für eine weitere Ausarbeitung dienten (siehe Abbildung 2 und 3).

Abbildung 2:

Abbildung 3:

Die von Claude Code zuerst erstellte Dokumentation war für einen schnellen Überblick hilfreich, aber für ein tieferes Verständnis – etwa warum die Migration genau auf diese Weise durchgeführt wurde – fehlten an einigen Stellen Details. Der Vorteil lag dennoch darin, dass eine brauchbare Grundlage vorhanden war, die sich manuell erweitern ließ. Auch hier ergab sich insgesamt eine Zeitersparnis.

Schon in den ersten Schritten war der Nutzen spürbar. Aufgaben rund um Projektstruktur und Vorbereitung wurden selbstständig übernommen. Das sind zwar keine komplexen Tätigkeiten, sie kosten aber gerade zu Beginn einer Migration Zeit und Aufmerksamkeit. Genau hier konnte das Modell gut entlasten.

Während der eigentlichen Migration half Claude Code vor allem dabei, schnell sinnvolle Richtungen (zum Beispiel: Quellenrecherche und Best Practices, Komponenten-Zuordnung, Verifikations-Checkliste .. usw ..) einzuschlagen. Statt jede Entscheidung von Grund auf neu zu treffen, entstanden früh funktionierende Lösungsansätze, die als solide Basis für die schrittweise Umsetzung der Migration und die Integration des Angular-Frontends mit dem bestehenden Backend dienten.

Testaspekt

Ein Aspekt, der in diesem Zusammenhang erwähnt werden sollte, ist der Umgang mit Tests. Ohne eine explizite Aufforderung oder klare Vorgaben legt Claude Code mit unspezifischen Prompts keinen besonderen Fokus auf das Schreiben oder Ausführen automatisierter Tests. Der Schwerpunkt liegt zunächst darauf, eine lauffähige Anwendung zu erzeugen und die Migration funktional umzusetzen.

Das wurde unter anderem beim Build des Backends sichtbar. Für den initialen Start wurde ein Maven-Build mit deaktivierter Testausführung verwendet, wobei Claude Code die Tests automatisch deaktivierte:

`mvn clean install -DskipTests`

Dieser Parameter sorgt dafür, dass vorhandene Tests zwar kompiliert, aber nicht ausgeführt werden. Das deutet darauf hin, dass die grundsätzliche Testbarkeit des Codes berücksichtigt wurde, die tatsächliche Verifikation durch automatisierte Tests in diesem ersten Durchlauf jedoch keine priorisierte Rolle spielte.

Gerade in einem frühen, explorativen Migrationsschritt ist dieses Vorgehen nachvollziehbar. Gleichzeitig zeigt es aber auch deutlich, dass Themen wie Testabdeckung, Teststrategie und kontinuierliche Testausführung explizit eingefordert und klar definiert werden müssen, wenn sie von Beginn an eine zentrale Rolle im Migrationsprozess spielen sollen.

Abbildungen zum Code vor (Vaadin) und nach der Migration (Angular)

Vaadin Flow Login View - Server-side UI in Java

Angular Login Component - Client-side SPA

Vaadin Product Grid - Server-side Data Table with i18n

Angular client-side product grid

Zusammenfassung

Vorteile einer relativ unspezifischen Migration:

• Schnelle erste Ergebnisse: Das Modell kann auf Basis des kompletten Quellcodes sofort funktionierende Lösungen generieren, ohne dass vorher detaillierte Spezifikationen vorliegen.

• Unterstützung bei Projektstruktur und Vorbereitung: Aufgaben wie Komponenten-Zuordnung, Dokumentation der ersten Schritte und grundlegende Projektorganisation werden automatisch übernommen, was Zeit spart.

• Flexibilität für iterative Weiterentwicklung: Frühzeitig erstellte funktionierende Ansätze dienen als solide Basis für schrittweise Migration und spätere Optimierungen, ohne dass das Backend neu geschrieben werden muss.

Nachteile einer relativ unspezifischen Migration:

• Geringer Fokus auf Tests: Automatisierte Tests werden nicht ausgeführt, Teststrategie und Testabdeckung müssen manuell nachgeholt werden.

• Teilweise nicht funktionierende Implementierungen: Einige Features wurden nur rudimentär umgesetzt oder funktionieren nicht vollständig, z. B. die Lokalisierung (i18n).

• Schwer nachvollziehbare Änderungen: Da die Migration in einem einzigen Schritt durchgeführt wurde, ist es schwierig, einzelne Änderungen nachzuvollziehen oder gezielt zu debuggen.

Als Ergebnis des ersten Tests entstand eine funktionierende, wenn auch nicht perfekte Angular-Anwendung, die mit dem bestehenden Backend kommunizieren kann. Auch wenn diese Lösung noch nicht produktionsreif ist, wurde deutlich, dass Claude Code Opus den Weg zum ersten lauffähigen Zustand deutlich verkürzen kann.

Von der explorativen zur strukturierten Migration - Vorschau auf den zweiten Teil der Serie

Zu Beginn möchte ich betonen, dass es für eine Frontend-Migration – in diesem Fall von Vaadin zu Angular – keine einzige „richtige“ Lösung gibt. Die Komplexität des Projekts und die geschäftlichen Anforderungen spielen dabei eine große Rolle.

Die folgende Struktur beschreibt einen Ansatz, der sich für mich als praktikabel erwiesen hat, wenn mit Claude Code gearbeitet wird. In anderen Projekten können jedoch auch andere Vorgehensweisen genauso gut funktionieren.

Gleichzeitig ist wichtig zu erwähnen, dass der erste Migrationsversuch bewusst mit sehr wenig Kontext gestartet wurde. Claude Code fehlten viele Informationen, die man in einem realistischen Projekt normalerweise von Anfang an bereitstellen würde.

Genau hier zeigt sich auch ein bekanntes Grundprinzip bei der Arbeit mit Sprachmodellen: garbage in, garbage out. Je klarer und strukturierter die Eingaben sind, desto besser und verlässlicher ist in der Regel auch das Ergebnis. Die nachfolgende Vorgehensweise baut auf diesen Erfahrungen auf.

Im nächsten Abschnitt beschreibe ich eine Spezifikationsstruktur, mit der Claude Code nicht nur schneller, sondern auch kontrollierter arbeiten kann. Die Idee für diese Struktur entstand für mich aus einer Richtung, die in den letzten Monaten zunehmend an Bedeutung gewinnt: dem sogenannten Context Engineering.

Dabei geht es weniger um einzelne Prompts, sondern darum, einem Sprachmodell über strukturierte Kontexte, Regeln und Artefakte möglichst klar zu vermitteln, wie es arbeiten soll und in welchem Rahmen es Entscheidungen treffen darf.

Auf dieses Konzept wurde ich erstmals durch eine Videoserie meines ehemaligen Lehrers aufmerksam, der die Möglichkeiten von KI-Agenten erklärte. Diese Serie weckte mein Interesse und gab den Anstoß, die Idee für die Spezifikationsstruktur in meinem Projekt auszuprobieren.

Die folgenden Dateien sind daher nicht als starre Vorgaben zu verstehen, sondern als eine Sammlung von Kontextbausteinen, die dem Modell helfen sollen, konsistenter, nachvollziehbarer und kontrollierter zu arbeiten.

UI-Design-Plan: klare visuelle Vorgaben

Ein sinnvoller erster Schritt ist ein eigener ui-design-plan Ordner. Dort können Screenshots, Figma-Designs oder einfache Skizzen abgelegt werden. Diese dienen als visuelle Orientierung und helfen dem Modell, ein UI zu erstellen, das den Erwartungen möglichst nahekommt.

So werden viele Annahmen vermieden. Statt das Aussehen selbst zu „erraten“, bekommt das Modell klare Hinweise. Zusätzlich bleiben UI-Entscheidungen versioniert und später nachvollziehbar.

claude.md: klare Regeln für die KI

Die Datei claude.md kann man sich als eine Art Arbeitsanleitung für die KI vorstellen. Sie wird beim Start von Claude Code automatisch eingelesen, und hier wird zum Beispiel festgelegt, wann die anderen .md Dateien vom Modell eingelesen werden sollen.

Inhalt zum Beispiel:

• in welcher Reihenfolge Dateien gelesen werden
• wie Ergebnisse nach einer Iteration dokumentiert werden
• dass der Projektstand regelmäßig in der State.md aktualisiert wird
• wann Rückfragen erlaubt sind
• welche Technologien und Frameworks verwendet werden dürfen

Klare Regeln machen das Verhalten der KI nachvollziehbarer und besser steuerbar.

Backlog.md: iteratives Vorgehen

Mit einer Backlog.md-Datei lässt sich festlegen, in welchen Schritten die Migration erfolgen soll. Die Aufgaben werden möglichst klein und klar definiert.

Für jede Iteration sollte festgehalten werden:

• was das Ziel ist
• wann sie als abgeschlossen gilt

Das hilft, schrittweise vorzugehen und verhindert zu große, unübersichtliche Sprünge.

Stack.rules.md: technische Leitplanken

In der Stack.rules.md-Datei werden technische Vorgaben gesammelt, zum Beispiel:

• welche CSS-Lösung genutzt werden soll (z. B. Tailwind CSS)
• welche Authentifizierungs- oder Datenbanklösung verwendet wird
• welche Frameworks bevorzugt sind

Diese Leitplanken schränken die „kreative Freiheit“ der KI bewusst ein. Das reduziert späteren Anpassungsaufwand und sorgt für konsistenten Code.

State.md: Kontext festhalten

Die Datei State.md startet leer und wird nach jeder Iteration aktualisiert. Sie enthält eine kurze Zusammenfassung dessen, was bereits umgesetzt wurde, und wo das Projekt aktuell steht.

So bleibt der Kontext erhalten – auch wenn eine Session später neu gestartet wird.

Fazit

Der genaue Inhalt dieser Dateien ist immer projektabhängig und hängt stark von den Anforderungen und Erwartungen ab. Mit einer klaren Struktur und einem schrittweisen Vorgehen kann Claude Opus eine Frontend-Migration jedoch deutlich beschleunigen. Richtig eingesetzt ist es ein hilfreiches Werkzeug, das in komplexen Migrationsprojekten echten Mehrwert liefern kann.

Ein großes Dankeschön an Christopher Flocke, der sich die Zeit genommen hat, meinen Artikel durchzulesen. Mit seinen Anmerkungen und Verbesserungsvorschlägen ist der folgende Blogpost noch ein Stück besser geworden.