Eine Merge-Queue für KI-Agenten ist der zuverlässigste Weg, main grün zu halten, sobald du mehr als einen Agenten gleichzeitig laufen lässt. Mit einem einzelnen Agenten gibt es kein Drama: Er arbeitet auf einem Branch, du schaust ihn dir an, du mergst. Wenn aber drei oder vier Agenten anfangen, auf ihren eigenen Branches fertig zu werden, ändert sich das. Jeder Branch besteht für sich, du mergst sie nacheinander, und main ist rot.
Dieser Beitrag erklärt, warum Branches paralleler Agenten main brechen, wie eine Merge-Queue das behebt und wie die Merge-Queue von AgentVera Schritt für Schritt funktioniert.
Allein grün, zusammen rot
Beginnen wir mit einem Beispiel. In main gibt es eine Funktion formatPrice(amount). Du lässt zwei Agenten gleichzeitig laufen:
- Agent A fügt einen Währungsparameter hinzu:
formatPrice(amount, currency), und aktualisiert jede Aufrufstelle. - Agent B baut einen neuen Rechnungsbildschirm, der
formatPrice(amount)aufruft.
Beide Branches starteten vom selben main. As Tests bestehen, denn in As Welt gibt es den Rechnungsbildschirm nicht. Bs Tests bestehen, denn in Bs Welt hat die Funktion noch ein Argument. Auch Git sieht keinen Konflikt: Die beiden Branches haben unterschiedliche Dateien angefasst.
Du mergst A, dann B. Git sagt nichts. Doch main ruft jetzt eine Funktion mit zwei Parametern mit einem Argument auf, und die Typprüfung schlägt fehl.
Das ist ein semantischer Konflikt: kein textueller Konflikt, und trotzdem brechen sich die Änderungen gegenseitig. Parallele Agenten machen ihn häufiger, weil:
- Agenten einander nicht sehen. Jeder arbeitet in seinem eigenen Worktree und weiß nicht, was die anderen tun.
- Branches sich schnell anhäufen. Am frühen Nachmittag können fünf oder sechs Branches warten.
- Jeder Branch auf einer alten Basis getestet wurde. Je länger ein Branch wartet, desto veralteter ist seine Basis.
- Das Mergen in Reihenfolge von Hand mühsam ist. Nach jedem Merge aktualisierst du den nächsten Branch, startest die Tests neu und behebst Konflikte. Man fängt an, es zu überspringen.
Was ist eine Merge-Queue?
Eine Merge-Queue reiht die Branches ein, die auf ihre Übernahme warten, mergt jeden auf die aktuelle Spitze des Zielbranches und testet dann dieses Ergebnis. Die Idee ist einfach: Bevor ein Branch landet, teste, wie main nach seiner Landung tatsächlich aussehen wird.
Im Vergleich zum Mergen von Hand:
| Mergen von Hand | Merge-Queue | |
|---|---|---|
| Worauf der Test läuft | Die eigene Basis des Branches | Aktuelle Spitze von main + der Branch |
| Semantische Konflikte | Werden gefunden, nachdem sie main getroffen haben | Werden vor der Landung abgefangen |
| Reihenfolge | Wer zuerst klickt | Reihenfolge der Queue |
| Ein defekter Branch | Bricht main | Wird abgelehnt, main bleibt sauber |
Auch GitHub hat eine Merge-Queue auf Repository-Ebene, die Pull Requests einreiht und sie zusammen mit der neuesten Version des Zielbranches testet. Die Queue von AgentVera wendet dieselbe Idee auf deinem Desktop für die Branches deiner Agenten an und ergänzt Agenten, die unterwegs Merge-Konflikte lösen und fehlschlagende Checks reparieren.
So funktioniert die Merge-Queue von AgentVera
Die Queue steckt in der Desktop-App unter Details → Automation → Merge queue. Jedes Projekt hat eine Queue; in einem Multi-Repo-Projekt hat jedes Repo seine eigene Queue und eigene Einstellungen. Branches landen einer nach dem anderen.
1. Ein Branch tritt der Queue bei
Es gibt drei Wege hinein:
- Von Hand: Gib den Branch-Namen im Feld Branch ein, vergib optional einen Title und drücke Add to queue.
- Aus einem Parallel-Team: Wenn ein Parallel-Team fertig ist, schickst du seinen Integrations-Branch mit Queue.
- Aus einer Automation: Wähle als Auslieferung einer Automationsregel Add to the merge queue, und der Branch des fertigen Agenten geht direkt in die Queue.
Auch Karten im Review-Posteingang bieten Send to the merge queue. Jeder Eintrag zeigt, woher er kam: manuell, Parallel-Team oder Automation.
2. Er wird auf die aktuelle Spitze des Ziels gemergt
Wenn er an der Reihe ist, wird der Branch in einem eigenen, separaten Worktree der Queue auf die aktuelle Spitze des Ziels gemergt. Dein Arbeitsordner und die Ordner deiner Agenten bleiben unberührt. Hat das Repo ein Remote, wird zuerst das Ziel geholt und der Merge auf der neuesten origin-Version ausgeführt.
Die Strategie wählst du in den Einstellungen: Merge commit oder Squash. Ist der Branch bereits im Ziel enthalten, wird der Eintrag als gelandet markiert.
3. Ein Konflikt bekommt einen Agenten
Gibt es beim Merge einen Konflikt, hält die Queue nicht an. Sie öffnet einen Resolver-Agenten, und der Eintrag wechselt auf „resolving conflicts“. Dem Agenten wird gesagt, er solle die Absicht beider Seiten bewahren, keine Konfliktmarker zurücklassen und das Ergebnis committen.
Wenn der Agent abgibt, verlässt sich AgentVera nicht einfach auf sein Wort. Es prüft auf ungemergte Dateien, sucht nach den Markern <<<<<<< und >>>>>>> und bestätigt, dass der Branch wirklich gemergt ist. Schlägt davon etwas fehl, schlägt der Eintrag fehl und landet nicht.
Ist „Automatic model“ an, wird das Modell des Resolvers nach der Schwierigkeit der Aufgabe gewählt.
4. Der Check läuft auf dem gemergten Ergebnis
Sobald das gemergte Ergebnis bereitsteht, führt die Queue einen Check-Befehl aus. Lass Check leer, dann nutzt sie den Testbefehl des Projekts, oder schreib einen eigenen wie pnpm typecheck && pnpm test.
Schlägt der Check fehl, bekommt der Resolver-Agent das Ende der Ausgabe und versucht, es zu reparieren. Es gibt höchstens zwei Reparaturrunden. Ist der Check dann immer noch rot, wird der Eintrag rejected (abgelehnt), und die Queue macht weiter. Der defekte Branch erreicht main nie.
Genau das passiert im formatPrice-Beispiel: Bs Branch wird auf ein main gemergt, das schon A enthält, die Typprüfung schlägt fehl, der Resolver passt den Aufruf des Rechnungsbildschirms an die neue Signatur an, und der Check wird grün.
5. Freigabe und Landung
Ein Branch, der besteht, ist bereit. Standardmäßig ist Land passing branches automatically aus, der Eintrag wartet also als „ready, awaiting approval“, und du bekommst eine Benachrichtigung. Sieh ihn dir an und drücke Land, wenn du zufrieden bist.
Die Landung läuft so:
- Mit Remote wird das gemergte Ergebnis auf den Zielbranch gepusht. GitHub-Repos nutzen die GitHub-Anmeldung auf deinem Rechner.
- Ohne Remote wird der lokale Zielbranch per Fast-Forward vorgezogen. Er wird nie unter nicht committeter Arbeit weggezogen.
- Hat sich das Ziel inzwischen bewegt, wird der Eintrag auf der neuen Spitze neu aufgebaut und erneut geprüft. Das passiert höchstens dreimal; bewegt sich das Ziel weiter, schlägt der Eintrag fehl.
Schließt du die App und öffnest sie wieder, geht unterbrochene Arbeit nicht verloren; sie kommt zurück in die Queue.
Einstellungen
Es sind nicht viele, und alle liegen im selben Tab:
| Einstellung | Was sie tut | Standard |
|---|---|---|
| Target branch | Der Branch, auf dem die Arbeit landet | Leer: Standardbranch |
| Merge | Merge commit oder Squash | Merge commit |
| Check | Befehl, der auf dem gemergten Ergebnis läuft | Leer: der Testbefehl des Projekts |
| Land passing branches automatically | Lässt bestandene Branches ohne Freigabe landen | Aus |
Bei eingereihten Einträgen kannst du mit Up und Down umsortieren, einen mit Cancel stoppen und einen fehlgeschlagenen oder abgebrochenen mit Retry neu starten. Jeder Eintrag hat sein eigenes Log und seinen Verlauf, und Einträge mit Pull Request haben einen Button, der ihn auf GitHub öffnet.
Die Queue teilt sich Ressourcen mit anderer Hintergrundarbeit und hat Vorrang: Merges laufen vor Automationen und Parallel-Teams. Agenten, die du selbst startest, werden nie eingereiht.
Parallel-Teams und die Queue zusammen
Die Merge-Queue zahlt sich am meisten mit einem Parallel-Team aus. Ein Parallel-Team teilt eine große Aufgabe in bis zu acht Teile auf; standardmäßig laufen drei Agenten gleichzeitig, jeder in seinem eigenen Worktree. Die Teile werden in einen Integrations-Branch gemergt, und ein Integrations-Agent kümmert sich um Konflikte und den Check.
Wenn das Team fertig ist, hast du einen Integrations-Branch. Schick ihn mit Queue ab. Inzwischen kann ein anderes Team oder eine Automation etwas auf main geschickt haben; die Queue nimmt alles der Reihe nach und testet jeden Eintrag auf dem neuesten main.
Einen größeren Überblick über die Arbeit mit mehreren Agenten gibt dir parallele Coding-Agenten.
Häufige Fehler
- Ein leerer Check und kein Testbefehl. Die Queue mergt trotzdem, kann aber ohne etwas zu prüfen keine semantischen Konflikte abfangen. Definiere den Testbefehl des Projekts oder trage einen Befehl in Check ein.
- Nur Unit-Tests. Viele Brüche wie der oben zeigen sich in der Typprüfung oder im Build. Nimm diese in den Check auf.
- Automatische Landung am ersten Tag einschalten. Aktiviere Land passing branches automatically nicht, bevor du die Queue eine Weile beobachtet hast. Gib erst ein paar Wochen von Hand frei.
- Riesige Branches. Die Queue nimmt sie an, aber die Wahrscheinlichkeit für Konflikte und Fehlschläge wächst mit der Größe. Gib Agenten kleine, klar umrissene Aufgaben.
- Abgelehnte Einträge ignorieren. Eine Ablehnung deutet meist auf einen echten Design-Konflikt hin. Lies das Log und schick die Arbeit bei Bedarf mit einer Notiz an den Agenten zurück.
Ein Beispieltag
Morgens
Du startest drei Agenten für drei Aufgaben: die Checkout-Seite, die Reporting-API und ein Dependency-Update. Jeder arbeitet in seinem eigenen Worktree. Dazu gibt es einen CI-Fehler von letzter Nacht; eine Automationsregel hat ihn schon aufgefangen und den Fix in die Queue geschickt.
Spätvormittag
Während die Agenten fertig werden, öffnest du ihre Karten im Review-Posteingang. Die Checkout-Seite und die Reporting-API sehen gut aus, also nutzt du für beide Send to the merge queue. In der Queue stehen jetzt drei Einträge: der CI-Fix, die Checkout-Seite und die Reporting-API.
Mittags
Der CI-Fix besteht seinen Check und wartet auf Freigabe. Du drückst Land. Die Checkout-Seite wird auf das neue main gemergt und besteht. Die Reporting-API kollidiert mit einem Typ, den die Checkout-Seite geändert hat; der Resolver-Agent greift ein, passt die Aufrufstellen an, und der Check wird grün. Du hast nur zweimal freigegeben.
Nachmittags
Das Dependency-Update ist nach zwei Reparaturrunden immer noch rot und wird abgelehnt. main bleibt sauber. Das Log zeigt einen Major-Versionssprung in einer Bibliothek, also gibst du die Arbeit mit engeren Anweisungen an einen Agenten zurück.
Checkliste
- Hat das Projekt einen Testbefehl, oder steht ein Befehl in Check?
- Deckt der Check Typprüfung und Build ab?
- Stimmt der Target branch? Leer bedeutet den Standardbranch.
- Passt die Merge-Strategie zur Gewohnheit deines Teams: Merge commit oder Squash?
- Ist Land passing branches automatically mit Absicht an oder aus?
- Bist du bei GitHub-Repos auf diesem Rechner bei GitHub angemeldet?
- Sind die Aufgaben deiner Agenten klein und klar umrissen?
Zum Schluss
Parallele Agenten sind schnell, aber Tempo, das main bricht, hält nicht. Eine Merge-Queue mergt und testet jeden Branch auf dem neuesten main, sodass Branches, die allein bestehen, main nicht gemeinsam brechen können. In AgentVera übergibt die Queue Konflikte und fehlschlagende Checks an einen Agenten, prüft das Ergebnis selbst und überlässt dir standardmäßig das letzte Wort.
Mehr dazu:
Um AgentVera auszuprobieren, starte auf der Startseite.