Agentisches Engineering

SwarmForge im Test: So funktioniert Uncle Bobs Agentenschwarm wirklich

Sechs KI-Agenten, sechs Git-Worktrees, eine dauerhafte Nachrichtenschlange und ein Satz Qualitätsgates, die Shell-Befehle sind statt guter Absichten. Der tmux-Teil ist daran das Uninteressanteste.

Mit unserem KI-Engineering-Team sprechen KI-Entwicklungsleistungen ansehen

Das Problem, für das es gebaut ist

Geben Sie einem einzelnen Coding-Agenten ein echtes Feature, und er schreibt Implementierung und Tests in einem Zug, aus demselben Verständnis, mit denselben blinden Flecken. Hat er die Anforderung falsch gelesen, kodieren die Tests dieses Missverständnis und werden grün. Bitten Sie denselben Agenten, seine Arbeit zu prüfen, stimmt er sich selbst zu, denn die Argumentation, die den Code erzeugt hat, steht noch in seinem Kontext und wirkt weiterhin plausibel. Menge macht das schlimmer statt besser: die Ausgabe ist plausibel, reichlich und billig, also wird der prüfende Mensch zum Nadelöhr und fängt an zu überfliegen. SwarmForge ist eine Wette auf eine bestimmte Antwort darauf: Qualität kann nicht vom Autor kommen, also bekommt jede prüfende Disziplin ihren eigenen Agenten, ihren eigenen Kontext, ihren eigenen Arbeitsbaum und eine Prüfung, die entweder mit null endet oder nicht.

Die tragende Entwurfsentscheidung ist nicht Parallelität. Sie ist, dass Rollen ausschließlich über committeten Code kommunizieren. Ein prüfender Agent sieht nie die Erklärung des Autors, warum der Code in Ordnung ist — er sieht einen Commit und einen Task-Namen und lässt seine eigenen Werkzeuge darauf laufen.

Was es mechanisch ist

SwarmForge ist ein Harness aus Shell und Babashka um Primitive, die die meisten Teams schon haben. Jede Rolle ist ein tmux-Fenster, das eine Agenten-CLI gegen einen eigenen Git-Worktree unter .worktrees/ betreibt, sodass nie zwei Agenten dasselbe Arbeitsverzeichnis anfassen. Das Verhalten kommt aus reinem Text: eine constitution.prompt, die Vorrang vor allem anderen beansprucht und dem Agenten sagt, beim Start und bei jeder Aufgabe jede Datei in swarmforge/constitution/articles/ zu lesen und zu befolgen, plus ein Rollen-Prompt unter swarmforge/roles/<role>.prompt. Gemeinsame Artikel regeln Engineering, Handoffs und Workflow; lokale Artikel sind der Ort, an dem ein Projekt sie überschreibt. Kommunikation ist eine dateibasierte Schlange, die einem Daemon gehört, und die einzigen zwei Nachrichtentypen, die ein Agent senden darf, sind ein Git-Handoff und eine Notiz. Das ./swarm-Skript ist nur ein dünner Bootstrap: es holt das Skript-Archiv, falls das Verzeichnis fehlt, und übergibt dann an swarmforge/scripts/swarmforge.sh.

Drei Schwarmformen

Jeder Branch ist eine andere Antwort darauf, wie viel Prozess eine Aufgabe verdient. main ist dokumentarisch; die lauffähigen Topologien liegen auf den Pack-Branches. Der Fluss ist ein Ring, keine Warteschlange.

two-pack

coder → cleaner → coder

Ein coder, der test-first arbeitet, und ein cleaner für Aufräumarbeiten, CRAP- und DRY-Review sowie Architekturkorrekturen. Die kleinste Schleife, die Schreiben und Beurteilen noch trennt, und die einzige Form, deren Kosten bei normaler Arbeit leicht zu rechtfertigen sind.

four-pack

specifier → coder → refactorer → architect → specifier

Gherkin-Akzeptanzspezifikationen stehen am Anfang. Ein refactorer räumt verhaltenserhaltend auf und erhöht die Coverage, ein architect prüft Struktur und Abhängigkeitsrichtung, bevor der Ring zur Spezifikation zurückkehrt.

six-pack

