Vom Entwurf zum bestandenen Quality Gate.

1. Anthropic-API-Key konfigurieren

Du hast zwei Wege, den Key in die Plattform zu bekommen:

Variante A: über die UI (empfohlen)

1. Klick im Header oben rechts auf dein Benutzer-Icon und wähle Integrationen (oder navigiere zu /integrations).
2. Auf der Karte Anthropic klick auf Schlüssel setzen bzw. "Anthropic API-Key hinzufügen".
3. Trage den Key (beginnt mit sk-ant-...) ein und speichere.

Der Key wird mit AES-GCM unter dem Master-Key aus deiner .env verschlüsselt in der Datenbank gespeichert. Im Klartext sieht ihn danach niemand mehr.

localhost:8080/integrations

Variante B: per Env-Variable (Air-Gap)

Wenn du den Key als Env-Var setzen willst (z.B. für Air-Gap-Setups), füge in deine .env hinzu:

SOFTWAREFABRIK_ANTHROPIC_API_KEY=sk-ant-...

Dann: docker compose down && docker compose up -d.

2. Default-Adapter auf claudecode stellen

Damit du nicht bei jedem Run den Adapter manuell wählen musst, setzt du den globalen Default:

1. Klick oben rechts auf Einstellungen (oder navigiere zu /einstellungen) und wähle den Reiter Adapter.
2. Setze Default-Execution-Adapter (execution.adapter.default) auf claudecode.
3. Setze Default-Modell für Claude Code (execution.claudecode.model) auf claude-sonnet-5 (gutes Preis-Leistungs-Verhältnis für die meisten Tasks). Für tiefere Architektur-Aufgaben ist claude-opus-4-8 stärker, aber teurer.
4. Speichern.

Die Änderung wirkt sich nach maximal 5 Minuten aus (TTL-Cache). Wenn du es sofort sehen willst, klick unten auf der Settings-Seite auf "Cache jetzt invalidieren".

3. Container-Sandbox aktivieren (optional)

Wenn du Docker auf dem Host hast und den Agent isoliert laufen lassen willst:

1. Einstellungen → execution.sandbox.variant → container.
2. Optional: execution.sandbox.image → eigenes Image mit Claude-CLI vorinstalliert.

Fehlt Docker im PATH, fällt die Plattform mit Log-Warnung auf die lokale Sandbox zurück.

4. Neues Projekt mit dem Wizard

Klick auf "Neues Projekt mit Assistent anlegen" oder navigiere zu /wizard:

1. Schritt 1 – Template: wähle "Modernes Spring Boot Backend".
2. Schritt 2 – 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
   • Datenbank: Postgres
   • Architektur: hexagonal
   • Sprache: Deutsch
3. Schritt 3 – Quality Gates: Schalte ArchUnit und OWASP Dependency-Check an. Trivy und Playwright lass aus (Trivy ist für Container-Builds gedacht, Playwright für Frontends).
4. Schritt 4 – Zusammenfassung: kontrolliere alle Werte sowie die Kosten-Schätzung und klicke "Projekt anlegen".

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

• technologyPreferences: "Java 25, Spring Boot 4.x, Maven, Postgres 16"
• architecturePreferences: "Hexagonale Architektur (domain / application / web / infrastructure)"
• qualityGates: "ArchUnit-Layer-Tests, OWASP Dependency-Check"

5. Artefakte prüfen und justieren

Klick im Projekt-Editor auf "Markdown-Artefakte generieren". Die Plattform erzeugt sechs Dateien. 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. Bei Bedarf preferredModel pro Rolle anpassen.
4. WORKFLOW.md — Phasenmodell und Approval-Punkte.
5. DEFINITION_OF_DONE.md — wann ist der Run 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.

6. Planen – Plan-Run erzeugt das Backlog

Statt sofort Code zu erzeugen, lässt du den Agenten zuerst planen. Klick auf "Neuer Run" (/runs/new) und wähle als Run-Modus "Planen" statt "Bauen":

