Erst das Gerüst, dann die Fachlichkeit

Nach der ersten Architekturentscheidung liegt die Versuchung nahe, direkt mit dem ersten Feature zu starten.

Spielerverwaltung klingt greifbar. Turnierliste auch. Eine Drag-and-Drop-Gruppeneinteilung wäre sogar sichtbar genug, um früh ein gutes Gefühl zu erzeugen. Man könnte also einfach sagen:

Bau mir die erste Version der Turnier-App.

Genau das ist aber nicht der Weg, den ich in diesem Projekt gehen möchte.

Der erste Schritt nach der Architekturentscheidung ist nicht das erste Feature. Der erste Schritt ist ein technisches Gerüst.

Ein Skeleton.

Nicht, weil Skeletons besonders spannend sind. Sondern weil sie Reibung reduzieren, bevor diese Reibung teuer wird.

Präambel: KI-generierter Code, menschliches Review

Diese Feldbericht-Serie begleitet ein kleines reales Softwareprojekt: eine Turnier-App für einen Verein. Gleichzeitig ist sie ein Experiment in KI-gestützter Softwareentwicklung.

Der gesamte Code in diesem Projekt wird bewusst durch Coding-Agenten generiert. Meine Rolle ist nicht, jede Zeile selbst zu schreiben, sondern die fachliche Richtung, die Architektur, die Prompts, die Reviews und die Korrekturen zu übernehmen.

Das Ziel ist nicht, so zu tun, als könne man einem Agenten einfach sagen: „Bau mal eine App“ — und am Ende fällt ein sauberes Produkt heraus.

Genau das passiert in der Praxis meistens nicht.

Gute Ergebnisse entstehen nicht durch magische Prompts, sondern durch klare Aufgaben, enge Grenzen, passende Kontextdateien, wiederholtes Review und bewusstes Nachsteuern.

In dieser Serie geht es deshalb um zwei Ebenen:

Das Produkt Eine kleine Turnier-App, mit der ein Verein Spieler verwalten, Turniere vorbereiten, Gruppen bilden, Ergebnisse erfassen und Turnierstände nachvollziehen kann.
Die Arbeitsweise Wie weit kommt man heute mit KI-generiertem Code? Wo entstehen Architekturdrifts? Welche Fehler sind erwartbar? Wie präzise müssen Prompts sein? Welche Rolle spielen Agent Files, Projektkonventionen und Review-Schleifen?

Ein wiederkehrendes Thema wird Architekturdrift sein.

Coding-Agenten sind gut darin, vorhandene Muster aufzugreifen. Aber sie interpretieren Lücken. Wenn ein Auftrag ungenau ist, entstehen schnell eigene Ordnerstrukturen, ungefragte Abstraktionen, verfrühte Features oder Architekturentscheidungen, die nie getroffen wurden.

Deshalb werden die Prompts in diesem Projekt bewusst klein, überprüfbar und begrenzt formuliert.

Nicht:

Baue die komplette Turnier-App.

Sondern eher:

Lege nur das technische Skeleton an:
Angular-App, API, Service, Datenbank, Docker Compose und Preview-Deployment.
Keine Fachlogik.

Solche Prompts sind weniger spektakulär, aber deutlich kontrollierbarer. Sie reduzieren Interpretationsspielraum und machen Ergebnisse reviewbar.

Eine besondere Rolle spielen dabei Agent Files. Sie dokumentieren Konventionen, Architekturgrenzen, Projektentscheidungen und wiederkehrende Regeln direkt im Arbeitskontext des Agenten. Sie ersetzen kein Review, aber sie reduzieren Reibung. Der Agent muss weniger raten, und ich muss weniger korrigieren.

Warum nicht direkt Fachlichkeit?

Ein neues Projekt besteht am Anfang aus sehr vielen offenen Fragen.

Nicht nur fachlich, sondern auch technisch:

Wie heißt das Projekt?
Wo liegt die Angular-App?
Gibt es eine klassische App oder doch ein Microfrontend?
Wo liegen Domain-, Model- und Presentation-Code?
Wie startet die API?
Wie erreicht die API den Service?
Gibt es eine Datenbank?
Gibt es RabbitMQ?
Wie sieht Docker Compose aus?
Wie funktioniert Preview?
Welche Deployables müssen in die Matrix?
Welche Checks müssen grün sein?

Wenn diese Fragen erst beim ersten Feature geklärt werden, vermischen sich zwei Dinge, die man besser trennt:

Kann das Projekt technisch überhaupt sauber laufen?
Löst das Feature fachlich das richtige Problem?

Beides gleichzeitig zu beantworten ist möglich. Aber es erhöht die Reibung.