specifier → coder → cleaner → architect → hardener → QA

Ergänzt einen Hardening-Durchgang, der den Code mutiert, um zu finden, wo die Testsuite blind ist, und eine unabhängige QA-Rolle, die über die Benutzeroberfläche verifiziert. Vier der sechs Rollen laufen im Batch-Modus, damit sich Werkzeuge über ein ganzes Prioritätsband amortisieren.

Wie eine Änderung tatsächlich den Ring durchläuft

Dies ist das six-pack, und es lohnt sich, es als Pipeline von Abbruchkriterien zu lesen statt als Liste von Jobtiteln. Jede Zeile ist ein Rollen-Prompt im Repository, und jede Austrittsbedingung ist ein Befehl, der erfolgreich sein muss.

specifier

→ coder

Erhält: Eine Anfrage des Menschen, im master-Worktree
Tut: Schreibt Gherkin-Akzeptanzspezifikationen und die Spezifikation der End-to-End-QA-Suite, stellt Fragen, wo die Absicht unklar ist, und reduziert Beispielparameter auf die Werte, die tatsächlich die Akzeptanzmutation beeinflussen.
Austrittskriterium: Committet nicht, bis der Mensch ausdrücklich zustimmt. Das ist das einzige menschliche Gate im Ring, und es sitzt vorne, wo es am billigsten ist.

coder

→ cleaner

Erhält: Ein Git-Handoff mit einem Commit und einem stabilen Task-Namen
Tut: Schreibt fokussierte Unit-Tests, die das gewünschte Verhalten ausdrücken und, in den Worten des Rollen-Prompts, bei einer plausiblen falschen Implementierung fehlschlagen würden. Dann nur so viel Produktionscode, dass sie grün werden. Generierte Akzeptanztests werden ausdrücklich nicht als Ersatz für Unit-Tests akzeptiert.
Austrittskriterium: Die lokale Verifikation ist grün. Mutation, CRAP und DRY laufen hier nicht — die gehören späteren Rollen, damit der coder seine eigene Arbeit nicht bewerten kann.

cleaner

→ architect

Erhält: Einen Batch gleich priorisierter Handoffs
Tut: Führt zuerst das CRAP-Werkzeug aus und drückt die Komplexität auf 6 oder darunter, dann das DRY-Werkzeug gegen Duplikate, dann das Mutationswerkzeug nur im Scan- und Zählmodus — teilt jede Datei mit mehr als 100 Mutationsstellen — und erhöht die Coverage, wo sinnvoll.
Austrittskriterium: Verhalten unverändert, Tests weiter grün, Komplexität und Duplikation gesenkt. Ausdrücklich verboten: Mutationstests laufen lassen oder Verhalten hinzufügen.

architect

→ hardener

Erhält: Einen Batch aufgeräumter Commits
Tut: Teilt Code in Module mit echten Grenzen, hält Abhängigkeiten nach innen gerichtet, jagt Zyklen und Framework-Lecks und isoliert Anwendungspolitik von UI, Dateisystem, Datenbank und Netzwerk. Ergänzt automatisierte Architekturprüfungen, wo praktikabel.
Austrittskriterium: Verhalten erhalten und Suite grün. Verboten ist git merge per Hand: gemergt wird nur über ready_for_next.sh.

hardener

→ QA

Erhält: Einen Batch strukturell geprüfter Commits
Tut: Führt das Sprach-Mutationswerkzeug Datei für Datei aus, differenziell gegen bestehende Manifeste, mit bis zu acht parallelen Workern, und behebt überlebende Mutanten, bevor es weitergeht. Dann ein Gherkin-Akzeptanzmutationslauf auf soft-Ebene, dann CRAP, dann DRY, in genau dieser Reihenfolge.
Austrittskriterium: Jedes Werkzeug der Kette muss sauber sein, bevor das nächste läuft. Das ist die Rolle, die entscheidet, ob die Tests überhaupt etwas testen.

QA

→ specifier

