Einführung — softwarefabrik.io

Was ist die Software Factory?

Eine lokale Webanwendung, mit der du AI-gestützte Entwicklungsprozesse strukturiert anstößt, überwachst und nachvollziehst. Du arbeitest nicht direkt mit der CLI von Claude Code, Codex oder Gemini, sondern über eine UI-zentrierte Control Plane.

Stell dir die Plattform als Cockpit vor: du beschreibst dein Projekt, wählst dein Team aus Agentenrollen, definierst ein Ziel — und die Plattform startet einen Run, sammelt Logs, Tokens und Kosten und liefert dir am Ende einen reproduzierbaren Workspace mit Git-Historie, Build-Status und Quality-Gate-Resultat.

Eckdaten v0.19.0:

4 Vendor-Adapter 6 Wizard-Templates 4 Quality-Gate-Toggles 5 Reviewer-Rollen 2 Sandbox-Varianten

Das mentale Modell

Die Plattform denkt in fünf Ebenen. Wer diese versteht, findet sich in der UI sofort zurecht:

Projekt — Idee, Zielbild und Anforderungen, als Entwurf, dann als Markdown-Artefakte.
Artefakte — PROJECT.md, INSTRUCTIONS.md, AGENTS.md, WORKFLOW.md, DEFINITION_OF_DONE.md als Arbeitsgrundlage für den Agent.
Team — Sammlung von Agentenrollen mit Leitplanken und Modellzuordnung.
Run — konkrete Ausführung mit Status, Phasen, Logs, Token-Verbrauch und Kosten.
Quality Gate — automatische Bewertung des Ergebnisses durch mehrere Reviewer.

Merksatz: Gute Runs beginnen mit guten Artefakten. Plane bewusst vor dem ersten Run-Klick.

Anmelden

Nach dem lokalen Start (z.B. via docker compose up) erreichst du die Plattform im Browser. Die Anmeldung erfolgt mit einem administrativen Konto, das beim Bootstrap aus Konfiguration angelegt wird:

SOFTWAREFABRIK_ADMIN_USER=admin
SOFTWAREFABRIK_ADMIN_PASSWORD=ChangeMe-2026!

Wichtig: Ohne explizit gesetztes Passwort wird absichtlich kein Bootstrap-Admin angelegt. Schwache Defaults wären ein Security-Bug.

Wenn du nur schauen willst: Live-Demo unter demo.softwarefabrik.io. Dort bist du als demo-Nutzer automatisch eingeloggt; täglich um 04:00 wird die Datenbank zurückgesetzt.

Das Dashboard verstehen

Nach dem Login landest du auf dem Dashboard — der Kommandozentrale für Projekte, Runs und Statusübersichten:

Kennzahlen oben: Projekte (gesamt / Entwurf / aktiv), aktive Runs, 14-Tage-Token-Verbrauch und 14-Tage-Kosten in EUR.
Charts: Run-Aktivität, Token-Verteilung Input/Output und EUR-Kostenkurve — komplett serverseitig gerendertes SVG.
Letzte Projekte: schneller Einstieg in bestehende Vorhaben.
Letzte Runs: direkter Sprung zu Logs, Git-Status und Phasen.

Das Dashboard der Softwarefabrik nach dem Login — Das Dashboard nach dem Login — Kennzahlen, Lizenzstatus und Hinweise (hier: aktiver **Mock-Adapter** auf der Demo). Deine Kommandozentrale für Projekte und Runs.

Ein Projekt anlegen

Zwei Wege:

Projekt-Assistent (empfohlen): Vier-Schritt-Wizard mit Stepper, Template-Auswahl, Quality-Gate-Toggles und Zusammenfassung mit Kosten-Schätzung und Objective-Vorschau.
Schnell-Anlegen: minimales Formular (Projekttitel, Produktname) — du landest direkt im Editor und füllst alles selbst.

Beim Abschluss entstehen die strukturierten Markdown-Artefakte. Der Wizard schreibt zusätzlich den Initial-Objective-Prompt, der später im ersten Run als Eingabe für den Agent dient.

