Jenseits von Copy-Paste: Backstage mit KI-gestützter Entwicklung aufbauen

Wie Claude Sonnet 4.5 und GitHub Copilot uns durch das Labyrinth von Custom-Backstage-Integrationen geholfen haben

Das Backstage-Versprechen (und die Realität)

Spotifys Backstage-Plattform verspricht eine schöne Vision: ein einheitliches Developer-Portal, in dem Teams Services entdecken, Ressourcen aus Templates erstellen und ihre gesamte Infrastruktur über ein einziges Interface verwalten können. Die Dokumentation ist umfassend, die Community lebendig und die Screenshots sehen fantastisch aus.

Dann versuchst du es tatsächlich für deinen spezifischen Use Case zu implementieren.

Plötzlich steckst du tief in YAML-Konfigurationen, debuggst GitHub-Action-Parameter, kämpfst mit ArgoCD-Sync-Policies und fragst dich, warum deine Crossplane-Ressourcen nicht erstellt werden. Der "einfach dem Quickstart folgen"-Ansatz funktioniert perfekt... bis er es nicht mehr tut. Und wenn er es nicht tut, bist du auf dich allein gestellt, setzt Stack-Overflow-Posts, GitHub-Issues und Dokumentation zusammen, die davon ausgeht, dass du schon weißt, was du tust.

Hier wird es mühsam.

Nicht weil Backstage schlecht designed ist – ganz im Gegenteil. Es ist unglaublich flexibel und mächtig. Aber diese Flexibilität bedeutet, dass fertige Lösungen selten genau zu deinem Use Case passen. Du musst verstehen:

• Wie Backstages Scaffolder-Actions funktionieren
• Welche GitHub-Integrationsmethode zu deinen Bedürfnissen passt
• Wie man YAML für deinen spezifischen Workflow strukturiert
• Welche RBAC-Berechtigungen erforderlich sind
• Wie verschiedene Komponenten interagieren

Und ehrlich gesagt? Manchmal möchte man einfach nur die Sache bauen, ohne Experte für jede Technologie im eigenen Stack zu werden.

KI-gestützte Entwicklung im Einsatz

Das hat sich geändert, als wir KI in den Entwicklungsprozess einbrachten:

Traditionelle Entwicklung läuft oft so ab:

1. Dokumentation lesen
2. Beispielcode kopieren
3. An den eigenen Use Case anpassen
4. Debuggen, wenn es nicht funktioniert
5. Schritte 1–4 wiederholen, bis es klappt

KI-gestützte Entwicklung ändert den Workflow:

1. Beschreibe, was du erreichen willst
2. Die KI schlägt Ansätze vor und generiert Implementierungen
3. Du validierst und testest die Ergebnisse
4. Du iterierst basierend darauf, was funktioniert und was nicht
5. Die KI behält den Kontext über die gesamte Konversation hinweg bei

Der Hauptunterschied? Man verbringt weniger Zeit mit Suchen und mehr Zeit mit Validieren. Die KI wird zu einem kompetenten Pair-Programmer, der sich alles über dein Projekt merkt.

Ein reales Beispiel: Eine GitOps-Plattform aufbauen

Lass mich erzählen, was passiert ist, als wir versuchten, Backstage mit Crossplane und ArgoCD zu integrieren. Das war kein Tutorial-Szenario – das war echte Arbeit mit echten Frustrationen.

Der erste Versuch: "Einfach Dateien lokal speichern"

Die Anfrage: "Lass Backstage-Templates Crossplane-Ressourcen erstellen und lokal speichern."

Einfach genug, oder? Ein Template erstellen, etwas YAML generieren, auf Disk speichern. Klassischer Backstage-Scaffolder-Use-Case.

Die Realität: Backstages Scaffolder läuft in einem sandboxed temporären Verzeichnis. Deine Dateien existieren etwa 3 Sekunden, bevor sie gelöscht werden. Die Dokumentation erwähnt das nebenbei, aber man realisiert die Implikationen erst, nachdem man eine Stunde damit verbracht hat, sich zu fragen, warum die Dateien verschwinden.

