Strukturierte Migration mit Claude Code - Context Engineering statt Prompt Engineering

Garbage in, garbage out

Im ersten Teil dieser Serie haben wir einen bewusst explorativen Ansatz gewählt: Den kompletten Quellcode hochladen, einmal prompten, schauen was passiert. Das Ergebnis war beeindruckend schnell – aber auch inkonsistent: Drei verschiedene State-Management-Ansätze, deaktivierte Tests und eine oberflächliche Dokumentation. Das Problem lag nicht am Modell, sondern an dem, was wir ihm gegeben haben. Garbage in, garbage out [^1] – wer einem Sprachmodell vage Anweisungen und keinen strukturierten Kontext gibt, bekommt ein Ergebnis, das bestenfalls funktional, aber selten konsistent ist. Die Lösung liegt deshalb nicht im besseren Prompt, sondern im besseren Kontext. Genau hier setzt dieser zweite Teil an. [^1]: Vgl. Sheposh, R. (2024): Garbage in, garbage out (GIGO), EBSCO Research Starters. https://www.ebsco.com/research-starters/computer-science/garbage-garbage-out-gigo

Context Engineering vs. Prompt Engineering

Lange galt Prompt Engineering als die zentrale Kompetenz im Umgang mit Sprachmodellen: den einen perfekten Satz formulieren, der die beste Antwort erzeugt. In der Praxis zeigt sich jedoch, dass ein einzelner Prompt bei komplexen Aufgaben wie einer Frontend-Migration schnell an seine Grenzen stößt – egal wie sorgfältig er formuliert ist. Andrej Karpathy und Simon Willison haben diesen Paradigmenwechsel treffend auf den Punkt gebracht: Nicht der einzelne Prompt entscheidet über die Qualität des Ergebnisses, sondern der gesamte Kontext, in dem das Modell arbeitet [^2]. Context Engineering bedeutet, dem Modell über strukturierte Dateien, Regeln und Artefakte einen klar definierten Informationsrahmen zu geben – welche Technologien erlaubt sind, wie der Code aussehen soll, welche Aufgabe als nächstes ansteht. Die Analogie liegt nahe: Nicht die Frage an einen neuen Kollegen ist entscheidend, sondern welche Unterlagen auf seinem Schreibtisch liegen. Bei Migrationsprojekten heißt das konkret: Nicht ein ausgefeilter Prompt steuert die Migration, sondern ein Set aus Spezifikationsdateien, das den Lösungsraum eingrenzt. [^2]: Vgl. Karpathy, A. (2025): Diskussionsbeiträge zu Context Engineering; Willison, S. (2025): „Context Engineering“, simonwillison.net.

Analysephase als Vorbereitung

Die Antwort auf diese Herausforderung liegt in der Strukturierung des Kontextes: Der effektivste Weg, den Lösungsraum für das Sprachmodell einzuschränken und konsistente Ergebnisse zu erzielen, ist die Verwendung sogenannter Spezifikationsdateien (Spec-Files). Bevor wir die Spec-Files erstellen können, müssen wir das Quellsystem in seiner Tiefe verstehen. Wer stack.rules.md befüllen will, muss wissen, welche Technologien im Altsystem stecken. Wer backlog.md mit sinnvollen Aufgaben füllen will, muss die Abhängigkeiten zwischen Komponenten kennen. Welche Bereiche dabei relevant sind, hängt vom konkreten Projekt ab. In unserem Beispiel liefern drei Perspektiven die Basis, um die Spec-Files gezielt zu befüllen.

Quellcode verstehen

Die technische Erschließung der bestehenden Codebasis – strukturiertes Reverse Engineering statt oberflächliches Lesen. Welche Views existieren, welche Services und Backends werden genutzt, wie ist die Datenhaltung aufgebaut? Welche Abhängigkeiten existieren auf Code-Ebene (Import-Graphen, Aufrufketten, Modulkopplung) und auf Applikationsebene (Service-Kommunikation, API-Abhängigkeiten, Datenflüsse)? Das Ziel ist nicht Code-Review, sondern ein vollständiges Bild der Ist-Funktionalität und Ist-Architektur – als Grundlage für stack.rules.md und die Iterationsplanung in backlog.md.