Wenn beim ersten Spieler-CRUD gleichzeitig Docker, Routing, API-Kommunikation, CI, Preview-Deploy und Ordnerstruktur entstehen, wird jedes Review unscharf. Ist der Fehler jetzt fachlich? Ist es ein Infrastrukturproblem? Hat der Agent die Architektur falsch verstanden? Oder fehlt einfach eine Environment-Variable?

Ein Skeleton zieht diese Fragen nach vorne.

Es beantwortet noch keine fachliche Frage. Aber es sorgt dafür, dass spätere fachliche Arbeit auf einer stabileren Startlinie beginnt.

Ein gutes Skeleton beweist Betriebsfähigkeit, nicht Fachlichkeit.

Reibung reduzieren, bevor mehr Menschen dazukommen

Das Skeleton ist nicht nur für den Coding-Agenten hilfreich. Es ist auch ein Schritt, der spätere Zusammenarbeit vorbereitet.

Solange nur eine Person experimentiert, kann vieles im Kopf bleiben. Man weiß irgendwie, welche App gemeint ist. Man weiß, welcher Compose-Befehl gerade passt. Man weiß, welche Ordner wichtig sind und welche nur temporär entstanden sind.

Sobald weitere Menschen, Reviews oder weitere Agenten dazukommen, reicht dieses implizite Wissen nicht mehr.

Dann braucht das Projekt eine klare Startlinie:

Wie wird lokal gestartet?
Wie wird gebaut?
Wie wird deployed?
Welche Container gehören zum System?
Welche Pfade sind Konvention?
Welche Architekturentscheidung ist bereits getroffen?
Was gehört ausdrücklich nicht in diesen Schritt?
Welche Checks beweisen, dass der Stand brauchbar ist?

Das Skeleton reduziert genau diese Reibung.

Es macht aus einer Idee ein begehbares Projekt.

Nicht fertig. Nicht fachlich wertvoll. Aber betretbar.

Das ist ein Unterschied.

Was das Skeleton leisten soll

Für diese Turnier-App war das Ziel des Skeleton-Schritts bewusst technisch:

Angular App
    ↓
API Gateway
    ↓
Service
    ↓
PostgreSQL

Dazu kommen die Infrastrukturbausteine, die in meinem Architektur-Labor ohnehin verwendet werden:

Docker
Docker Compose
Preview Deployment
RabbitMQ
CI/CD
Deployables Matrix

Der Auftrag war also nicht:

Baue Spieler, Turniere und Ergebnisse.

Sondern:

Lege ein deploybares Projektgerüst an, das später Fachlichkeit aufnehmen kann.

Konkret sollte entstehen:

eine klassische Angular-Standalone-App
kein Microfrontend
keine Module Federation
ein NestJS API Gateway
ein NestJS Service
eine eigene Datenbank
eine Preview-Konfiguration
Dockerfiles und Compose-Dateien
Einträge in der Deployables-Infrastruktur
minimale Health-/Hello-Endpunkte
vorbereitete Libraries für domain, model und presentation

Damit ist noch kein Turnier möglich. Aber das System kann als System existieren.

Was ausdrücklich nicht ins Skeleton gehört

Mindestens genauso wichtig wie der positive Scope ist der negative Scope.

Der Agent sollte ausdrücklich keine Fachlogik bauen.

Nicht enthalten:

keine Spielerverwaltung
keine Turnierverwaltung
keine Gruppeneinteilung
kein Drag & Drop
kein Spielplan-Generator
keine Ergebnis-Erfassung
keine Tabellenberechnung
keine Eltern-Live-Ansicht
keine detaillierte Auth-/Rollenlogik

Das klingt vielleicht pedantisch. Ist es aber nicht.

Coding-Agenten sind darauf trainiert, hilfreich zu sein. Wenn man ihnen Raum lässt, füllen sie diesen Raum. Aus „lege eine Struktur an“ wird dann schnell „ich habe schon mal ein paar Komponenten, Services, Models, Beispielrouten und Fachlogik ergänzt“.

Das ist gut gemeint. Aber es ist nicht immer gut.

Für diesen Schritt wollte ich keine halbe Turnier-App. Ich wollte ein Gerüst, das ich sauber reviewen kann.

Ein Skeleton ist kein halbes Feature.

Prompt Light: kleine Aufträge, harte Grenzen

Der Begriff „Prompt Light“ beschreibt für mich keine Zauberformel. Er beschreibt eher eine Arbeitsweise:

Kleine, präzise, überprüfbare Aufträge statt großer Wunschzettel.

Ein guter Prompt für einen Coding-Agenten sollte nicht nur sagen, was entstehen soll. Er sollte auch sagen, was nicht entstehen soll.

