ki-eit/11-legacy-migration-greenfield.md

11. Legacy, Migration und Greenfield

Kern: Legacy friert den Stack ein — dann zählt Strangler mit engen Slices und Golden Paths. Greenfield: Defaults agent-tauglich von Tag 1.

These 7 invers (Kap. 2–3) heißt: Der Stack ist oft gesetzt. Migration und Greenfield ändern das Budget, nicht die Grundlogik. In Legacy seid ihr teurer unterwegs (Context, Review, Unklarheit). In Greenfield könnt ihr die teuren Fehler von Tag 1 vermeiden — wenn ihr Verify, Instructions und Golden Paths vor der Feature-Flut setzt, nicht danach.

{width=90%}

11.1 Die typische Migrations-Session, die schiefgeht

Auftrag: „Customer-Modul modernisieren.“ Der Agent bekommt den Monolithen-Ordner, drei Legacy-READMEs und den Wunsch „wie Spring Boot 3 und Standalone“. Er liefert in einer Session: neue Entities, parallele DTOs, ein zweites Security-Filter-Muster, Angular-NgModule und Standalone-Mix, und einen Diff, der zehn Packages anfasst. Kein einziger Endpunkt ist end-to-end nutzbar. Die alten Integrationstests sind rot; die neuen Unit-Tests sind grün auf Mock-Luft. Review wird zur Archäologie.

Du merkst den Big-Bang daran, dass:

• der Diff kein einzelnes Outcome beschreibt,
• Alt und Neu zwei Wahrheiten parallel pflegen (ohne Fassade),
• Tests nach dem Umbau „irgendwann“ kommen sollen,
• der Agent den Stack „wegpromptet“, statt einen Schnitt zu strangeln.

Was du tust: Slice auf eine nutzbare Scheibe schrumpfen (Kap. 8), Tests um den Schnitt vor dem Rewrite, Fassade/ACL dokumentieren — nicht „noch einen Prompt, der alles modern macht“.

11.2 Legacy / JEE / Monolith

Legacy ist kein moralisches Urteil. Es ist hohe Unsicherheit für Mensch und Agent: gemischte Idiome, spärliche Tests, implizite Domain-Regeln, oft JEE- oder Framework-Historie neben Spring Boot 3.

Realität	Was der Agent braucht
Mehrere gültige Muster im selben Repo	eine markierte Zukunft + deprecatete Inseln
Wenig automatisierte Tests	Tests um den Schnitt bevor Refactor
Implizite Business-Regeln	Dateien mit Vorrang / kurze Domain-Notizen im Package
Externe Systeme / Batch	Ausschlüsse im Task; kein „nebenbei mitziehen“
Ownership unklar	Session-Grenzen; Handoff (Kap. 2.5, 8)

Nicht wegpompten. Ein Agent, der den Monolithen „aufräumt“, multipliziert Risiko: Behavior-Änderungen ohne Spec, Security-Defaults, stille Contract-Brüche. Besser: Anti-Corruption-Layer und Fassaden benennen, im Package-AGENTS.md verlinken, und den Agent dahinter oder davor arbeiten lassen — nicht mitten im ungetesteten Kern ohne Netz.

Do this	Avoid that
Fassade/ACL-Pfad in AGENTS.md	„modernisiere das Package“ ohne Grenze
Charakterisierungstests am Schnitt	Refactor ohne rotes/grünes Orakel
Legacy-Inseln hard-deprecaten oder markieren	Alt und Neu gleichrangig im Agent-Suchindex (Kap. 4.6 Ignore; Kap. 5.2 In-distribution)

11.3 Strangler mit engen Slices

Strangler heißt: kleine vertikale Ersetzungen statt Big-Bang. Kapitel 8 liefert den Schnitt (Outcome, Contract, FE/BE-Sessions); hier die Migrations-Linse.

Sinnvolle Reihenfolge (anpassen):

1. Hotspot wählen — schmerzhaft, aber begrenzbar (eine User-Journey, ein Endpoint-Cluster).
2. Tests um den Schnitt — was heute gilt, muss messbar bleiben.
3. Contract / Fassade — alte Welt spricht mit neuer über eine klare Kante.
4. Dünner Slice — neue Implementierung hinter Flag oder neuer Route; altes bleibt, bis grün.
5. Traffic schwenken — bewusst; Review oft gelb/rot (Kap. 12).
6. Altes entfernen — eigener Slice, nicht „nebenbei im selben Diff“.

Feature-Flags und Legacy-Routen ändern nicht den vertikalen Schnitt — nur Deploy und Ampel (Kap. 8.6). Multi-Repo: oft Backend-Strangler zuerst, Frontend folgt mit Contract-Handoff.

Do this	Avoid that
Ein Outcome pro Strangler-Slice	„Domain-Modell fertig, UI später“
Alt und Neu über Fassade verbinden	Zwei parallele Welten ohne Übergang
Entfernen des Alten als eigenen Slice	Big-Delete im selben PR wie der Neubau

Mini-Beispiel: „Bestellstatus anzeigen“ läuft heute über ein SOAP-ähnliches Legacy-API. Slice: OpenAPI-Contract + neuer Spring-Endpoint + Adapter auf den Legacy-Service + Angular-Liste. DoD: scoped Tests Adapter + Controller; kein Payment, kein Checkout-Rewrite. Später: Adapter durch echte Persistenz ersetzen — nächster Slice. Derselbe Schnitt über Wochen: 11.3.1 (Composite, Kap. 2.7).

{width=90%}

11.3.1 Anonymisierter Verlauf

Orders-Status-Strangler — B2B-Customer-Portal, Angular + Spring Boot, Legacy-SOAP Bestellstatus. Composite (~9 Wo., 6 Slices); kalibriert an Kap. 2.7; kein Framework-Wechsel (These 7 invers).

