Vom Entwurf zum bestandenen Quality Gate.

1. Neues Projekt mit dem Wizard

Für dieses Tutorial legst du Stack und Prüfwerkzeuge selbst fest. Klick unter Projekte auf "Ausführlicher Assistent" (oder öffne /wizard und klick "Neuen Assistenten starten"). Der kurze Weg ohne diese Details ist "Neues Projekt" → Schnellstart (Name, Art, Beschreibung, siehe Schnellstart).

1. Schritt 1 – Zielplattform: Web.
2. Schritt 2 – Backend: wähle "Modernes Spring Boot Backend".
3. Schritt 3 – Frontend(s): keins (reine API).
4. Schritt 4 – Fragen: Trage realistische Werte ein:
   • Projekttitel: Telefonbuch-API
   • Vision: "REST-API für ein einfaches Telefonbuch mit CRUD-Endpoints und Postgres-Persistenz."
   • Java-Version: 25
   • Basis-Paketname: io.beispiel.telefonbuch
   • Datenbank: PostgreSQL
   • Architektur: hexagonal
   • Sprache: Deutsch
5. Schritt 5 – Quality-Gates: Schalte ArchUnit und OWASP Dependency-Check an. Trivy lass aus (Trivy ist für Container-Builds gedacht; Playwright erscheint nur mit einem Frontend).
6. Schritt 6 – Zusammenfassung: kontrolliere alle Werte sowie die Kosten-Schätzung und klicke "Projekt anlegen und bearbeiten".

Du landest im Projekt-Editor mit allen Feldern bereits sinnvoll vorbelegt. Der Wizard hat aus deinen Antworten u.a. Folgendes gemacht:

• technologyPreferences: "Template: Modernes Spring Boot Backend. Spring Boot <Version>. Java 25."
• architecturePreferences: "Datenbank: PostgreSQL. Architektur-Stil: hexagonal. Basis-Paket: io.beispiel.telefonbuch."
• nonfunctionalRequirements: "Aktivierte Quality-Gates: …" (ArchUnit, OWASP Dependency-Check)

2. Artefakte prüfen und justieren

Speichere im Projekt-Editor und klick auf der Projektseite unter "Technische Einstellungen" (in „Einfach“ eingeklappt) auf "Markdown-Artefakte generieren". Die Plattform erzeugt sechs Dateien (anzusehen und zu bearbeiten unter "Artefakte anzeigen"). Lies sie einmal durch:

1. PROJECT.md — die Charta. Ist die Vision klar? Stimmt die Zielgruppe?
2. INSTRUCTIONS.md — die konkrete Arbeitsanweisung an den Agenten. Das ist die wichtigste Datei. Wenn hier Tippfehler oder Doppeldeutigkeiten drin sind, übernimmt der Agent sie eins zu eins.
3. AGENTS.md — die Rollenbeschreibung des Teams, im Workspace mit den Engineering-Guardrails davor.
4. WORKFLOW.md — Phasenmodell und Approval-Punkte.
5. DEFINITION_OF_DONE.md — wann ist der Lauf fertig?
6. README.md — Lese-Einstieg für den Agenten in den Workspace.

Korrigiere alles, was unklar ist. Beispiel: Wenn in INSTRUCTIONS.md steht "erstelle CRUD-Endpoints", ergänze konkret, welche Felder eine Person hat (Name, Telefonnummer, E-Mail). Je präziser, desto kleiner die Wahrscheinlichkeit für Halluzinationen.

3. Planen – Plan-Lauf erzeugt das Backlog

Statt sofort Code zu erzeugen, lässt du den Agenten zuerst planen. Öffne im Projekt "Backlog / Pläne" (Projektseite, unter "Technische Einstellungen"):