Für den Skeleton-Schritt enthielt der Auftrag deshalb mehrere klare Bestandteile.

1. Zielzustand

Der Prompt beschreibt zuerst das Ergebnis, nicht nur die Tätigkeit.

Ziel ist ein deploybares Infrastruktur-/Corpus-Gerüst.
Die Preview-App soll deploybar sein.
Die Container sollen sauber starten.

Damit ist der Erfolg prüfbar.

Nicht subjektiv wie:

Baue eine gute Grundlage.

Sondern konkret:

App startet.
API antwortet.
Service startet.
Datenbank läuft.
Preview ist deploybar.
Docker Compose ist valide.

2. Architekturentscheidung

Die vorherige Entscheidung wird wiederholt:

Es soll kein Microfrontend entstehen.
Das Frontend ist eine klassische Angular Standalone App.

Das ist wichtig, weil im bestehenden Architektur-Labor bereits Microfrontend- und SCS-Muster existieren. Ein Agent könnte aus Gewohnheit genau diese Muster wiederverwenden, obwohl sie für dieses Projekt bewusst verworfen wurden.

Kontext ist hilfreich. Aber Kontext kann auch in die falsche Richtung ziehen.

3. Positiver Scope

Der Prompt listet die erwarteten Bausteine explizit auf:

apps/tournament
apps/tournament-api
apps/tournament-service

libs/tournament/domain
libs/tournament/model
libs/tournament/presentation

Damit muss der Agent nicht raten, wie die Zielstruktur ungefähr heißen könnte.

4. Negativer Scope

Der Prompt grenzt aus:

Bitte ausdrücklich keine Fachlogik implementieren.

Und dann noch konkreter:

Keine Spielerverwaltung.
Keine Turnierverwaltung.
Keine Gruppeneinteilung.
Kein Drag & Drop.
Kein Scheduling.
Keine Ergebnislogik.
Keine Elternansicht.

Negative Anforderungen sind keine Pedanterie. Sie sind Leitplanken.

5. Referenzen im Repository

Der Agent soll nicht irgendeinen Standard aus dem Internet verwenden, sondern bestehende Muster im Repository prüfen:

Orientiere dich an bestehenden Stacks wie todos, tasks oder members-directory.

Damit wird die Wahrscheinlichkeit höher, dass Docker, Compose, CI und Projektstruktur zum bestehenden System passen.

6. Prüfkriterien

Am Ende des Prompts stehen Checks:

Format
Build
Docker Compose config
Docker Build Targets
Preview Compose
Deployables Matrix vollständig

Der Agent soll nicht nur Code erzeugen, sondern auch zeigen, ob der Stand tragfähig ist.

7. Berichtspflicht

Der Agent soll am Ende zusammenfassen:

welche Apps angelegt wurden
welche Libraries angelegt wurden
welche Docker-/Compose-Dateien geändert wurden
welche CI-/Matrix-Dateien geändert wurden
welche Checks erfolgreich waren
welche Punkte bewusst offen bleiben

Das klingt nach Formalismus. Tatsächlich ist es Review-Hilfe.

Ein sauberer Abschlussbericht zeigt schnell, ob der Agent den Auftrag verstanden hat oder ob er irgendwo abgebogen ist.

Agent Files als Projektgedächtnis

Prompts sind wichtig. Aber Prompts allein reichen nicht.

Wenn jeder Prompt alle Architekturregeln, Namenskonventionen, Projektgrenzen und bisherigen Entscheidungen wiederholen muss, wird die Arbeit mühsam. Außerdem steigt die Wahrscheinlichkeit, dass wichtige Regeln vergessen werden.

Dafür sind Agent Files hilfreich.

Sie sind kein Ersatz für Architekturdenken. Aber sie sind ein Projektgedächtnis für den Agenten.

Dort können Dinge stehen wie:

Dieses Projekt nutzt Angular Standalone.
Die App bleibt dünn.
Presentation-Code liegt in libs/tournament/presentation.
Models liegen in libs/tournament/model.
Domain-nahe Frontendlogik liegt in libs/tournament/domain.
Kein Microfrontend für dieses Projekt.
Keine Module Federation.
Backend startet als Deployment-Monolith.

Agent Files reduzieren Reibung, weil sie wiederkehrenden Kontext aus dem einzelnen Prompt herausziehen.

Der einzelne Prompt wird dadurch kleiner und zielgerichteter.

Statt jedes Mal die komplette Projektphilosophie zu erklären, kann der Prompt sagen:

Beachte die vorhandenen Agent Files und setze nur diesen nächsten Schritt um.

Natürlich bleibt Review notwendig. Ein Agent File verhindert keinen Fehler. Aber es macht manche Fehler unwahrscheinlicher.

