Eine Webanwendung, die von vier Teams parallel entwickelt wird, tendiert ohne expliziten Gegendruck zur lokalen Optimierung: Jedes Team löst seine Bildschirme nach eigenem Gutdünken — eigene Abstände, eigene Interaktionsmetaphern, eigene Komponentenbezeichnungen. Das Ergebnis ist keine Anwendung, sondern eine Sammlung von vier Mini-Anwendungen mit einer gemeinsamen Navigationsleiste. Nutzerinnen bemerken die Brüche sofort; sie lernen nicht eine Anwendung, sie lernen vier.
| Symptom | Ursache | Konsequenz |
|---|---|---|
| Inkonsistente Abstände und Typografie | Kein gemeinsames Token-Set | Visuelles Rauschen, Wahrnehmung mangelnder Qualität |
| Gleiche Aktion heißt in Team A „Speichern", in Team B „Übernehmen" | Kein Glossar, keine Patterns | Sachbearbeiterinnen müssen pro Bereich neu lernen |
| Team A baut eine Tabelle mit Inline-Edit, Team B baut ein Modal | Keine Pattern-Vereinbarung | Inkonsistentes mentales Modell der Nutzerin |
| Prototyp-Feedback kommt nach Sprint 6, wenn Architektur feststeht | Kein frühzeitiger Handover-Kanal | Teure Nacharbeiten, demotivierte Teams |
| Neue Teams reißen bestehende Routen auf | Keine Extension-Point-Disziplin | Shell bricht bei jedem Onboarding |
Das Problem ist nicht Inkompetenz — es ist fehlendes Koordinationssystem. Vier kompetente Teams ohne gemeinsame Architektur produzieren zuverlässig Fragmentierung. Die Lösung ist kein Meeting mehr. Sie ist ein Prozess mit definierten Artefakten, Grenzen und Übergabepunkten.
Prototyp-getriebene Entwicklung (PGE) stellt den laufenden Prototypen ans Anfang, nicht ans Ende. Der Prototyp ist kein Wegwerfartefakt vor dem „echten" Sprint — er ist das verbindliche Kommunikationsmedium zwischen UX-Design und Implementierung. Jede Interaction-Entscheidung, die im Prototypen getroffen wird, muss nicht mehr in einem Sprint-Review neu verhandelt werden.
PGE gliedert sich in drei Phasen, die sich überlappen und iterieren:
| Phase | Artefakt | Verantwortlich | Handover-Kanal |
|---|---|---|---|
| Foundation | Mentale Modelle, Zones, Design-Token-Spec, Pattern-Katalog | UX-Lead + Architektinnen | Leserecht aller Teams auf ux/foundations/ und ux/patterns/ |
| Prototype | Statische HTML-Frames + laufende Preact-SPA | UX-Team | figma-make-prompt.md → /prototype-Skill → HTML-Frames; Forward-Container im Stack |
| Implementation | Angular-Komponenten, Storybook-Stories, REST-Backend | Domain-Teams | @traefik-microstack/shared aus Verdaccio; Remote-Entry-Kontrakt |
Eine Interaction-Entscheidung wird genau einmal getroffen — im Prototypen — und danach in Code übersetzt. Teams implementieren keine Screens, die keinen Prototyp-Nachweis haben. Teams erfinden keine Patterns, die nicht im Katalog stehen.
Das Repository kodiert eine strikte Abhängigkeitsreihenfolge im Ordner ux/,
die durch die Sibling-Ordering-Regel aus CLAUDE-16 erzwungen wird: eine
spätere Schicht darf frühere lesen, aber nie umgekehrt.
| Schicht | Ordner | Schlüsselartefakte | Leser |
|---|---|---|---|
| Foundations | ux/foundations/ | clerk-mental-model.md, single-screen-rationale.md, SVG-Diagramme | Alle Teams, POs, PMs |
| Patterns | ux/patterns/ | search-results.mdx, detail-form.mdx, comparison-view.mdx, instant-command-resolution.mdx | Domain-Architektinnen, Frontend-Leads |
| Screens | ux/screens/{screen}/ | figma-make-prompt.md, SCREEN.md, Iterations-Screenshots | Implementierende Entwicklerinnen, Storybook-Autorinnen |
| Prototype | ux/prototype/app/ | Preact-SPA, src/components/*.tsx, src/data/ | POs (Akzeptanztest), Architektinnen (API-Kontrakt-Ableitung) |
Die Storybook-Instanz (ux/frontend/) ist der fünfte Kanal: sie rendert
Angular-Komponenten, die aus den Pattern-Definitionen abgeleitet wurden. Storybook ist
der Nachweis, dass die Implementierung mit dem Pattern übereinstimmt — nicht mit einem
Design-Tool-Export.
Der Übergang vom UX-Prototypen zur Angular-Implementierung ist kein Übergabedokument und kein Ticket mit Anhang. Er ist ein definiierter Kanal aus vier Stationen, von denen jede ein versioniertes Artefakt produziert.
Das Schlüsselartefakt ist nicht ein Figma-Export, kein Screenshot und kein Confluence-Dokument.
Es ist die figma-make-prompt.md — eine strukturierte Spezifikation in drei
Abschnitten:
/prototype-Skill und für den Angular-Entwickler.Diese Struktur macht das Dokument maschinell verwertbar (der /prototype-Skill
liest es und erzeugt HTML-Frames) und menschlich lesbar (Entwicklerinnen
implementieren daraus Angular-Komponenten ohne Rückfragen). Das Dokument ersetzt das
Design-Tool; es ist das Design.
Kein Angular-Team beginnt mit der Implementierung eines Screens, für den noch kein
figma-make-prompt.md existiert. Das Dokument ist die Definition of Ready
für UI-Tickets. Ohne es gibt es keinen Review-Maßstab.
Die Anwendung ist eine einzige Shell, die zur Laufzeit Micro-Frontends per Angular Native Federation lädt. Neue Teams erweitern die Anwendung, ohne den bestehenden Code zu berühren. Es gibt drei Koordinationspunkte — alle drei sind minimal und versioniert.
Die Konsequenz ist bemerkenswert: Ein neues Team kann produktiv werden, ohne
bestehenden Code zu kennen. Es kennt das Kommunikationsprotokoll (drei
Koordinationspunkte) und das Pattern-Katalog — beides ist in ux/patterns/
und der DOMAIN.md des Repository-Roots dokumentiert.
| Extension Point | Datei | Änderung für ein neues Team |
|---|---|---|
| Remote-Registrierung | platform/shell/src/environments/federation.manifest.json | Ein Eintrag: "loans": "/loans/remoteEntry.json" |
| Shell-Route | platform/shell/src/app/components/pages/main/main.routes.ts | Ein loadRemoteModule-Eintrag für path: 'loans' |
| Compose-Einbindung | docker-compose.yaml (Root) | Eine Zeile: - loans/docker-compose.yaml |
| Shared-Lib-Konsum | loans/frontend/package.json | "@traefik-microstack/shared": "0.0.x" |
| Domain-Doku | loans/DOMAIN.md | Neues Dokument nach Standard-Template |
Ein Monorepo ist keine Entscheidung für oder gegen ein Build-Tool. Es ist eine Aussage über Koordinationskosten: Dinge, die sich zusammen verändern, leben zusammen. Die drei Koordinationspunkte aus §5 sind deshalb minimal, weil das gesamte System — Shell, Remotes, Backends, UX-Schichten, Infrastruktur — in einem einzigen Repository liegt und damit atomar refaktorierbar ist.
Die Axiom-Regel CLAUDE-16 codiert die Teamgrenze als Ordner-Grenze:
Alle Datei-Operationen eines Teams sind auf seinen Ordner und seine Nachfolger beschränkt.
Kein Team schreibt in das Verzeichnis eines anderen Teams. Diese Regel ist in den
Claude-Code-Agenten erzwungen und in jedem DOMAIN.md dokumentiert.
Team-Topologie und Ordner-Topologie sind kongruent. Das Team, das
partner-search/ besitzt, berührt nichts außerhalb dieses Ordners — außer
den drei expliziten Koordinationspunkten. Diese Kongruenz macht Code-Reviews atomar
und Onboarding vorhersehbar.
Die Gegenthese lautet: Teams arbeiten autonomer in separaten Repositories. Das ist richtig — aber Autonomie und Kohärenz stehen in Spannung. Das Monorepo löst diese Spannung durch selektive Durchlässigkeit: Teams sind autonom innerhalb ihrer Ordner, koordiniert an den drei definierten Punkten. Multi-Repo gibt volle Autonomie und erzwingt Koordination an jedem Punkt — durch Versionierung, CI-Abhängigkeiten, Deployment-Choreographie. Die vollständige Argumentation gegen Multi-Repo folgt in §9.
Vier Teams, je vier Entwicklerinnen und Architektinnen, ein PO, ein PM. Die Verantwortungsgrenzen folgen der Domain-Struktur des Repository.
| Rolle | Anzahl | Primäre Artefakte | Review-Pflicht |
|---|---|---|---|
| UX-Lead | 1 (domainübergreifend) | ux/foundations/, ux/patterns/, figma-make-prompt.md | Alle neuen Screens, alle Pattern-Abweichungen |
| Domain-Architektin | 1 pro Team | {domain}/DOMAIN.md, federation.config.js, API-Kontrakt | Shell-Koordinationspunkte, Shared-Lib-Änderungen |
| Frontend-Entwicklerin | 2 pro Team | Angular-Komponenten, Storybook-Stories | Pattern-Konformität (gegen ux/patterns/) |
| Backend-Entwicklerin | 1 pro Team | Spring/Quarkus-Service, Flyway-Migrationen | API-Pfad-Konventionen, Traefik-Labels |
| Product Owner | 1 pro Team | Tickets, Akzeptanzkriterien | HTML-Frame-Review (Station 2) vor Sprint-Start |
| Project Manager | 1 pro Team | Sprint-Planung, Dependency-Tracking | Koordinationspunkte-Änderungen (koordiniert mit anderen PMs) |
Drei formale Übergabepunkte verhindern, dass Teams mit unklaren Anforderungen beginnen:
figma-make-prompt.md existiert, ist versioniert, wurde vom UX-Lead freigegeben. Ohne Gate 1 startet kein Prototyping-Sprint.Gates sind Qualitäts-Schwellen, keine Bürokratie. Ein Gate, das regelmäßig übersprungen wird, weil es „zu aufwändig" ist, zeigt an, dass der Handover-Prozess zu schwer ist — nicht, dass das Gate falsch ist. In diesem Fall muss die Tooling-Seite (Skill-Automatisierung, Template-Qualität) verbessert werden.
Der Prozess ist auf 10–15 Teams skalierbar ohne strukturellen Umbau. Was sich verändert ist die Kapazität — nicht die Architektur.
| Dimension | 4 Teams (heute) | 10–15 Teams (Ziel) |
|---|---|---|
| Shell-Koordination | PMs koordinieren mündlich | Dediziertes Platform-Team besitzt Shell und Shared-Lib; Domain-Teams stellen PRs |
| Pattern-Katalog | UX-Lead pflegt alleine | Pattern-RFC-Prozess: jedes Team kann Patterns vorschlagen; UX-Lead entscheidet |
| Shared-Lib-Versionen | Patch-Bumps nach Bedarf | Semver mit Minor-Freeze-Fenstern; Breaking Changes ankündigen 2 Sprints vorher |
| Monorepo-Größe | < 50.000 LOC | Sparse-Checkout per Domain; CI prüft nur betroffene Domains; kein Full-Build nötig |
| Onboarding | UX-Lead erklärt persönlich | Automatisierte Onboarding-Tracks: ux/foundations/abstract.html + Domain-Scaffold-Skript |
| Review-Bottleneck | UX-Lead reviewed alle Screens | Domain-eigene UX-Reviewer; UX-Lead nur bei Pattern-Abweichungen und neuen Patterns |
Das Skalierungsmodell folgt dem Inner-Source-Muster: Das Platform-Team (Shell + Shared-Lib + UX-Foundations) ist der „Upstream" — gut dokumentiert, hohe Einstiegshürde für Änderungen. Domain-Teams sind Konsumenten und Contributor. Die Koordinationspunkte bleiben dieselben drei, aber ihr Governance-Prozess wird formaler.
Unabhängig von der Teamzahl gilt: ein Eintrittspunkt (Shell), ein Netz (Traefik), ein Pattern-Katalog, eine Shared-Lib, ein Monorepo. Komplexität wächst linear mit Teams, nicht exponentiell — weil die Koordinationspunkte konstant bleiben.
Die intuitive Alternative: Jedes Team bekommt ein eigenes Repository. Autonomie ist vollständig, Build-Systeme sind unabhängig, Teams können ohne Rücksicht auf andere deployen. Diese Architektur ist unter bestimmten Bedingungen richtig — aber nicht für eine kohärente Webanwendung, die von Endnutzerinnen als Einheit wahrgenommen werden muss.
Das Kernproblem ist der Integrationstest-Blindspot: In getrennten Repos
sieht kein automatisierter Test die kombinierte Anwendung. Eine Änderung in Team A kann
Team B brechen — und wird es erst in der Integrationsumgebung. In diesem Repository läuft
der vollständige Stack mit make up — Playwright-E2E-Tests prüfen die gesamte
Anwendung vor jedem Commit.
| Einwand für Multi-Repo | Widerlegung |
|---|---|
| „Teams müssen unabhängig deployen können" | Unabhängiges Deployment ist orthogonal zur Repository-Struktur. Forward-Container ermöglichen in diesem Repo lokales Dev ohne andere Teams zu stören. Deployment-Unabhängigkeit folgt aus der Remote-Federation-Architektur, nicht aus separaten Repos. |
| „Merge-Konflikte auf Root-Dateien sind ein Problem" | Die Root-Koordinationspunkte (federation.manifest.json, docker-compose.yaml include:) ändern sich selten — bei Onboarding eines neuen Teams, nicht im laufenden Betrieb. Drei Zeilen Merge-Konflikt alle zwei Monate ist kein Argument für Multi-Repo. |
| „Technologie-Freiheit ist wichtig" | Backend-Technologie-Freiheit ist in diesem Repo bereits realisiert: partner-search betreibt Spring und Quarkus simultan (CLAUDE-13). Die einzige Constraint ist der Frontend-Framework-Standard (Angular) — erzwungen durch die shared-library und die Federation-Integration. Diese Constraint ist kein Fehler, sie ist das Design. |
Multi-Repo pro Team ist geeignet für unabhängige Produkte mit losen Kopplungen (Microservices ohne gemeinsames UI, separate mobile Apps). Für eine kohärente Webanwendung mit geteilter UX, geteilten Komponenten und einem gemeinsamen Routing-Graph ist Multi-Repo eine Wahl für Autonomie auf Kosten von Kohärenz — und die Endnutzerin zahlt den Preis.
Die zweite Alternative: Ein zentrales Design-System-Team liefert zuerst den vollständigen Komponentenkatalog — Farben, Typografie, Buttons, Inputs, Tables — und Domain-Teams bauen darauf auf. Kein Prototyping, kein laufender Beweis. Erst Tokens, dann Screens.
Das strukturelle Problem: Ein Designsystem, das vor den Screens gebaut wird, enthält Komponenten ohne Kontext. Welcher Button-Zustand ist nötig? Welche Tabellenvariante? Das entscheidet sich erst im Screen — aber der Screen existiert noch nicht. Das Design-System-Team rät oder baut auf Verdacht. Ergebnis: entweder ein überentwickeltes System mit 40 Komponentenvarianten, von denen 30 nie benutzt werden, oder ein unterentwickeltes System, das die Domain-Teams zur Kompensation zwingt.
Der Ansatz in diesem Repository kehrt die Reihenfolge um: Foundations und Pattern-Katalog kommen zuerst (als Markdown und SVG, kein Code), dann die Screen-Spec, dann der Prototyp, dann die Storybook-Story, dann das Angular-Komponent. Das Designsystem entsteht aus dem Prototypen — nicht vor ihm. Jede Storybook-Story ist der Beweis, dass eine Komponente real gebraucht wird.
| Einwand für Design-System-First | Widerlegung |
|---|---|
| „Ohne Designsystem baut jeder seine eigenen Buttons" | Der Pattern-Katalog (ux/patterns/) und das figma-make-prompt.md-Format erzwingen Konsistenz ohne vollständiges Designsystem. Das Designsystem (@traefik-microstack/shared) wächst organisch mit den Screens — es enthält keine Komponente, die nicht gebraucht wird. |
| „Iterationen im Prototypen sind teuer" | Eine Preact-Komponente zu iterieren kostet Stunden. Eine Angular-Komponente, die in Produktion ist, zu iterieren kostet Sprints. Der Prototyp ist deshalb billig — nicht trotzdem, sondern weil er kein Produktionscode ist. |
Design-System-First ist geeignet, wenn das Designsystem ein eigenständiges Produkt ist (Material Design, Carbon Design System, Tailwind). Für eine produktgebundene Webanwendung ist es Wasserfall-Risiko: Das System wird gebaut, bevor die Anforderungen durch echtes Prototyping sichtbar sind.
Die dritte Alternative existiert selten als bewusste Entscheidung. Sie entsteht durch Abwesenheit: kein expliziter UX-Prozess, kein Pattern-Katalog, kein Handover-Kanal. Jedes Team baut nach eigenem Ermessen, stimmt sich gelegentlich per Slack ab und hofft auf Kohärenz.
Freestyle ist die dominante Praxis in Projekten ohne UX-Architektur — und der häufigste Grund für „wir müssen das Frontend komplett neu bauen" nach 18 Monaten. Die Pathologien sind bekannt:
| Typische Freestyle-Rechtfertigung | Was sie tatsächlich bedeutet |
|---|---|
| „Wir sind agil — wir brauchen kein Upfront-Design" | Agilität bedeutet frühe Feedback-Loops, nicht Abwesenheit von Koordination. PGE ist agiler als Freestyle, weil der Prototyp früher Feedback ermöglicht als die fertige Implementierung. |
| „Jedes Team kennt seine Nutzerinnen am besten" | Das stimmt für Domänenwissen. Es stimmt nicht für Interaktionsmuster — die Nutzerin ist dieselbe Person in allen Domains und erwartet Kohärenz. |
| „Pattern-Kataloge werden nicht gelesen" | Pattern-Kataloge, die als 200-seitige PDFs ausgeliefert werden, werden nicht gelesen. MDX-Dateien mit Beispiel-Code und laufenden Storybook-Stories werden genutzt. Das Format entscheidet. |
Unstrukturierter Freestyle ist kurzfristig der schnellste Weg zum ersten Demo-Sprint. Er ist langfristig der teuerste Weg zur kohärenten Anwendung — weil die Konsolidierungsschuld mit jeder Sprint-Iteration wächst und nie abbezahlt wird, solange Features priorisiert werden.
| Einwand | Mitigation |
|---|---|
| „figma-make-prompt.md ist zu aufwändig zu schreiben" | Das Format ist einmalig zu lernen und dann templatesierbar. Der /prototype-Skill und /wireframe-from-screenshot generieren Entwürfe automatisch. Ein vollständiges Dokument wie das sachbearbeiter-dashboard entsteht in einem halben Arbeitstag. |
| „Preact-SPA ist überflüssig wenn wir schon HTML-Frames haben" | HTML-Frames prüfen Visuelles. Die Preact-SPA prüft Interaktion: Token-Auflösung, Panel-Übergänge, Keyboard-Flows. Diese können in statischen Frames nicht getestet werden. Beide Artefakte sind komplementär, nicht redundant. |
| „Storybook ist ein zweites System neben Angular" | Storybook rendert Angular-Komponenten. Es ist kein zweites System — es ist der Test-Harness für UI-Komponenten. Eine Komponente, die keine Story hat, kann nicht gegen das Pattern validiert werden. |
| „Das Monorepo wird zu langsam" | Docker-Layer-Caching, Maven-Mirror (Reposilite), npm-Mirror (Verdaccio) und Sparse-Checkout halten Build-Zeiten bei Wachstum beherrschbar. Das Repository hat diese Infrastruktur bereits in infrastructure/build-services/. |
| Einwand | Mitigation |
|---|---|
| „UX-Lead wird Bottleneck bei 10+ Teams" | Teilweise gelöst durch dezentrale UX-Reviewer pro Domain-Cluster. Aber: Neue Patterns müssen weiterhin durch den UX-Lead freigegeben werden — das ist beabsichtigt, nicht ein Fehler. Echte Skalierung erfordert ein UX-Gremium statt einer Person. |
| „Domain-Teams können die Pattern-Grenzen nicht immer einhalten" | Pattern-Grenzen werden durch Storybook-Reviews erzwungen, nicht durch Willenskraft. Aber Storybook-Reviews sind manuell. Automatisierte Visual-Regression-Tests (z.B. Chromatic) würden diesen Punkt vollständig mitigieren — das ist offen. |
| Spannung | Ehrliche Position |
|---|---|
| Prototyp-Technologie (Preact) und Produktions-Technologie (Angular) sind verschieden | Die Divergenz ist beabsichtigt: Der Prototyp muss leichtgewichtig und schnell änderbar sein. Angular-Overhead in der Prototyping-Phase verlangsamt Iterationen. Die Konversion kostet Arbeit — sie ist aber einmalig und gut dokumentiert durch die Storybook-Brücke. |
| figma-make-prompt.md ist nicht mit Figma-Exportformaten kompatibel | Das Dokument ist bewusst kein Figma-Export. Es ist eine strukturierte Spezifikation, die menschlich und maschinell lesbar ist. Wer Figma als primäres Design-Tool beibehält, muss einen Übersetzungsschritt einplanen. Der Ansatz ist Figma-agnostisch — das ist eine Stärke, schafft aber Reibung bei Teams, die Figma-native arbeiten. |
Die Abhängigkeiten sind strikt. Foundations vor Patterns, Patterns vor Screens, Screens vor Implementierung. Dieser Ordnung zu folgen spart mehr Zeit als sie kostet.
ux/foundations/clerk-mental-model.md.ux/foundations/ festhalten. Keine UI-Arbeit, bevor diese stabil sind.ux/patterns/).figma-make-prompt.md vollständig spezifizieren./prototype-Skill ausführen: HTML-Frames für PO-Review.tests/) wachsen mit jedem neuen Route/API-Endpunkt.abstract.html-Einführung, Pair-Session mit Platform-Team.Quellen: ux/DOMAIN.md · ux/foundations/clerk-mental-model.md · ux/foundations/single-screen-rationale.md · ux/patterns/ · ux/screens/sachbearbeiter-dashboard/figma-make-prompt.md · ux/prototype/app/ · platform/shell/src/environments/federation.manifest.json · platform/shared/public-api.ts · docker-compose.yaml · .claude/agents/developing-in-domain.md · CLAUDE.md (CLAUDE-13, CLAUDE-16)