UI erfassen

Die bestehende Benutzeroberfläche wird Schritt für Schritt dokumentiert – Seitenstruktur, Navigation, Formulare und User-Flows – und gleichzeitig das fachliche Vokabular, also Entitäten, Regeln und Besonderheiten, explizit festgehalten. Ergänzend lassen sich mit Tools wie V0 von Vercel UI-Entwürfe generieren, deren exportierte Screenshots in z. B. einem ui-design-plan-Ordner landen und der KI eine klare visuelle Vorgabe geben.

Von der Analyse zu den Spec-Files

Diese Erkenntnisse liefern gemeinsam den Kontext, der in die Spec-Files einfließt. Die Analysephase kann dabei selbst KI-gestützt ablaufen – von der Code-Archäologie bis zur automatischen Transkription von Interviews. Hier geht es um das Ergebnis: Die gewonnenen Erkenntnisse sind die Grundlage, auf der die Spec-Files stehen. Ohne sie wäre Context Engineering nur eine leere Hülle – strukturierte Dateien ohne belastbaren Inhalt.

Die 4 Spec-Files im Detail

claude.md – Das Regelwerk

Das Herzstück der KI-gesteuerten Migration ist die CLAUDE.md – eine Steuerungsdatei, die der KI nicht nur sagt, was sie tun soll, sondern wie sie denken soll. Sie legt fest, in welcher Reihenfolge die Projektdateien gelesen werden, welche davon als verbindlich gelten und wie mit Widersprüchen umzugehen ist. Folgender Passus in der CLAUDE.md gewährleistet das.

1…
2Claude MUSS folgende Quellen als verbindlich betrachten:
3
41. backlog.md – alle Aufgaben, Iterationen und Backlog-Items.
52. state.md – aktueller Projektstand, abgeschlossene Änderungen, offene Fragen, Entscheidungen.
63. stack.rules.md – technische Leitplanken, Frameworks, CSS, Authentifizierung.
74. ui-design-plan – visuelle Vorgaben, Screenshots, Figma-Designs.
8...

Ein oft unterschätzter Aspekt sind sogenannte Semantic Anchors: etablierte Begriffe, die im Projektkontext eine spezifische Bedeutung haben. In der CLAUDE.md dieses Projekts ist etwa „Angular Material v20 (M3)“ explizit festgelegt – ohne diese Präzisierung könnte die KI auf ältere Komponenten zurückgreifen, die optisch und technisch abweichen. Ebenso entscheidend sind explizite Rückfrage-Regeln: Die KI soll nicht eigenständig interpretieren, wenn ein Backlog-Item unklar ist, UI-Vorgaben fehlen oder eine Änderung andere Iterationen beeinflussen könnte. Die CLAUDE.md benennt diese Auslöser konkret – und legt fest, dass Rückfragen gebündelt gestellt werden, nicht einzeln nacheinander.

1…
2Kommunikation & Rückfragen
3
4- Claude **MUSS** Rückfragen stellen, wenn:
5 - Ein Backlog-Item unklar oder mehrdeutig formuliert ist.
6 - UI-Vorgaben in `ui-design-plan/` fehlen oder widersprüchlich sind.
7 - Technische Entscheidungen nötig sind, die nicht in `stack.rules.md` abgedeckt sind.
8 - Eine Änderung potenziell andere Iterationen oder bestehende Funktionalität beeinflusst.
9
10- Claude **DARF NICHT** fehlende Informationen erraten oder stillschweigend Annahmen treffen.
11- Rückfragen werden **gebündelt** gestellt – nicht einzeln nacheinander.
12- Bei Unsicherheiten zur Priorität oder Reihenfolge gilt: `backlog.md` ist maßgeblich.
13…

