Der erste Architekturdrift

Der erste Architekturdrift

Bis hierhin war die Reise erstaunlich produktiv.

Aus einer Idee für eine kleine Turnier-App wurde ein lauffähiges technisches Gerüst. Die Preview-Umgebung startet. Frontend, API Gateway, Service, Datenbank und RabbitMQ laufen. Die statischen Quality Gates der CI greifen. Keycloak ist integriert. Das API Gateway validiert JWTs und akzeptiert nur Tokens, die für die Tournament API gedacht sind.

Das ist für ein junges Projekt kein schlechter Stand.

Und trotzdem gab es jetzt den ersten klar sichtbaren Architekturdrift.

Keinen dramatischen. Keinen, der das Projekt gefährdet. Aber einen, der genau zeigt, warum KI-generierter Code nicht einfach “fertig” ist, nur weil er läuft.

Was passiert ist

Im Repository gibt es bereits eine gewachsene App-Struktur.

Apps liegen nicht beliebig direkt unter apps/, sondern sind nach ihrer Rolle gruppiert:

apps/
├─ apis/
├─ hosts/
├─ remotes/
└─ services/

Diese Struktur ist nicht nur kosmetisch. Sie hilft, im Monorepo schnell zu erkennen, welche Art von Anwendung man vor sich hat.

Ein API Gateway gehört nach apps/apis.

Ein Service gehört nach apps/services.

Frontend-Apps oder Remotes gehören in den entsprechenden Frontend-Bereich.

Nach dem Skeleton- und Auth-Schritt lagen allerdings mehrere neue Apps direkt auf oberster Ebene:

apps/connect-four-remote
apps/tournament
apps/tournament-api
apps/tournament-service

Funktional war das erstmal kein Weltuntergang.

Die Apps konnten gebaut werden. Die Container liefen. Die Preview funktionierte. Aus Sicht eines kurzfristigen technischen Durchstichs war vieles erledigt.

Aus Sicht der Repository-Struktur war es trotzdem ein Drift.

Warum dieser Drift nachvollziehbar ist

Wichtig ist mir: Das ist kein Bashing.

Der Coding-Agent hat bis hierhin schnell und effektiv gearbeitet. Er hat ein neues Projektgerüst angelegt, Docker- und Preview-Strukturen vorbereitet, Keycloak integriert und das API Gateway abgesichert.

Der Drift ist nicht entstanden, weil “KI nichts kann”.

Er ist entstanden, weil der Agent aus vorhandenem Kontext gelernt hat.

Im Repository gab es bereits eine App, die auf oberster Ebene lag. Dadurch entstand offenbar ein Muster:

Eine neue App kann direkt unter apps/ liegen.

Aus menschlicher Sicht war klar: Das war kein gewünschtes neues Standardmuster, sondern selbst schon ein früherer Strukturdrift.

Für den Agenten war dieser Unterschied nicht zwingend offensichtlich.

Und genau das ist ein wichtiger Punkt bei KI-gestützter Entwicklung:

Ein Coding-Agent erkennt nicht automatisch, welche vorhandenen Muster gute Architektur sind und welche nur historische Unfälle.

Er sieht Kontext. Er sieht Beispiele. Er imitiert.

Wenn ein Repository alte Kompromisse, Übergangslösungen oder Drift enthält, können diese Dinge zu scheinbaren Konventionen werden.

Architekturdrift ist nicht immer laut

Architekturdrift zeigt sich nicht immer als kaputter Build, roter Test oder nicht startender Container.

Manchmal ist alles grün.

Und trotzdem verschiebt sich die Struktur.

Genau das macht Drift so unangenehm. Er ist oft nicht technisch falsch, sondern architektonisch unpräzise.

In diesem Fall war der Drift klein:

Apps lagen an der falschen Stelle.

Aber solche kleinen Verschiebungen summieren sich.

Heute liegt eine App auf Root-Ebene. Morgen orientiert sich der nächste Prompt daran. Übermorgen entstehen neue Pfade, neue Sonderfälle, neue Dokumentation und neue Ausnahmen.

Irgendwann weiß niemand mehr, was Absicht und was Zufall ist.

Deshalb lohnt es sich, solche Dinge früh zu korrigieren.

Die Korrektur

Der Fix ist konzeptionell einfach:

apps/tournament
→ apps/remotes/tournament

apps/tournament-api
→ apps/apis/tournament-api

apps/tournament-service
→ apps/services/tournament-service

apps/connect-four-remote
→ apps/remotes/connect-four-remote

Dabei geht es nicht darum, die Anwendung fachlich zu verändern. Es geht nur darum, die Struktur wieder an die bestehende Monorepo-Konvention anzupassen.

Wichtig ist aber: In einem Nx-Monorepo sollte man solche Moves nicht blind per Dateimanager machen.

Pfade hängen an vielen Stellen:

• Projektkonfigurationen
• TypeScript-Konfigurationen
• Build Targets
• Dockerfiles
• Docker Compose
• CI/CD
• Deployables-Matrix
• Preview-Konfiguration
• Imports
• Agent Files oder Dokumentation

Deshalb ist so ein Move ein kleiner Architektur-Fix, kein reines Ordner-Aufräumen.

Wenn möglich, sollte ein Nx-Move-Generator genutzt werden. Wenn das nicht sauber funktioniert, müssen die Pfade manuell angepasst und konsequent geprüft werden.

Warum das Review hier entscheidend ist