Erhält: Einen Batch gehärteter Commits
Tut: Unabhängige Endverifikation: die Akzeptanzspezifikation, die End-to-End-Suite über die Benutzeroberfläche ohne API-Abkürzungen, Unit- und Property-Tests sowie projektspezifische Release-Prüfungen. Reproduziert jeden Fehler, bevor Code geändert wird.
Austrittskriterium: Führt CRAP und DRY erneut aus, bevor abgeschlossen wird. Widerspricht die QA-Suite dem Gherkin oder den Unit-Tests, hält sie an und fragt einen Menschen, statt einen Gewinner zu bestimmen.

Der Transport ist der ungewöhnliche Teil

Die meisten Agenten-Frameworks lassen Agenten miteinander reden. SwarmForge tut das bewusst nicht: ein Daemon besitzt die Zustellung, das Dateisystem ist die Schlange, und tmux dient nur dazu, ein untätiges Fenster anzustoßen.

Die Topologie ist eine Konfigurationsdatei

conf

Das gelieferte six-pack setzt jede Rolle auf dasselbe Backend mit aktiviertem Permission-Bypass und markiert die gesamte hintere Hälfte des Rings als Batch-Konsumenten. Der Rollenname muss dem Prompt-Dateinamen entsprechen, der in diesem Repository hardender geschrieben wird.

# swarmforge/swarmforge.conf
# window-invisible <role> <agent> <worktree> [task|batch] [extra-cli-args...]
window-invisible specifier codex master           --yolo
window-invisible coder     codex coder            --yolo
window-invisible cleaner   codex cleaner    batch --yolo
window-invisible architect codex architect  batch --yolo
window-invisible hardender codex hardender  batch --yolo
window-invisible QA        codex QA         batch --yolo

Die Schlange ist ein Verzeichnis, und der Ort ist der Zustand

text

Es gibt keine Datenbank und keinen Broker im Speicher. Die Position eines Handoffs im Baum ist sein Status, der Dateiname sortiert nach Priorität und Zeit, und die Header tragen den Audit-Trail. Ein abgestürzter Schwarm setzt fort, indem er die Platte liest.

.swarmforge/handoffs/
  outbox/
    tmp/            # drafts land here, then get renamed in atomically
  sent/
  failed/           # malformed or undeliverable, with diagnostics
  inbox/
    new/
    in_process/
    completed/

# filename sorts the queue for you
<priority>_<timestamp>_<sequence>_from_<sender>_to_<recipients>.handoff
# priority 00-99, lower first; UTC YYYYMMDDTHHMMSSZ

Ein Agent darf nur bitten, nie zustellen

Der Agent schreibt einen Entwurf mit vier Headern und ruft das Gate-Skript. Er kann id, from, recipient und keinen Zeitstempel schreiben — die sind reserviert, damit die Provenienz im Audit-Trail nicht von dem gefälscht werden kann, was geprüft wird. Er tippt auch keinen SHA: das Skript kanonisiert und validiert den Commit als echtes, eindeutiges Objekt mit zehn Zeichen.

# ./tmp/handoff.txt — drafted inside the assigned worktree
type: git_handoff
to: hardender
priority: 00
task: task-1-cave-setup

# hand it to the protocol gate; the daemon does delivery
swarm_handoff.sh ./tmp/handoff.txt

# receiving side, driven by the role's mode in .swarmforge/roles.tsv
ready_for_next.sh     # -> TASK: / BATCH: / NO_TASK, plus the payload
done_with_current.sh  # -> stamps completed_at, then pulls the next item

Die Gates, die der hardener passieren muss, in dieser Reihenfolge

Das macht den Schwarm zu mehr als einem Rollenspiel. Die Constitution installiert diese Werkzeuge beim Start frisch aus den Repositories des Autors — crap4go, crap4java und crap4clj für Komplexität, mutate4go, clj-mutate und mutate4java für Mutation und die dry4*-Familie für Duplikate — und das Rollen-Prompt legt ihre Reihenfolge fest.

# hardener: nothing advances until the previous check is clean
mutate4go ./...            # one file at a time, differential, <= 8 workers
gherkin-mutator --level soft   # mutate the acceptance examples too
crap4go ./...              # complexity against coverage
dry4go ./...               # duplication

# then, and only then
swarm_handoff.sh ./tmp/handoff.txt   # to: QA

Warum jeder Mechanismus so geformt ist

Als Engineering gelesen sind die meisten seltsam wirkenden Entscheidungen Abwehrmaßnahmen gegen konkrete Fehlermodi von Agenten.