Nach jeder abgeschlossenen Iteration dokumentiert die KI ihre Änderungen, Entscheidungen und offenen Punkte – strukturiert und nachvollziehbar. So entsteht kein klassisches Protokoll, das niemand liest, sondern eine lebendige Übergabedokumentation, die den nächsten Schritt vorbereitet.

1…
2Dokumentationsregeln (state.md)
3
4- Claude **MUSS** die `state.md` am **Ende jeder Iteration** aktualisieren – niemals mitten in der Implementierung.
5- Die Datei dient als Single Source of Truth für den aktuellen Projektstand.
6…

stack.rules.md  – Technische Leitplanken

Ohne explizite technische Vorgaben trifft die KI bei jeder Iteration neu eigene Entscheidungen – mal RxJS-BehaviorSubject, mal NgRx, mal Signals. Das Ergebnis: inkonsistenter Code. Die stack.rules.md verhindert genau das. Sie arbeitet mit drei Mechanismen: Positive Festlegungen mit maximaler Präzision – statt „verwende Angular“ steht dort „Angular 20, Standalone Components, bootstrapApplication(), kein NgModule“. Explizite Ausschlüsse benennen, was nicht erlaubt ist: „Kein NgRx, kein Akita“ beim State Management, „kein SCSS, kein LESS“ bei den Styles. Und konkrete Code-Beispiele liefern die verbindliche Blaupause – etwa diese Vorgabe für den reaktiven State:

• signal() für reaktiven lokalen und Service-State.
• computed() für abgeleitete Werte (z. B. gefilterte Produktliste).
• effect() nur für Side-Effects (z. B. Logging, LocalStorage-Sync).

Das Resultat: Die KI produziert über alle Iterationen hinweg konsistenten Code – nicht weil sie es „versucht“, sondern weil die Spec ihr keinen anderen Weg lässt.

backlog.md – Iterative Aufgaben

KI-Agenten brauchen keine langen Epics – sie brauchen kleine, vollständig beschriebene Aufgaben, die in einer einzigen Session bearbeitbar sind. Die backlog.md ist genau das: ein sequenzieller Fahrplan aus Iterationen, die streng nacheinander abgearbeitet werden. Keine darf übersprungen oder zusammengefasst werden – das steht explizit in der Datei. Jede Iteration folgt demselben Schema: ein klares Ziel, konkrete Deliverables mit betroffenen Dateien und Klassen, und implizite Akzeptanzkriterien durch z.B. die Angabe erwarteter HTTP-Statuscodes und Verhaltensweisen. Iteration 3 etwa legt nicht nur fest, dass CRUD-Endpunkte für Produkte entstehen sollen – sie benennt exakt, welche Methoden auf welchen Pfaden, welche Rollen berechtigt sind und welche Statuscodes zurückgegeben werden müssen:

• POST /api/products – Neues Produkt erstellen (nur Admin)
• PUT /api/products/{id} – Produkt aktualisieren (nur Admin)
• DELETE /api/products/{id} – Produkt löschen (nur Admin)
• Korrekte HTTP-Statuscodes (201 Created, 204 No Content, 400, 403, 404)

Diese Granularität ist kein Zufall: Je präziser das Backlog-Item, desto weniger Interpretationsspielraum hat die KI –  und desto vorhersehbarer ist das Ergebnis. 

state.md – Sessionübergreifendes Gedächtnis

KI-Agenten haben kein Langzeitgedächtnis. Jede neue Session beginnt bei null – es sei denn, der Kontext wurde explizit gesichert. Genau das leistet die state.md: Sie ist das Projekttagebuch, das nach jeder abgeschlossenen Iteration aktualisiert wird und der KI beim nächsten Start sofort zeigt, wo sie steht. Jeder Iterationseintrag folgt demselben Schema:  Status und Datum geben den zeitlichen Rahmen, umgesetzte Änderungen listen betroffene Dateien mit kurzem Zweck, Entscheidungen dokumentieren das Warum hinter technischen  Weichenstellungen, und offene Punkte bereiten die nächste Iteration vor. So steht dort etwa:

1Iteration 3 – REST-API: Produkte schreiben
2
3**Status:** Abgeschlossen
4 **Datum:** 2026-02-14
5
6  Umgesetzte Änderungen
7  - `ProductResource.java` – POST/PUT/DELETE ergänzt, Admin-Prüfung via @RolesAllowed
8
9Entscheidungen
10  - Bean Validation statt manueller Prüfung – weniger Code, einheitliche Fehlermeldungen
11Offene Punkte
12  - Rate Limiting nicht umgesetzt – kein Backlog-Item, daher zurückgestellt

Kein Prosatext, keine Erklärungen – nur der Fakt und, wo nötig, der Grund. So startet die KI in der nächsten Session nicht bei null, sondern mit dem vollständigen Kontext der vorherigen Iteration.

ui-design-plan – Visuelle Vorgaben statt Ratespiel

Ohne visuelle Vorgaben erfindet die KI das UI-Design selbst – und trifft dabei Entscheidungen, die niemand abgesegnet hat. Farben, Abstände, Komponentenanordnung: Alles folgt dem, was in den Trainingsdaten am häufigsten vorkam, nicht dem, was das Produkt tatsächlich soll. Der ui-design-plan-Ordner löst dieses Problem, indem er der KI eine visuelle Referenz mitgibt: Screenshots der bestehenden Vaadin-Anwendung, ergänzt um Hinweise zu Farbschema, Layout-Besonderheiten und dem Verhalten einzelner Views. Die KI liest diese Vorgaben zu Beginn jeder relevanten Iteration und leitet daraus ab, wie die Angular-Komponente aussehen und sich verhalten soll – nicht wie sie ihrer Meinung nach aussehen könnte.

Optional lässt sich der Ordner um Figma-Exporte oder Wireframes erweitern, wenn das Ziel-Design vom Original abweicht. Entscheidend ist nicht das Format, sondern das Prinzip: Die KI bekommt eine Referenz, auf der sie zeigen kann. Was dort steht, gilt – alles andere ist Spekulation.

In unserem Fall haben wir uns mit dem Tool v0 von Vercel einen Design-Entwurf generieren lassen. 

V0 ist ein KI-Tool zur schnellen Erstellung moderner Benutzeroberflächen. Man kann entweder eine Textbeschreibung oder einen Screenshot eingeben, und das Tool generiert daraus automatisch UI-Code. Dieses Tool ist auch eine sehr gute Lösung für den Fall, dass noch keine konkreten Design Pläne für die neue UI existieren.

UI design plan von V0

In diesem Projekt habe ich dem V0-Tool einen Screenshot der alten Benutzeroberfläche gegeben und es gebeten, das Design zu modernisieren. Der Vorschlag des V0-Tools dient somit als optische Referenz hier im Projekt.

Herleitung von der Erstellung der Spec Files

Wir haben die Migration mithilfe von Claude Code durchgeführt. Zuerst habe ich die Datei CLAUDE.md als zentrales Regelwerk erstellt, da diese beim Start von Claude Code automatisch in den Kontext geladen wird. Ich habe die Regeln, die für Claude entscheidend sind, so präzise und kurz wie möglich formuliert. Dabei wurde bewusst auf automatisch generierte Inhalte von Claude verzichtet, da diese oft ungenau sind und die spezifische Geschäftslogik nicht korrekt erfassen; sie dienen höchstens als ergänzungs- und überarbeitungsbedürftiger Entwurf.

Danach habe ich einen kurzen Exkurs gemacht und Claude in einem Prompt gebeten, mein Projekt zu analysieren und eine Art Source-Code-Archäologie durchzuführen. Das Ergebnis war die Datei vaadin-code-archeology.md. Sie hat unter anderem die Modellstruktur, die Abhängigkeiten zwischen den Modulen, das gesamte Backend, das UI-Modul sowie die Authentifizierung analysiert. Insgesamt haben wir dadurch ein ziemlich umfassendes Bild unseres Projekts erhalten.