Traditioneller Ansatz:

• Google "backstage persist scaffolder output"
• 3 Jahre altes GitHub-Issue finden
• Jemanden entdecken, der einen Workaround mit Custom Actions vorschlägt
• Versuchen, diese Custom Action zu implementieren
• Realisieren, dass man Backstage neu bauen muss
• Karrierewechsel in Erwägung ziehen

KI-gestützter Ansatz:

User: "Die Dateien werden erstellt, verschwinden aber. Warum?"

KI: "Backstages Scaffolder nutzt temporäre Verzeichnisse, die nach der Ausführung aufgeräumt werden. Für Persistenz hast du drei Optionen:

1. Push zu Git-Repository (ermöglicht GitOps)
2. Direkte API-Calls zu Kubernetes
3. Custom Storage Backend

Bei deinem Crossplane-Use-Case ermöglicht Option 1 GitOps-Patterns mit ArgoCD. Möchtest du das erkunden?"

Boom. Wir sind von einem toten Ansatz zu einer richtigen GitOps-Architektur in einem einzigen Austausch geschwenkt. Kein Googeln, kein Zusammensetzen von Stack-Overflow-Antworten, kein Durchlesen von 50-seitigen Design-Docs.

Die zweite Herausforderung: Das GitHub-Actions-Labyrinth

Jetzt mussten wir Dateien in ein bestehendes GitHub-Repository pushen. Wie schwer kann das sein?

Die Realität: Backstage hat DREI verschiedene GitHub-bezogene Actions:

• publish:github - Erstellt nur NEUE Repositories
• github:repo:push - Pusht zu bestehenden Repos (aber mit Einschränkungen)
• publish:github:pull-request - Erstellt Pull Requests

Jede hat unterschiedliche Parameter. Dokumentation existiert, ist aber verstreut. Beispiele sind oft veraltet.

Was tatsächlich passierte:

Versuch 1: publish:github verwendet

1steps:
2  - id: publish
3    action: publish:github
4    input:
5      repoUrl: github.com?owner=me&repo=my-existing-repo

Ergebnis: Fehler: "Repository already exists" Verlorene Zeit: 15 Minuten

Versuch 2: Zu github:repo:push mit force-Parameter gewechselt

1steps:
2  - id: push
3    action: github:repo:push
4    input:
5      force: true  # In einem GitHub-Issue gefunden

Ergebnis: Fehler: "force is not a valid parameter" Verlorene Zeit: 20 Minuten

Versuch 3: Dokumentation recherchiert, korrekte Action gefunden

1steps:
2  - id: pr
3    action: publish:github:pull-request
4    input:
5      repoUrl: github.com?owner=me&repo=my-repo
6      branchName: add-resource

Ergebnis: Es funktionierte! Aber erst nachdem das offizielle Backstage-GitHub-Repo geprüft wurde Verlorene Zeit: Weitere 20 Minuten

Insgesamt verschwendete Zeit: Fast eine Stunde Trial-and-Error

Was hätte passieren sollen:

User: "Ich muss Dateien in ein bestehendes GitHub-Repository pushen."

KI: Durchsucht Backstage-Dokumentation "Für bestehende Repositories nutze publish:github:pull-request. Das erstellt einen PR, was besser für GitOps-Workflows ist. Hier ist die Konfiguration:

[exakte YAML-Konfiguration]

Die publish:github-Action erstellt nur NEUE Repos, und github:repo:push benötigt Fast-Forward-Merges, was für deinen Use Case nicht funktioniert."

Hier glänzt KI: Sie kann schnell Dokumentation parsen, Kontext verstehen und die spezifische Lösung für dein exaktes Szenario liefern.

Die dritte Überraschung: Der catalog-info.yaml-Konflikt