Die Nachricht ist ein Commit, keine Erklärung

Ein Git-Handoff trägt einen Task-Namen und einen validierten Commit. Er kann nicht das Argument des Autors tragen, warum der Code gut ist, denn ein Argument verleitet den nächsten Agenten dazu, ihm zuzustimmen. Ein Commit lädt stattdessen zur Überprüfung ein. Das ist die am besten übertragbare Idee des Projekts.

Wake-ups sind generisch und dürfen verloren gehen

Die tmux-Benachrichtigung des Daemons sagt nur, dass Post da ist und man ready_for_next.sh ausführen soll, wenn man untätig ist. Sie nennt nie eine Datei, also kann kein Agent den interessanten Eintrag herauspicken und die Reihenfolge überspringen, und ein beschäftigter Agent darf sie gefahrlos ignorieren, weil das Abschließen einer Aufgabe die nächste ebenfalls holt.

Notizen sind auf achtzig Zeichen begrenzt und unerwünscht

Agenten dürfen eine freie Notiz nur senden, wenn ein Mensch, das Rollen-Prompt oder die Constitution es ausdrücklich verlangt. Bei Unklarheit oder Widerspruch lautet die Anweisung, anzuhalten und eine Person zu fragen. Das ist eine bewusste Weigerung, Agenten Anforderungen untereinander verhandeln zu lassen — genau dort gehen Multi-Agenten-Setups sonst leise schief.

Jede Rolle bekommt einen Worktree, nicht nur einen Branch

Isolation liegt auf Dateisystemebene, also kann die ganze Fehlerklasse, in der zwei Agenten dieselbe Datei im selben Moment ändern, nicht auftreten. Außerdem bleibt jede Rolle während der Arbeit unabhängig inspizierbar, was mehr zählt als es klingt, wenn man herausfinden will, was ein Schwarm getan hat.

Die hintere Hälfte des Rings konsumiert Batches

Cleaner, architect, hardener und QA nehmen alle wartenden Handoffs derselben Priorität als eine Einheit. Mutationsläufe, Coverage-Läufe und Architekturprüfungen sind pro Aufruf teuer und pro zusätzlicher Datei billig, also ist Batching der Unterschied zwischen einem Gate, das läuft, und einem, das abgeschaltet wird.

Der Standard ist ein Prompt-Baum mit explizitem Vorrang

constitution.prompt beansprucht Autorität, die Artikel tragen die Regeln, lokale Artikel überschreiben sie fürs Projekt, Rollen-Prompts sitzen darüber, und der Agent soll alles bei jeder Aufgabe neu lesen. Ihr Coding-Standard ist damit kein Dokument über die Arbeit mehr, sondern eine Eingabe für sie.

Das Urteil

Die wertvolle Hälfte von SwarmForge ist die Constitution und die Reihenfolge der Gates: benannte Rollen mit einer einzigen Verantwortung, Austrittskriterien, die ausführbare Befehle sind, und die harte Regel, dass der Autor einer Änderung sie niemals bewertet. Diese Hälfte ist wirklich gut, sie ist im Geiste sprachunabhängig, und Sie können sie in diesem Quartal in Ihrer bestehenden CI umsetzen — ganz ohne tmux. Die andere Hälfte, der Daemon und die dauerhafte Dateischlange, ist wunderbar gebaut und löst überwiegend ein Problem, das Sie vermeiden können: laufen Ihre Gates in der CI auf einem Pull Request, bekommen Sie Dauerhaftigkeit, Audit-Trail und Prioritätsreihenfolge kostenlos von Werkzeugen, die Ihr Team ohnehin betreibt.

Lesen Sie es als Referenzimplementierung eines Workflows, nicht als Plattform zum Übernehmen. Fangen Sie mit dem two-pack an, um zu spüren, ob getrennte Rollen Ihrer Arbeit überhaupt helfen, übernehmen Sie die Gate-Kette in jedem Fall, und greifen Sie nach dem Sechs-Rollen-Ring erst, wenn die Kosten eines Defekts die Kosten von sechs Agentenläufen pro Änderung klar übersteigen.

Was es richtig macht