Aus Neugier habe ich außerdem das Code-Review-Plugin ausprobiert. Das ist ein Entwickler-Tool, das den Quellcode automatisch auf Fehler, Stilprobleme und architektonische Muster überprüft. Für die Analyse von Quellcode ist es besonders nützlich, weil es schnell die Struktur der Codebasis, ihre Abhängigkeiten und mögliche Problemstellen aufdecken kann, ohne dass ein Mensch den Code vollständig lesen muss. Das Ergebnis davon war die Datei vaadin-code-archeology-code-review-plugin.md. Dieses Plugin fügt im Vergleich zur „codebeschreibenden Dokumentation“ eine deutlich tiefere Ebene des Verständnisses für die Codebasis hinzu. Es zeigt nicht nur die Struktur des Systems auf, sondern auch die bestehenden Probleme und gibt Hinweise darauf, wie man sie verbessern könnte.

Zum Beispiel: Das Problem besteht darin, dass die Methode getAllProducts() defensive Kopien (defensive copies) zurückgibt (für jedes Produkt wird new Product(p) erstellt). Dadurch werden Kategorien nur auf diesen Kopien entfernt, die anschließend verworfen werden. Die ursprünglichen Produkte behalten jedoch weiterhin die gelöschte Kategorie.Außerdem ist die Methode im Gegensatz zu deleteProduct() nicht synchronisiert (synchronized) – dadurch können bei parallelem Zugriff ebenfalls Fehler entstehen.Ein möglicher Fix wäre:

1public synchronized void deleteCategory(int categoryId) {
2   randomWait(1);
3
4   if (categories.removeIf(category -> category.getId() == categoryId)) {
5
6       products.forEach(product -> {
7
8           // direkt "products", nicht getAllProducts()
9           product.getCategory()
10                  .removeIf(category -> category.getId() == categoryId);
11
12       });
13   }
14}

Darüber hinaus analysiert das Plugin auch Datenflussprobleme, fehlende Modellvalidierung sowie Lücken in der Testabdeckung auf Systemebene und liefert oft konkrete Refactoring-Vorschläge.

Insgesamt bedeutet die Plugin-Version also nicht nur einen strukturierten Überblick über den Code, sondern zeigt auch technische Schulden, versteckte Fehler und potenzielle Risikostellen im System auf.

Als Nächstes habe ich die Datei stack.rules.md erstellt. Dabei habe ich festgelegt, welche Grundprinzipien am besten geeignet sind, um eine Angular-SPA zu entwickeln. Außerdem habe ich meine bevorzugten Test-Frameworks sowie CSS-Strategien definiert.

Die interessanteste Erfahrung entstand bei der Erstellung der Datei backlog.md. Ich habe Claude gebeten, auf Basis der bereits vorhandenen Spec-Dateien einen Backlog zu erstellen. Auf den ersten Blick habe ich ein sehr gut strukturiertes und scheinbar gründlich ausgearbeitetes Dokument erhalten.

Später stellte sich jedoch heraus, dass es in der Struktur einige Probleme gab. Zum Beispiel wären wir bis in die späteren Iterationen ohne E2E-Tests geblieben.

Die wichtigste Erkenntnis daraus ist, dass auch die Spec-Dateien immer sorgfältig überprüft werden müssen und man aktiv nach möglichen Fehlern oder Lücken suchen sollte. Daher habe ich die Erstellung der Grundprinzipien, explizit den Punkt für die E2E-Tests aufgenommen.  

Gedanken über den Ablauf und Erfahrungen

Unser Experiment lieferte 23 Iterationen für Claude Code, bestand aus 255 Unit-Tests und 50 E2E-Tests. Insgesamt beziffern wir den zeitlichen Aufwand mit weniger als 4,5 Arbeitstagen. Wie sind die Erfahrungen während der Arbeit? In den folgenden Abschnitten erfährst du mehr darüber.

