softwarefabrik.io
Dokumentation · v0.30.0

Benutzerhandbuch

Installation, Betriebsmodi, Projekte, Runs, Quality Gate — Schritt für Schritt.

Ausführliches Handbuch für Einzelplatz-Nutzer. Es deckt Installation und Betrieb (Claude-Abo, Codex-Abo, API-Keys), das Definieren von Projekten mit vollständigen Beispielen, den Run-Lebenszyklus und — ehrlich — was die Fabrik heute beim weiteren SDLC (Roadmap, Upgrades, Bugfixing) leistet und wo ihre Grenzen liegen.

Stand: Version 0.30.0. English version: user-manual.md. Screenshots liegen unter img/ (werden laufend ergänzt).

Inhalt

  1. Was die Software Factory ist (und was nicht)
  2. Installation & Betriebsmodi
  3. Ein Projekt definieren
  4. Einen Run durchführen
  5. Das Ergebnis: Workspace, Git, Artefakte
  6. Weiterentwicklung, Roadmap & SDLC — ehrlich
  7. End-to-End-Beispiel
  8. Troubleshooting & FAQ

1. Was die Software Factory ist (und was nicht)

Die Agentic Software Factory ist eine lokale Control Plane für KI-gestützte Softwareentwicklung. Statt einen Coding-Agenten (Claude Code, OpenAI Codex, Gemini, Aider) direkt in der Shell zu bedienen, beschreibst du dein Vorhaben strukturiert in einer UI; die Fabrik baut daraus präzise Eingabe-Artefakte, startet überwachte Runs, sammelt Logs/Tokens/Kosten und erzwingt Git-Disziplin und ein Build-Gate.

Das mentale Modell — „Cockpit": Du beschreibst das Projekt → wählst ein Team aus Agentenrollen → definierst ein Ziel → die Fabrik startet einen Run, arbeitet in einem isolierten Workspace, committet, baut (mvn verify) und liefert ein nachvollziehbares Ergebnis mit Git-Historie.

