Workflow-Übersicht

Workflows sind der Mechanismus von CodeCourier zur Orchestrierung mehrstufiger KI-Agenten-Pipelines. Statt einen einzigen Prompt an einen einzelnen Agenten zu senden, ermöglichen Workflows die Definition einer Sequenz von Agenten-Schritten - jeder mit eigener Rolle, eigenem CLI-Tool, Modell und eigenen Anweisungen -, die zusammenarbeiten, um qualitativ hochwertigere Ergebnisse zu erzielen. Ein Workflow ist eine wiederverwendbare Blaupause; bei jeder Ausführung erstellt CodeCourier einen Run, der die Ausführung durch jeden Schritt verfolgt.

Was ist ein Workflow?

Ein Workflow in CodeCourier ist eine Vorlage, die definiert, wie KI-Agenten bei einer Aufgabe zusammenarbeiten. Er legt fest:

• Welche Agenten teilnehmen - Jeder Schritt in der Pipeline entspricht einer Persona (einer benannten Agenten-Konfiguration mit eigenem CLI-Tool, Modell und eigenen Anweisungen).
• In welcher Reihenfolge sie ausgeführt werden - Schritte laufen sequenziell. Die Ausgabe eines Schritts wird zum Kontext für den nächsten.
• Ob eine Schrittgruppe iteriert - Ein Designer+Checker-Paar kann in einem Iteration Block platziert werden, sodass die Gruppe wiederholt wird, bis der Checker zustimmt, bis zum Iterationslimit des Blocks. Schritte außerhalb eines Iteration Block laufen einmal.
• Welche Sandbox-Konfiguration zu verwenden ist - Der Workflow trägt eine Standard-Sandbox-Konfiguration (CLI-Tool, Modell, Ressourcen), die für alle Schritte gilt, sofern nicht überschrieben.

Kernkonzepte

Blaupausen vs. Runs

Es gibt eine entscheidende Unterscheidung zwischen einem Workflow und einem Run. Ein Workflow ist eine Blaupause - er definiert die Pipeline- Struktur, führt aber nichts aus. Ein Run ist eine Ausführungsinstanz eines Workflows. Wenn Sie einen Workflow starten, erstellt CodeCourier einen Run-Datensatz, der Ausführungsstatus, Prompt, Konfiguration und Ergebnisse verfolgt. Sie können denselben Workflow mehrfach ausführen und so mehrere Runs mit unterschiedlichen Prompts und Konfigurationen erzeugen.

Persona-Pipelines

Das Workflow-System von CodeCourier nutzt eine Persona-Pipeline- Architektur. Jeder Schritt in der Pipeline ist an eine Persona gebunden - eine vorkonfigurierte Agentenidentität mit einer spezifischen Rolle (Designer, Checker, Optimizer, Prompter, Investigator, Evaluator, Judge oder Answerer), CLI-Tool, Modell und benutzerdefinierten Anweisungen. Das bedeutet, Sie kontrollieren nicht nur, was der Agent tut, sondern auch, wie er es tut.

Beispielsweise könnte ein Code-Review-Workflow folgendermaßen definiert sein:

1. Eine Designer-Persona mit Claude Opus für die Implementierung.
2. Eine Checker-Persona mit Claude Sonnet für E2E-Tests.
3. Eine Optimizer-Persona für die Codebereinigung nach der Freigabe.

Iteration Blocks

Iteration ist explizit und opt-in: sie befindet sich in einem Iteration Block-Knoten. Aufeinanderfolgende Schritte mit derselben loopId bilden einen Block, und der Block wiederholt sich als Einheit. Das kanonische Muster ist der Designer-Checker-Block:

1. Der Designer implementiert die angeforderten Änderungen.
2. Der Checker prüft die Implementierung und erzeugt ein Urteil.
3. Wenn der Checker zustimmt, verlässt der Block die Schleife und die Pipeline fährt fort. Wenn der Checker ablehnt, erhält der Designer das Feedback des Checkers und der Block läuft erneut.