Dieser Drift wäre leicht zu übersehen gewesen, weil das Ergebnis funktional gut aussah.

Genau hier liegt eine zentrale Aufgabe des menschlichen Reviews.

Nicht nur fragen:

Läuft es?

Sondern auch:

Liegt es richtig?
Passt es zu den Konventionen?
Wird hier ein falsches Muster etabliert?
Hat der Agent etwas aus dem Kontext übernommen, das gar keine Regel sein sollte?

Bei KI-generiertem Code ist das Review nicht nur Bug-Suche. Es ist Architekturpflege.

Der Agent kann sehr schnell Code erzeugen. Aber Geschwindigkeit verstärkt sowohl gute als auch schlechte Muster.

Wenn die Leitplanken klar sind, ist das ein Vorteil. Wenn die Leitplanken unscharf sind, entsteht Drift schneller, als man ihn manuell schreiben könnte.

Kein Vorwurf, sondern ein Signal

Ich finde diesen Drift sogar wertvoll.

Er zeigt früh, wo die Arbeitsweise nachgeschärft werden muss.

Für künftige Prompts bedeutet das:

• bestehende Ordnerstruktur explizit nennen
• nicht nur Ziel-Apps, sondern Zielpfade vorgeben
• alte Ausnahmen nicht als Vorbild stehen lassen
• Agent Files aktualisieren
• Architekturentscheidungen nicht nur im Chat, sondern im Projektkontext dokumentieren
• Review nicht auf Build-Erfolg reduzieren

Der Agent hat nicht “falsch gedacht”. Er hat aus Sicht des vorhandenen Kontextes plausibel weitergearbeitet.

Die Aufgabe ist jetzt, den Kontext zu verbessern.

Agent Files als Gegenmittel

Genau hier werden Agent Files wichtiger.

Wenn im Projektkontext klar steht:

API Gateways liegen unter apps/apis.
Services liegen unter apps/services.
Frontend-Apps liegen unter apps/remotes oder einer ausdrücklich definierten Frontend-Kategorie.
Neue Apps dürfen nicht direkt unter apps/ angelegt werden.

dann muss diese Regel nicht in jedem einzelnen Prompt neu erklärt werden.

Agent Files sind keine Garantie. Aber sie senken die Wahrscheinlichkeit, dass der Agent alte Drifts als neue Standards interpretiert.

Das Ziel ist nicht, jeden Fehler unmöglich zu machen.

Das Ziel ist, wiederkehrende Fehler unwahrscheinlicher zu machen.

Der aktuelle Stand

Trotz dieses Drifts ist der Projektstand insgesamt positiv.

Für das MVP-Projekt stehen mittlerweile die zentralen technischen Komponenten:

Frontend-App
API Gateway
Backend-Service
Preview-Datenbank
Preview-RabbitMQ

Alle relevanten Komponenten sind deploybar und laufen in der Preview-Umgebung.

Die statischen Quality Gates der CI greifen. Damit ist das Projekt nicht nur lokal lauffähig, sondern in den bestehenden Qualitäts- und Deployment-Prozess eingebunden.

Auch die Auth-Grundlage steht:

Angular Login via Keycloak
Bearer Token per Interceptor
JWT Strategy im API Gateway
Guard für geschützte Routen
sub als stabile technische User-ID
audience-Prüfung für tournament-api

Damit ist ein wichtiger Meilenstein erreicht.

Das System kann starten. Es kann deployed werden. Es kann Requests authentifizieren. Es hat eine stabile technische Benutzerkennung. Und es ist an die bestehende CI/CD-Struktur angebunden.

Es ist noch keine Turnier-App im fachlichen Sinne.

Aber es ist jetzt ein belastbares Projektgerüst.

Was daraus gelernt wird

Der erste Drift bestätigt im Grunde die bisherige Arbeitsweise.

Große Prompts wären gefährlicher gewesen. Wenn der Agent in einem Schritt Infrastruktur, Auth, Spieler, Turniere, Drag & Drop und Scheduling gebaut hätte, wäre so ein Strukturdrift vermutlich zwischen viel Fachcode untergegangen.

Durch die kleinen Schritte wurde er sichtbar.

Das ist der eigentliche Vorteil von Prompt Light:

kleiner Auftrag
kleiner Diff
klareres Review
schnellerer Fix

Der Drift war nicht schlimm, weil er früh erkannt wurde.

Und er war früh erkennbar, weil der Auftrag begrenzt war.

Fazit

KI-generierte Entwicklung ist nicht automatisch sauber. Aber sie ist auch nicht automatisch chaotisch.

Bis hierhin hat der Coding-Agent schnell und effektiv ein funktionierendes Projektgerüst aufgebaut. Genau das sollte man anerkennen.

Gleichzeitig zeigt der erste Architekturdrift, warum menschliches Review unverzichtbar bleibt.

Ein Build kann grün sein, während sich die Architektur trotzdem verschiebt.

Der entscheidende Punkt ist nicht, Drift vollständig zu vermeiden. Das wird in echten Projekten kaum gelingen — weder mit Menschen noch mit Agenten.

Der entscheidende Punkt ist, Drift früh zu erkennen, klein zu halten und konsequent zu korrigieren.

Für dieses Projekt heißt das:

Die technische Basis steht. Der erste Drift ist erkannt. Die Struktur wird korrigiert. Danach kann Fachlichkeit kommen.

Und genau so fühlt sich der aktuelle Stand richtig an.