Orchestrator-Pattern – dünner Screen, fette Step-Services
Datum: 2026-02-15
Warum ein Screen nicht 400 Zeilen Logik haben darf
Wenn Screen, Service und Datenbankzugriff in einer Datei landen, kann die KI nicht gezielt einen Schritt reparieren – sie „rührt überall“. Refactorings werden riskant, Tests unübersichtlich, Briefings unlesbar.
Das Orchestrator-Pattern trennt Koordination von Ausführung: der Screen bleibt dünn, der Orchestrator kennt nur die Step-Reihenfolge, die Step-Services enthalten die fachliche Arbeit.
Das Problem
| Monolith | Folge für KI + Team |
|---|---|
| Alles in `home.php` | Kein isolierter Fix |
| If-Ketten im Orchestrator | Schwer testbar |
| Services ohne Step-Nummer | Unklare Briefing-Zuordnung |
| Legacy `src/Orchestrator/` | Verstoß gegen Schichtenregeln |
Die KI braucht kleine, klar umrissene Aufgaben – die Architektur muss das vorgeben.
Das Pattern: drei Schichten
| Schicht | Verantwortung | Beispiel |
|---|---|---|
| <strong>Screen/CLI-Script</strong> | Bootstrap, Parameter, Orchestrator, Render | `htdocs/scripts/app/cv/cv.php` |
| <strong>Orchestrator</strong> | Nur Reihenfolge der Steps | `CvServiceOrchestrator::executeGetCvUI()` |
| <strong>Step-Services</strong> | Eine `public function execute…` pro Step | `CvUITemplateService::createCvUITemplateModel()` |
Screen-Regeln (Kurz)
001. Kein try-catch, keine Business-Logik.
002. Ein Orchestrator-Aufruf.
003. Twig-Render mit Model aus Orchestrator.
004. Briefing-Referenz im Dateikopf.
Orchestrator-Regeln
001. Steps nummeriert 001, 002, … im Briefing und als Inline-Kommentare.
002. Keine versteckten Schleifen über „alles prüfen“.
003. Rückgabe: ein UI-Template-Model oder void nach Redirect.
So sieht es bei uns aus
| Kontext | Orchestrator | Steps |
|---|---|---|
| Screen | `BlogpostServiceOrchestrator` | Markdown laden, HTML, Hero |
| Screen | `CvServiceOrchestrator` | UI-Model mit Timeline |
| CLI | `CLISubagentRalphLoopOrchestrator` | Parse, Logs, Ralph-Loop |
| CLI | `CLIDevelopmentWorkflowOrchestrator` | Checks, Tests |
Alle folgen demselben Muster. Briefings liegen unter `briefing/orchestrator-services/` bzw. `briefing/CLIOrchestrator/`.
Briefing-First am Orchestrator
Jeder Step im Briefing = eine Methode im Service. Subagents wie `subagent-check-orchestrator` vergleichen:
001. Step-Nummerierung im Briefing
002. Adjazenz (Step N → Step N+1)
003. PHP-Implementierung
004. Return-Typ und Model
Abweichung = FAILED, nicht „später fixen“.
Screen vs. CLI – gleiches Muster
Screen: Parameter → ScreenOrchestrator → Step-Services → Twig
CLI: argv/Env → CLIOrchestrator → Step-Services → Exit/Logs
`start-vendor-subagent-ralph-loop.php` ist nur der Entry-Point – die Logik sitzt in `CLISubagentRalphLoopOrchestrator` und Step-Services unter `src/CLIServices/`.
Anti-Patterns
001. God-Orchestrator – 15 Steps inline ohne eigene Service-Klassen.
002. Screen ruft Services direkt – Umgehung des Orchestrators.
003. Step-Service mit 20 public Methoden – Gehört aufgeteilt oder in private Helfer (Regeln beachten).
004. Orchestrator unter `src/Orchestrator/` – Legacy; nur mit `briefing.md`-Freigabe.
005. Briefing ohne Return-Beschreibung – KI rät Model-Typen.
Für die KI: Warum das funktioniert
Wenn du `subagent-check-screens` nur für `/cv` startest, findet der Agent:
- `cv.php` – 30 Zeilen
- `CvServiceOrchestrator` – 2 Steps
- `CvUITemplateService` – eine Hauptmethode
Scope ist begrenzt. Fixes sind lokal. Ralph-Loop konvergiert schneller.
Häufige Fragen
Reicht ein Service ohne Orchestrator?
Für trivial statische Screens manchmal ja – sobald mehrere Steps oder Testbarkeit wichtig: Orchestrator.
ApiScreen?
Gleiches Pattern mit `ApiScreen`-Präfix und eigenem Orchestrator-Pfad.
Wo liegen Step-Services?
`src/ScreenServices/{Kontext}/`, `src/CLIServices/{Kontext}/` – siehe `@skill-orchestrators`.
Verwandte Beiträge
| Beitrag | Thema |
|---|---|
| Briefing-First | Spezifikation vor Code |
| Prompt vs. Pipeline | CLI-Orchestratoren |
| Deep-Check | Services an falscher Stelle finden |
| Rules, Skills, Subagents | `subagent-check-orchestrator` |
Takeaway
KI kann große Aufgaben zerlegen – wenn die Architektur das vorgibt. Dünner Screen, Orchestrator als Dirigent, Step-Services als Musiker: wartbar für Menschen, steuerbar für Agents, prüfbar per Subagent.