Die ersten 7 Iterationen – Fast ereignislos

Die ersten sieben Iterationen verliefen nahezu ohne besondere Vorkommnisse: Claude hat die Aufgabe eingelesen, ich habe sie kurz überprüft und bestätigt, dann hat er das Ergebnis geliefert, das ich anschließend erneut akzeptiert habe – und dabei wurden die zuvor definierten Features zuverlässig und fehlerfrei umgesetzt.

Zu den umgesetzten Aufgaben gehörten unter anderem:

• REST-API Grundgerüst

• Authentifizierung

• REST-Endpunkte

• Kategorien erstellen

• Angular-Projekt initialisieren

• TypeScript-Modelle

• API-Services

• Auth-Guard

Bis zu diesem Punkt arbeitete Claude sehr selbstständig und strukturiert. Der klar definierte und gut strukturierte Backlog bildete die Grundlage der Entwicklung. Alles lief reibungslos – oder vielleicht doch nicht ganz?

Iteration 8 – Login-Seite

Ich startete wie gewohnt mit dem Prompt:

„Lass uns mit Iteration 8 fortfahren. Bitte berücksichtige unbedingt das entsprechende Bild aus dem ui_design_plan.“

Zusätzlich wies ich ausdrücklich auf das Design-Dokument hin. Später stellte sich heraus, dass dieser Hinweis eigentlich nicht notwendig war – die entsprechende Anweisung war bereits in der CLAUDE.md hinterlegt. Außerdem hatte der Hinweis letztlich weniger Einfluss als erwartet.

Das erste Ergebnis war innerhalb weniger Minuten fertig. Beim Starten der Anwendung auf localhost erwartete mich jedoch eine Überraschung.

Das erste fehlerhafte UI-Ergebnis auf der Login-Seite

Es trat ein Fehler auf. Mit einem einfachen Prompt bat ich Claude, die Ursache zu analysieren. Das Problem stellte sich als CSS-Konfigurationsfehler heraus und konnte schnell behoben werden. Innerhalb weniger Minuten erhielt ich eine korrigierte Version.

Erste Korrektur auf der Login-Seite

Das Ergebnis war fast perfekt. Lediglich die Form der Eingabefelder für Benutzername und Passwort entsprach noch nicht dem Design. Ich wies erneut deutlich darauf hin, dass das ui-design_plan Dokument verbindlich einzuhalten ist.Nach dieser Anpassung erhielt ich eine vollständig korrekte und optisch passende Login-Oberfläche.

Das Endergebnis der Login-Seite

Iteration 10 – Produkt-Grid

Auch hier war das Resultat sofort korrekt: Die vorhandenen Produkte wurden in einer übersichtlichen und ansprechend gestalteten Tabelle angezeigt.

Die vorhandenen Produkte in der Tabelle

Iteration 12 – Neues Produkt hinzufügen und bearbeiten

In dieser Iteration wurde es etwas komplexer. Im Vergleich zu den vorherigen Aufgaben hatte Claude hier deutlich mehr Schwierigkeiten. Das UI für „Produkt hinzufügen“ wurde visuell sofort korrekt umgesetzt. Die Logik hingegen bereitete Probleme:

• Beim Klick auf „Produkt hinzufügen“ wurde der Benutzer ausgeloggt.

• Das Dialogfenster blieb geöffnet.

• Das Produkt wurde nicht gespeichert.

• In den DevTools erschien ein 401-Fehlercode.

Nach meinem Hinweis analysierte Claude das Problem mehrere Minuten lang und lieferte eine erste Korrektur. Diese schloss zwar den Dialog korrekt, der 401-Fehler blieb jedoch bestehen. Erst nach einem weiteren Prompt wurde das Problem vollständig behoben.

Neues Produkt hinzufügen und bearbeiten