1. Fokus (optional): z.B. Skelett, Persistenz, CRUD-Endpoints, Tests, Doku — kleine, einzeln testbare Pakete.
2. Klick "Plan-Lauf starten". Die Fabrik legt den Plan-Lauf an und startet ihn sofort; den Planungsauftrag formuliert sie selbst.
3. Vor EXECUTION gibst du ihn auf der Laufseite mit "Freigeben und fortsetzen" frei (siehe Schritt 6).

Ein Plan-Lauf schreibt keinen Produktivcode. Er legt im Workspace unter plans/ Markdown-Dateien (plans/NNNN-*.md) an — eine pro Arbeitspaket. Nach dem Lauf indexiert die Plattform sie als Backlog-Items im Status PROPOSED.

4. Auswählen – Backlog-Item aktivieren

Öffne "Backlog / Pläne" im Projekt. Du siehst die aus dem Plan-Lauf erzeugten Items, jeweils mit Titel und Status. Such dir das erste, kleinste Paket aus — typischerweise "Skelett anlegen" — und klick "Aktivieren".

"Aktivieren" legt sofort einen Build-Lauf an, dessen Ziel der Plan ist, und startet ihn. Ein Item wird erst DONE, wenn sein Build-Lauf tatsächlich gemerged ist; so liest du den Fortschritt jederzeit am Backlog ab. Abhängigkeiten zwischen Items pflegst du mit "+ Blocker".

5. Bauen – Build-Lauf auf eigenem Branch

Das aktivierte Backlog-Item hat bereits einen Build-Lauf gestartet. Alternativ legst du einen Build-Lauf von Hand an — halte ihn klein. Navigiere zu /runs/new (oder auf der Projektseite in „Experte“ "Lauf mit allen Optionen anlegen"; das Projekt ist dann vorbelegt). Der kurze Weg ist "Nächster Auftrag" auf der Projektseite: Auftrag eintragen, "Bauen":

1. Projekt: Telefonbuch-API.
2. Titel des Laufs: Skelett anlegen (leer gelassen nimmt die Fabrik die erste Zeile des Auftrags)
3. Auftrag: ein konkreter Vorschlag wie dieser:

   Lege das initiale Maven-Projekt mit Spring Boot 4.x an.
   Erzeuge:
   - pom.xml mit spring-boot-starter-web, spring-boot-starter-data-jpa, postgresql, h2 (test)
   - Application-Klasse mit @SpringBootApplication
   - application.yml mit Postgres-Config (lokal) und H2 (test-Profil)
   - ein einfaches Person-Entity mit id, name, phone
   - ein PersonRepository als Spring Data JPA Repository
   - einen REST-Controller mit GET /persons (return all)
   - Smoke-Test mit @SpringBootTest, der den Context lädt
   - README mit "wie starte ich das" und "wie teste ich das"

4. KI-Werkzeug (Adapter): claude (Default aus den Einstellungen). Das Modell kommt aus der Agentenrolle im Team bzw. dem Rollen-Default.
5. Klick "Bauen" — der Lauf wird angelegt und startet sofort. ("Nur anlegen" legt ihn als Entwurf an; dann startest du ihn auf der Laufseite mit "Lauf starten".)

Der Build-Lauf arbeitet im persistenten Workspace des Projekts und legt für seine Änderungen einen eigenen Branch sdlc/run-<id8> an (die ersten acht Zeichen der Lauf-ID). So bleibt main sauber, und jeder Lauf ist als abgegrenzte Branch-Historie nachvollziehbar. Pro Projekt läuft dabei immer nur ein Lauf gleichzeitig.

6. Phasen-Approvals durchklicken

Während der Lauf arbeitet, durchläuft er sieben Phasen. Bei kritischen Übergängen wartet die Plattform auf deine bewusste Freigabe:

Die Knöpfe stehen auf der Laufseite unter Aktionen (nur die, die im aktuellen Stand gehen; der Kasten "Was jetzt?" nennt den nächsten Schritt): "Freigeben und fortsetzen" (optional mit Begründung) oder "Abbrechen" mit Grund — dann steht der Lauf auf Abgebrochen (CANCELLED). Browser-Notifications kannst du unten rechts auf der Laufseite aktivieren; sie feuern bei WAITING_FOR_APPROVAL oder Lauf-Ende.