Jeder Block hat sein eigenes loopMaxIterations-Limit (Standard 3), um Endlosschleifen zu verhindern. Wird das Limit ohne positives Urteil erreicht, wird der Block beendet und der Run als fehlgeschlagen markiert.

Schritte außerhalb eines Iteration Block laufen genau einmal. Ein Checker, der nicht in einem Block ist, gibt weiterhin ein Urteil ab (das im zugehörigen Run-Schritt gespeichert wird), löst aber keinen automatischen Retry aus.

Execution Blocks

Unter der Haube zerlegt der Orchestrator die Pipeline in Execution Blocks. Jeder Block ist entweder ein single-Block (ein oder mehrere Schritte, die einmal laufen) oder ein loop-Block (der Iteration Block - eine loopId-Gruppe, die sich wiederholt).

Ausführungsmodi

Workflows können auf verschiedene Arten ausgelöst werden, jede für einen anderen Anwendungsfall geeignet:

• Direkte Runs - Eine einzelne Ausführung, manuell von der Workflow-Detailseite oder der Runs-Seite ausgelöst. Der häufigste Einstiegspunkt für einmalige Aufgaben.
• Sprint Chains - Eine Batch-Ausführung, die denselben Workflow mehrfach hintereinander ausführt, einmal pro Sprint. Jeder Sprint erzeugt seinen eigenen Pull-Request. Sprint Chains sind ideal für phasenweise Entwicklungsarbeiten, bei denen jede Phase auf der vorherigen aufbaut. Die Chain verfolgt PR-URLs pro Sprint und unterstützt das Fortsetzen von einem beliebigen Sprint-Index, falls ein Sprint fehlschlägt.
• Wiederkehrende Aufgaben - Geplante Ausführungen, die automatisch in einer konfigurierten Frequenz ausgelöst werden (täglich, jeden zweiten Tag, wöchentlich, zweiwöchentlich oder monatlich). Jede Auslösung erzeugt einen Standard-Run mit Source scheduled. Wiederkehrende Aufgaben sind ideal für kontinuierliche Qualitätsprüfungen, automatisierte Abhängigkeits-Updates und andere Wartungs-Workflows, die regelmäßig laufen müssen.
• Work Chains (Issue-gesteuert) - Sequenzielle Runs, die von Issue-Session-Work-Chains erstellt werden. Jedes Element der Chain ist ein anderes Issue, das durch dieselbe Workflow-Pipeline verarbeitet wird.

Qualitäts-Scoring

Jeder Workflow-Run nimmt am Qualitäts-Scoring-System von CodeCourier teil. Wenn die Pipeline einen Evaluator-Schritt enthält, erzeugt dieser Schritt strukturierte Qualitäts-Scores in fünf Dimensionen:

• Korrektheit - Erfüllt die Implementierung die Anforderungen?
• Typsicherheit - Sind die TypeScript-Typen korrekt und vollständig?
• Code-Stil - Folgt der Code den Projektkonventionen?
• Testabdeckung - Sind die Änderungen durch Tests abgedeckt?
• Vollständigkeit - Ist die Implementierung vollständig abgeschlossen?

Diese fünf Dimensions-Scores werden zu einem composite-Score (0–100) kombiniert. Jeder Run verfolgt zudem einen Gesamt-qualityScore, der aus allen Evaluator-Schritten der Pipeline abgeleitet wird. Scores sind in der Run-Detailansicht und im Monitoring-Dashboard sichtbar, was eine Trendanalyse über die Zeit ermöglicht.

Workflow-Konfiguration

Jeder Workflow trägt eine Konfiguration, die steuert, wie seine Schritte ausgeführt werden:

• Name und Beschreibung - Ein menschenlesbarer Name und eine optionale Beschreibung für die Workflow-Blaupause.
• Standard-Sandbox-Konfiguration - Die Basiskonfiguration für alle während der Runs erstellten Sandboxes: Vorlagen-ID, Timeout, Speicher, CPU-Anzahl, Designer-Modell und Checker-Modell.
• Persona-Pipeline-Schritte - Ein geordnetes Array von Persona-Referenzen. Schritte, die zu einem Iteration Block gehören, tragen eineloopId (und die loopMaxIterations des Blocks); Schritte außerhalb eines Blocks tragen keine davon und werden einmal ausgeführt.