Unsere Templates generierten zwei Dateien:

• xnamespace.yaml - Die eigentliche Crossplane-Ressource
• catalog-info.yaml - Backstages Catalog-Eintrag

Wir pushten beide zu GitHub. ArgoCD überwachte das Repo und synchronisierte Änderungen zu Kubernetes.

Das Problem: ArgoCD versuchte, catalog-info.yaml auf Kubernetes anzuwenden. Kubernetes sagte "Was ist dieses backstage.io/Component-Ding?" und lehnte es ab.

Traditionelles Debugging:

• ArgoCD-Logs prüfen (verwirrend)
• Kubernetes-Events prüfen (noch verwirrender)
• Fehlermeldung googeln (keine exakten Treffer)
• Schließlich realisieren, dass ArgoCD ALLE YAML-Dateien synchronisiert
• Über ArgoCDs Exclude-Patterns lernen
• Konfiguration aktualisieren

Verlorene Zeit: 30-40 Minuten

KI-gestütztes Debugging:

User: "ArgoCD schlägt fehl mit 'could not find backstage.io/Resource'"

KI: "Das ist eine Backstage-Catalog-Entity, keine Kubernetes-Ressource. ArgoCD versucht, sie auf deinen Cluster anzuwenden. Du musst catalog-info.yaml-Dateien vom ArgoCD-Sync ausschließen:

source:
  directory:
    exclude: 'catalog-info.yaml'

Das sagt ArgoCD, alles AUSSER Backstage-Catalog-Einträge zu synchronisieren."

Zeit gespart: Problem und Lösung sofort verstanden.

Die Kraft der KI-gestützten Entwicklung

Das hat die Arbeit mit KI grundlegend anders gemacht:

1. Kontext-Beibehaltung über den gesamten Stack

Wir arbeiteten mit:

• Backstage (Templates, Scaffolder, Catalog)
• GitHub (Repos, PRs, Authentifizierung)
• ArgoCD (Sync-Policies, Anwendungen, RBAC)
• Crossplane (XRDs, Compositions, Providers)
• Kubernetes (Namespaces, RBAC, Service-Accounts)
• k3d (Cluster-Erstellung, Zertifikate)

Das sind SECHS verschiedene Technologien, jede mit eigenem Mental-Modell, Terminologie und Fallstricken.

Traditioneller Ansatz: Du musst konstant den Kontext wechseln:

• "Okay, ich bin jetzt im Backstage-Modus... schaue in die Scaffolder-Docs"
• "Jetzt muss ich an GitHub denken... was waren nochmal die API-Limits?"
• "Wechsle zu ArgoCD... wie war nochmal die Sync-Policy-Syntax?"

KI-gestützt: Das Modell behält den Kontext über ALLE diese Systeme:

User: "Der GitHub-Push funktionierte, aber ArgoCD synchronisiert nicht."

KI: "Lass mich prüfen:

• Template erstellt PR ✓
• GitHub-Repo zugänglich ✓
• Hat ArgoCD GitHub-Credentials? ← Das ist wahrscheinlich das Problem

Du musst ein Secret im argocd-Namespace mit dem Label 'argocd.argoproj.io/secret-type=repository' erstellen, das deinen Token enthält."

Die KI wechselt nicht den Kontext - sie sieht das gesamte System.

2. Mustererkennung über Technologien hinweg

Als wir schließlich fragten "Was ist mit Zertifikaten und RBAC für frische Cluster?", erkannte die KI sofort:

• k3d generiert neue Zertifikate pro Cluster (automatisch behandelt)
• Crossplane-Provider benötigt ClusterRole-Bindings (dynamischer SA-Name)
• Backstage benötigt möglicherweise Read-Permissions (optionaler SA)
• ArgoCD benötigt GitHub-Credentials (Secret neu erstellen)

Es ging nicht darum, Backstage speziell zu kennen - es ging um das Verständnis von Patterns:

• Certificate Authorities und Client-Zertifikate
• Service-Account-Permissions in Kubernetes
• Secret-Management über Cluster-Lifecycles hinweg

Das kann man nicht googeln. Es steht in keinem einzelnen Dokument. Es ist die akkumulierte Weisheit, mit diesen Patterns gearbeitet zu haben.

3. Proaktive Problemidentifikation

Am Ende unserer Session erstellten wir ein Automatisierungsskript. Zunächst:

• Cluster erstellt
• Crossplane installiert
• Ressourcen angewendet
• Backstage gestartet

Aber dann die Frage: "Was ist mit frischen Cluster-Anforderungen?"

Traditioneller Ansatz: Du würdest deployen, Fehler antreffen, dann debuggen:

$ ./setup.sh
[cluster created]
[crossplane installed]
[resources applied]
[tests run]
ERROR: Crossplane provider can't create namespace
[20 Minuten Debugging]
Ah, RBAC-Permissions!

KI-gestützter Ansatz:

KI: "Für frische Cluster benötigen wir:

1. Crossplane-Provider-RBAC (dynamische SA-Erkennung)
2. Backstage-Service-Account (optional)
3. ArgoCD-GitHub-Credentials

Lass mich Funktionen hinzufügen, die das automatisch handhaben."

Die KI antizipierte Probleme basierend auf dem Verständnis der Systemarchitektur, nicht nur der unmittelbaren Anforderungen.

Die Selbstreflexion: Was wir gelernt haben

Nach Abschluss des Projekts bat ich die KI, zu reflektieren, was gut lief und was nicht. Die Ergebnisse waren... überraschend aufschlussreich.

Was gut lief

Adaptive Problemlösung: Als lokale Speicherung scheiterte, schwenkten wir zu GitOps, ohne Momentum zu verlieren. Das ist, wo KI glänzt - sie ist nicht emotional in die erste Lösung investiert.

Umfassende Dokumentation: Wir erstellten 6 detaillierte Guides, während wir Probleme lösten. Die KI dokumentierte nicht nur "wie", sondern "warum", erfasste Kontext, während er frisch war.

Finale Automatisierung: Das Setup-Skript war exzellent - Handling dynamischer Service-Accounts, klares Feedback, Berücksichtigung frischer Cluster-Szenarien.

Was nicht gut lief

Mehrere Template-Iterationen (8+ Versionen): Wir bearbeiteten Templates 8-mal, probierten verschiedene GitHub-Actions aus. Wir hätten verfügbare Actions recherchieren sollen, BEVOR wir mit der Implementierung begannen.

Verzögerte RBAC-Konfiguration: Wir dachten nicht an frische Cluster-Anforderungen, bis explizit gefragt. Hätten "Clean-Slate"-Szenarien von Anfang an berücksichtigen sollen.

Unvollständige Anforderungserhebung: Starteten mit der Implementierung von "lokaler Speicherung", ohne zu fragen "Warum? Was ist das größere Bild?"

Die Note: A-

Ziel: Exzellent - komplette GitOps-Plattform mit Automatisierung Reise: Lehrreich, aber ineffizient - hätte direkter sein können Pfad: Zu viele Trial-and-Error-Iterationen

Die Selbstkritik war ehrlich: "Wir hätten dieses Ziel effizienter erreichen können, indem wir früher Dokumentation konsultiert und vorab mehr klärende Fragen gestellt hätten."

Das Gute, das Schlechte und die Zukunft

Das Gute: Wo KI glänzt

• Kontext-Beibehaltung: Details über Stunden von Konversation merken
• Code-Generierung: Korrekten, idiomatischen Code mit ordentlicher Fehlerbehandlung produzieren
• Dokumentation: Umfassende Guides erstellen, die das "Warum" erklären, nicht nur das "Wie"
• Anpassungsfähigkeit: Strategien wechseln, wenn Ansätze scheitern
• Mustererkennung: Wissen über verschiedene Technologien anwenden