Ergebnis des Skeleton-Schritts

Am Ende dieses Infrastruktur-Schritts war noch kein Spieler angelegt. Es gab kein Turnier. Keine Gruppen. Keine Paarungen. Keine Ergebnisse. Keine Tabelle.

Trotzdem war der Schritt erfolgreich.

Alle benötigten Docker-Systeme liefen:

tournament
tournament-api
tournament-service
preview-db
preview-rabbit

Damit war der technische Durchstich geschafft.

Die Anwendung existierte nicht nur als Ordnerstruktur im Repository, sondern als lauffähiges Preview-System.

Das ist unspektakulär. Und gleichzeitig ist es genau der Punkt.

Denn gerade neue Projekte scheitern oft nicht an der ersten Fachregel. Sie scheitern an Reibung:

Warum startet die App nicht?
Welche Node-Version wird erwartet?
Warum erreicht die API den Service nicht?
Welche Compose-Datei ist relevant?
Warum gibt es lokal andere URLs als in der Preview?
Warum fehlt ein Matrix-Eintrag?
Warum wird ein Docker-Image nicht gebaut?
Warum läuft es auf meinem Rechner, aber nicht im Deploy?

Der Skeleton-Schritt beantwortet diese Fragen früh.

Nicht perfekt. Aber früh genug, damit sie nicht später jedes Feature blockieren.

Was ich an diesem Ergebnis reviewe

Ein laufendes Preview-System ist gut. Aber es ersetzt kein Review.

Gerade bei KI-generiertem Code muss man prüfen, ob der Agent zwar etwas Lauffähiges gebaut hat, aber dabei die Architektur verschoben hat.

Typische Review-Fragen in diesem Schritt:

Ist wirklich keine Module Federation entstanden?
Ist die Angular-App eine klassische Standalone-App?
Bleibt die App dünn?
Liegt Presentation-Code in der passenden Library?
Wurden Domain, Model und Presentation sauber getrennt?
Sind Docker- und Compose-Namen konsistent?
Gibt es harte Produktions-URLs?
Sind Preview-Konfigurationen wirklich preview-tauglich?
Wurden bestehende Konventionen übernommen?
Sind unnötige Features entstanden?
Sind die Deployables vollständig in der Matrix?
Starten die Container nur zufällig oder reproduzierbar?

Das Ziel ist nicht, dem Agenten blind zu vertrauen. Das Ziel ist, die Arbeit so klein zu schneiden, dass Review überhaupt realistisch bleibt.

Je größer der Prompt, desto größer der Diff.

Je größer der Diff, desto schwerer das Review.

Je schwerer das Review, desto leichter rutscht Architekturdrift durch.

Warum das für spätere Features hilft

Nach dem Skeleton kann die Fachlichkeit kleiner geschnitten werden.

Statt künftig zu sagen:

Baue die Turnier-App.

kann der nächste Auftrag lauten:

Implementiere die Spielerverwaltung innerhalb der bestehenden Struktur.
Nutze libs/tournament/model für Modelle.
Nutze libs/tournament/presentation für UI.
Nutze die vorhandene API-/Service-Struktur.
Keine Turnierlogik.

Oder:

Implementiere nur die Turnierliste.
Keine Gruppeneinteilung.
Keine Ergebnislogik.
Keine Spielplan-Generierung.

Das ist der eigentliche Gewinn.

Das Skeleton macht spätere Prompts kleiner, weil die Grundsatzfragen bereits beantwortet sind.

Die Projektstruktur existiert. Die Container laufen. Die Preview steht. Die Namen sind gesetzt. Die Grenzen sind beschrieben.

Jetzt kann Fachlichkeit kommen, ohne jedes Mal Infrastruktur mitzuschleppen.

Fazit

Der Skeleton-Schritt wirkt auf den ersten Blick wie Vorarbeit. Ein bisschen Ordnerstruktur, ein bisschen Docker, ein bisschen CI, ein paar Platzhalter-Endpunkte.

Aber in einem KI-gestützten Projekt ist genau dieser Schritt entscheidend.

Er reduziert Interpretationsspielraum. Er macht Ergebnisse prüfbar. Er senkt Reibung für spätere Zusammenarbeit. Er trennt technische Tragfähigkeit von fachlicher Umsetzung. Und er sorgt dafür, dass Coding-Agenten nicht gleichzeitig Architektur, Infrastruktur und Produktlogik erraten müssen.

Der erste Auftrag nach einer Architekturentscheidung sollte deshalb nicht das erste Feature sein.

Er sollte beweisen, dass dieses Projekt als Projekt funktioniert.

Erst das Gerüst. Dann die Fachlichkeit.