Referenzprojekt

Ein agentisches Engineering-Setup für den ganzen Software-Development-Lifecycle

Das Referenzprojekt zeigt zwei vollständige Systeme: ein Produktivsystem und das Engineering-System, mit dem es gebaut wird.

Dieses Engineering-System reicht von Anforderungen und Spezifikation über Umsetzungsplanung, Implementierung, Tests, Review und Dokumentation bis zu Auslieferung und Betrieb. In jeder Phase übernehmen Agenten entweder die Arbeit selbst oder unterstützen den Menschen dabei. Dadurch kann ein einzelner Engineer jede Rolle abdecken. Der Aufbau des Engineering-Systems hat rund sechs Monate gedauert.

Das Produkt selbst ist eine laufende Multi-Tenant-SaaS-Plattform für mehrere Kundenmarken. Sie besteht aus drei Backend-Services und einem Frontend-Monorepo, das sowohl die Webanwendung als auch die nativen Mobile-Apps enthält.

Die KI, mit der das System entwickelt wird, und die KI, die Teil des Produkts ist, sind zweierlei. Das Diagramm trennt diese beiden Ebenen bewusst voneinander. Dazwischen liegen die Repositories: Jedes davon dient als Arbeitsbereich für Agenten und ist – mit Ausnahme des Operations-Repositorys – zugleich ein eigenständig deploybares Modul.

Ein Klick auf eine Box zeigt, was dahintersteckt und warum es so aufgesetzt ist; die Abschnitte darunter gehen tiefer.

Wie es gebaut wird

1Claude Codeglobale Agent-Konfiguration: Agenten · Skills · Commands · Workflows · Hooks · MCP-Server2Agent-Schicht in jedem RepositoryAgent-Anweisungen · Dokumentation für Agenten · Repo-Skills · Pre-Commit-Gates3Code-Hosting & AuslieferungBitbucket Pipelines · GitHub Actions · Registries · Image-Scanning4Issue-Tracking & WissensdatenbankEpics, Stories, Tasks und Bugs in Jira · Prozesse, Anforderungen und Analysen in Confluence

↓arbeitet an

Die Repositories

drei Backend-Services

5Core-Data-ServiceKotlin · Spring Boot · die Stammdaten der Plattform6Domain-ServiceKotlin · Spring Boot · Spring AI · die Fachlichkeit des Produkts7File-ServiceKotlin · Spring Boot · Upload, Validierung, Speicherung

Identität

8Identity-ProviderKeycloak · Open Source · OAuth · Social Login · Marken-Themes

Frontend

9Frontend-MonorepoNext.js-Web · React-Native-Apps (Expo) · Embed-SDK

Betrieb

10Betrieb & RegistryYAML-Registry · Azure CLI · kubectl · Helm · Expo EAS · GitHub CLI · Application-Insights-Analysen

↓läuft als

Was läuft

11Managed-Cloud-PlattformMicrosoft Azure · Kubernetes · verwaltetes PostgreSQL · Container Registry · Application Insights12KI im ProduktAzure OpenAI · Azure AI Content Safety · Google Vertex AI13Mobile-VerteilungExpo EAS · EAS Update · App Store · Google Play · Firebase14DrittdiensteStripe · Payrexx · SendGrid · Google Places · Turnstile · Tag Manager