Wie Workflows ausgeführt werden

Wenn ein Workflow ausgelöst wird, geschieht Folgendes:

1. Run-Erstellung - Ein Run-Datensatz wird in der Datenbank mit dem Prompt, der Konfiguration und einer Referenz auf die Workflow-Blaupause erstellt.
2. Trigger.dev-Dispatch - Ein Hintergrund-Task wird an die Trigger.dev-Task-Queue gesendet. Dies ist der Workflow- Orchestrator, der die gesamte Ausführung verwaltet.
3. Schritt-Ausführung - Der Orchestrator verarbeitet jeden Execution Block sequenziell. Für jeden Schritt erstellt er eine E2B- Sandbox, richtet die Umgebung ein, führt den KI-Agenten aus und protokolliert die Ergebnisse.
4. Verdict-Behandlung - Für Checker-Schritte bestimmt das Urteil (Pass/Fail mit Feedback), ob die Schleife fortgesetzt wird.
5. Run-Abschluss - Wenn alle Schritte abgeschlossen sind, wird der Run-Status auf completed aktualisiert. Schlägt ein Schritt fatal fehl, wird der Run als failed markiert.
6. PR-Erstellung - Hat der Run an einem Git-Branch gearbeitet, wird automatisch ein Pull-Request erstellt.

Verbindung zu anderen Funktionen

• Sandboxes - Jeder Workflow-Schritt erstellt und nutzt seine eigene Sandbox. Der Sandbox-Lebenszyklus wird vom Schritt- Executor verwaltet.
• Personas - Workflow-Schritte referenzieren Personas für ihre Agenten-Konfiguration. Eine Persona-Änderung wirkt sich auf alle Workflows aus, die sie verwenden.
• Issues - Issue-Sessions können Probleme entdecken, die als sequenzielle Workflow-Runs über Work Chains ausgeführt werden.
• Sprint Chains - Batch-Ausführung, die denselben Workflow mehrfach ausführt, wobei jeder Sprint seinen eigenen PR erzeugt.
• Wiederkehrende Aufgaben - Geplante Automatisierung, die den Workflow in einer konfigurierten Frequenz ohne manuellen Eingriff auslöst.
• Learnings - Learnings werden aus Workflow- Run-Sandboxes extrahiert und über kompilierte Learning-Versionen in zukünftige Runs eingespeist.
• Nutzungserfassung - Jeder Workflow-Run erzeugt Nutzungsdatensätze für E2B-Rechenzeit, KI-Token-Verbrauch und Gesamtkosten.

Anwendungsfälle

• Design-Review-Zyklen - Ein Designer implementiert Änderungen und ein Checker verifiziert sie mit E2E-Tests, schleifend bis die Qualität passt.
• Prompt-Verfeinerung - Ein Prompter-Agent verfeinert eine vage Aufgabenbeschreibung zu einem detaillierten Prompt, bevor er an einen Designer weitergegeben wird.
• Untersuchung-dann-Fix - Ein Investigator analysiert die Codebasis, um das Problem zu verstehen, dann implementiert ein Designer den Fix basierend auf der Untersuchung.
• Multi-Agenten-Codegenerierung - Verschiedene Agenten übernehmen unterschiedliche Aspekte (Frontend, Backend, Testing) eines Features in Folge.
• Qualitäts-gegated Auslieferung - Ein Evaluator-Schritt bewertet die Implementierung gegen Qualitätsschwellen, bevor der PR geöffnet wird, sodass nur produktionsreife Änderungen zur Prüfung eingereicht werden.
• Phasenweise Batch-Entwicklung - Sprint Chains führen denselben Workflow über mehrere Phasen eines Projekts aus, wobei jeder Sprint einen abgrenzbaren, überprüfbaren Satz Änderungen liefert.
• Kontinuierliche Automatisierung - Wiederkehrende Aufgaben lösen Qualitäts-, Sicherheits- oder Abhängigkeits-Workflows nach Zeitplan aus und halten die Codebasis ohne manuellen Eingriff gesund.