1. Projekt: Telefonbuch-API.
2. Run-Modus: Planen.
3. Ziel:

   Erstelle einen Umsetzungsplan für die Telefonbuch-API.
   Zerlege das Vorhaben in kleine, einzeln testbare Arbeitspakete
   (Skelett, Persistenz, CRUD-Endpoints, Tests, Doku) und schreibe
   für jedes Paket eine Datei nach plans/ mit Titel, Ziel und
   Definition of Done.

4. Run starten wie gewohnt: "Auf READY setzen", dann "Run starten".

Ein Plan-Run schreibt keinen Produktivcode. Er legt im Workspace unter plans/ mehrere Markdown-Dateien an — eine pro Arbeitspaket. Die Plattform liest diese Dateien aus und macht aus jeder ein Backlog-Item mit Titel, Ziel und Status OPEN.

7. Auswählen – Backlog-Item aktivieren

Öffne den Reiter "Backlog" im Projekt. Du siehst die aus dem Plan-Run erzeugten Items, jeweils mit Titel, Ziel und Status. Such dir das erste, kleinste Paket aus — typischerweise "Skelett anlegen" — und klick "Aktivieren".

Das aktivierte Item wird zum Ziel des nächsten Build-Runs: die Plattform übernimmt sein Ziel und seine Definition of Done direkt ins Run-Formular. Erledigte Items wandern später auf DONE, sodass du den Fortschritt jederzeit am Backlog abliest.

8. Bauen – Build-Run auf eigenem Branch

Aus dem aktivierten Backlog-Item startest du einen Build-Run. Halte ihn klein. Navigiere zu /runs/new (oder nutze "Aus Backlog-Item bauen"):

1. Projekt: Telefonbuch-API.
2. Run-Modus: Bauen.
3. Run-Titel: Skelett anlegen
4. Ziel: aus dem Backlog-Item vorbefüllt. Bei einem manuellen Run nimm einen konkreten Vorschlag wie diesen:

   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"

5. Adapter: claudecode (Default-Settings). Modell: claude-sonnet-5.
6. Klick "Run anlegen", dann "Auf READY setzen" und "Run starten".

Der Build-Run arbeitet im persistenten Workspace des Projekts und legt für seine Änderungen einen eigenen Branch sdlc/run-<run-id> an. So bleibt main sauber, mehrere Runs kollidieren nicht, und jeder Run ist als abgegrenzte Branch-Historie nachvollziehbar.

9. Phasen-Approvals durchklicken

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

Approval-Knöpfe erscheinen rechts neben der aktuellen Phase. Du kannst Freigeben oder Ablehnen klicken — bei Ablehnung wird der Run auf CANCELED gesetzt. Browser-Notifications kannst du oben rechts aktivieren; sie feuern bei WAITING_FOR_APPROVAL oder Run-Ende.

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

Während der EXECUTION-Phase strömen die Claude-Code-Outputs live in den Log-Bereich (Tab Logs). Achte auf:

• "Reading PROJECT.md..." — Agent hat die Charta gelesen.
• "Reading INSTRUCTIONS.md..." — Agent hat die Anweisungen gelesen.
• "Creating pom.xml..." — Erste Datei wird geschrieben.
• "git commit -m 'chore: initial scaffold'" — Erster Commit.

Auf der rechten Seite siehst du die Git-Ansicht mit Branches, Commits und einem Diff-Viewer. Klick auf einen Commit, um den Diff zu sehen. Das ist die ehrlichste Sicht auf das, was der Agent tatsächlich gemacht hat — keine Marketingsprache, nur Code.

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

11. Selbstkorrektur – automatische Feedback-Wiederholung

Geht der Build in der VALIDATION-Phase auf Rot (Kompilierfehler, fehlgeschlagene Tests), bricht der Run 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 Run geht zurück auf RUNNING.
3. Der Agent repariert im selben Branch, danach läuft mvn verify erneut.

Diese Schleife ist begrenzt: nach einer in den Settings konfigurierbaren Zahl von Korrekturversuchen gibt die Plattform auf und lässt den Run auf NEEDS_CORRECTION stehen, damit du eingreifst. So verbrennt eine hartnäckig rote Aufgabe nicht endlos Tokens.