Heutiger Reifegrad (ehrlich): Die Fabrik kann beides — das initiale Aufsetzen eines neuen Projekts („Greenfield-Scaffolding") und die iterative Weiterentwicklung über mehrere Versionen: persistenter Workspace, Repo-Import, Plan-/Build-Runs mit Backlog, Branch-Isolation, Pull-Requests, automatische Korrekturschleife, Meilenstein-Releases und zeitgesteuerte Routinen (siehe Kapitel 6). Was heute noch fehlt oder eingeschränkt ist, steht in 6.3.1 — dieses Handbuch sagt an jeder Stelle klar, was geht und was nicht.

2. Installation & Betriebsmodi

Der Einzelplatz läuft hybrid: Postgres im Docker-Container, die Fabrik-App nativ als dein Betriebssystem-Benutzer. Grund: Im Abo-Modus ruft die Fabrik das Agenten-CLI (claude / codex) als derselbe OS-User auf und liest dessen Login aus dem Home-Verzeichnis — in einem Container wäre weder das CLI noch der Login vorhanden.

2.1 Voraussetzungen

Was Wofür Check
Java 25 (JRE/JDK) führt die Fabrik aus java -version
Docker (Desktop/Engine) nur für Postgres docker compose version
Agenten-CLI (eines davon) wird als Subprozess gerufen claude --version / codex --version / kimi --version / gemini --version / aider --version
Git Workspaces, Diffs git --version
(Build-Tool des Zielprojekts) für das Build-Gate, z.B. Maven je nach Stack
(optional) Trivy SBOM und Dependency-/Lizenz-Scan trivy --version
(optional) Docker/Podman Container-Sandbox pro Run docker --version

Das Einzelplatz-Testpaket liegt im Repository unter dist/einzelplatz/ (compose.yml, .env.example, start.sh, start.ps1, README.md). Die ausführbare softwarefabrik-app.jar lädst du aus dem GitHub-Release der gewünschten Version und legst sie neben die Start-Skripte.

2.2 Modus A — Claude-Abo (Sign-in)

Runs laufen über dein Claude-Max/Pro-Abo statt über einen API-Key.

  1. Einmalig anmelden: 
    claude        # Login-/OAuth-Flow durchlaufen
    Danach liegen die Credentials unter ~/.claude (Linux/WSL/macOS) bzw. %USERPROFILE%\.claude (Windows).
  2. In der .env: 
    SOFTWAREFABRIK_EXECUTION_ADAPTER=claude
SOFTWAREFABRIK_CLAUDECODE_AUTH_MODE=subscription
    Im Abo-Modus entfernt die Fabrik einen evtl. gesetzten ANTHROPIC_API_KEY aktiv aus dem Subprozess (sonst hätte der Key Vorrang vor dem Abo).
  3. Optional, falls die Credentials nicht am Standardort liegen: 
    SOFTWAREFABRIK_CLAUDECODE_CONFIG_DIR=/pfad/zu/.claude

2.3 Modus B — Codex-Abo (Sign in with ChatGPT)

Analog, mit OpenAI Codex über ein ChatGPT-Plus/Pro-Abo.

  1. Einmalig anmelden: 
    codex login   # „Sign in with ChatGPT"
    Credentials landen unter ~/.codex/auth.json bzw. %USERPROFILE%\.codex\auth.json.
  2. In der .env: 
    SOFTWAREFABRIK_EXECUTION_ADAPTER=codex
SOFTWAREFABRIK_CODEX_AUTH_MODE=subscription
    Im Abo-Modus wird OPENAI_API_KEY aktiv aus dem Subprozess entfernt.
  3. Optional anderes Verzeichnis (CODEX_HOME): 
    SOFTWAREFABRIK_CODEX_CONFIG_DIR=/pfad/zu/.codex

Der Auth-Modus ist auch in der UI unter Einstellungen umschaltbar und greift ohne Neustart (max. 5 Min Cache).

2.4 Modus C — Kimi-Abo (Moonshot AI)

Analog zu Claude und Codex, mit der Kimi-CLI über eine „Kimi for Coding"-Mitgliedschaft (Flatrate statt Token-Abrechnung).

  1. Einmalig anmelden: 
    kimi login
    Credentials landen unter ~/.kimi-code bzw. %USERPROFILE%\.kimi-code.
  2. In der .env: 
    SOFTWAREFABRIK_EXECUTION_ADAPTER=kimi
SOFTWAREFABRIK_KIMI_AUTH_MODE=subscription
    Besonderheit: Die Kimi-CLI liest Schlüssel nur aus ihrer config.toml bzw. dem KIMI_MODEL_*-Override-Trio. Im Abo-Modus strippt die Fabrik dieses Trio aktiv aus dem Subprozess, im API-Key-Modus injiziert sie es.
  3. Optional anderes Verzeichnis (KIMI_CODE_HOME): 
    SOFTWAREFABRIK_KIMI_CONFIG_DIR=/pfad/zu/.kimi-code

Im Abo-Modus sind die Modell-Aliasse k3 und kimi-for-coding gültig; in der Kostenübersicht werden sie mit 0,00 € geführt, weil bei Flatrate keine Token-Kosten entstehen.

2.5 Modus D — API-Keys

Klassisch über API-Keys (keine Abo-Anmeldung). Auth-Modus bleibt der Default api-key; du stellst nur den passenden Key bereit.

Adapter .env Key
Claude Code SOFTWAREFABRIK_EXECUTION_ADAPTER=claude ANTHROPIC_API_KEY=sk-ant-…
OpenAI Codex SOFTWAREFABRIK_EXECUTION_ADAPTER=codex OPENAI_API_KEY=sk-…
Google Gemini SOFTWAREFABRIK_EXECUTION_ADAPTER=gemini GEMINI_API_KEY=…
Aider SOFTWAREFABRIK_EXECUTION_ADAPTER=aider je nach Backend-Modell
Kimi (Moonshot) SOFTWAREFABRIK_EXECUTION_ADAPTER=kimi KIMI_API_KEY=… bzw. MOONSHOT_API_KEY=…
Lokales Modell SOFTWAREFABRIK_EXECUTION_ADAPTER=local-llm — (OpenAI-kompatibler Endpunkt)
AWS Bedrock SOFTWAREFABRIK_EXECUTION_ADAPTER=bedrock AWS-Zugangsdaten (experimentell)
Google Vertex AI SOFTWAREFABRIK_EXECUTION_ADAPTER=vertex GCP-Zugangsdaten (experimentell)
Azure OpenAI SOFTWAREFABRIK_EXECUTION_ADAPTER=azure-openai Azure-Zugangsdaten (experimentell)
Mock (ohne Tool/Key) SOFTWAREFABRIK_EXECUTION_ADAPTER=mock —

Die drei Cloud-Gateways (Bedrock, Vertex, Azure OpenAI) sind implementiert, aber nicht end-to-end gegen echte Cloud-Zugangsdaten verifiziert. Vor produktivem Einsatz selbst prüfen.

Beispiel (Claude per API-Key):

SOFTWAREFABRIK_EXECUTION_ADAPTER=claude
SOFTWAREFABRIK_CLAUDECODE_AUTH_MODE=api-key
ANTHROPIC_API_KEY=sk-ant-...

Tipp zum Ausprobieren ohne Kosten: Mit SOFTWAREFABRIK_EXECUTION_ADAPTER=mock durchläufst du den kompletten Run-Flow ohne echten Agenten — ideal, um die UI und den Lebenszyklus kennen­ zulernen, bevor du echtes Geld/Token ausgibst.

2.6 Modus E — Lokales Modell (Air-Gap)

Für Betrieb ohne jeden Netzzugang: ein OpenAI-kompatibles lokales Backend (Ollama, vLLM, LM Studio, self-hosted).

SOFTWAREFABRIK_EXECUTION_ADAPTER=local-llm

Ergänzend für echten Air-Gap-Betrieb:

  • Container-Sandbox aktivieren (Einstellungen → execution.sandbox.variant=container); sie startet den Agenten je Run in einem ephemeren Container mit --network=none.
  • PR-/CI-Rückkopplung aus lassen (Default) und die Remote-Host-Allowlist leer bzw. auf interne Hosts setzen.
  • Lizenz ohne Rückkanal: siehe docs/adr/0009-air-gap-ueber-refresh-required-false.md.

2.7 Starten & Einloggen

# im Ordner dist/einzelplatz/ (mit der danebenliegenden .jar)
cp .env.example .env           # SOFTWAREFABRIK_ADMIN_PASSWORD anpassen!
./start.sh                     # Windows: ./start.ps1

Das Skript fährt Postgres hoch und startet die Fabrik. Danach im Browser: http://localhost:8080, Login admin / dein SOFTWAREFABRIK_ADMIN_PASSWORD.

Stoppen: Ctrl+C (App) und docker compose down (Postgres; -v löscht auch die Daten).

3. Ein Projekt definieren

Es gibt zwei Wege, ein Projekt anzulegen:

  • Projekt-Wizard (/wizard) — geführt, empfohlen für den Einstieg.
  • Schnell anlegen (/projects/new) — Experten-Formular, alle Felder frei.

3.1 Der Projekt-Wizard

Der Wizard führt in sechs Schritten durch die Anlage. Seit Version 0.11 denkt er in drei orthogonalen Dimensionen — Zielplattform × Backend × Frontend(s) — sodass sich auch Full-Stack- und Multi-Target-Produkte (ein Backend, mehrere Clients) ausdrücken lassen.

Schritt Inhalt
1 — Zielplattform & Projekttyp Web / Mobile / Desktop (Mehrfachauswahl) oder „bestehendes Repo importieren"
2 — Backend Backend-Technologie (Spring Boot, Quarkus, ASP.NET, FastAPI/Flask, Node) oder „kein Backend"
3 — Frontend(s) Mehrfachauswahl, gefiltert nach Plattform und Backend (z.B. Thymeleaf/Vaadin nur mit Java, Blazor/WPF nur mit .NET; React/Angular/Vue/Flutter sind backend-agnostisch)
4 — Fragen Basisdaten + stack-spezifische Felder (z.B. Java-Version, DB, Architektur-Stil)
5 — Quality-Gates optionale Toggles (ArchUnit, OWASP Dependency-Check, Trivy, ESLint, Playwright …), vereint über alle gewählten Stacks
6 — Zusammenfassung Review + lokale Token-/Kostenschätzung + Vorschau des Initial-Prompts

Am Ende legt der Wizard ein Projekt im Status „Entwurf" an und leitet in den normalen Projekt-Editor — dort sind alle Felder weiter editierbar.

Hinweis zum Filter: Wird eine Zielplattform von keinem gewählten Frontend abgedeckt, warnt der Wizard (er blockiert nicht). Du kannst also bewusst ohne Frontend fortfahren (z.B. reine API) und später ergänzen.

3.2 Die 13 Felder der Projektdefinition

Die Projektdefinition ist das Herzstück — aus ihr werden die Agenten-Artefakte erzeugt. Sie hat 13 inhaltliche Felder (plus Stammdaten Titel/Produktname):

Feld Bedeutung Beispiel
shortDescription Ein-/Zweizeiler, worum es geht „REST-API zur Verwaltung von Wartungsaufträgen."
vision Zielbild, was am Ende erreicht sein soll „Techniker erfassen Aufträge mobil; Disponenten planen im Web."
targetAudience Wer nutzt das Produkt „Außendienst-Techniker und Innendienst-Disponenten."
technologyPreferences gewünschter Stack / Versionen „Spring Boot 3.4, Java 21, PostgreSQL, Maven."
architecturePreferences Architektur-Stil, Schichten, Pakete „Hexagonal, Ports&Adapters, Basis-Paket io.beispiel.wartung."
securityRequirements Sicherheits-Anforderungen „OAuth2/OIDC-Login, Rollen Admin/Disponent/Techniker."
accessibilityRequirements Barrierefreiheit „WCAG 2.1 AA für die Web-UI."
nonfunctionalRequirements NFRs (Performance, Verfügbarkeit, Quality-Gates) „p95 < 300ms; ArchUnit + OWASP-Check aktiv."
gitWorkflowPreferences Branching/Commit-Konventionen „Conventional Commits; Trunk-based."
documentationRequirements gewünschte Doku „README, ADRs für Architekturentscheidungen, OpenAPI."
languagePreference Sprache für Kommentare/Doku (de/en) „de"
sectorContext Branchen-/Domänenkontext „Facility-Management, DSGVO-relevant."
freeText alles Weitere; hier landet auch der Wizard-Prompt (frei)

Je präziser diese Felder, desto besser der Startkontext des Agenten. Leere Felder erscheinen als offene Platzhalter im generierten Prompt — die kannst du im Editor nachziehen, bevor du den ersten Run startest.

3.3 Was die Fabrik daraus macht (Artefakte)

Beim Generieren erzeugt die Fabrik aus der Definition versionierte Markdown-Artefakte, die der Agent als Eingabe bekommt:

  • PROJECT.md — 14 nummerierte Abschnitte, 1:1 aus den Feldern (Zielbild, Stack, Architektur, Security, NFRs, Git, Doku, Sprache, Sektor, Freitext).
  • INSTRUCTIONS.md — Arbeitsweise (autonom), Architektur-/Security-Leitplanken, Build/Test (mvn verify), Git-Disziplin, verbotene Abkürzungen.
  • Zusätzlich: AGENTS.md, WORKFLOW.md, DEFINITION_OF_DONE.md, README.md.

Diese Dateien werden beim Run in den Workspace geschrieben und committet; PROJECT.md/INSTRUCTIONS.md gehen zusätzlich direkt in den Agenten-Aufruf.

3.4 Beispiel-Definitionen

Beispiel 1 — Spring-Boot-REST-API + React-Web (Full-Stack)

Titel:               Wartungsauftrags-Portal
Produktname:         MaintHub
shortDescription:    Web-Portal + REST-API zur Verwaltung von Wartungsaufträgen.
vision:              Disponenten planen Aufträge im Web; eine saubere REST-API
                     bedient später auch eine Mobile-App.
targetAudience:      Innendienst-Disponenten (Web), perspektivisch Techniker (Mobile).
technologyPreferences:  Backend Spring Boot 3.4 / Java 21 / PostgreSQL / Maven;
                        Frontend React + Vite + TypeScript.
architecturePreferences: Hexagonal (Ports & Adapters), Basis-Paket
                         io.beispiel.maint; REST unter /api/v1.
securityRequirements:    OAuth2/OIDC; Rollen ADMIN, DISPONENT.
nonfunctionalRequirements: ArchUnit-Schichtentests + OWASP Dependency-Check aktiv;
                           p95 < 300 ms.
gitWorkflowPreferences:  Conventional Commits, trunk-based.
documentationRequirements: README, OpenAPI-Spec, ADRs.
languagePreference:  de
sectorContext:       Facility-Management.

Wizard-Auswahl dazu: Plattform = Web · Backend = Spring Boot · Frontend = React.

Beispiel 2 — Python-FastAPI-Service (reine API, kein Frontend)

Titel:               Belegerkennungs-Service
Produktname:         DocScan API
shortDescription:    FastAPI-Service, der hochgeladene Belege per OCR strukturiert.
vision:              Andere Systeme schicken PDFs/Bilder und bekommen
                     strukturierte JSON-Belegdaten zurück.
targetAudience:      Interne Backends (Maschine-zu-Maschine).
technologyPreferences:  Python 3.12, FastAPI, SQLAlchemy + PostgreSQL, uv.
architecturePreferences: Layered (api / service / repository), Root-Package docscan.
securityRequirements:    API-Key pro Client; Rate-Limiting.
nonfunctionalRequirements: Ruff + mypy + pytest-cov aktiv; Bandit-Scan.
languagePreference:  en
sectorContext:       Buchhaltung/Fintech.

Wizard-Auswahl: Plattform = Web · Backend = Python FastAPI · Frontend = (keins / reine API).

Beispiel 3 — Statisches Frontend (kein Backend)

Titel:               Produkt-Landingpage
Produktname:         LaunchPad
shortDescription:    Schnelle, statische Marketing-Landingpage.
vision:              Performante, barrierearme Seite ohne Server-Backend.
targetAudience:      Endkunden/Interessenten.
technologyPreferences:  Node 22, Vite, plain HTML/CSS/JS.
accessibilityRequirements: WCAG 2.1 AA.
nonfunctionalRequirements: Playwright-E2E + Trivy aktiv; Lighthouse > 95.
languagePreference:  de

Wizard-Auswahl: Plattform = Web · Backend = kein Backend · Frontend = Statisches Frontend.

4. Einen Run durchführen

Ein Run ist ein überwachter Ausführungslauf des Agenten gegen ein Ziel.

4.1 Team, Adapter, Ziel

Beim Anlegen eines Runs (/runs/new) wählst du:

  • Adapter — welcher Agent ausführt (claude, codex, gemini, aider, kimi, local-llm, bedrock, vertex, azure-openai, mock; Default aus den Einstellungen, ggf. eingeschränkt durch Projekt- oder Mandanten-Policy).
  • Team — die beteiligten Agentenrollen.
  • Ziel (objective) — frei pro Run (bis 4000 Zeichen). Genau hier sagst du, was dieser Run tun soll, z.B. „Lege das Projekt-Skelett gemäß PROJECT.md an und implementiere den Auftrags-CRUD."

4.2 Der Run-Lebenszyklus

Ein Run durchläuft sieben fachliche Phasen:

INTAKE → PROMPT_ASSEMBLY → WORKSPACE_PREPARATION → EXECUTION → VALIDATION → CORRECTION → COMPLETION

und technische Status: DRAFT → READY → PREPARING → RUNNING → (WAITING_FOR_APPROVAL) → VALIDATING → COMPLETED (bzw. NEEDS_CORRECTION, FAILED, TIMEOUT, CANCELLED, PAUSED).

Ablauf in der UI:

  1. „Auf bereit setzen" (DRAFT → READY).
  2. „Run starten" (READY → PREPARING): Workspace wird angelegt, git init, die Markdown-Artefakte werden geschrieben und committet (Checkpoint).
  3. RUNNING: Der Agent arbeitet; Live-Logs streamen per Server-Sent-Events.
  4. VALIDATING: mvn verify (Build-Gate).
  5. COMPLETED oder NEEDS_CORRECTION.

Du kannst Runs pausieren/fortsetzen und abbrechen.

4.3 Freigabe-Gate & Inline-Diff

Vor der Ausführungsphase greift — je nach Policy — ein Freigabe-Gate: Der Run geht in WAITING_FOR_APPROVAL. Auf der Run-Detailseite siehst du einen Inline-Diff der Workspace-Änderungen seit dem frühesten Checkpoint (bis 256 KB) und gibst per „Freigeben" frei.

4.4 Validierung & Korrektur

Die VALIDATION-Phase führt heute mvn verify aus (Java-zentriert; ohne pom.xml wird sie übersprungen). Ist der Build rot, geht der Run in NEEDS_CORRECTION.

Ehrliche Einschränkung: Eine automatische Korrektur-/Feedback-Schleife („gib Feedback, lass den Agenten nachbessern") ist heute nicht implementiert. Der Übergang NEEDS_CORRECTION → RUNNING ist in der Zustandsmaschine erlaubt, wird aber von keiner UI-Aktion ausgelöst. Praktisch heißt das: Bei rotem Build legst du heute einen neuen Run mit angepasstem Ziel an (siehe Kapitel 6).

4.5 Quality-Gate / KI-Review

Zusätzlich zum Build-Gate gibt es das Quality-Gate (/runs/{id}/quality-gate). Es ruft sechs read-only Reviewer auf und aggregiert deren Befunde zu einem Verdict (PASSED / WARNING / FAILED / SKIPPED / ERROR):

Reviewer Art Prüft
claude-review LLM (read-only) Diff-Review durch Claude Code
aider-review LLM (read-only) Diff-Review durch Aider
security statisch Hardcoded Keys, Path-Traversal, SQL-Konkatenation, Runtime.exec, Passwort-Logging
architecture-reviewer statisch Schichtenverstöße, JPA in der Domäne, Änderungen an bestehenden Flyway-Migrationen (CRITICAL)
hallucination-review statisch erfundene Klassen/Methoden, TODO-Marker, „Tests laufen durch" ohne Teständerung
dependency-scan Trivy CVEs und Lizenzverstöße in Abhängigkeiten

Reviewer sind read-only — sie schreiben nie in den Workspace.

Policy: strict blockt CRITICAL + HIGH, verlangt SECURITY und ARCHITECTURE und setzt eine Confidence-Schwelle von 0,70; lenient blockt nur CRITICAL. Drei Regeln gelten immer, unabhängig von der Policy: SECURITY/HIGH und SECURITY/CRITICAL blocken, ARCHITECTURE/CRITICAL blockt, und ein abgestürzter Reviewer führt zu ERROR — nie zu einem stillen Pass.

Betriebsmodus (Einstellungen, mandantenweit über Policy-as-Code übersteuerbar):

Modus Wirkung
off Reviewer laufen nicht
advisory (Default) Befunde werden erhoben und angezeigt, blockieren aber nicht
blocking Ein FAIL erzeugt Feedback und startet die Korrekturschleife

Seit v0.14 läuft das Gate als Teil der Run-Pipeline nach erfolgreichem Build; es lässt sich zusätzlich manuell auf der Run-Detailseite anstoßen.

5. Das Ergebnis: Workspace, Git, Artefakte

Jedes Projekt hat einen persistenten Workspace unter <workspaces-root>/<projekt-slug>/. Darin:

  • ein Git-Repo, das der erste Run initialisiert (bzw. beim Repo-Import geklont oder kopiert wird),
  • die generierten Markdown-Artefakte (bei jedem Run aktualisiert, nicht destruktiv),
  • MEMORY.md aus dem kuratierten Projekt-Gedächtnis,
  • AGENTS.md mit den Engineering-Guardrails (plus eine minimale CLAUDE.md, die darauf verweist),
  • der vom Agenten erzeugte Code.

Wichtig: Der Workspace gehört dem Projekt, nicht dem Run. Ein Folge-Run arbeitet auf dem bestehenden Code weiter — genau das macht iterative Entwicklung möglich. Jeder Build-Run zweigt dafür auf einen eigenen Branch sdlc/run-<id8> ab und wird bei Erfolg in den Base-Branch gemerged bzw. als Pull-Request eröffnet. Bei Misserfolg bleibt die Arbeit zur Inspektion auf dem Run-Branch, der Base bleibt sauber.

Konsequenz: Pro Projekt läuft immer nur ein Run gleichzeitig (Concurrency-Guard). Verschiedene Projekte laufen parallel.

6. Weiterentwicklung, Roadmap & SDLC — ehrlich

Du hast gefragt, ob das, was du mit dem KI-Assistenten an der Fabrik selbst machst (Roadmap-getriebene Weiterentwicklung, Upgrades, Bugfixing über viele Versionen), mit der Fabrik abbildbar ist. Seit dem SDLC-Ausbau lautet die Antwort: Ja — der iterative Loop wird jetzt unterstützt. Greenfield-Aufbau und Weiterentwicklung auf bestehendem Code laufen über dieselbe Fabrik.

6.1 Der iterative SDLC-Loop (jetzt unterstützt)

Planen (Plan-Run) → Backlog aus plans/*.md → auswählen/aktivieren
   → Bauen (Build-Run auf persistentem Workspace) → Validieren
   → Lernen (Memory) → neu Planen
  • Projekt-persistenter Workspace + Re-Run. Folge-Runs arbeiten auf dem bestehenden Code/Git-Repo weiter (<root>/<slug>/workspace), statt jeden Run leer zu starten. „Run 2" sieht den Code von „Run 1". Pro Projekt ist immer nur ein aktiver Run gleichzeitig (Concurrency-Guard).
  • Echter Repo-Import. Das existing-repo-import-Template bringt ein bestehendes Repo (lokaler Pfad → Kopie inkl. .git; Git-URL → git clone) in den persistenten Workspace; danach geht die Weiterentwicklung über Plan-/Build-Runs — nicht über erneutes Scaffolding.
  • Project-Memory. Kuratierte Learnings/Entscheidungen pro Projekt (DB-Quelle, in der UI unter Memory editierbar) werden vor jedem Run als MEMORY.md in den Workspace gespiegelt und danach aus einer vom Agenten aktualisierten MEMORY.md zurück-ingestiert. Adapterunabhängig, versionsstabil.
  • Roadmap/Pläne als Backlog. Ein Plan-Run (ändert keinen Code) lässt den Agenten plans/NNNN-*.md mit nächsten Schritten erzeugen; die Fabrik indexiert sie als Backlog-Items (Auswahlmenü unter Backlog / Pläne). „Aktivieren" startet einen Build-Run, dessen Ziel der Plan-MD ist — auf dem bestehenden Code. Inhalt der Pläne lebt im Repo (plans/), Status/Reihenfolge in der DB.

6.2 Branch/PR, Selbstkorrektur, Quality-Gate & Auto-Loop (jetzt unterstützt)

Der frühere „Iterations-Block" ist umgesetzt:

  1. Branch-Isolation pro Build-Run. Jeder Build-Run arbeitet auf einem eigenen Branch sdlc/run-<id>; bei Erfolg wird in den Base-Branch gemerged (bzw. ein PR eröffnet, s.u.), bei Misserfolg bleibt die Arbeit zur Inspektion auf dem Branch und der Base bleibt sauber.
  2. Push + Pull-Request (GitHub). Ist am Projekt eine Git-Remote-URL gesetzt und unter Integrationen ein GitHub-Token hinterlegt, pusht ein erfolgreicher Build-Run seinen Branch und öffnet einen Pull-Request (Merge dann über den PR) — sonst greift der lokale Merge.
  3. Automatische Korrektur-Feedback-Schleife. Bei rotem Build speist die Fabrik das Build-Feedback automatisch in einen erneuten Lauf auf demselben Branch ein (NEEDS_CORRECTION → RUNNING), bis zu 2 Versuchen; danach bleibt der Run in NEEDS_CORRECTION.
  4. Quality-Gate in der Pipeline. Nach erfolgreichem Build läuft optional das KI-Quality-Gate als Teil der Pipeline. Modus unter Einstellungen: off / advisory (Default: ausführen + protokollieren) / blocking (FAILED/ERROR löst die Korrektur-Schleife aus).
  5. Auto-Folgevorschläge. Optional (Einstellung) stößt ein erfolgreicher Build-Run automatisch einen Plan-Run an → der Loop Plan→Build→Plan schließt sich selbst.

6.3 Weitere Bausteine (seit v0.15 dazugekommen)

Meilenstein-Release. Unter /projects/{id}/milestones bündelst du Runs zu einer Version. Der Release erzeugt Changelog-Eintrag, Git-Tag und — bei gesetzter GitHub-Remote — ein GitHub-Release.

Routinen. Unter /projects/{id}/routines legst du zeitgesteuerte Plan- oder Build-Runs an (an-/abschaltbar). Zusammen mit den Auto-Folgevorschlägen läuft der Loop planen → bauen → prüfen → mergen → neu planen ohne manuellen Anstoß weiter — mit den Freigabepunkten als bewussten Haltestellen.

Backlog mit Abhängigkeiten. Backlog-Items können voneinander abhängen; ein Item wird erst DONE, wenn sein Build-Run tatsächlich gemerged ist — nicht schon, wenn Code geschrieben wurde.

Skill-/Plugin-Bibliothek. Unter /skills verwaltest du versionierte Skills und Plugins. Sie werden vor jedem Run als .claude/skills/<name>/SKILL.md, .claude/agents/<rolle>.md und .claude/settings.local.json in den Workspace materialisiert. Damit ist nachvollziehbar, welche Erweiterung in welcher Version im Kontext eines Laufs war.

Engineering-Guardrails. Eine vendor-neutrale Verhaltens-Policy fließt bei jedem Run in den Kontext jedes Coding-Agenten und wird als AGENTS.md ins Repo projiziert — eine Quelle, mehrere Projektionen, statt einer gepflegten Kopie je Werkzeug.

Repo-Realität. Vor jedem Build-Run wird der Base-Branch auf den Remote-Stand vorgespult. Ein Merge-Konflikt bricht den Run nicht ab, sondern geht mit den Konfliktdateien als Arbeitsanweisung in die Korrekturschleife. Bei aktivierter PR-Rückkopplung (git.pr-feedback.enabled, Default aus) wartet der Run im Zustand WAITING_FOR_PR auf grüne CI und Merge; rote CI startet ebenfalls eine Korrektur.

Mehrbenutzerbetrieb. Rollen (VIEWER … ADMIN), Mandanten, optionales SSO, Budget-Caps, Policy-as-Code, Compliance-Profile und die signierte Audit-Kette sind vorhanden — beschrieben im separaten Administrationshandbuch.

6.3.1 Was noch offen ist (Ausblick)

  • Weitere Git-Hosts: Push, Pull-Request, CI-Statusabfrage und Release sind gegen die GitHub-API implementiert. GitLab, Bitbucket und Azure DevOps fehlen noch; dort greift der lokale Merge.
  • Issue-Tracker-Sync (Jira/Linear/GitHub Issues) als Backlog-Quelle.
  • Parallele Multi-Branch-Ausführung: pro Projekt läuft nur ein Run gleichzeitig (bewusst zurückgestellt).
  • Seat-scharfe Budget-Obergrenzen — die Auswertung je Nutzer gibt es (/mandanten/seat-kosten), der Hard-Cap wirkt aber nur je Mandant.
  • Cloud-Gateways (Bedrock/Vertex/Azure OpenAI) sind nicht end-to-end verifiziert.
  • Projektübergreifendes Lernen.

6.4 Empfohlener Arbeitsablauf

  1. Neues Projekt: Wizard → Definition → Artefakte → Build-Run (Scaffolding). Bestehendes Repo: im Wizard „Repo importieren", Pfad/URL angeben.
  2. Optional: Git-Remote am Projekt + GitHub-Token unter Integrationen setzen → Build-Runs erzeugen PRs.
  3. Plan-Run starten (Backlog/Pläne): die KI schlägt die nächsten Schritte als plans/*.md vor.
  4. Im Backlog ein Item aktivieren → Build-Run setzt es auf dem bestehenden Code um (eigener Branch, Selbstkorrektur, optional Quality-Gate).
  5. Memory pflegen: Entscheidungen/Learnings kuratieren; sie fließen in jeden Folge-Run.
  6. Wiederholen (Loop) — optional automatisch via Auto-Folgevorschläge. mock-Adapter zum kostenlosen Üben des gesamten Loops.

7. End-to-End-Beispiel

Ein kompletter Durchlauf mit Beispiel 1 (Spring Boot + React):

  1. Wizard: /wizard → Plattform Web → Backend Spring Boot (Java 21, PostgreSQL, hexagonal, Paket io.beispiel.maint) → Frontend React (TypeScript) → Quality-Gates ArchUnit + OWASP → Zusammenfassung → Projekt anlegen.
  2. Editor: Felder aus 3.4 prüfen/ergänzen, speichern. Artefakte generieren.
  3. Run anlegen: Adapter claude (oder mock zum Üben), Team wählen, Ziel: „Lege das Spring-Boot-Skelett gemäß PROJECT.md an, implementiere den Auftrags-CRUD (Entity, Repository, REST unter /api/v1) und ein React-Frontend mit Auftragsliste. mvn verify muss grün sein."
  4. „Auf bereit setzen" → „Run starten". Live-Logs verfolgen.
  5. Freigeben, wenn der Inline-Diff stimmt.
  6. Nach mvn verify grün → COMPLETED. Optional Quality-Gate anstoßen.
  7. Ergebnis-Workspace inspizieren und in dein Repo übernehmen.

8. Troubleshooting & FAQ

  • claude: command not found / CreateProcess error=2 — CLI nicht im PATH. claude --version prüfen; ggf. SOFTWAREFABRIK_CLAUDECODE_COMMAND (bzw. …CODEX_COMMAND) auf den vollen Pfad setzen.
  • Run-Auth-Fehler / 401 — Abo-Login fehlt. Einmal claude / codex login ausführen; das Credential-Verzeichnis muss befüllt sein.
  • Abo-Modus rechnet trotzdem über API ab? — Stelle sicher, dass kein ANTHROPIC_API_KEY/OPENAI_API_KEY in der Umgebung steht. Die Fabrik strippt ihn im Abo-Modus zwar aktiv, sauberer ist, ihn ganz wegzulassen.
  • Port 8080 belegt — andere App beenden oder SOFTWAREFABRIK_PORT setzen.
  • Postgres startet nicht — läuft Docker? (docker ps). Windows: Docker Desktop zuerst starten. Port 5432 belegt → lokales Postgres stoppen.
  • VALIDATION wird übersprungen — kein pom.xml im Workspace; mvn verify ist das Build-Gate für Java-Stacks.
  • „Run 2 baut nicht auf Run 1 auf" — sollte nicht passieren: der Workspace ist projekt-persistent. Prüfe, ob wirklich dasselbe Projekt verwendet wird und ob der vorherige Run gemerged wurde (bei NEEDS_CORRECTION liegt die Arbeit noch auf dem Run-Branch).
  • Run bleibt in WAITING_FOR_PR — der PR ist noch nicht gemerged oder die CI ist nicht grün. Poller aktiv? (git.pr-feedback.enabled).
  • Quality-Gate meldet ERROR — ein Reviewer ist abgestürzt (z.B. fehlende CLI). Das ist bewusst kein stiller Pass; CLI installieren oder den Reviewer über den Gate-Modus abschalten.
  • Merge-Konflikt — die Fabrik speist die Konfliktdateien automatisch als Korrekturauftrag ein (max. 2 Versuche); danach bleibt der Run in NEEDS_CORRECTION und du löst manuell auf.
  • Nur ausprobieren ohne Kosten — SOFTWAREFABRIK_EXECUTION_ADAPTER=mock.