7. Logs lesen, Git-Diff anschauen, Approval mit Inline-Diff

Während der EXECUTION-Phase strömen die Claude-Code-Outputs live in die Log-Ansicht ("Logs anzeigen"). Achte zum Beispiel auf:

• "Reading PROJECT.md..." — Agent hat die Charta gelesen.
• "Reading INSTRUCTIONS.md..." — Agent hat die Anweisungen gelesen.
• "Creating pom.xml..." — Erste Datei wird geschrieben.
• "Starte automatische Korrektur (Versuch 1/2)" — der Build war rot, die Fabrik speist das Feedback ein (siehe Schritt 8).

Unter "Git-Status" siehst du Branch, HEAD, Working Tree und die letzten Commits. Die Commits erstellt die Fabrik selbst (der Agent darf nicht committen).

Bei WAITING_FOR_APPROVAL blendet die Detail-View den git diff seit Lauf-Start direkt ein — kein Wechsel ins Terminal nötig. Wenn es passt: Freigeben und fortsetzen mit kurzer Begründung.

8. Selbstkorrektur – automatische Feedback-Wiederholung

Geht der Build in der VALIDATION-Phase auf Rot (Kompilierfehler, fehlgeschlagene Tests), bricht der Lauf nicht ab. Stattdessen wechselt er auf NEEDS_CORRECTION, und die Plattform startet die Selbstkorrektur:

1. Die Plattform sammelt die Fehlerausgabe von mvn verify (Compiler- und Test-Logs).
2. Sie baut daraus einen Korrektur-Prompt und schickt ihn an den Agenten — der Lauf geht zurück auf RUNNING.
3. Der Agent repariert im selben Branch, danach läuft mvn verify erneut.

Diese Schleife ist begrenzt: nach zwei automatischen Korrekturversuchen gibt die Plattform auf und lässt den Lauf auf NEEDS_CORRECTION stehen, damit du eingreifst. So verbrennt eine hartnäckig rote Aufgabe nicht endlos Tokens.

9. Quality Gate – aus, beratend oder blockierend

Nach erfolgreichem Build läuft das Quality Gate automatisch als Teil der Pipeline (Modus advisory, Default). Auf der Laufseite unter "Quality-Gate" siehst du das Ergebnis oder stößt es mit "Quality-Gate ausführen" erneut an. Es ruft sechs Reviewer auf (bei gebundener, freigegebener Spec zusätzlich spec-conformance):

• aider-review — ruft die Aider-CLI im read-only-Modus auf, sucht nach Smells.
• dependency-scan — Trivy-Scan auf CVEs und Lizenzverstöße in Abhängigkeiten.
• claude-review — ruft Claude Code im read-only-Modus auf, lässt das Modell selbst kritisieren.
• security-reviewer — statische Heuristik: Hardcoded Passwörter, schwache Krypto, SQL-Injection-Patterns, …
• architecture-reviewer — prüft Schichten- und Modulgrenzen anhand der Artefakte.
• hallucination-reviewer — sucht erfundene Methoden, Pakete oder API-Aufrufe.

Pro Reviewer siehst du Findings mit Severity (LOW / MEDIUM / HIGH / CRITICAL) und Confidence-Score. Das aggregierte Verdict ist eines von:

Wie der Quality Gate wirkt, steuerst du über den Modus (Seite Leitplanken, /leitplanken: Stufe Ausgewogen = advisory, Vorsichtig = blocking; in „Experte“ als Einzelwert; über Policy-as-Code übersteuerbar):