Das Schlechte: Aktuelle Einschränkungen

• Documentation-First: Sollte offizielle Docs recherchieren, bevor Implementierungen versucht werden
• Annahmen-Verifizierung: Nimmt manchmal an, dass Parameter existieren, ohne zu prüfen
• Produktions-Mentalität: Fokussiert auf "make it work" vor "make it production-ready"
• Testing-Strategie: Reaktiv statt proaktiv
• Security-Timing: Sicherheitsaspekte kamen spät im Prozess

Die hässliche Wahrheit

Selbst mit KI-Unterstützung ist der Bau von custom Backstage-Integrationen immer noch mühsam. Aber es ist auf eine andere Weise mühsam:

Ohne KI: Mühsam, weil man konstant:

• Dokumentation durchsucht
• Beispiel-Code liest
• Kryptische Fehler debuggt
• Zwischen Technologien den Kontext wechselt
• Partielle Lösungen zusammensetzt

Mit KI: Mühsam, weil man:

• An Spezifikationen iteriert
• Generierte Lösungen validiert
• Klärende Fragen stellt
• Umfassenden Code reviewed
• Architektur-Entscheidungen trifft

Letzteres ist viel produktivere Mühsal. Man verbringt Zeit mit High-Level-Entscheidungen, nicht mit Low-Level-Implementierungs-Details.

Praktische Lektionen: So funktioniert diese Arbeitsweise

Wenn du KI-gestützte Entwicklung ausprobieren möchtest, hier sind praktische Muster, die funktioniert haben:

1. Beginne mit "Warum" statt "Was"

Sage nicht: "Erstelle ein Backstage-Template, das Dateien lokal speichert"

Sage lieber: "Ich möchte, dass Backstage-Nutzer Crossplane-Ressourcen erstellen können. Die Ressourcen sollen versionskontrolliert, automatisch auf den Cluster angewendet und in einer UI sichtbar sein. Was ist der beste Ansatz?"

Das lädt die KI ein, Architektur vorzuschlagen, anstatt nur deine möglicherweise fehlerhafte Idee zu implementieren.

2. Bestehe auf Dokumentation

Akzeptiere nicht: "Versuche den force-Parameter"

Frage stattdessen: "Kannst du mir in der offiziellen Dokumentation zeigen, wo dieser Parameter definiert ist?"

Lass die KI Quellen zitieren. Das fängt Annahmen früh ab.

3. Denke an Neuanfänge

Nimm nicht an: Die aktuelle Umgebung wird immer existieren

Frage stattdessen: "Wenn ich alles lösche und von vorne anfange, was wird gebraucht? Was ist mit Zertifikaten, RBAC, Secrets?"

Das fängt versteckte Abhängigkeiten ab.

4. Fordere Testpläne an

Nicht einfach: "Bring es zum Laufen"

Sage stattdessen: "Erstelle eine Test-Checkliste, bevor du implementierst. Was könnte bei jedem Schritt schiefgehen?"

Das fördert proaktives Problemlösen.

5. Frage nach mehreren Lösungen

Akzeptiere nicht einfach: Die erste Implementierung

Frage stattdessen: "Was sind alternative Ansätze? Was sind die Trade-offs?"

Das hilft dir, informierte Entscheidungen zu treffen.

Das Setup-Skript: KI-gestützte Entwicklung in Aktion

Unser finales Ergebnis war ein 573-zeiliges Bash-Skript, das:

• Prerequisites prüft
• k3d-Cluster erstellt
• Crossplane installiert
• Ressourcen anwendet
• RBAC konfiguriert
• ArgoCD installiert
• GitHub-Credentials konfiguriert
• Port-Forwards startet
• Passwörter extrahiert
• Umfassende Zusammenfassung anzeigt
• Backstage-Deployment konfiguriert
• Backstage startet

Traditioneller Ansatz: Das würde Tage dauern:

• Tag 1: Basis-Cluster-Erstellung zum Laufen bringen
• Tag 2: Crossplane-Installation hinzufügen
• Tag 3: RBAC-Probleme debuggen
• Tag 4: ArgoCD-Integration hinzufügen
• Tag 5: Polieren und dokumentieren

KI-gestützter Ansatz: Erstellt in einer Anfrage:

User: "Erstelle ein Setup-Skript, das alles automatisiert, was wir manuell gemacht haben, inklusive Handling frischer Cluster, dynamischer Service-Accounts und klarem User-Feedback."

KI: [Generiert 573-zeiliges Skript mit:

• Farbcodierter Ausgabe
• Fehlerbehandlung
• Dynamischer SA-Erkennung
• Umfassender Zusammenfassung
• Background-Process-Management]

War es perfekt? Nein - wir verfeinerten es basierend auf der RBAC-Diskussion. Aber es war 95% korrekt bei der ersten Generierung, und wir konnten an der Spezifikation iterieren ("füge RBAC-Konfiguration hinzu") statt am Code.

Blick nach vorn: Die Zukunft des Platform Engineering

Backstage ist nicht einzigartig darin, "mühsam zu sein, wenn fertige Lösungen nicht passen." Das beschreibt den größten Teil des Platform Engineering:

• Kubernetes-Operator benötigen Verständnis von CRDs, Controllern, RBAC
• Service-Meshes brauchen Sidecar-Injection, mTLS, Traffic-Policies
• GitOps-Tools benötigen Repository-Struktur, Sync-Policies, Secrets
• CI/CD-Pipelines brauchen Runner, Caching, Artifact-Management

Jedes Platform-Tool verspricht "einfaches Setup" und liefert "einfach für den Happy-Path."

KI eliminiert diese Komplexität nicht. Aber sie verändert, wie man damit umgeht:

Statt ein Experte in 6 verschiedenen Technologien zu werden, wird man ein Experte darin, zu beschreiben, was man braucht und zu validieren, was man bekommt.

Statt stundenlang Dokumentation zu lesen, hat man Konversationen über Trade-offs und Ansätze.

Statt 30 Minuten zu debuggen, erklärt man den Fehler und bekommt potenzielle Lösungen in 30 Sekunden.

Das Fazit

Der Bau unserer Backstage + Crossplane + ArgoCD-Plattform dauerte etwa 6 Stunden Hin-und-Her mit Claude Sonnet 4.5. Es beinhaltete:

• Mehrere Architektur-Pivots
• 8+ Template-Iterationen
• 3 verschiedene GitHub-Actions ausprobiert
• ArgoCD-Konfigurations-Debugging
• RBAC-Implementierung
• Komplettes Automatisierungs-Skript
• 6 detaillierte Dokumentations-Dateien

Ohne KI? Ich schätze, das hätte 2-3 Tage Arbeit gebraucht, möglicherweise mehr. Und die Dokumentation wäre ein nachträglicher Einfall gewesen.

War es perfekt? Nein - wir hätten effizienter sein können, indem wir:

• Der KI gesagt hätten, Docs zu recherchieren, bevor implementiert wird
• Klärende Fragen vorab gestellt hätten
• Frische-Cluster-Szenarien früher berücksichtigt hätten

War es wertvoll? Absolut. Wir sind von null zu einer tatsächlich funktionierenden, automatisierten GitOps-Plattform an einem einzigen Tag gekommen, mit umfassender Dokumentation und einem tiefen Verständnis davon, wie alles funktioniert.

Das ist die Kraft der KI-gestützten Entwicklung: Verbringe deine Zeit mit Validieren und Entscheiden, nicht mit Suchen und Debuggen.

Probiere es selbst aus

Wenn du diesen Workflow erleben möchtest:

1. Wähle eine komplexe Integration (starte nicht mit "hello world")
2. Beschreibe dein Ziel, nicht deine Implementierung
3. Frage "warum", bevor du Lösungen akzeptierst
4. Bestehe auf Dokumentations-Referenzen
5. Denke an Neuanfänge und Edge Cases
6. Frage nach Alternativen und Trade-offs

Und denk daran: KI ist ein Kollaborateur, kein Zauberstab. Du musst immer noch:

• Verstehen, was du baust
• Den generierten Code validieren
• An Produktions-Implikationen denken
• Architektur-Entscheidungen treffen

Aber du verbringst deine Zeit mit hochwertige Aktivitäten (Architektur, Anforderungen, Validierung) statt mit geringwertigen Aktivitäten (Syntax-Debugging, Dokumentations-Suche, Beispiel-Kopieren).

Das ist ein Trade-off, den ich jedes Mal eingehen würde.

Was wir hätten besser machen können: Hin zu wirklich Spezifikations-getriebener Entwicklung

Wenn wir auf unsere Erfahrung zurückblicken, wurde uns etwas Wichtiges klar: Wir hätten wirklich spezifikations-getriebene Entwicklung verfolgen sollen.

Was tatsächlich passiert ist

Unser Workflow sah so aus:

1. Beschreiben, was wir wollten
2. KI generierte Code
3. Wir haben es ausprobiert
4. Es funktionierte nicht perfekt
5. Wir haben debuggt und iteriert
6. Wiederholen, bis es funktionierte

Das ist besser als traditionelle Entwicklung, aber es ist immer noch reaktiv. Wir haben immer noch Trial-and-Error gemacht, nur schneller.

Wie wirklich Spezifikations-getriebene Entwicklung aussieht

Echte spezifikations-getriebene Entwicklung wäre:

1. Umfassende Spezifikationen im Voraus definieren
2. KI konsultiert autoritative Quellen
3. KI generiert Implementierung basierend auf verifizierten Mustern
4. Implementierung entspricht beim ersten Versuch der Spezifikation
5. Du validierst gegen die Spezifikation, nicht gegen "funktioniert es?"

Wie wir spezifikations-getriebener hätten sein können

Hier sind konkrete Dinge, die wir anders hätten machen sollen:

1. Dokumentations-Konsultation zuerst erzwingen

Was wir gemacht haben: Gefragt "Wie pushe ich in ein bestehendes GitHub-Repo?" und ausprobiert, was die KI zuerst vorgeschlagen hat.

Was wir hätten tun sollen:

"Bevor du irgendetwas vorschlägst, durchsuche die offizielle Backstage-Dokumentation nach GitHub-Integrations-Actions. Liste alle verfügbaren Actions mit ihren vorgesehenen Anwendungsfällen auf und empfehle dann die beste Lösung."

Das erzwingt Verifikation vor der Implementierung. Kein Raten, kein Trial-and-Error.

2. Anforderungsdokumente vor dem Codieren erstellen

Was wir gemacht haben: Angefangen mit "mach Templates, die Dateien lokal speichern" und geschwenkt, als es nicht funktionierte.

Was wir hätten tun sollen:

"Ich möchte Kubernetes-Ressourcen durch Backstage erstellen. Sie müssen:

• Versionskontrolliert sein
• Automatisch auf Cluster angewendet werden
• In einer UI sichtbar sein
• Auditierbar sein

Erstelle ein Design-Dokument, das:

1. Architektur-Optionen auflistet
2. Trade-offs vergleicht
3. Einen Ansatz mit Begründung empfiehlt
4. Bekannte Einschränkungen dokumentiert

NUR NACHDEM ich das Design genehmigt habe, solltest du Code generieren."

3. Testpläne vor der Implementierung fordern

Was wir gemacht haben: Features gebaut, dann gemerkt, dass wir RBAC brauchen, dann nachgerüstet.

Was wir hätten tun sollen:

"Bevor du irgendeinen Code für das Automatisierungs-Skript schreibst, erstelle einen Testplan, der Folgendes abdeckt:

• Fresh-Cluster-Szenarien
• Fehlermodi für jede Komponente
• Sicherheitsanforderungen (RBAC, Secrets)
• Aufräum-Prozeduren

Zitiere für jeden Punkt die offizielle Dokumentations-Anforderung."

4. Lebendige Spezifikationen pflegen

Was wir gemacht haben: Direkt am Code iteriert. YAML geändert, Parameter angepasst, vor Ort debuggt.

Was wir hätten tun sollen: Eine Spezifikationsdatei pflegen, die aktualisiert wird, dann Implementierungen regenerieren:

 1# spec.md
 2
 3## GitHub-Integrations-Anforderungen
 4- Action: publish:github:pull-request (laut Backstage-Docs v1.2.3)
 5- Ziel: Bestehendes Repository
 6- Branch-Strategie: Feature-Branches
 7- Quelle: Link zur offiziellen Dokumentation
 8
 9## Wenn sich Anforderungen ändern:
101. Diese Spezifikation aktualisieren
112. KI bitten, Implementierung basierend auf aktualisierter Spezifikation zu regenerieren
123. Niemals generierten Code direkt bearbeiten

5. Spezifikationen versionieren und validieren

Was wir gemacht haben: Eine Konversation gehabt, die sich organisch entwickelt hat. Schwer zu reproduzieren.

Was wir hätten tun sollen:

Projektstruktur:
├── specs/
│   ├── v1-initial-requirements.md
│   ├── v2-added-gitops.md
│   ├── v3-added-rbac.md
├── implementations/
│   ├── template-v1.yaml (generiert aus Spezifikation v1)
│   ├── template-v2.yaml (generiert aus Spezifikation v2)
│   ├── template-v3.yaml (generiert aus Spezifikation v3)
└── validation/
    └── test-results-v3.md

Das macht die Evolution nachvollziehbar und reproduzierbar.

Der praktische Unterschied

KI-gestützt (was wir gemacht haben):

• Schneller als traditionelle Entwicklung
• Beinhaltet immer noch Trial-and-Error
• Kontext in Konversation behalten
• Schwer zu reproduzieren
• Spezifikationen implizit

Spezifikations-getrieben (was wir hätten tun sollen):

• Upfront-Design-Aufwand
• Minimales Trial-and-Error
• Spezifikationen explizit und versioniert
• Einfach zu reproduzieren
• KI validiert gegen autoritative Quellen

Wann welcher Ansatz Sinn macht

Nutze KI-gestützt wenn:

• Erkunden und Lernen
• Prototyping
• Du noch nicht genau weißt, was du willst
• Geschwindigkeit wichtiger ist als Reproduzierbarkeit

Nutze Spezifikations-getrieben wenn:

• Produktions-Systeme bauen
• In Teams arbeiten (Spezifikationen werden zu geteiltem Wissen)
• Du das Setup später reproduzieren musst
• Compliance und Auditierbarkeit wichtig sind
• Du technische Schulden minimieren möchtest

Unsere ehrliche Einschätzung

Wir haben enorm viel Zeit im Vergleich zur traditionellen Entwicklung gespart. Aber wir hätten noch mehr sparen und etwas Wartbareres bauen können, indem wir:

1. Dokumentations-Recherche vor der Implementierung erzwungen hätten
2. Design-Dokumente vor Code geschrieben hätten
3. Explizite Spezifikationen erstellt hätten
4. Spezifikationen als Source of Truth behandelt hätten
5. Die KI ihre Quellen hätten zitieren lassen

Durch die Einführung wirklich spezifikations-getriebener Entwicklung können wir KI-gestützte Workflows von "schnellerem Trial-and-Error" zu "präzisem, reproduzierbarem Engineering" erheben. Das ist die Zukunft des Platform Engineering, und wir freuen uns darauf, unseren Ansatz weiter zu verfeinern.