Diese Einführung erklärt die Plattform Schritt für Schritt — von der allerersten Anmeldung bis zum überwachten Entwicklungs-Run. Sie richtet sich bewusst an Einsteigerinnen und Einsteiger und konzentriert sich auf Bedienung, nicht auf tiefe Architekturentscheidungen. Wer mit der Plattform schnell ein erstes Projekt anlegen will, findet im Projekt-Assistenten einen geführten Pfad in vier Schritten — mit Stepper, Kosten-Schätzung und Vorschau des Initial-Prompts.
Die Agentic Software Factory ist 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. Das reduziert Reibung und macht jeden Run reproduzierbar.
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.
Die Plattform denkt in fĂĽnf Ebenen. Wer diese versteht, findet sich ĂĽberall in der UI sofort zurecht:
PROJECT.md, INSTRUCTIONS.md, AGENTS.md, ... als Arbeitsgrundlage fĂĽr den Agenten.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!
Wenn du nur die Plattform anschauen willst, ohne lokal zu installieren: nutze die Live-Demo unter demo.softwarefabrik.io. Dort bist du als demo-Nutzer automatisch eingeloggt; täglich um 04:00 wird die Datenbank zurückgesetzt, damit jeder Besuch frisch anfängt.
Nach dem Login landest du auf dem Dashboard. Es ist die Kommandozentrale fĂĽr Projekte, Runs und StatusĂĽbersichten:
Im Header findest du jederzeit den Theme-Toggle (Hell/Dunkel, persistiert in localStorage) und das Benutzer-Popover mit Logout-Knopf.
Seit v0.4.0 gibt es zwei Wege, ein neues Projekt zu starten. Wähle den, der zu deinem Erfahrungsstand passt:
Der Projekt-Assistent fĂĽhrt dich in vier Schritten durch die Anlage:
Nach dem Abschluss landest du im normalen Projekt-Editor mit allen Feldern bereits vorbelegt.
Über Schnell anlegen auf der Projekt-Liste öffnest du ein minimales Formular mit nur zwei Feldern: Projekttitel und Produktname. Du landest direkt im Projekt-Editor und füllst die Inhalte selbst.
Empfehlenswert, wenn du schon weiĂźt, wie die Plattform tickt, und keine Template-Vorbelegung brauchst.
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:
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. |
Seit v0.4.0 hast du als Bootstrap-Admin einen eigenen Bereich /einstellungen. Werte gelten global fĂĽr alle Projekte und Runs der Instanz, lassen sich aber pro Projekt ĂĽberschreiben (Override-Reihenfolge: PROJECT > USER > GLOBAL > YAML):
claude-sonnet-4-6).SettingService hat einen 5-min-TTL-Cache.Die Plattform modelliert klassische Rollen: Architect, Developer, Reviewer, QA, Security Reviewer, Documentation und Merge/Release. Du legst pro Projekt ein Team an, das eine Auswahl davon enthält. Beim Run-Start wird das Team an den Coding-Agent übergeben (über AGENTS.md).
Pro Rolle kannst du ein preferredModel hinterlegen — Architect kriegt z.B. claude-opus-4-7, der Reviewer claude-haiku-4-5. Der Claude-Code-Adapter haengt das Modell als --model-Flag an und faellt bei unbekannten IDs auf den CLI-Default zurueck (Phase 5, seit v0.6.0).
Ein Run verbindet Projekt, Ziel und Team zu einer konkreten AusfĂĽhrung. Felder sind:
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.
Während ein Run läuft, arbeitest du mit drei Sichten:
Status (RUNNING / PAUSED / WAITING_FOR_APPROVAL / COMPLETED / FAILED), aktuelle Phase, Token- und Kostenstand. Buttons fĂĽr Pause / Resume / Cancel.
Server-Sent-Events streamen die Agent-Ausgaben live in den Browser. Heartbeat alle 20 s, Auto-Reconnect nach 5 s, Auto-Scroll-Toggle.
Branch, Commit-Liste, Working Tree und Diff. So siehst du in Echtzeit, was der Agent in den Workspace schreibt.
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:
VerfĂĽgbare Reviewer:
Sonderregeln (immer blockierend, unabhängig von der Policy): SECURITY/HIGH und ARCHITECTURE/CRITICAL. Reviewer-Crashes werden als ERROR sichtbar gemacht, nicht verschluckt.
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.
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.
/projects/<id>/edit. Schau dir an, was die Plattform aus deinen Antworten gemacht hat — besonders technologyPreferences, architecturePreferences und nonfunctionalRequirements. Klick auf "Markdown-Artefakte generieren".PROJECT.md, INSTRUCTIONS.md und AGENTS.md. Du musst nicht alles verstehen — aber siehst du, wie aus den Wizard-Fragen ein konsistenter Auftrag wurde?READY, dann "Run starten".| 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. |
| 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 (z.B. Plan, Implement, Review, Merge). Sichtbar im Run-Detail. |
| Policy | Regelwerk, das festlegt, wo ein Run automatisch weiterlaufen darf und wo Approval nötig ist. |
| 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). Mehrere 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>/. |
Aus der Erfahrung mit den ersten Pilotnutzern — typische Reibungspunkte und wie man sie vermeidet:
Die Plattform startet beim ersten Aufruf mit einer leeren DB. Wenn du noch keinen Bootstrap-Admin gesetzt hast, wird auch kein Konto angelegt. Setze die beiden Env-Variablen SOFTWAREFABRIK_ADMIN_USER und ...PASSWORD in .env, dann docker compose up erneut.
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.
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.
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.
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.
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).
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.
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.