• off: der Quality Gate läuft gar nicht; der Lauf gilt allein nach grünem Build als fertig.
• advisory (Default): die Reviewer laufen und melden Findings, blockieren aber nichts — ein FAILED-Verdict ist nur ein Hinweis. Gut zum Einstieg.
• blocking: ein FAILED- oder ERROR-Verdict erzeugt Feedback und startet die Korrekturschleife; geliefert wird erst nach bestandenem Gate.

Die Policy bestimmt die Schärfe: lenient (Default) blockiert nur CRITICAL, strict blockiert HIGH und CRITICAL und verlangt Security- und Architektur-Review. Unabhängig davon sind SECURITY/HIGH, SECURITY/CRITICAL und ARCHITECTURE/CRITICAL immer blockierend. Reviewer-Crashes erscheinen als ERROR — sie werden nicht verschluckt; eine fehlende Reviewer-CLI ergibt SKIPPED.

Typische Findings beim ersten Lauf:

• "Hardcoded password in application.yml" — der Agent hat ein Default-Postgres-Passwort eingebaut. Fix: Property mit ${POSTGRES_PASSWORD} referenzieren.
• "Missing test coverage" — der Smoke-Test deckt nur den Context-Load ab. Fix: Folge-Lauf mit Ziel "Tests schreiben".

10. Liefern – Push + Pull-Request oder lokaler Merge

Ist der Build grün (und im Modus blocking auch das Quality Gate), liefert die Fabrik das Ergebnis automatisch aus. Was dabei passiert, hängt davon ab, ob du ein Git-Remote samt GitHub-Token hinterlegt hast.

Variante A: mit Git-Remote + GitHub-Token → Pull-Request

1. Hinterlege unter /integrations auf der Karte GitHub ein Personal Access Token (Scope repo) und auf der Projektseite das Git-Remote (Push & PR) (z.B. git@github.com:dein-user/telefonbuch-api.git; der Host muss in SOFTWAREFABRIK_GIT_ALLOWED_HOSTS stehen, Default github.com).
2. Der nächste erfolgreiche Build-Lauf pusht seinen Branch sdlc/run-<id8> zum Remote und öffnet einen Pull-Request gegen den Base-Branch — ohne weiteren Klick.
3. Du reviewst den PR auf GitHub wie jeden anderen und mergst ihn dort.

Variante B: ohne Remote → lokaler Merge

Ohne Remote oder Token fällt die Plattform auf einen lokalen Merge zurück: der Branch sdlc/run-<id8> wird im persistenten Workspace nach main gemergt. Das Ergebnis liegt dann lokal vor, und du kannst es später selbst pushen (siehe Schritt 13).

11. Lernen – Project-Memory

Das Project-Memory hält Entscheidungen, Konventionen und Learnings fest. Du pflegst es im Projekt unter "Memory"; aktualisiert ein Agent die Datei MEMORY.md im Workspace, übernimmt die Fabrik das nach dem Lauf zurück.

Vor jedem Lauf spiegelt die Plattform das Memory als MEMORY.md in den Workspace, und der Lauf-Auftrag nennt die Datei ausdrücklich. So wiederholt der Agent nicht dieselben Fehler, bleibt bei einmal gewählten Mustern (z.B. "Passwörter immer als Env-Var, nie hardcoded") und baut auf dem bereits Erreichten auf, statt bei null anzufangen.

12. Weiter – Auto-Folgevorschläge schließen den Loop