Der Projekt-Assistent zum Anlegen eines neuen Projekts — Der **Projekt-Assistent** führt in vier Schritten durch die Anlage — Zielplattform, Backend, Frontend(s) und die passenden Fragen.

Tipp: Auch wenn du den Assistenten nicht brauchst, lohnt sich beim ersten Mal ein einziger Durchgang — du siehst, was die Plattform aus deinen Antworten macht.

Projektinhalte ergänzen

Im Bearbeitungsbildschirm pflegst du die eigentlichen Projektinhalte. Diese fließen direkt in die generierten Markdown-Artefakte ein. Je präziser hier, desto verlässlicher der spätere Run:

Vision: 2–4 Sätze. Was soll am Ende dabei rauskommen?
Zielgruppe: Wer wird die Software nutzen?
Technologie-Präferenzen: Stack, Versionen, Frameworks. Bei Wizard-Anlage automatisch vorbelegt.
Architektur-Präferenzen: Datenbank, Architektur-Stil, Package-Struktur.
Sicherheit & Accessibility: Projektspezifische Anforderungen.
Nicht-funktionale Anforderungen: Performance-Ziele, SLAs.
Git-Workflow & Doku: Branching-Modell, Commit-Konventionen.
Sprache: Steuert UI-Sprache der generierten Artefakte (de/en).
Freitext: Alles, was sonst nirgendwo passt.

Markdown-Artefakte erzeugen

Mit einem Klick auf Markdown-Artefakte generieren erzeugt die Plattform sechs Spezifikationsdateien für den Coding-Agent:

Datei	Wozu
`PROJECT.md`	Vision, Zielgruppe, Anforderungen — die „Charta“ des Projekts.
`INSTRUCTIONS.md`	Konkrete Arbeitsanweisung für den Agent.
`AGENTS.md`	Rollen im Team (Architect, Developer, Reviewer …) inkl. Modellzuordnung.
`WORKFLOW.md`	Phasenmodell, Approval-Punkte, Branching-Konventionen.
`DEFINITION_OF_DONE.md`	Wann ist ein Run fertig? Build grün, Quality-Gate bestanden, …
`README.md`	Lese-Einstieg für den Agent in den Workspace.

Wichtig: Lies diese Dateien einmal durch, bevor du den ersten Run startest. Tippfehler oder unklare Formulierungen werden vom Agent sehr ehrlich umgesetzt — du siehst sie hinterher in den Commits.

Settings und Defaults

Als Bootstrap-Admin hast du den Bereich /einstellungen. Werte gelten global, lassen sich aber pro Projekt überschreiben (Override-Reihenfolge: PROJECT > USER > GLOBAL > YAML). Beispiele:

workspace.root — Wo Run-Workspaces angelegt werden.
execution.adapter.default — Default-Adapter für neue Runs.
execution.sandbox.variant — local oder container.
execution.claudecode.model — Default-Modell für Claude.
budget.daily.tokens, budget.weekly.tokens — Token-Caps.

Cache-Tipp: Setting-Änderungen wirken nach max. 5 Minuten ohne Restart — der SettingService hat einen 5-min-TTL-Cache.

Team und Rollen

Klassische Rollen: Architect, Developer, Reviewer, QA, Security Reviewer, Documentation, Merge/Release. Pro Projekt ein Team aus einer Auswahl davon. Beim Run-Start landet das Team in AGENTS.md. Pro Rolle kann ein preferredModel hinterlegt werden — der Claude-Code-Adapter hängt es als --model-Flag an und fällt bei unbekannten IDs auf den CLI-Default zurück.

Run anlegen und starten

Ein Run verbindet Projekt, Ziel und Team zu einer konkreten Ausführung. Felder sind:

Projekt: Pflicht. Aus den vorhandenen Projekt-Entwürfen oder bereits aktiven Projekten.
Team: Optional. Default ist das Team des Projekts.
Run-Titel: Pflicht. Kurz und sprechend, z.B. „Initiale Anlage des BFF-Skeletts“.
Ziel: Pflicht. Was soll der Run konkret tun? Hier kann ruhig viel Detail rein, der Agent liest es als Top-Level-Instruktion.
Adapter: Falls du einen anderen als den Default willst.