1. 1Claude Code globale Agent-Konfiguration: Agenten · Skills · Commands · Workflows · Hooks · MCP-Server. Claude Code ist die Umgebung, in der die Agenten arbeiten. Der grösste Teil des agentischen Setups liegt nicht in einem einzelnen Repository, sondern in einer globalen Konfiguration – so gilt in allen sechs dieselbe Arbeitsweise. Dazu gehören Agenten, die als Rollen definiert sind; Skills, die ein Vorgehen festhalten; eine feste Regel, die entscheidet, welche Tests überhaupt geschrieben werden; Hooks, die destruktive Befehle blockieren; und MCP-Server, die Jira, die IDE und die Produktivdatenbanken anbinden – Letztere nur lesend. Sechs der Agenten sind Modul-Experten, einer pro Repository. Eine Session in einem anderen Repository fragt sie nach Fakten und bekommt Datei und Zeile als Beleg, statt den Code des Nachbarn zu erraten. Darüber liegt die Orchestrierung: ein eigenes Loop-Framework, das einen Agenten headless so lange neu startet, bis ein vorab festgelegtes Abschlusskriterium erfüllt ist. So läuft ein langer, mechanischer Durchgang durch, ohne dass jemand danebensitzt.
2. 2Agent-Schicht in jedem Repository Agent-Anweisungen · Dokumentation für Agenten · Repo-Skills · Pre-Commit-Gates. Jedes Repository hat seine eigenen Agent-Anweisungen; die grösseren haben zusätzlich eine Dokumentationsschicht für Agenten. Über sie findet der Agent die richtige Stelle, statt sich die Codebasis jedes Mal neu zu erschliessen. Repository-lokale Skills erledigen die Arbeit, die es nur im jeweiligen Repository gibt, etwa eine White-Label-Marke aufsetzen, Nutzerdokumentation aus dem Code erzeugen oder ein Deployment fahren. Pre-Commit-Gates mit projektspezifischen Checks setzen durch, was hier «korrekt» heisst, statt dass ein Reviewer daran denken muss. Weiterlesen: Architekturgrenzen automatisch prüfen
3. 3Code-Hosting & Auslieferung Bitbucket Pipelines · GitHub Actions · Registries · Image-Scanning. Die Backends und der Identity-Server liegen auf Bitbucket und werden über Bitbucket Pipelines ausgeliefert: testen, das Image bauen, in die Registry schieben, das Demo-Release auf dem Hauptbranch automatisch aktualisieren; Produktion ist ein manueller Schritt, der nur von einem getaggten Commit aus läuft. Das Frontend-Monorepo liegt auf GitHub und wird über GitHub Actions auf dieselbe Weise ausgeliefert, zusätzlich mit Mobile-Builds und Over-the-Air-Updates. Jedes Image durchläuft einen Sicherheitsscan mit Trivy, und jedes Helm-Chart liegt neben dem Service, den es deployt. Die Linie, die diese Pipelines ziehen, entscheidet, wie viel unbeaufsichtigt laufen darf: Alles Umkehrbare läuft automatisch – Tests, Images, das Demo-Release –, und jeder Schritt, der sich nicht zurücknehmen lässt, wartet darauf, dass ihn ein Mensch startet. Weiterlesen: Ein Agent löst das Jira-Ticket, ein Mensch entscheidet, wo es darauf ankommt
4. 4Issue-Tracking & Wissensdatenbank Epics, Stories, Tasks und Bugs in Jira · Prozesse, Anforderungen und Analysen in Confluence. Jira ist das Backlog; Confluence enthält das Release-Protokoll, die Runbooks und die Links zu den API-Spezifikationen. Beide sind für den Agenten über einen MCP-Server erreichbar, sodass ein Ticket in einem Skill aufgenommen, analysiert, umgesetzt und bis zum Review gebracht werden kann – und ein Produktiv-Release von dem Skill protokolliert wird, der es erkannt hat. Weiterlesen: Ein Agent löst das Jira-Ticket, ein Mensch entscheidet, wo es darauf ankommt
5. 5Core-Data-Service Kotlin · Spring Boot · die Stammdaten der Plattform. Ein Kotlin- und Spring-Boot-Service, dem die Stammdaten der Plattform gehören: die Konten, die Clubs, Partner und Fanclubs, die über die Plattform Angebote einstellen, die getrennten Mandanten, zu denen sie gehören, Loyalty, Einwilligung und Verifikation sowie jeder ausgehende Benachrichtigungskanal. Seine API ist spec-first – sieben OpenAPI-Dokumente werden validiert, und daraus wird Code generiert, bevor irgendetwas kompiliert wird –, und ein Vertrag wird per Prüfsumme gegen den Nachbarservice abgeglichen, der ihn konsumiert, sodass eine Abweichung den Build scheitern lässt und nicht erst die Integration. Weiterlesen: Architekturgrenzen automatisch prüfen
6. 6Domain-Service Kotlin · Spring Boot · Spring AI · die Fachlichkeit des Produkts. Der Service, der die Fachlichkeit des Produkts trägt: die Angebote, die ein Club oder ein Partner einstellt, die Verkaufsformen – Festpreis, kostenlose Anmeldung, Verlosung und vor allem Auktion –, Zahlungen und Rechnungsstellung über zwei Zahlungsanbieter sowie Gamification. Die Auktion ist der Teil, der kein gewöhnlicher Checkout ist: Ein Fan gibt ein Maximalgebot ab statt eines festen Betrags, und das System bietet bis zu diesem Maximum automatisch nach; ein spätes Gebot verlängert die Laufzeit, sodass eine Auktion nicht in letzter Sekunde weggeschnappt werden kann; und ein Zuschlag wird per Karte abgerechnet oder, oberhalb eines konfigurierten Betrags, per Rechnung, die bei Auktionsende erstellt wird. Jede Regel, die entscheidet, wer gewinnt und was zu zahlen ist, wird hier durchgesetzt; die Apps zeigen das Ergebnis.
7. 7File-Service Kotlin · Spring Boot · Upload, Validierung, Speicherung. Ein kleiner Service mit einer Aufgabe: eine Datei annehmen, prüfen, ob sie ist, was sie zu sein vorgibt – den echten Typ ermitteln, ein SVG mit eingebettetem Skript abweisen und ebenso ein Dokument, das den Server dazu bringen will, in seinem Auftrag etwas nachzuladen –, sie speichern und mit dem Datensatz verknüpfen, zu dem sie gehört. Dateien liegen als Zeilen in der relationalen Datenbank statt in einem Blob-Bucket – eine Vereinfachung, die sich bei der heutigen Grösse leisten lässt.
8. 8Identity-Provider Keycloak · Open Source · OAuth · Social Login · Marken-Themes. Keycloak ist der einzige Identity-Provider für Web, Mobile und die Backends und wird nur dort erweitert, wo das Mehrmarken-Setup es verlangt: Die Login-Seite ermittelt, von welcher Marken-Site der Besuch kommt, und verweist mit ihren Links zu Nutzungsbedingungen und Datenschutz genau dorthin, und dreizehn Marken-Themes sind Farb- und Logo-Schichten über einem gemeinsamen Satz Templates statt dreizehn eigener Sätze. Eine weitere Erweiterung meldet dem Backend der Plattform eine neue Registrierung. Keycloak wird zuerst deployt, alles andere validiert seine Tokens; die Admin-Konsole liegt auf einem separaten, IP-beschränkten Host, getrennt vom öffentlichen Login – die Oberfläche, über die sich Identitäten ändern lassen, ist damit aus dem Internet nicht erreichbar.
9. 9Frontend-Monorepo Next.js-Web · React-Native-Apps (Expo) · Embed-SDK. Ein pnpm- und Turborepo-Workspace enthält die Next.js-Web-App, die jeden Marken-Host bedient, die Mobile-App als Plattform-Build und als eigenen Build einer Marke, eine aus dem Code erzeugte Astro-Site mit der Dokumentation für Anbieter, ein einbettbares SDK und die 23 gemeinsamen Pakete darunter. Entscheidend ist der Schnitt: Die Mobile-App einer Marke ist ein Theme und ein Konfigurationseintrag, kein neues Projekt, weil Screens, Routen und die generierten API-Clients bereits geteilt sind – und diese Clients entstehen aus den Backend-Spezifikationen der benachbarten Repositories. Hier ist das Agent-first-Setup am dichtesten. Der Gewinn: Das teure Wissen steckt in der Umgebung, nicht in einem Kopf. Vor jedem Commit laufen 26 projektspezifische Checks – Routen-Parität zwischen den Apps, Sprach-Parität, Vollständigkeit einer Marke, Verwendung der Design-Tokens, Aktualität generierter Konfiguration –, sodass ein Fehler in Sekunden auffällt statt in einem Review-Kommentar. Eine Dokumentationsschicht für Agenten, die ihrerseits in CI validiert wird, sorgt dafür, dass der Agent die nächste Änderung bei der Dokumentation beginnt, statt sich den Code neu zu erschliessen. Weiterlesen: Architekturgrenzen automatisch prüfen
10. 10Betrieb & Registry YAML-Registry · Azure CLI · kubectl · Helm · Expo EAS · GitHub CLI · Application-Insights-Analysen. Kein Service: eine YAML-Registry als einzige Quelle der Wahrheit für jeden Service, jede Umgebung und jede Secret-Referenz, die Tools, die sie lesen, die Runbooks und der Docker-Compose-Stack für die lokale Entwicklung. Secrets sind benannte Referenzen statt Werte – sie erreichen den Cluster als Kubernetes-Secrets und liegen in einem Tresor –, sodass eine Umgebung verdrahtet werden kann, ohne dass jemand eines davon liest. Die Skills dieses Repositorys erledigen Betriebsarbeit: den Identity-Server deployen, einen Mobile-Build erzeugen und ein Over-the-Air-Update ausliefern, die Telemetrie abfragen und auswerten, was sie zeigt. Im selben Repository liegt die Sicherheitsarbeit, die man belegen können muss, statt sie im Kopf zu haben: ein Schwachstellen-Register pro Repository, gespeist aus Container-Scans; eine Prüfung der fremden Actions, auf die die Pipelines gepinnt sind; ein Register darüber, wer Produktiv-Adminrechte hält; und die PCI-DSS-Verantwortungsmatrix, nach der ein Kartenzahlungs-Audit fragt, durch eine eigene Regressions-Suite aktuell gehalten. Und das SQL für einen Löschantrag, das genau die Daten einer Person entfernen darf und sonst nichts, wird von Code aus expliziten Eingaben erzeugt – nie frei von einem Modell geschrieben.
11. 11Managed-Cloud-Plattform Microsoft Azure · Kubernetes · verwaltetes PostgreSQL · Container Registry · Application Insights. Ein Kubernetes-Cluster trägt einen Demo- und einen Produktiv-Namespace: die drei Backends, den Identity-Server und die Web-App, hinter einem nginx-Ingress mit automatischen Zertifikaten. Alle Datenbanken, auch die von Keycloak, laufen auf verwaltetem PostgreSQL. Images liegen in der Azure-Registry, Telemetrie in Application Insights mit abfragebasierten Alarmen.
12. 12KI im Produkt Azure OpenAI · Azure AI Content Safety · Google Vertex AI. Die KI, die das Produkt selbst aufruft – zu unterscheiden von der KI, die es baut. Textgenerierung über Azure OpenAI, Moderation über Azure AI Content Safety sowie Bildgenerierung und suchgestützte Recherche über Gemini-Modelle auf Google Vertex AI. All das wird aus dem Domain-Service heraus aufgerufen; die Frontends rufen nie direkt ein Modell auf.
13. 13Mobile-Verteilung Expo EAS · EAS Update · App Store · Google Play · Firebase. Beide Mobile-Apps werden über Expos EAS gebaut und eingereicht, erreichen ihre Nutzer über den App Store und Google Play und erhalten JavaScript-Updates over the air. So ist ein Fix noch am selben Tag auf den installierten Apps, ohne auf eine Store-Prüfung zu warten; der Produktiv-Kanal ist durch eine Freigabe abgesichert. Expos Push-Dienst stellt Benachrichtigungen über APNs und FCM zu, und eine Firebase-Remote-Konfiguration sagt einer installierten App, wann sie ein Update braucht.
14. 14Drittdienste Stripe · Payrexx · SendGrid · Google Places · Turnstile · Tag Manager. Zahlungen über Stripe – Checkout, Connect, Tax – und Payrexx; Transaktions-E-Mails über SendGrid; Adresserfassung über Google Places; Bot-Schutz auf Formularen über Cloudflare Turnstile; Web-Analyse nach Einwilligung über Google Tag Manager.

Die Konzepte dahinter

Eine Erkenntnis beginnt in der täglichen Entwicklungsarbeit – bei einem Problem, das dabei auftritt, und bei dem, was seine Lösung verlangt hat. Die Abschnitte darunter sind die andere Hälfte: die Konzepte, die aus dieser Arbeit entstanden sind, so wie sie hier angewendet werden.

Sie zeigen das Konzept, keinen Quellcode. Eine Implementierung gehört zu ihrem Stack, und wer sie liest, lernt nur diese eine Codebasis kennen; das Konzept ist der Teil, der sich mitnehmen lässt – ein Skill erscheint deshalb als eigene Struktur mit seinen Regeln als Pseudocode, eine Pipeline als ihre Stufen. Und genau darauf verweist eine Erkenntnis: Sie entwickelt ihr Thema eigenständig, und wo ein konkreter Fall das Argument leichter annehmbar macht, verlinkt sie auf den Abschnitt, der ihn zeigt – dieselbe Idee, bereits an einem realen System angewendet.