12. Quality Gate – aus, beratend oder blockierend

Nach COMPLETION klick auf den Reiter "Quality Gate". Du startest die fünf Reviewer:

• aider-review — ruft die Aider-CLI im read-only-Modus auf, sucht nach Smells.
• claude-review — ruft Claude Code im read-only-Modus auf, lässt das Modell selbst kritisieren.
• security — statische Heuristik: Hardcoded Passwörter, schwache Krypto, SQL-Injection-Patterns, …
• architecture-reviewer — prüft Schichten- und Modulgrenzen anhand der Artefakte.
• hallucination-review — 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 streng der Quality Gate wirkt, steuerst du über die Policy (Einstellungen → Quality Gate, pro Projekt überschreibbar):

• Aus: der Quality Gate läuft gar nicht; der Run gilt allein nach grünem Build als fertig.
• Beratend: die Reviewer laufen und melden Findings, blockieren aber nichts — ein FAILED-Verdict ist nur ein Hinweis. Gut zum Einstieg.
• Blockierend: ein FAILED-Verdict verhindert die Lieferung (Schritt 13). Erst wenn der Gate auf PASSED oder WARNING steht, darf gepusht oder gemergt werden.

Unabhängig von der Policy sind SECURITY/HIGH und ARCHITECTURE/CRITICAL immer blockierend — sie kippen das Verdict auf FAILED. Reviewer-Crashes erscheinen als ERROR — sie werden nicht verschluckt, sondern gemeldet.

Typische Findings beim ersten Run:

• "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-Run mit Ziel "Tests schreiben".

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

Steht der Quality Gate (je nach Policy) auf Grün, lieferst du das Ergebnis 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 im Projekt das Git-Remote (z.B. git@github.com:dein-user/telefonbuch-api.git).
2. Klick beim abgeschlossenen Run auf "Liefern" bzw. "Pull-Request öffnen".
3. Die Plattform pusht den Branch sdlc/run-<run-id> zum Remote und öffnet einen Pull-Request gegen main — mit dem Run-Ziel als Titel und einer Zusammenfassung (Diff, Quality-Gate-Verdict) als Beschreibung.
4. 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-<run-id> wird im persistenten Workspace nach main gemergt. Das Ergebnis liegt dann lokal vor, und du kannst es später selbst pushen (siehe Schritt 16).

14. Lernen – Project-Memory

Jeder abgeschlossene Run hinterlässt Spuren im Project-Memory: getroffene Entscheidungen, wiederkehrende Quality-Gate-Findings, Konventionen, die der Agent etabliert hat. Du findest es im Reiter "Memory" des Projekts.

Beim nächsten Build-Run liest die Plattform dieses Memory aus und hängt es an den Prompt an. 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.

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

Ein Mega-Run, der alles auf einmal macht, geht in der Praxis selten gut. Viel besser: kleine, fokussierte Folge-Runs. Genau dafür schlägt die Plattform nach jedem Run automatisch Folge-Items vor — abgeleitet aus offenen Quality-Gate-Findings, der Definition of Done und dem restlichen Backlog. Beispiele:

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."

Du übernimmst einen Vorschlag mit einem Klick ins Backlog (Status OPEN) — und stehst wieder bei Schritt 7 (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.

16. Workspace inspizieren & exportieren

Der Workspace liegt unter ./workspaces/<run-id>/ (oder dem in den Settings konfigurierten Pfad). Wechsle dorthin und schau dir an, was der Agent gebaut hat:

cd ./workspaces/<run-id>
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 Run startest.

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

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

Tipps für gute Prompts und Run-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 Runs à 10 Minuten als ein Run à 30 Minuten. Du kannst dazwischen korrigieren.

Wenn was schiefgeht – Debug-Strategien

Was du jetzt kannst & weitere Schritte

• Projekt strukturiert anlegen, beschreiben, in den Run schicken.
• Mit einem Plan-Run ein Backlog erzeugen und Items aktivieren.
• Build-Runs 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: Einführung für Glossar und mentales Modell, Architektur für den Unterbau, Lizenzmodell für Tiers und Limits, oder die FAQ für typische Stolperfallen.