⁠Da Claude den Fehler nicht direkt beheben konnte, habe ich mir den Lösungsweg im Detail erklären lassen, um sicherzugehen, dass ich in die richtige Richtung gehe.

Die Tests sind trotz der Fehler grün

Auch wenn alle Unit-Tests grün waren, konnten sie bestimmte Fehler schlicht nicht erkennen. Der Grund: Sie testen isolierte Komponenten mit gemocktem HTTP und bilden nicht das reale Zusammenspiel von Browser, Proxy, Cookies und Backend ab.

Zwei Bugs blieben deshalb unentdeckt – einer im Zusammenspiel von Interceptor und Dialog, ein anderer durch ein echtes Infrastrukturproblem im Browser-Flow. Die bestehenden Tests prüfen nur Teilaspekte wie das Öffnen von Dialogen oder Service-Aufrufe, aber nicht den kompletten Nutzerfluss.

Die eigentliche Lücke: fehlende E2E-Tests. Erst realistische End-to-End-Tests (z. B. mit Playwright), die einen echten User-Flow durchspielen, hätten diese Probleme sofort sichtbar gemacht.

Ein strukturelles Problem im Backlog

Besonders interessant war eine wichtige Erkenntnis: Im Backlog war geplant, die E2E-Tests erst in Iteration 22 zu implementieren. Das bedeutet, dass alle Features mit Benutzerinteraktion bis zu diesem Zeitpunkt nicht vollständig getestet waren.

Das war eine klare Schwachstelle in der Planung.

Wir entschieden uns daher, dies sofort zu korrigieren. Wir richteten Playwright ein und erstellten mehrere E2E-Tests speziell für diese Funktionalität.

Playwright-Tests

Funktionen, die ohne weitere Probleme implementiert wurden:

About-Seite mit verschiedenen Systeminformationen

Admin-Seite zum Hinzufügen einer neuen Kategorie

Erfahrungen: promptbasierte KI-Unterstützung vs. Spec-driven-Ansatz

Meine Erfahrungen mit der Arbeit mit spec. files waren insgesamt sehr positiv. Natürlich hat die Migration mehr Zeit in Anspruch genommen (rund 32 bis 34 effektive Arbeitsstunden) als der Prozess, der – wie im ersten Blogpost beschrieben – mit nur einem einzigen Prompt gestartet wurde (in etwa 30 Minuten). Im Laufe des Prozesses hatte ich jedoch viel mehr Gelegenheit, mein ursprüngliches Projekt gründlich kennenzulernen, und konnte mehr Zeit darauf verwenden, das Code-Review-Plugin und das V0 zu nutzen, d. h. Quellen mit dem Code zu verknüpfen, um möglichst genaue Informationen als Ausgangsbasis bereitzustellen. Dadurch ist das Endergebnis deutlich präziser geworden und kommt einer realen, produktiv nutzbaren Anwendung wesentlich näher.

Da wir die Regeln im Voraus klar definiert haben, wurden auch die Tests nicht ausgelassen. Durch die Aufteilung des Arbeitsprozesses in kleinere Schritte können Fehler schnell erkannt und werden weder überspringen noch vergessen. Auf Grundlage der vorher festgelegten UI-Designs wurde schließlich genau die Benutzeroberfläche entwickelt, die in den Anforderungen beschrieben war.

Auch das Schreiben einer angemessenen Menge an qualitativ hochwertiger Dokumentation war deutlich besser kontrollierbar. Bei jeder Iteration hatte ich die Möglichkeit, die neu erstellten Dateien zu überprüfen, sodass ich mögliche Mängel bereits während des Prozesses korrigieren konnte.

Insgesamt bin ich sowohl mit dem Ablauf als auch mit dem Ergebnis sehr zufrieden. Ich würde nicht sagen, dass sich die beiden Ansätze gegenseitig ausschließen. Der erste, promptbasierte Ansatz lässt sich super für den ersten Entwurf eines Prototypen nutzen. Sobald das Projekt jedoch weiter fortgeschritten ist, hilft der spezifikationsbasierte Ansatz die Software innerhalb konkreterer Leitplanken, mittels claude code weiterzuentwickeln.