+ Qualitätsgates sind Befehle mit Schwellwerten — Mutation, CRAP, DRY, Coverage — statt Adjektive in einem Styleguide
+ Der Prüfer sieht nie die Argumentation des Autors, nur einen Commit, und nur so ist eine Agentenprüfung überhaupt etwas wert
+ Die Reihenfolge entspricht echter Engineering-Sequenz: spezifizieren, implementieren, aufräumen, umstrukturieren, härten, unabhängig verifizieren
+ Worktree-Isolation beseitigt gleichzeitige Bearbeitungsschäden konstruktiv statt durch Sperren
+ Der Schlangenzustand liegt auf der Platte, mit einem Audit-Trail, den Agenten strukturell nicht fälschen können, also setzt ein Absturz fort und ein Lauf ist rekonstruierbar
+ Das eine menschliche Freigabe-Gate sitzt zur Spezifikationszeit, wo Meinungsänderungen am billigsten sind
+ Alles ist beobachtbarer Klartext — Fenster, die man lesen kann, Prompts, die man ändern kann, eine Schlange, die man mit ls auflistet

Was es Sie kostet

− Die gelieferte Konfiguration betreibt jeden Agenten mit Permission-Bypass, das gesamte Design setzt also voraus, dass Sie sechs Agenten unbeaufsichtigt Befehle in Ihrem Repository ausführen lassen wollen
− Sechs Agentenläufe pro Änderung sind für kleine Arbeit wirtschaftlich absurd, und nichts im Ring entscheidet, dass eine Aufgabe weniger Prozess verdient
− Die ausführbare Toolchain sind die eigenen crap4*-, mutate4*- und dry4*-Projekte des Autors für Go, Clojure und Java — außerhalb dieser Sprachen gilt der Startvertrag der Constitution nicht und Sie liefern eigene Äquivalente
− Diese Werkzeuge bei jedem Start frisch von GitHub zu installieren ist langsam, netzabhängig und eine Lieferketten-Angriffsfläche, die nun Ihnen gehört
− zsh, tmux und Babashka auf macOS ist der glückliche Pfad; Windows bedeutet WSL und einen Terminal-Adapter-Shim
− Die Weiterleitungsregel verlangt, dass eine Rolle stromabwärts weitergibt, unabhängig davon, ob sie etwas geändert hat, der Ring erzeugt also Verkehr, selbst wenn eine Stufe wirkungslos war
− Rollen-Prompts sind keine Durchsetzung: nichts verhindert, dass eine Rolle ihr eigenes Gate überspringt, außer dem Satz, der es ihr verbietet — die echten Garantien sind nur so stark wie Ihre CI-Kopie davon
− Es ist sichtbar in Arbeit — ein Dashboard, eine Hitzeanzeige, ein Fenster-Watchdog und divergierende Pack-Branches, wobei main absichtlich nicht lauffähig ist

Was sich lohnt, auch ohne es zu betreiben

Lassen Sie den Autor die Arbeit niemals bewerten

- Führen Sie die Qualitätswerkzeuge in einem separaten Schritt mit separatem Kontext aus, getrennt von dem, der den Code schrieb
- Geben Sie dem prüfenden Schritt das Diff und die Werkzeuge, nicht die Begründung des Autors
- Bei Agenten-Workflows ist das keine Prozesshygiene, sondern der Unterschied zwischen einem Review und einem Stempel

Machen Sie aus jedem Gate einen Exit-Code

- Komplexität, Duplikate, Coverage und überlebende Mutanten haben alle Werkzeuge, die nicht null zurückgeben
- Legen Sie ihre Reihenfolge fest und stoppen Sie die Pipeline beim ersten Fehlschlag
- Ein Agent handelt korrekt auf einen fehlgeschlagenen Befehl und vage auf einen Absatz Ratschläge

Handoffs schmal, validiert und auditierbar

- Eine Commit-Referenz plus ein stabiler Task-Name zwingt die Absicht in den Code und die Message
- Validieren Sie an der Grenze, damit eine fehlerhafte Anfrage scheitert, bevor die nächste Stufe einen Lauf darauf verschwendet
- Halten Sie Provenienzfelder außerhalb der Reichweite des Senders, wenn der Audit-Trail etwas bedeuten soll