Big-Bang „Customer modernisieren“ (11.1): ~480 LoC, gemischte Security, null Outcome → Abbruch. Hotspot nur Status-Lesen. 1 Charakterisierungstests (~1,5 Wo. bis scoped grün). 2 OpenAPI + Endpoint + Adapter (Mini-Beispiel); Stopp, als Payment mitwanderte. 3 Angular-Liste — Ampel gelb (AuthZ, Kap. 12). 4 Flag 10 % Lesepfad; Review-Budget gerissen → Handoff + Package-AGENTS.md. 5 Traffic 50 %→100 %; 2 Residual-Bugs als eigener Fix. 6 Legacy-Lesepfad entfernen (eigener PR). Hebel: Tests vor Rewrite, Fassade/ACL, ein Outcome, scoped DoD.

Metrik	Vorher	Nach 3–4 Slices (~5 Wo.)	Nach Abschluss (~9 Wo.)
Review-Minuten (Median, Agent-PR)	85	48	32
Nacharbeits-Commits / Agent-PR	2,4	1,2	0,7
First-Slice-Accept	22 %	40 %	54 %
PR-Größe P75 (LoC)	~480	~220	~170
Zeit bis 1. grünem scoped Slice	— (nie)	~1,5 Wochen	—
Traffic Lesepfad Order-Status (neu)	0 %	~50 %	~100 %
Residual-Bugs nach Schwenk	n/a	2 (Mapping/Edge)	0 nach Fix-Slice

Lesart: 54 % First-Slice unter Greenfield-Happy-Paths (2.7 D/E) — Legacy und gelbe Security begrenzen. Review-Minuten und Diff sanken durch engen Schnitt, nicht durch „besseres Modell“.

11.4 Greenfield-Defaults

Greenfield ist die Chance, Kap. 4 und 9 vor der Feature-Flut zu setzen. Wer erst hundert Features baut und dann „Agents einführt“, kauft sich Legacy-Reibung auf frischem Code.

Minimum von Tag 1 (oder Repo-Init):

Hebel	Default
Runtime	Pin (Node/JDK) + Wrapper im Repo
Verify	Tight / Slice-DoD / Heavy non-interactive in Instructions/AGENTS.md
Angular	Standalone/Signals (oder euer fester Stil) + ein Referenz-Feature
Spring / Quarkus	ein Golden-Path-Endpoint + Security-Pattern + scoped Test
Contract	OpenAPI (o. Ä.) im Repo, wenn Multi-Team/Multi-Repo absehbar
Ignore	node_modules, target, Dist, Coverage — von Anfang an
Permissions	Deny-Default für Destruktion/Deploy; kein YOLO-Team-Default (Kap. 12)

Moderne Angular-Defaults und aktuelles Spring Boot 3.x / Quarkus sind die In-distribution-Basis (Kap. 3.4, 5–7). Hausgebrau darf dazu — aber mit Beispielpfad, sonst erfindet der Agent Tutorial-Welt.

Do this	Avoid that
AGENTS.md + Convention eures Agents bevor Feature-Flut	„Rules später, wenn wir Zeit haben“
Ein Happy-Path pro App/Service	Drei Starter-Templates ohne Wahrheit
Contract-first wo Teams parallel bauen	FE und BE raten drei Sprints

Greenfield spart den teuren Vorher-Zustand aus 11.3.1.

11.5 Wann welches Muster

Situation	Muster	Agent-Fokus
Monolith, hoher Schmerz an einer Kante	Strangler-Slice	Fassade + Tests + dünnes Outcome
Mehrere Apps, geteilter Contract	Contract-first + Handoff	Kap. 8; Sessions getrennt
Neues Produkt / neues Modul grün	Greenfield-Defaults	Kap. 4 + 9 Tag 1
Nur Framework-Bump (z. B. Angular major)	enge Slices + Golden Path	nicht „alles modernisieren“ in einer Session
Quarkus neben Spring	bewusstes zweites Backend	Kap. 7 — kein 1:1-Port

Das ist keine Migrationsmethodik-Fibel. Es ist die Übersetzung: Agents multiplizieren den Schnitt, den ihr vorgibt. Big-Bang-Schnitt → Big-Bang-Diff. Enger Strangler → reviewbarer Diff.

Key Takeaways

• Legacy: Alignment + enge Slices + Tests vor Umbau — nicht wegpompten.
• Strangler = vertikale Scheiben (Kap. 8) an einer Fassade; Altes entfernen separat.
• Strangler-Wirkung messbar: Review-Minuten, First-Slice, Traffic-%, Residual-Bugs (11.3.1; Kap. 2.6–2.7).
• Greenfield: agent-freundliches Repo von Tag 1 (Kap. 4 + 9).
• These 7 invers gilt auch hier: Stack/Bestand oft gesetzt — der Hebel ist Schnitt und Wahrheit im Repo.

Praktische nächste Schritte

1. Einen Legacy-Hotspot mit Strangler-Slice skizzieren (Outcome, Fassade, DoD-Commands).
2. Charakterisierungstest oder Contract am Schnitt festnageln, bevor der Agent umbaut.
3. Ab Slice 1 Metriken tracken: Review-Minuten, Nacharbeits-Commits, First-Slice-Accept; optional Traffic-% / Residual-Bugs.
4. Greenfield- oder Modul-Init: Checkliste Kap. 4 (Runtime, Instructions, Ignore) abhaken.
5. Package-AGENTS.md: „Zukunft vs. Legacy-Insel“ in zwei Sätzen markieren.
6. Danach Kap. 12 — Permissions, Review und HITL, sobald Migration Security oder Prod berührt.