Ein Mega-Lauf, der alles auf einmal macht, geht in der Praxis selten gut. Viel besser: kleine, fokussierte Folge-Läufe. Genau dafür gibt es die Auto-Folgevorschläge (Einrichtung → Einstellungen, unter "Erweitert" → Läufe → "Auto-Folgevorschläge nach Build-Lauf", Default aus): Nach jedem erfolgreichen Build-Lauf startet die Fabrik automatisch einen Plan-Lauf, der die nächsten Schritte als plans/*.md ins Backlog legt. Mögliche Vorschläge:

1. Vorschlag: "Schreibe Unit-Tests für PersonRepository und PersonController, decke alle CRUD-Operationen ab. Ziel: ≥ 85 % Line-Coverage."
2. Vorschlag: "Behebe das Quality-Gate-Finding 'Hardcoded password' und ersetze den Wert durch eine Env-Var-Referenz in application.yml."
3. Vorschlag: "Ergänze README.md um eine Sektion 'Deployment' mit docker-compose-Beispiel und eine Sektion 'API-Beispiele' mit curl-Aufrufen pro Endpoint."

Die Vorschläge erscheinen im Backlog (Status PROPOSED) — und du stehst wieder bei Schritt 4 (Auswählen). Damit schließt sich der Loop: planen → auswählen → bauen → korrigieren → prüfen → liefern → lernen → weiter. Jeder Durchlauf nutzt denselben persistenten Workspace und das gewachsene Project-Memory.

13. Workspace inspizieren & exportieren

Der Workspace gehört dem Projekt und liegt unter ./workspaces/<projekt-slug>/workspace/ (bzw. unter dem in den Settings konfigurierten Workspace-Wurzelpfad). Wechsle dorthin und schau dir an, was der Agent gebaut hat:

cd ./workspaces/<projekt-slug>/workspace
ls -la
git branch -a
git log --oneline -20
git diff HEAD~5 HEAD

Du kannst von hier aus weiterarbeiten — eigene Commits machen, in einen Remote pushen, branchen, mergen. Die Plattform fasst diesen Workspace nicht mehr an, solange du nicht einen weiteren Lauf startest.

Hast du in Schritt 10 lokal gemergt (Variante B), kannst du das Ergebnis jederzeit von Hand exportieren:

# in ein neues GitHub-Repo schieben:
cd ./workspaces/<projekt-slug>/workspace
git remote add origin git@github.com:dein-user/telefonbuch-api.git
git push -u origin main

Tipps für gute Prompts und Lauf-Ziele

• Konkret statt allgemein. "CRUD für Person" ist schwach. "GET /persons (Liste), GET /persons/{id} (Detail), POST /persons (anlegen mit Body {name, phone}), PUT /persons/{id}, DELETE /persons/{id}" ist stark.
• Definition of Done formulieren. "Build muss grün sein", "Tests müssen ≥ 85 % Line- und ≥ 81 % Branch-Coverage haben", "README muss API-Beispiele enthalten". Das macht den Quality Gate erst sinnvoll.
• Beispieldaten mitgeben. Wenn der Agent eine Migration schreiben soll, gib ein Beispiel mit: "Beispiel-Person: Max Mustermann, +49 30 12345678, max@example.org". Das verhindert generische Lorem-Ipsum-Daten.
• Was NICHT zu tun ist auch sagen. "Verwende keine externen Libraries außer Spring Boot Starters" verhindert, dass der Agent eine exotische Lib einbaut, die du dann nicht warten willst.
• Iterativ denken. Lieber drei Läufe à 10 Minuten als ein Lauf à 30 Minuten. Du kannst dazwischen korrigieren.

Wenn was schiefgeht – Debug-Strategien

Was du jetzt kannst & weitere Schritte

• Projekt strukturiert anlegen, beschreiben, in den Lauf schicken.
• Mit einem Plan-Lauf ein Backlog erzeugen und Items aktivieren.
• Build-Läufe auf eigenem Branch laufen lassen und live mitverfolgen.
• Vor Approval prüfen, was der Agent geändert hat.
• Selbstkorrektur bei rotem Build nutzen und den Quality Gate (aus/beratend/blockierend) anwenden.
• Ergebnisse per Pull-Request oder lokalem Merge ausliefern.
• Aus Project-Memory und Auto-Folgevorschlägen den Loop schließen.

Nächste Schritte: Begriffe und Hilfe für Glossar und mentales Modell, Architektur für den Unterbau, Preise für Stufen und Grenzen, oder die FAQ für typische Stolperfallen.