Den Standard dort halten, wo die Arbeit passiert

- Regeln als Prompt-Artikel werden bei jeder Aufgabe gelesen, im Gegensatz zu einer Wiki-Seite, die niemand öffnet
- Gemeinsame Regeln von projektlokalen Overrides trennen, damit die Ausnahme eines Teams nicht zur Regel für alle wird
- Mit dem Code versionieren und Änderungen daran wie Code reviewen

Der Workflow ist der Beitrag

Nimmt man tmux, Babashka und die Tarball-Installation weg, bleibt eine These über Software-Engineering: die Disziplinen, die Code bewohnbar halten, sind trennbar, jede verdient ihren eigenen Durchgang mit eigenen Anweisungen, und keine davon kann glaubwürdig von der Partei ausgeführt werden, die den Code geschrieben hat. Das galt schon vor Agenten. Agenten verändern nur den Einsatz, denn das Ausgabevolumen ist gestiegen und der prüfende Mensch nicht schneller geworden.

Übernehmen Sie also die Teile, die die Übersetzung überstehen. Benennen Sie Ihre Durchgänge und geben Sie jedem eine Aufgabe. Machen Sie jedes Austrittskriterium zu einem Befehl. Setzen Sie das menschliche Gate auf die Spezifikationszeit. Verweigern Sie dem Autor einer Änderung jede Rolle bei ihrer Beurteilung. Ob diese Pipeline aus sechs tmux-Fenstern, zwei Menschen oder einer CI-Datei mit fünf geordneten Jobs besteht, zählt weit weniger als die Frage, ob die Gates existieren und wirklich laufen.

FAQ

Was braucht man, um SwarmForge zu betreiben?

zsh, git, tmux und Babashka sowie eine konfigurierte Agenten-CLI wie Claude, Codex, Copilot oder Grok. Es gibt keinen Cloud-Dienst und keine Orchestrierungsschicht aufzusetzen: der Schwarm besteht aus tmux-Fenstern, die man beobachten kann, Worktrees pro Rolle auf der Platte und einer Schlange aus Textdateien.

Mit welchem Branch sollte ein Team starten?

two-pack. Zwei Rollen genügen, um zu erkennen, ob die Trennung von Schreiben und Beurteilen Ihrer Arbeit hilft, und die Kosten eines Sechs-Rollen-Rings sind vorher sehr schwer zu rechtfertigen. main ist dokumentarisch und betreibt keinen Schwarm.

Ist es sicher, Agenten mit Permission-Bypass zu betreiben?

Das ist die größte offene Betriebsfrage des Designs. Die gelieferte Konfiguration gibt jeder Rolle Bypass-Flags, und nur das macht einen unbeaufsichtigten Ring überhaupt möglich. Wenn Sie es probieren, dann auf einem wegwerfbaren Klon oder in einem Container ohne Zugangsdaten, und halten Sie die echten Qualitätsgates in der CI, wo der Schwarm sie nicht überspringen kann.

Funktioniert es nur für Go, Clojure und Java?

Die Orchestrierung ist sprachunabhängig, die ausführbaren Gates sind es nicht. Die Constitution nennt die eigenen Mutations-, CRAP- und DRY-Werkzeuge des Autors für diese drei Sprachen. Auf anderen Stacks behalten Sie die Rollenstruktur und setzen Äquivalente ein, etwa Stryker oder PIT für Mutation und einen beliebigen Bericht aus Komplexität plus Coverage für die CRAP-Berechnung.

Erübrigt ein Agentenschwarm die QA?

Nein, und das Design behauptet es auch nicht. Es hebt QA in eine benannte Rolle mit ausführbaren Skripten und einer ausdrücklichen Regel, anzuhalten und einen Menschen zu fragen, wenn die QA-Suite der Spezifikation widerspricht. Irgendwer muss weiterhin wissen, was das Produkt seinen Nutzern schuldet, und irgendwer gibt das Release frei.

Welche Idee lohnt sich am meisten zu kopieren?

Dass der Agent, der den Code geschrieben hat, der schlechtestmögliche Richter darüber ist, und dass die Lösung ein separater Kontext mit einem Werkzeug samt Exit-Code ist. Alles andere im Repository ist Implementierungsdetail dieses Satzes.