Zusammenfassung

Vorteile

• Konsistente Code-Generierung durch stack.rules

• Nachvollziehbare Schritte durch backlog.md

• Sessionübergreifender Kontext durch state.md

• Reduzierte Rework-Rate (von ~40% auf ~10%)

Nachteile

• Initialer Aufwand: Spec-Files müssen geschrieben und gepflegt werden

• Erfordert klares Verständnis der Zielarchitektur vorab

• Noch sequentiell: Komponenten werden eine nach der anderen migriert

Wann sinnvoll?

• Mittlere Projekte (10-50 Komponenten)

• Langfristige Wartung geplant

• NICHT für kleine POCs oder Prototypen (dort reicht der explorative Ansatz aus dem ersten Blogpost)

Zusammenfassend lässt sich sagen, dass die Zusammenarbeit mit Claude – nachdem wir im Voraus (fast) perfekt ausgearbeitete Spec-Files erstellt hatten – meiner Meinung nach die Arbeit eines Entwicklers deutlich beschleunigen kann. Während der Entwicklung treten auch ohne KI immer wieder Probleme auf, deren Ursache man zuerst verstehen muss. Man muss recherchieren, debuggen und verschiedene Lösungen ausprobieren.

Während der Arbeit mit Claude musste ich jedoch kein einziges Mal selbständig debuggen. Wenn ein Fehler auftrat, konnte ich ihn identifizieren und mit einfachen Prompts korrigieren lassen – selbst dann, wenn der Fehler ursprünglich von der KI verursacht wurde. Die Einbindung externer Tools wie Playwright oder ng lint/ng build über die Claude CLI verbessert das Debugging deutlich, da deren Output Claude zusätzlichen Kontext für präzisere Analysen liefert.

Natürlich werden in komplexeren Anwendungen auch die Probleme entsprechend komplizierter. Wenn man die zu erledigenden Aufgaben jedoch ausreichend klein strukturiert – so wie wir es zum Beispiel in der backlog.md gemacht haben – stellt selbst komplexe Geschäftslogik kein großes Hindernis dar. Fehler lassen sich dann relativ leicht erkennen und beheben.

Alles in allem hat die Arbeit mit Spec-Files die Effizienz im Vergleich zum ersten, eher explorativen und rein promptbasierten Ansatz deutlich verbessert. Claude hat strukturierter und gründlicher gearbeitet und sich in den meisten Fällen an die von uns definierten Regeln gehalten.

Trotzdem habe ich auch bei dieser Vorgehensweise – selbst mit Spec-File-basierter Migration – bewusst am Prinzip des „Human in the loop“ festgehalten. Meiner Erfahrung nach ist ein menschliches Review sowie die Kontrolle weiterhin notwendig, zumindest zum aktuellen Zeitpunkt, um die Qualität der Umsetzung sicherzustellen.

Ausblick: Vorschau auf den dritten und abschließenden Teil der Serie – agentenbasierte Migration

In diesem nächsten Schritt stellen sich zentrale Fragen aus dem zweiten Blogpost neu: Was passiert, wenn bereits die Analysephase systematisch KI-gestützt erfolgt? Und wie verändert sich der Ansatz, wenn nicht mehr ein einzelner Agent alle Schritte nacheinander übernimmt, sondern spezialisierte Agents parallel zusammenarbeiten? Der dritte Blogpost greift genau diesen Gedanken auf und zeigt eine Weiterentwicklung hin zu einem modularen System aus spezialisierten Agents für Analyse und Migration. Statt eines einzelnen Agents, der alle Aufgaben sequenziell abarbeitet, entsteht ein koordiniertes Zusammenspiel aus Analyzer-, Architect-, Translator- und Reviewer-Agents, die gemeinsam effizienter und strukturierter arbeiten.