Tutorial · v0.8.1

Erster Workflow gegen Claude Code

Dieses Tutorial zeigt dir den vollständigen Plattform-Workflow gegen den echten Claude-Code-Adapter — vom API-Key bis zum bestandenen Quality Gate. Plane etwa 45 Minuten ein. Wenn du die Plattform noch gar nicht installiert hast, mach erst den Schnellstart und komm zurück.

Voraussetzungen

Schnellstart durchgespielt: Plattform läuft lokal auf http://localhost:8080, du bist als admin eingeloggt.
Anthropic-API-Key: einen Key mit Zugriff auf claude-sonnet-4-6 oder claude-opus-4-7. Den Key generierst du unter console.anthropic.com. Ein Key kostet pro Token, also für ein erstes Tutorial reichen ein paar Euro Guthaben.
Claude-Code-CLI installiert: die Plattform ruft claude als Subprozess auf. Installation siehe Claude-Code-Dokumentation. Prüfe mit claude --version.
Claude-Code mindestens einmal interaktiv angemeldet: die Plattform nutzt deine lokal gespeicherten Credentials.
JDK 21 oder 25 lokal installiert: der Workspace-Build (mvn verify) braucht ein lokales JDK. Prüfe mit java -version.
Maven (≥ 3.9): prüfe mit mvn -v. Alternativ kann der Wrapper ./mvnw aus dem generierten Workspace genutzt werden.

Schritt 1: Anthropic-API-Key konfigurieren

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

Variante A: über die UI (empfohlen)

Klick im Header oben rechts auf dein Benutzer-Icon.
Wähle "Integrationen" aus dem Popover (oder navigiere zu /integrations).
Klick auf "Anthropic API-Key hinzufügen".
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 niemand mehr.

Variante B: per Env-Variable

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. Die UI-Variante ist aber sauberer, weil sie einen Audit-Log-Eintrag erzeugt.

Schritt 2: Default-Adapter auf `claudecode` stellen

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

Klick oben rechts auf "Einstellungen" (oder navigiere zu /einstellungen).
Wähle den Reiter "Adapter".
Setze "Default-Execution-Adapter" auf claudecode.
Setze "Default-Modell für Claude Code" auf claude-sonnet-4-6 (gutes Preis-Leistungs-Verhältnis für die meisten Tasks). Für tiefere Architektur-Aufgaben ist claude-opus-4-7 stärker, aber teurer.
Speichern.

Die Änderung wirkt sich nach maximal 5 Minuten aus (TTL-Cache). Wenn du es sofort sehen willst, kannst du in der UI auf "Cache jetzt invalidieren" klicken — der Knopf liegt unten auf der Settings-Seite.

Audit-Trail: Jede Setting-Änderung erzeugt einen Eintrag in audit_event. Du siehst in der Settings-UI direkt unter dem Wert, wer ihn zuletzt geändert hat (User-Subject + Timestamp).

Schritt 3: Neues Projekt mit dem Wizard

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

Schritt 1 — Template: wähle "Modernes Spring Boot Backend".
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: 21
- Datenbank: Postgres
- Architektur: hexagonal
- Sprache: Deutsch
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).
Schritt 4 — Zusammenfassung: kontrolliere alle Werte 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 21, Spring Boot 3.x, Maven, Postgres 16"
architecturePreferences: "Hexagonale Architektur (domain / application / web / infrastructure)"
qualityGates: "ArchUnit-Layer-Tests, OWASP Dependency-Check"

Drafts überleben Restart: Wenn dein Browser abstürzt oder du die Plattform neu startest, ist dein Wizard-Fortschritt unter wizard_draft gespeichert. Beim nächsten Aufruf von /wizard bietet die Plattform "Entwurf fortsetzen" an.

Schritt 4: Artefakte prüfen und justieren

Klick im Projekt-Editor auf "Markdown-Artefakte generieren". Die Plattform erzeugt sechs Dateien. Lies sie einmal durch:

PROJECT.md — die Charta. Ist die Vision klar? Stimmt die Zielgruppe?
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.
AGENTS.md — die Rollenbeschreibung des Teams. Bei Bedarf preferredModel pro Rolle anpassen.
WORKFLOW.md — Phasenmodell und Approval-Punkte.
DEFINITION_OF_DONE.md — wann ist der Run fertig?
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.

Tipp: Stelle dir vor, du übergibst den Auftrag an einen externen Entwickler, den du nur per Dokument briefst. Lass keine impliziten Annahmen drin.

Schritt 5: Erster Run – Skelett anlegen

Halte den ersten Run klein. Klick auf "Neuer Run" oder navigiere zu /runs/new:

Projekt: wähle Telefonbuch-API.
Run-Titel: Skelett anlegen

Ziel: Verwende einen konkreten Vorschlag wie diesen:

Lege das initiale Maven-Projekt mit Spring Boot 3.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"

Adapter: claudecode (Default-Settings).
Modell: claude-sonnet-4-6.
Klick "Run anlegen".

Der Run ist im Status DRAFT. Klick "Auf READY setzen", dann "Run starten".

Schritt 6: Phasen-Approvals durchklicken

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

Phase	Was passiert	Approval?
`PROMPT_ASSEMBLY`	Plattform liest `PROJECT.md` + `INSTRUCTIONS.md` und baut den Initial-Prompt.	Nein, läuft automatisch.
`WORKSPACE_PREPARATION`	Workspace-Verzeichnis anlegen, `git init`, Artefakte hineinkopieren, initialer Commit.	Nein, automatisch.
`EXECUTION`	Plattform startet `claude --print <prompt>` im Workspace. Agent schreibt Files, macht Commits.	Ja (Default-Policy). Du klickst "Freigeben", bevor der Agent loslegt.
`VALIDATION`	Plattform startet `mvn verify` im Workspace. Build und Tests laufen.	Nein, automatisch.
`COMPLETION`	Bei grünem Build: Status `COMPLETED`. Bei rotem Build: `NEEDS_CORRECTION`.	Ja. Du bestätigst, ob das Ergebnis akzeptabel ist.

Approval-Knöpfe erscheinen rechts neben der aktuellen Phase. Du kannst Freigeben oder Ablehnen klicken — bei Ablehnung wird der Run auf CANCELED gesetzt.

Schritt 7: Logs lesen, Git-Diff anschauen

Während der EXECUTION-Phase strömen die Claude-Code-Outputs live in den Log-Bereich. 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.

Live-Streaming via SSE: Die Logs nutzen Server-Sent Events. Wenn die Verbindung kurz wegbricht (z.B. WLAN-Wechsel), reconnectet der Browser nach 5 Sekunden automatisch und zeigt die letzten 50 Zeilen nochmal — keine Lücke.

Schritt 8: Quality Gate

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:

PASSED WARNING FAILED SKIPPED ERROR

Sonderregeln: SECURITY/HIGH und ARCHITECTURE/CRITICAL sind immer blockierend, unabhängig von der Policy-Einstellung. 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".

Schritt 9: Folge-Runs aufbauen

Ein Mega-Run, der alles auf einmal macht, geht in der Praxis selten gut. Viel besser: kleine, fokussierte Folge-Runs. Auf der Run-Liste siehst du oben den Knopf "Neuer Run aus letztem Setup". Drei Klicks, dann:

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

Jeder dieser Runs nutzt denselben Workspace und schreibt in denselben Git-Branch. Du kannst nach jedem Run-Ende den Quality Gate erneut starten, um zu sehen, ob die Findings weniger werden.

Schritt 10: Workspace inspizieren

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

Wenn dir das Ergebnis gefällt, kannst du den Workspace 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 ≥ 80 % 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

Symptom	Ursache	Lösung
`claude: command not found`	Plattform findet die CLI nicht im PATH.	Setze in den Settings unter Adapter den absoluten Pfad: `/usr/local/bin/claude` (Linux/macOS) oder `C:\Users\<user>\AppData\Local\claude\claude.exe` (Windows). Alternativ Env-Var `SOFTWAREFABRIK_CLAUDECODE_COMMAND`.
Run hängt in `EXECUTION`	Claude wartet auf interaktive Eingabe (z.B. weil Login nötig).	Logs prüfen. Meist hilft: einmal manuell `claude` im Terminal starten und dort einloggen.
`mvn verify` scheitert sofort	Agent hat kein Maven-Projekt erzeugt oder eine wirre `pom.xml`.	Im Workspace per Hand reinschauen, Fehler verstehen, Folge-Run mit Korrektur-Ziel.
Quality Gate sagt `ERROR`	Reviewer ist gecrasht (z.B. weil Aider-CLI fehlt).	Im Quality-Gate-Detail siehst du pro Reviewer den Fehler. Fehlende CLIs in den Settings auf "deaktiviert" stellen.
Token-Budget erschöpft	Plattform blockiert neue Runs ab 100 % Tagesbudget.	Settings → Budget. Cap erhöhen oder warten bis Mitternacht (Reset).
Run gecancelt mit `WORKSPACE_LOCKED`	Voriger Run hat Lock nicht freigegeben (Plattform-Crash).	Workspace-Verzeichnis löschen, Run neu anlegen. Ist ein bekannter Edge Case.

Weitere Schritte

EinführungGlossar und mentales Modell der Plattform.

ArchitekturüberblickWie die Plattform technisch tickt.

SchnellstartFalls du jemanden onboarden willst.

FAQAntworten auf typische Fragen.

LizenzmodellTiers und Limits im Detail.

WhitepaperHintergrund auf 76 Seiten.