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,README.mdals Arbeitsgrundlage für den Agent. - Team — Sammlung von Agentenrollen mit Leitplanken und Modellzuordnung.
- Lauf — konkrete Ausführung mit Status, Phasen, Logs, Token-Verbrauch und Kosten.
- Quality Gate — automatische Bewertung des Ergebnisses durch mehrere Reviewer.
Begriffe in der Fabrik
So heißen die Dinge in der Oberfläche. In Klammern steht, wie Entwickler es oft nennen.
- Projekt
- Das, was entstehen oder verbessert werden soll — mit Beschreibung, Projektordner und allen Läufen.
- Lauf (Run)
- Ein Auftrag an den KI-Agenten: Er arbeitet im Projektordner, baut und prüft das Ergebnis. Ein Lauf hat Schritte (Phasen) und endet abgeschlossen, gescheitert oder abgebrochen.
- Auftrag
- Was der Lauf tun soll, in deinen Worten — z. B. „Der Highscore soll nach dem Neustart erhalten bleiben.“
- Bauen
- Legt den Lauf an und startet ihn sofort.
- KI-Agent (Adapter)
- Das Programm, das die eigentliche Arbeit macht, z. B. Claude Code oder Codex. Es meldet sich über ein Abo oder einen API-Schlüssel an.
- Abo / API-Schlüssel
- Abo: Du meldest dich einmal in der KI-Anwendung an und zahlst monatlich. API-Schlüssel: Abrechnung nach Verbrauch. Wie du beides einrichtest, steht unter Echte Läufe einrichten.
- Projektordner (Workspace)
- Der Ordner auf dem Rechner, auf dem die Fabrik läuft. Dort liegt das Ergebnis; du kannst es auch als ZIP herunterladen.
- Freigabe (Approval)
- Ein Mensch bestätigt, bevor es weitergeht — je nach Einstellung vor der Ausführung, vor dem Merge oder nie.
- Qualitätsprüfung (Quality-Gate)
- Prüft das Ergebnis nach dem Bauen (Tests, Sicherheit, Abhängigkeiten): beratend oder blockierend.
- Build-Prüfung (Build-Gate)
- Baut und testet das Projekt. „Nicht geprüft“ heißt: Die Fabrik hat keinen Build gefunden — kein Fehler, aber auch keine Bestätigung.
- Probelauf
- Baut ein gerade importiertes Projekt einmal ohne Agent, damit du weißt, wie es vorher stand.
- Leitplanken (Guardrails)
- Wie vorsichtig die Fabrik arbeitet: Vorsichtig, Ausgewogen oder Schnell — oder einzeln eingestellt.
- Einfach / Experte
- Wie viel die Oberfläche zeigt. Was du darfst, bestimmt deine Rolle, nicht die Darstellung.
- Rolle
- Lesend, Entwickler, Betreuer (Maintainer), Eigentümer (Owner), Administrator — von „nur ansehen“ bis „alles einrichten“.
- Mandant (Tenant)
- Im Team-Betrieb ein abgegrenzter Bereich, z. B. eine Abteilung: Projekte und Kosten bleiben getrennt.
- Attestierung
- Jede wichtige Aktion steht in einer signierten, lückenlosen Kette — nachträglich nicht unbemerkt änderbar.
- Policy-as-Code
- Signierte, versionierte Regeln für die ganze Fabrik, z. B. welche KI-Agenten erlaubt sind. Stärker als die Einstellungen in der Oberfläche.
Begriffe auf der Website und in der Doku
Diese Wörter siehst du vor allem auf den Seiten zu Architektur, Preisen und Betrieb.
- Control Plane
- Die steuernde Schicht: Die Fabrik ist eine lokale Webanwendung, die Läufe anlegt, startet, überwacht und protokolliert. Die eigentliche Arbeit am Code macht der KI-Agent; die Fabrik gibt ihm den Rahmen, prüft das Ergebnis und hält fest, was passiert ist.
- Lease
- Eine zeitlich begrenzte, signierte Bestätigung der Lizenz, die die Fabrik beim Lizenzserver abholt und regelmäßig erneuert. Solange das Lease gültig ist, braucht die Fabrik keinen Kontakt zum Lizenzserver. Laufzeiten je Stufe: siehe Preise.
- Grace-Period
- Kulanzzeit nach Ablauf des Leases, etwa wenn der Lizenzserver nicht erreichbar war: Läufe starten weiter. Danach lässt sich eine kurze Notfall-Grace aktivieren; ist auch sie abgelaufen, startet kein neuer Lauf mit einem echten KI-Agenten mehr, bis die Lizenz erneuert ist; Läufe mit dem Mock bleiben möglich. Dauer: siehe Preise.
- JWT
- JSON Web Token — ein signiertes, maschinenlesbares Datenpaket. Lizenz und Lease sind JWTs mit Ed25519-Signatur; die Fabrik prüft sie offline gegen den eingebetteten öffentlichen Schlüssel.
- Conductor
- Der Teil der Fabrik, der vor jedem Lauf die Konfiguration für die Agenten-CLI in den Projektordner schreibt, bei Claude Code z. B.
.claude/settings.local.jsonund.claude/agents/<rolle>.md. - SSE
- Server-Sent Events — damit kommen die Logs eines Laufs live in den Browser. Bricht die Verbindung ab, verbindet sich der Browser nach 5 Sekunden neu; ein Heartbeat alle 20 Sekunden hält sie hinter Proxys offen.
- Capability-Routing
- Die Fabrik wählt das Modell je Art des Laufs: Plan- und Spec-Läufe nehmen das Modell des Architect, Build-Läufe das des Developer (bei Claude Code z. B. ein starkes Modell zum Planen, ein schnelleres zum Bauen).
Weitere Begriffe von A bis Z
Fachbegriffe aus Handbuch, Tutorial und Academy — je in einer Zeile.
| Begriff | Bedeutung |
|---|---|
| Adapter | Backend-Komponente, die einen konkreten Agenten anspricht — Coding-CLIs (Claude Code, Codex, Gemini, Kimi, Aider), lokales Modell, Cloud-Gateways (Bedrock, Vertex, Azure OpenAI) oder Mock. |
| Agent / Agentenrolle | Logische Rolle wie Architect, Developer, Reviewer. Wird in AGENTS.md beschrieben und vom Coding-Agent als Kontext gelesen. |
| Approval | Manueller Freigabepunkt im Lauf — vor der Ausführung oder vor dem Merge, je nach Leitplanken. 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-Lauf stößt automatisch den nächsten Plan-Lauf an, sodass sich der SDLC-Loop von selbst weiterdreht. |
| Backlog | Liste der vom Plan-Lauf 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 | Monatsbudget in EUR je Projekt (Auswertung → Budget). Die Alert-Schwelle warnt, mit aktiver Durchsetzung blockiert es neue Läufe bei Überschreitung; dazu kommt ein optionaler Hard-Cap je Mandant. |
| Build-Container | Je Projekt einstellbarer Rahmen für Build-Gate und Probelauf: eigenes Image, CPUs, Speicher, Zeitlimit (seit v0.45.0, MAINTAINER und höher). Der Betreiber begrenzt Images und Obergrenzen. |
| Build-Gate / NICHT_GEPRUEFT | Die Phase VALIDATION: Die Fabrik baut und testet das Projekt selbst, passend zum Projektprofil. Erkennt sie keinen Build oder fehlt ein Werkzeug, heißt das Ergebnis NICHT_GEPRUEFT (nicht geprüft) — das gilt nie als bestanden; der Lauf braucht dann vor dem Merge eine Freigabe. |
| 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. Simuliert den Lauf mit deterministischen Pseudo-Tokens, schreibt aber keinen Code (im Plan-Modus nur einen Beispiel-Plan). Ideal zum Lernen. |
| Phase | Abschnitt eines Laufs. Sieben in fester Reihenfolge: INTAKE, PROMPT_ASSEMBLY, WORKSPACE_PREPARATION, EXECUTION, VALIDATION, CORRECTION, COMPLETION. Sichtbar auf der Laufseite. |
| Plan-Lauf | Lauf-Typ, der nicht baut, sondern Vorschläge für die nächsten Schritte als plans/*.md erzeugt — die Quelle des Backlogs. |
| Build-Lauf | Lauf-Typ, der einen ausgewählten Backlog-Vorschlag auf einem eigenen Branch (sdlc/run-…) tatsächlich umsetzt. |
| Policy | Regeln für Läufe: In der Oberfläche heißen sie Leitplanken (Stufe, Freigaben, Quality-Gate-Modus, Sandbox, Kosten); als Policy-as-Code gelten sie signiert für die ganze Fabrik und gehen den Leitplanken vor. |
| Project-Memory | Projektgebundener Speicher für Entscheidungen und Learnings, der in jeden Folge-Lauf einfließt und so kontinuierliche Weiterentwicklung ermöglicht. |
| Projektprofil | Beschreibung eines Stacks als Daten: woran die Fabrik ihn erkennt, wie das Build-Gate ihn baut und testet und welche Befehle der Agent dafür ausführen darf. Stufe A (geprüft): Maven, .NET; Stufe B (nutzbar): Gradle, Python, Node.js, Go, Rust, CMake. |
| Pull-Request | Beim Liefern automatisch geöffneter GitHub-PR für den Lauf-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 Lauf-Output prüft (CLI-basiert oder statische Heuristik). Sechs Reviewer stehen zur Verfügung (claude-review, aider-review, security-reviewer, architecture-reviewer, hallucination-reviewer, dependency-scan); bei gebundener, freigegebener Spec läuft zusätzlich spec-conformance. |
| Run / Lauf | In der Oberfläche „Lauf“. 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, KI-Zugang, Betriebsmodus, Arbeitsbereich und Git-Autor, Modelle, Kosten, Läufe, Funktionsschalter. ADMIN-only. Quality Gate und Sandbox stehen unter Leitplanken. |
| Team | Sammlung von Agentenrollen, die einem Projekt zugeordnet ist und in den Artefakten erscheint. |
| Toggle (Quality Gate) | Im Wizard (Schritt 5): Schalter für Prüfwerkzeuge wie ArchUnit, OWASP Dependency-Check, Trivy, Playwright oder stackspezifisch ESLint, Ruff, Bandit … 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. |
| Werkzeuge | Toolchains, die die Fabrik selbst installiert (Einrichtung → Werkzeuge, ADMIN, seit v0.45.0): JDK, Maven, .NET SDK, Node.js, Go, uv — ohne Administratorrechte, aus der offiziellen Quelle, mit Prüfsumme. Agent und Build-Gate nutzen sie gemeinsam. |
| Wizard | Projektanlage unter /wizard: der Schnellstart (/wizard/schnellstart, Name, Art, Beschreibung) oder der „Ausführliche Assistent“ in sechs Schritten. |
| Workspace | Persistentes Verzeichnis pro Projekt mit eigenem Git-Repo, in dem der Coding-Agent arbeitet; Folge-Läufe setzen darauf auf. Standard unter ./workspaces/<projekt-slug>/workspace/. |
Häufige Stolperfallen
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_PASSWORD in der .env und starte die Fabrik neu (Startpaket: ./start.sh bzw. .\start.ps1).
„Der Lauf hängt im Entwurf“
„Bauen“ startet einen Lauf sofort. Im Entwurf (DRAFT) bleibt er nur, wenn er nicht starten konnte — die Laufseite nennt dann den Grund (Rechte, Budget, Richtlinie) — oder wenn du ihn in „Experte“ mit „Nur anlegen“ angelegt hast. Dann klickst du „Lauf starten“.
„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 und schickt alle 20 s einen Heartbeat; bleibt es trotzdem leer, muss der Proxy SSE (text/event-stream) ungepuffert durchreichen.
„Mein Adapter schlägt fehl“
Vendor-Adapter brauchen einen API-Key oder einen Abo-Login. Die CLIs lesen Keys aus der Umgebung des Fabrik-Prozesses (z.B. ANTHROPIC_API_KEY); fehlt ein Key dort, setzt die Fabrik im API-Key-Modus den unter /integrations gespeicherten ein (Claude ab 0.41.1, die übrigen Adapter ab 0.41.2). 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 Log des Laufs mit klarer Meldung. Die Systemprüfung (Einrichtung → Werkzeuge & System) zeigt vorher, welche Agent-Programme installiert sind und ob Abo-Login oder Schlüssel vorhanden sind.
„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 auf der Laufseite. 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 Monatsbudget je Projekt unter Auswertung → Budget. Mit aktivierter Durchsetzung blockiert es neue Läufe bei > 100 % Auslastung; die Alert-Schwelle (Standard 80 %) warnt nur — sinnvoll für die ersten Wochen.