Ein neuer Run startet in DRAFT. Du wechselst ihn auf READY und startest ihn dann bewusst mit Run starten. Damit hast du zwei Bestätigungspunkte, bevor Token verbrannt werden — bewusst so designt.

Quick-Start: Wenn du schon einen erfolgreichen Run hast, klick in der Run-Liste auf „Neuer Run aus letztem Setup“. Drei Klicks, fertig.

Run überwachen

Während ein Run läuft, arbeitest du mit drei Sichten:

01 · DETAIL

Run-Detail

Status (RUNNING / PAUSED / WAITING_FOR_APPROVAL / COMPLETED / FAILED), aktuelle Phase, Token- und Kostenstand. Buttons für Pause / Resume / Cancel.

02 · LOGS

Logs (live)

Server-Sent-Events streamen die Agent-Ausgaben live in den Browser. Heartbeat alle 20 s, Auto-Reconnect nach 5 s, Auto-Scroll-Toggle.

03 · GIT

Git-Ansicht

Branch, Commit-Liste, Working Tree und Diff. So siehst du in Echtzeit, was der Agent in den Workspace schreibt.

Quality Gate

Am Ende eines Runs (oder auf Wunsch zwischendurch) lässt du das Quality Gate laufen. Es ruft mehrere Reviewer auf, aggregiert die Findings und liefert eine Entscheidung:

PASSED WARNING FAILED SKIPPED ERROR

Verfügbare Reviewer (fünf):

architecture-reviewer — prüft Schichten- und Modulgrenzen.
hallucination-review — sucht erfundene Methoden / Pakete.
security — statische Heuristik für typische Sicherheits-Smells.
aider-review — ruft die Aider-CLI im read-only-Modus auf.
claude-review — ruft die Claude-Code-CLI im read-only-Modus auf.

Sonderregeln (immer blockierend, unabhängig von der Policy): SECURITY/HIGH und ARCHITECTURE/CRITICAL. Reviewer-Crashes werden als ERROR sichtbar gemacht, nicht verschluckt.

Der iterative SDLC-Loop

Ein einzelner Run ist nur ein Baustein. Über mehrere Runs hinweg schließt die Plattform einen vollständigen, sich selbst tragenden Software-Lifecycle — vom Vorschlag über den Bau bis zur Auslieferung als Pull-Request — und beginnt danach von vorn. Auf einem projekt-persistenten Workspace bleibt der Stand zwischen den Runs erhalten, sodass aufeinander aufbauend weiterentwickelt wird statt jedes Mal bei Null zu starten.

