Die Spezifikation ist der Wunschzettel, der Orchestrator ist der Werkstattmeister, die Agenten sind die Handwerker. Menschen entscheiden, was und wie; die Agenten erledigen die Arbeit dazwischen, selbstständig und nicht Schritt für Schritt gesteuert. Der Domänenexperte und der Software Engineer bleiben in der Werkstatt.
Verantwortet Anforderungen, Use Cases und Glossar. Setzt einen Use Case auf Approved, beantwortet die offenen Fragen und zeichnet die Abnahme ab.
Verantwortet Architektur, ADRs, Stack-Datei und Harness. Reviewt und merget den Pull Request der Werkstatt und justiert den Harness, wenn die Erstdurchlaufquote sinkt.
Auswahl, Reihenfolge, Gates, Wiederholungen und Budgets: ein wiederverwendbarer GitHub-Actions-Workflow des Marketplace, aufgerufen von einem kleinen Stub in Ihrem Repository.
Code und Tests für einen Use Case. Jede Station ist eine eigene Headless-Sitzung von Claude Code mit aiup-core und den Layer-Plugins, die Ihre Stack-Datei nennt.
Spezifikation, Code und Tests einer Änderung liegen auf demselben Branch und gelangen mit einem Pull Request in den Standardbranch. So trägt der Standardbranch nie eine Spezifikation ohne ihren Code, und die beiden laufen nie auseinander.
Jeder Use Case durchläuft dieselben Stationen, von links nach rechts. Nur zwei Schleifen führen zurück: Ein gescheitertes Gate führt in eine Korrekturrunde, eine Lücke in der Spezifikation zu einem Menschen. Alles dazwischen läuft automatisch.
Eine Station arbeitet, ein Gate prüft nur. Zwischen den Stationen stehen sechs Gates, G1 bis G6, nummeriert in der Reihenfolge, in der sie laufen. Jedes beantwortet eine Ja-oder-Nein-Frage, und keines verlässt sich auf das Wort eines Agenten: Ein Gate ist ein Skript, ein Build-Kommando oder eine Prüfung, deren Urteil im Code verifiziert wird. Ein Use Case geht nur weiter, wenn das Gate Ja sagt.
Bevor Code entsteht, prüft der Spec-Lint von /spec-review den Use Case: Ids, Links, Format, schwache Wörter. Ausserdem prüft er, dass keine blockierende offene Frage den Use Case aufhält. Ein reines Skript, ohne KI. Scheitert es, ist der Use Case blockiert: kein Code, nur die Befunde gehen zurück an die Fachexpertin oder den Fachexperten.
Nach Implementierung und Tests läuft das Kommando Build aus der Stack-Datei: Der Code kompiliert, die Migrationen laufen, die Codegenerierung funktioniert. Ein roter Build führt in eine Korrekturrunde.
Alle Tests, die die Kommandos Unit tests und Integration tests der Stack-Datei ausführen, müssen bestehen, auch die neuen, aus der Spezifikation geschriebenen. Ein roter Test führt in eine Korrekturrunde.
Was Ihr Build durchsetzt, etwa ArchUnit-Regeln für die Architektur, dazu die Spurprüfung: Der Implementierer darf keine Tests ändern, der Tester keinen Produktionscode, und keine Station die Spezifikation. Eine verletzte Regel führt in eine Korrekturrunde; ein Spurwechsel wird rückgängig gemacht.
Eine nur lesende Abdeckungsprüfung ordnet jedem Schritt des Hauptszenarios, jedem alternativen Ablauf und jeder Geschäftsregel Code und einen Test zu. Ihr Urteil «vollständig» wird im Code verifiziert, bevor es zählt. Eine Lücke im Code geht an den Implementierer, eine Lücke in den Tests an den Tester.
Höchstens max_rounds Korrekturrunden (Standard 4) und max_cost_usd (Standard 15 USD) je Use Case. Ist das Budget aufgebraucht, ist der Use Case festgefahren: Der Code wird verworfen und als Diff in den Laufdaten aufbewahrt, damit nichts Halbfertiges in den Pull Request gelangt.
| Station oder Gate | Was läuft | Bei einem Fehler |
|---|---|---|
| G1 Spec-Lint | spec_lint.py von /spec-review für den Use Case (Ids, Links, Format, schwache Wörter) sowie seine blockierenden offenen Fragen. Ohne Sprachmodell | Blockiert: nur die Befunde gelangen in den Pull Request |
| Implementieren | /use-case-implement über die Schichten der Stack-Datei, mit dem Diff der Spezifikation gegenüber der Abzweigung vom Standardbranch | – |
| Testen | /use-case-test in einer neuen Sitzung, mit demselben Diff der Spezifikation. Ein Test, der dem Code widerspricht, bleibt rot | – |
| Offene Fragen | Nach jeder Agenten-Station: spec_lint.py --questions, danach die blockierenden offenen Fragen des Use Cases | Blockiert |
| G2 Build | Das Kommando Build aus docs/architecture/stack.md: Der Code kompiliert, die Migrationen laufen, die Codegenerierung funktioniert | Korrekturrunde |
| G3 Tests | Die Kommandos Unit tests und Integration tests der Stack-Datei: Jeder Test ist grün | Korrekturrunde |
| G4 Harness | Was der Build durchsetzt, etwa ArchUnit-Regeln, dazu die Spurprüfung | Korrekturrunde; ein Spurwechsel wird rückgängig gemacht |
| G5 Abdeckung der Spezifikation | Der Abdeckungs-Agent, nur lesend: Jeder Schritt des Hauptszenarios, jeder alternative Ablauf und jede Geschäftsregel braucht Code und einen Test. Ein Urteil «vollständig» wird verifiziert | Lücke im Code: Korrekturrunde. Lücke in den Tests: Testrunde |
| G6 Budget | Höchstens max_rounds Korrekturrunden (Standard 4) und max_cost_usd (Standard 15 USD) je Use Case | Festgefahren: Der Code wird verworfen und als Diff in den Laufdaten aufbewahrt |
Implementierer, Tester und Prüfer laufen je in einer eigenen Sitzung von Claude Code. Tester und Prüfer lesen die Spezifikation, nicht die Überlegungen des Implementierers: Ein Test vom selben Agenten, der den Code geschrieben hat, bestätigt eher den Code. So bleibt die Spezifikation das Orakel, und kein Agent benotet seine eigene Arbeit.
Eine Sitzung, die scheitert, etwa an einem abgelehnten Schlüssel, einem unbekannten Modell oder einem Rate Limit, wird ein zweites Mal gestartet. Ein zweites Scheitern beendet den Use Case als festgefahren, was immer der Build über den unveränderten Code sagt.
Ein roter Build geht zuerst an den Implementierer, mit dem Build-Log und dem Diff der Spezifikation, der nur Produktivcode ändert. Ist der Build danach noch rot, bekommt der Tester in derselben Runde das neue Log und repariert die Tests, die nicht kompilieren oder der Spezifikation widersprechen; ein Test, der der Spezifikation folgt, bleibt rot. Beide Schritte zählen als eine Runde.
Eine Lücke, die die Prüfung im Code findet, geht an den Implementierer, eine Lücke in den Tests an den Tester. Die Prüfung meldet alle Lücken in einem Durchgang, und eine spätere Prüfung kontrolliert die vorherige Matrix Zeile für Zeile, damit die Runden nicht für eine Lücke nach der anderen verbraucht werden.
Das Urteil der Prüfung setzt einen Use Case auf Tested, deshalb wird es im Code kontrolliert und nicht auf das Wort des Agenten hin übernommen. Die Prüfung läuft mit einem aufgezeichneten Tool-Log, und die Werkstatt verifiziert drei Dinge: Die Abdeckungsmatrix hat eine Zeile für jeden Schritt, jeden alternativen Ablauf und jede Geschäftsregel der Spezifikation, keine davon fehlend oder teilweise; das Log zeigt, dass der Prüfer die Spezifikation gelesen hat; und jede Datei, die die Matrix zitiert, wurde tatsächlich geöffnet.
Scheitert eine Kontrolle, läuft die Prüfung in derselben Runde ein zweites Mal mit den Befunden; das kostet keine Korrekturrunde, denn eine fehlerhafte Prüfung ist keine Lücke im Code. Lässt sich auch dieses Urteil nicht verifizieren, wandert der Use Case auf Implemented, was einen grünen Build behauptet und nicht mehr. Ein Scheitern Richtung festgefahren würde funktionierenden Code wegen eines Fehlers der Prüfung verwerfen; ein Scheitern Richtung Tested wäre genau die Behauptung, die die Kontrolle verhindern soll.
Trifft eine Station auf eine Lücke in der Spezifikation, rät sie nicht. Sie hält eine blockierende offene Frage in docs/open_questions.md fest, und die Werkstatt stoppt den Use Case.
Die Werkstatt fragt den Agenten nicht, ob er steckengeblieben ist. Nach jeder Station liest sie docs/open_questions.md, die Datei, die jeder Skill ohnehin schreibt, und die Kontrolle ist deterministisch. Eine Frage zählt, wenn sie Open oder Answered ist, als blockierend markiert, und den Use Case nennt (UC-003, einen Schritt, einen alternativen Ablauf oder eine Geschäftsregel) oder eine Anforderung, die der Use Case verlinkt.
Davor prüft spec_lint.py --questions die Datei selbst. Eine fehlerhaft geschriebene Frage würde kein Parser als blockierend lesen, deshalb blockiert ein Fehler dort den Use Case ebenfalls.
Ein blockierter Use Case trägt nur seine Fragen zum Pull Request bei: Halb gebauter Code ist kein Vorschlag, und auch nicht versionierte Dateien werden verworfen. Der Domänenexperte beantwortet die Frage im Änderungsbranch und passt den Use Case an. Sein Status ist noch Approved, also baut ihn der nächste Lauf erneut aus der beantworteten Spezifikation.
Im AI Unified Process Studio führt ein blockierter Use Case direkt zu seinen offenen Fragen im Offene-Fragen-Editor.
Jede Station bleibt in ihrer Spur, und keine Station darf ändern, was über sie urteilt. Was die Linie überschreitet, wird zurückgesetzt und im Pull Request aufgeführt, so fällt ein abdriftender Skill im Review auf, statt den Lauf scheitern zu lassen.
Die Werkstatt hält zwischen Läufen keinen eigenen Zustand. Sie wählt die Use Cases, die sich auf dem Branch geändert haben und Approved sind, und setzt einen fertigen im selben Pull Request wie seinen Code auf Tested: nur vorwärts, in der Sprache der Spezifikation. Nach dem Merge wird er nicht mehr ausgewählt; ein blockierter, festgefahrener oder ausstehender ist noch Approved und wird es.
| Ausgang | Bedeutung | Was der Pull Request enthält |
|---|---|---|
| ready (bereit) | Alle Gates grün | Code, Tests, Status Tested (Implemented, wenn der Stack keine Abdeckungsprüfung hat oder ihr Urteil nicht verifiziert werden konnte), der abgeleitete Status der verlinkten Anforderungen und die neue Farbe des Use Cases im Use-Case-Diagramm |
| blocked (blockiert) | Fehler im Spec-Lint, eine blockierende offene Frage oder eine Datei der offenen Fragen, die der Lint ablehnt | Nur die neuen offenen Fragen |
| stuck (festgefahren) | Nach den Korrekturrunden noch rot, über dem Budget, eine Sitzung, die zweimal scheiterte, oder die Zeit des Laufs war um | Nichts von diesem Use Case; sein Code bleibt als Diff in den Laufdaten |
| pending (ausstehend) | Nicht gebaut, weil ein früherer Use Case des Laufs anhielt | Nichts; er wird im nächsten Lauf gebaut |
| skipped (übersprungen) | Nicht gebaut, weil der Use Case nicht Approved ist, auch wenn seine Id von Hand angegeben wurde | Nichts; der Grund nennt seinen Status |
Die Use Cases laufen in Id-Reihenfolge, und der Lauf hält beim ersten an, der nicht bereit ist, weil spätere Use Cases derselben Änderung auf ihm aufbauen können. Die Stationen hören zehn Minuten vor der Frist des Laufs auf, damit der Pull Request noch geöffnet wird: Der Use Case, der dann noch läuft, endet festgefahren, die vor ihm behalten ihr Ergebnis.
Die Anforderungen und das Use-Case-Diagramm folgen dem Status im selben Commit, so findet /spec-review keinen Widerspruch zwischen einem Use Case auf Tested und seinen Anforderungen, die noch auf Open stehen.
Der Pull Request nennt den Commit, auf dem die Gates liefen. Ein Commit, der danach darauf gepusht wird, ist von keinem gedeckt: Der Status Tested gilt für den Commit, den die Werkstatt gebaut hat, also lassen Sie die Werkstatt nach einer Änderung erneut laufen.
Die Laufdaten kommen als Build-Artefakt: eine Zusammenfassung je Use Case, eine Metrikzeile je Station (Runde, Exit-Code, Kosten, Sekunden), die Build-Logs, die Ausgabe des Lints und die Abdeckungsmatrix. Die Erstdurchlaufquote, der Anteil der Use Cases, die ohne Korrekturrunde bereit sind, zeigt, ob ein Problem in der Spezifikation oder im Harness liegt.
Das Studio richtet die Werkstatt zusammen mit der KI-Generierung ein und startet sie auf dem Branch, auf dem Sie arbeiten. Niemand muss ein Workflow-Kommando kennen.
Auf der Startseite baut «Änderung bauen» jeden genehmigten Use Case, dessen Spezifikation sich auf Ihrem Branch geändert hat. Für einen einzelnen genehmigten Use Case empfiehlt der Bereich zum nächsten Prozessschritt die Werkstatt jetzt als ersten Eintrag, vor der Implementierung und den Tests des Use Cases, die als weitere Möglichkeiten folgen.
Vor dem Start nennt das Studio den Änderungsbranch als Ziel des Pull Requests und die Kostengrenze je Use Case. Nach dem Lauf zeigt es den Pull Request und je Use Case den Ausgang, den neuen Status, die Anzahl der Korrekturrunden und die Kosten.
Die Werkstatt läuft vollständig auf GitHub Actions mit Claude Code im Headless-Modus; ein zusätzlicher Server ist nicht nötig. Das Studio erledigt diese Schritte für Sie; ohne Studio dauern sie wenige Minuten.
Ein Projekt mit den Artefakten des AI Unified Process und einer ausgefüllten Stack-Datei, docs/architecture/stack.md, mit Layers und Commands, geschrieben von /stack. Ein Projekt mit einem kombinierten Stack-Plugin übergibt es als stack_plugin; ohne Stack-Datei greift die Werkstatt auf das Build-Werkzeug zurück, das sie im Wurzelverzeichnis des Repositorys findet. Erlauben Sie GitHub Actions, Pull Requests zu erstellen, unter Settings → Actions → General → Workflow permissions.
GitHub startet keinen Workflow für einen Pull Request, der mit dem Token des Jobs geöffnet wurde. Ohne AIUP_PR_TOKEN kommt der Pull Request deshalb ohne Checks an, obwohl das eigene Build-Gate der Werkstatt lief. Mit einem Fine-grained Token eines Maschinenbenutzers (Contents und Pull requests: Read and write) läuft die CI Ihres Projekts darauf. Dasselbe Secret dient der KI-Generierung, ein Token pro Repository genügt.
Ein schlanker Stub in Ihrem Repository ruft den wiederverwendbaren Workflow des Marketplace auf, veröffentlicht hinter dem Tag v1. Er hat eine Quelle, die Datei aiup-werkstatt-stub.yml des Marketplace; das Studio schreibt eine wortgetreue Kopie bei der Einrichtung der Generierung. Committen Sie ihn unverändert in den Standardbranch und legen Sie die Änderungsbranches von dort an: Modell, Budget und die übrigen Grenzen sind Eingaben des Laufs, keine Zeilen der Datei. Ändert sich der Stub später, mergen Sie den Standardbranch in jeden offenen Änderungsbranch.
Aus dem Studio oder von Hand auf einem Änderungsbranch, mit oder ohne Use-Case-Ids. Ohne Ids baut die Werkstatt jeden genehmigten Use Case, dessen Spezifikation sich gegenüber der Abzweigung vom Standardbranch unterscheidet.
| Eingabe | Standard | Bedeutung |
|---|---|---|
| use_cases | leer | Zu bauende Ids; leer heisst jeder genehmigte Use Case, dessen Spezifikation sich auf dem Branch geändert hat. Eine Id, die nicht Approved ist, wird übersprungen |
| correlation_id | – | Id des Laufs; benennt den Ergebnisbranch aiup/werkstatt-<id> und das Artefakt mit den Laufdaten |
| stack_plugin | leer | Ein kombiniertes Stack-Plugin wie aiup-blazor-dotnet; leer für Layer-Plugins |
| java_version | 25 | Temurin-JDK, auf dem Stationen und Build-Kommandos laufen; leer behält den Standard des Runner-Images |
| model | claude-opus-5-5 | Modell jeder Station |
| max_turns | 150 | Turns je Station; stoppt Schleifen, die eigentliche Grenze ist das Kostenbudget |
| max_rounds | 4 | Korrekturrunden je Use Case |
| max_cost_usd | 15 | Kostenbudget je Use Case |
| timeout_minutes | 180 | Obergrenze des ganzen Laufs; die Stationen hören zehn Minuten früher auf |
Die KI-Generierung, die Schaltfläche «In CI ausführen» neben jedem nächsten Schritt im Studio, führt einen Skill aus und liefert sein Ergebnis als Pull Request. Einen Use Case so von Hand zu bauen, ein Lauf nach dem anderen, überlässt die Kontrolle dem Reviewer. Die Werkstatt verkettet die Schritte und prüft das Ergebnis zuerst.
| KI-Generierung (aiup-generate) | Werkstatt (aiup-werkstatt) | |
|---|---|---|
| Was läuft | Ein Skill auf einem Artefakt, vom Anforderungskatalog bis zu den Tests | Der ganze Bau eines Use Cases: Spec-Lint, Implementierung, Tests, Build, Abdeckungsprüfung, Korrekturrunden |
| Sitzungen | Eine | Eine je Station, so benotet kein Agent seine eigene Arbeit |
| Kontrolle | Durch den Reviewer | Durch Gates vor dem Review; nur grüne Use Cases bringen Code mit |
| Umfang | Das Artefakt, auf dem Sie sie starten | Jeder genehmigte Use Case, der sich auf dem Änderungsbranch geändert hat, oder einer, den Sie nennen |
| Ergebnis | Ein Pull Request | Ein Pull Request gegen den Änderungsbranch, mit fortgeschriebenem Status |
| CI | GitHub Actions oder Bitbucket Pipelines | GitHub Actions |
| Im Studio | «In CI ausführen» neben dem Kommando jedes nächsten Schritts | «Änderung bauen» auf der Startseite und der empfohlene erste nächste Schritt eines genehmigten Use Cases |
AI Unified Process Studio schreibt die Spezifikationen, richtet die Werkstatt in Ihrem Repository ein und startet sie auf Ihrem Änderungsbranch. Fordern Sie eine Einladung an, oder nehmen Sie Kontakt auf, wenn Sie Unterstützung beim Einrichten des Harness für Ihren Stack möchten.