Planen — ein Plan-Run erzeugt Vorschläge für die nächsten Schritte als plans/*.md. Sie erscheinen anschließend als Backlog.
Auswählen — im Backlog aktivierst du einen Vorschlag, der als Nächstes umgesetzt werden soll.
Bauen — ein Build-Run setzt den Vorschlag auf einem eigenen Branch (sdlc/run-…) auf dem projekt-persistenten Workspace um.
Selbstkorrektur — schlägt der Build fehl, speist die Fabrik das Build-Feedback automatisch in einen erneuten Lauf auf demselben Branch ein (begrenzte Anzahl Versuche, Übergang NEEDS_CORRECTION → RUNNING).
Quality-Gate — nach erfolgreichem Build prüft das KI-Quality-Gate das Ergebnis. Der Modus ist wählbar: aus, beratend oder blockierend.
Liefern — bei gesetzter Git-Remote und hinterlegtem GitHub-Token wird der Branch gepusht und automatisch ein Pull-Request geöffnet. Ohne Remote/Token erfolgt ein lokaler Merge in den Base-Branch.
Lernen — das Project-Memory hält Entscheidungen und Learnings fest, die in jeden Folge-Run einfließen.
Weiter — optional stößt ein erfolgreicher Build automatisch den nächsten Plan-Run an (Auto-Folgevorschläge) — der Loop schließt sich und beginnt wieder bei Planen.

Kurz gesagt: Planen → Auswählen → Bauen → Selbstkorrektur → Quality-Gate → Liefern → Lernen → Weiter. Jeder Durchlauf hinterlässt einen gepushten Branch mit Pull-Request (oder einen lokalen Merge) und füttert den nächsten.

Policies & Approvals

Policies legen fest, in welchen Phasen ein Run automatisch fortlaufen darf und wo eine manuelle Freigabe nötig ist. Standardmäßig sind unkritische Phasen automatisiert; vor Ausführung und Abschluss wartet die Plattform auf eine bewusste Nutzerentscheidung. So ist sichergestellt, dass kein Run unbemerkt etwas Schwerwiegendes commitet.

Der Run durchläuft sieben Phasen: INTAKE → PROMPT_ASSEMBLY → WORKSPACE_PREPARATION → EXECUTION → VALIDATION → CORRECTION → COMPLETION.

Tipps für die Praxis

Fang mit dem Mock-Adapter an, bevor du einen echten Vendor-API-Key einsetzt. Mock liefert deterministische Pseudo-Tokens und du siehst die Plattform-Mechanik ohne Kosten.
Halte das Ziel eines Runs klein. Lieber drei Runs à „Skelett anlegen“, „Tests schreiben“, „Doku ergänzen“ als einen Mega-Run.
Quality Gate früh anwerfen, nicht erst am Ende. Findings sammeln sich sonst.
Beobachte Logs und Git-Ansicht in den ersten Minuten. Wenn der Agent in die falsche Richtung läuft, brichst du früh ab statt Tokens zu verbrennen.
Nutze den Wizard auch zum Lernen: Schritt 4 zeigt dir, was die Plattform aus deinen Antworten macht — ein guter Spickzettel für die Felder im normalen Editor.

Wichtig: Für diese Einführung brauchst du keine ADRs. Konzentriere dich erstmal auf Wizard, Artefakte, Run, Logs und Quality Gate — der Rest erklärt sich, sobald die ersten Runs durchgelaufen sind.

Die ersten 30 Minuten — geführter Walkthrough

Wenn du gerade frisch eingeloggt bist und nicht weißt, wo du anfangen sollst: hier ist eine bewusst kleinschrittige Reihe, die in 30 Minuten ein erstes Erfolgserlebnis liefert.

Minute 0–2: Dashboard scannen

Schau dir die Kennzahlen an. Wenn alles auf 0 steht — perfekt, du bist auf einer leeren Instanz. Wenn Werte da sind, ist es eine Demo oder Vorgänger-Instanz.
Minute 2–10: Wizard durchklicken

Klick auf „Neues Projekt mit Assistent anlegen“. Wähle „Modernes Spring Boot Backend“. Beantworte die Fragen — du kannst überall Beispielwerte nehmen, später ist alles editierbar. Schalte ArchUnit als einzigen Quality-Gate-Toggle an. Schließe ab.
Minute 10–15: Projekt-Editor erkunden

Du landest unter /projects/<id>/edit. Schau dir an, was die Plattform aus deinen Antworten gemacht hat — besonders technologyPreferences, architecturePreferences und nonfunctionalRequirements. Klick auf „Markdown-Artefakte generieren“.
Minute 15–18: Artefakte lesen

Öffne PROJECT.md, INSTRUCTIONS.md und AGENTS.md. Du musst nicht alles verstehen — aber siehst du, wie aus den Wizard-Fragen ein konsistenter Auftrag wurde?
Minute 18–25: Run anlegen

Klick auf „Neuer Run“. Wähle das Projekt, gib einen Run-Titel („Skelett anlegen“) und ein Ziel ein („Lege das initiale Maven-Projekt mit Spring Boot, Health-Endpoint und einem ersten Smoke-Test an“). Wähle den Mock-Adapter — das kostet nichts und du siehst die Mechanik. Status auf READY, dann „Run starten“.
Minute 25–30: Live mitschauen

Du landest auf der Run-Detail-Seite. Logs strömen rein. Beobachte den Token-Counter, die Phasen-Updates, den Git-Status. Wenn der Run fertig ist (Mock braucht ~10 Sekunden), wirf einen Blick auf den Workspace-Diff.

Geschafft! Damit hast du den kompletten Lifecycle einmal durchgespielt — Projekt, Artefakte, Run, Logs, Diff. Jetzt kannst du dasselbe mit einem echten Adapter (Claude / Codex / Gemini / Aider) wiederholen — nur dann brauchst du einen API-Key.

Glossar — die Begriffe in einer Zeile

Begriff	Bedeutung
Adapter	Backend-Komponente, die mit einer konkreten Coding-CLI (Claude Code, Codex, Gemini, Aider, Mock) spricht.
Agent / Agentenrolle	Logische Rolle wie Architect, Developer, Reviewer. Wird in `AGENTS.md` beschrieben und vom Coding-Agent als Kontext gelesen.
Approval	Manueller Freigabepunkt zwischen Run-Phasen. Verhindert, dass kritische Schritte ohne Bestätigung laufen.
Artefakte	Die sechs Markdown-Dateien (`PROJECT.md` …), die der Agent als Spezifikation liest.
Auto-Folgevorschläge	Optionale Funktion: ein erfolgreicher Build-Run stößt automatisch den nächsten Plan-Run an, sodass sich der SDLC-Loop von selbst weiterdreht.
Backlog	Liste der vom Plan-Run erzeugten Vorschläge (`plans/*.md`). Aus dem Backlog wird der nächste umzusetzende Schritt aktiviert.
Bootstrap-Admin	Das initiale Admin-Konto, das beim ersten Start aus den Env-Variablen `SOFTWAREFABRIK_ADMIN_USER/PASSWORD` angelegt wird.
Budget	Token-Cap pro Tag oder Woche. Soft-Schwelle warnt, harter Modus blockiert neue Runs bei Überschreitung.
Draft / Entwurf	Status eines Projekts oder Wizard-Drafts: noch nicht final, noch editierbar, noch nicht in Benutzung.
Mock-Adapter	Test-Adapter, der ohne API-Key funktioniert. Schreibt deterministische Pseudo-Inhalte in den Workspace. Ideal zum Lernen.
Phase	Abschnitt eines Runs. Sieben in fester Reihenfolge: `INTAKE`, `PROMPT_ASSEMBLY`, `WORKSPACE_PREPARATION`, `EXECUTION`, `VALIDATION`, `CORRECTION`, `COMPLETION`. Sichtbar im Run-Detail.
Plan-Run	Run-Typ, der nicht baut, sondern Vorschläge für die nächsten Schritte als `plans/*.md` erzeugt — die Quelle des Backlogs.
Build-Run	Run-Typ, der einen ausgewählten Backlog-Vorschlag auf einem eigenen Branch (`sdlc/run-…`) tatsächlich umsetzt.
Policy	Regelwerk, das festlegt, wo ein Run automatisch weiterlaufen darf und wo Approval nötig ist.
Project-Memory	Projektgebundener Speicher für Entscheidungen und Learnings, der in jeden Folge-Run einfließt und so kontinuierliche Weiterentwicklung ermöglicht.
Pull-Request	Beim Liefern automatisch geöffneter GitHub-PR für den Run-Branch (bei gesetzter Remote + Token). Ohne Remote/Token: lokaler Merge in den Base-Branch.
Selbstkorrektur	Automatische Feedback-Schleife: ein fehlgeschlagener Build wird mit dem Build-Feedback erneut auf demselben Branch versucht (begrenzt, `NEEDS_CORRECTION` → `RUNNING`).
Quality Gate	Aggregierte Bewertung mehrerer Reviewer-Findings. Liefert eine Entscheidung: PASSED / WARNING / FAILED / SKIPPED / ERROR.
Reviewer	Read-only-Komponente, die einen Run-Output prüft (CLI-basiert oder statische Heuristik). Fünf Reviewer pro Quality-Gate-Lauf.
Run	Konkrete Ausführung eines Coding-Agenten gegen ein Projekt. Hat Status, Phasen, Logs, Token-Verbrauch und Git-Workspace.
Settings	Globale Plattform-Konfiguration unter `/einstellungen`. Adapter-Defaults, Workspace-Pfad, Budget. ADMIN-only.
Team	Sammlung von Agentenrollen, die einem Projekt zugeordnet ist und in den Artefakten erscheint.
Toggle (Quality Gate)	Im Wizard: Schalter für ArchUnit / OWASP / Trivy / Playwright. Aktivierte Toggles erscheinen als Sektion im generierten Initial-Prompt.
Versions-Cache	DB-Tabelle, die täglich um 03:00 die aktuellsten stabilen Versionen für Spring Boot, ArchUnit, Trivy etc. abholt. Datenquelle für die Wizard-Vorbelegungen.
Wizard	Vier-Schritt-Assistent unter `/wizard` für die geführte Projektanlage.
Workspace	Lokales Verzeichnis pro Run, in dem der Coding-Agent seine Files schreibt. Standard unter `./workspaces/<run-id>/`.

Häufige Stolperfallen für Einsteiger

Aus der Erfahrung mit den ersten Pilotnutzern — typische Reibungspunkte und wie man sie vermeidet:

„Ich sehe keinen Login-Knopf“

Die Plattform startet beim ersten Aufruf mit einer leeren DB. Wenn du noch keinen Bootstrap-Admin gesetzt hast, wird auch kein Konto angelegt. Setze SOFTWAREFABRIK_ADMIN_USER und ...PASSWORD in .env, dann docker compose up erneut.

„Der Run hängt in DRAFT“

Ein neuer Run ist immer in DRAFT. Du musst ihn erst auf READY setzen und dann den „Run starten“-Knopf klicken. Doppelt bewusst, damit nicht versehentlich Tokens verbrannt werden.

„Logs erscheinen nicht“

SSE-Verbindungen bleiben hinter manchen Reverse-Proxies oder Corporate-Firewalls hängen. Wenn du gar nichts siehst: prüfe die DevTools-Konsole. Die Plattform reconnectet automatisch nach 5 s — falls das nicht reicht, schaltet die Run-Detail-Seite einen Polling-Fallback an.

„Mein Adapter schlägt fehl“

Vendor-Adapter brauchen API-Keys. Setze sie in /integrations oder per Env-Var. Beim Mock-Adapter passiert das nie — den nimmst du also für die ersten Tests. Falls eine CLI lokal nicht installiert ist, erscheint der Fehler im Run-Log mit klarer Meldung.

„Ich habe ein Wizard-Draft, das nicht weggeht“

Drafts ohne Abschluss bleiben in der DB. Du kannst sie über „Wizard verwerfen“ auf der Zusammenfassungsseite explizit beenden, oder sie verschwinden automatisch nach 30 Tagen durch den Cleanup-Job.

„Die Versions-Cache-Tabelle ist leer / stale“

Beim Fresh-Install läuft der tägliche Refresh-Job noch nicht — du siehst die Fallback-Versionen aus dem Code. Über „Jetzt manuell refreshen“ auf /einstellungen/wizard/versions kannst du den Lookup sofort triggern (braucht Internet).

„Quality Gate sagt FAILED, aber ich sehe nichts“

Klick auf das Quality-Gate-Ergebnis im Run-Detail. Du siehst pro Reviewer die Findings inkl. Confidence-Score. SECURITY/HIGH und ARCHITECTURE/CRITICAL sind immer blockierend — auch wenn die Policy „lenient“ steht.

„Ich verbrauche zu viele Tokens“

Setze ein Budget unter /einstellungen (Tag oder Woche). Der harte Modus blockiert neue Run-Anlagen bei > 100 % Auslastung. Soft-Schwelle (Standard 80 %) warnt nur — sinnvoll für die ersten Wochen.

Wo es weitergeht

ARCHITEKTUR

Einführung für neue Nutzer.