Review, während der Agent noch arbeitet

Um 10:40 Uhr startest du einen verwalteten Run auf dem Billing-Service: "Dokumentiere, wie man den Service lokal aufsetzt und startet." Um 11:02 Uhr kommt ein Pull Request mit einer neuen docs/setup.md. Sie ist ordentlich. Zeile 12 sagt neuen Kolleginnen und Kollegen, sie sollen go build ./... ausführen, was die Build-Tags auslässt, die der Service braucht. Ihr erster Build schlägt also auf eine Weise fehl, die das Dokument nirgends erklärt. Und irgendwann um Minute sechs hat der Agent entschieden, dass der Docker-Abschnitt der README veraltet ist, und ihn neu geschrieben. Darum hatte niemand gebeten.

Nichts davon ist im Review schwer zu beheben. Was das Review nicht zurückgeben kann, sind die zwanzig Minuten dazwischen. Der Agent hat diese Entscheidungen früh getroffen, ohne dass jemand sie geprüft hat, und alles Weitere darauf aufgebaut. Die Korrektur ist dann ein zweiter Run, der bei null anfängt, dieselben Dateien noch einmal liest und einen zweiten Pull Request öffnet.

So haben Archyls Managed Agent Runs bisher funktioniert. Die Run-Seite hatte einen Ereignis-Feed und ein Steuerungsfeld, du konntest den Tool-Aufrufen also folgen, wenn du den Tab offen gelassen hast, am Laptop oder auf dem Handy. Aber was der Agent vorhatte und was er bis dahin geschrieben hatte, musstest du dir aus den Payloads der Tool-Aufrufe zusammensuchen oder aus dem Pull Request erfahren. Für ein nächtliches Dependency-Audit ist das in Ordnung. Für eine Änderung, die du sowieso reviewen wirst, legt es das Review genau an die Stelle, an der es am meisten kostet.

Runs haben jetzt eine Review-Schleife. Das hat sich geändert:

Der Rest dieses Posts spielt dieselbe Aufgabe noch einmal durch, auf die neue Art, in der Reihenfolge, in der du sie erleben würdest. Die Aufgabe ist ein Beispiel; jede unten zitierte Nachricht hat das Format, das der Agent tatsächlich erhält.

Zuerst kommt der Plan

Bevor er eine Datei anfasst, wird der Agent angewiesen, propose_plan mit einer Zusammenfassung in einem Satz und ein paar konkreten Schritten aufzurufen. Der Prompt verlangt 3 bis 8, und das Tool lehnt mehr als 12 ab, damit ein Plan auf einen Blick lesbar bleibt. Das Panel Plan oben auf der Run-Seite macht daraus eine Checkliste. Während der Agent arbeitet, markiert er jeden Schritt als In Arbeit, Erledigt oder Übersprungen, manchmal mit einer kurzen Notiz, und das Panel zeigt den aktuellen Schritt und den Fortschritt (2/4).

Standardmäßig wird der Plan geteilt, und der Agent legt sofort los. Schalte Plan zuerst prüfen unter Koordination im Agentenprofil ein, dann wartet er stattdessen auf dich. Das Panel wechselt in den Review-Modus, in dem du Schritte umbenennen, Details ergänzen sowie Schritte hinzufügen, entfernen oder neu anordnen kannst.

Für das Setup-Dokument hat der Agent fünf Schritte vorgeschlagen. Der vierte war "Docker-Abschnitt der README aktualisieren", die Neufassung, um die niemand gebeten hatte. Du entfernst ihn, ergänzt ein Detail an Schritt 2, und aus dem Button Plan freigeben wird Bearbeiteten Plan freigeben. Das bekommt der Agent zurück:

The plan was approved with edits. Follow this plan:
1. Read the Makefile, docker-compose.yml and the config loader
2. Write prerequisites and environment variables — take values from .env.example, never from a real .env
3. Document the build, test and run commands
4. Link docs/setup.md from the README
Call update_plan when each step starts and when it is done or skipped.

Deine bearbeitete Fassung ist der Plan, dem der Agent folgt, und der, den die Checkliste abbildet. Ist ein Plan falsch und nicht nur leicht daneben, schickt Änderungen anfordern stattdessen Feedback. Der Agent überarbeitet ihn und schlägt eine neue Revision vor, und frühere Revisionen bleiben im Feed, damit du siehst, was dein Feedback verändert hat.

Solange kein Plan freigegeben ist, kann der Agent weder Dateien schreiben noch über Archyls Tools das Architekturmodell ändern noch über einen Konnektor in ein Repository pushen. Das ist keine Zeile im Prompt, an der er sich vorbeiargumentieren könnte. Die Aufrufe werden abgelehnt, und der Agent liest:

changes are refused until your plan is approved: call propose_plan and wait for the review

Prüft niemand den Plan innerhalb einer Stunde, schlägt der Run fehl, ohne etwas geändert zu haben. Ein Profil, das ein Review verlangt, darf es nicht überspringen, nur weil niemand aufgetaucht ist.

Fragen, wenn ein Mensch entscheiden muss

Manche Entscheidungen sollte der Agent nicht allein treffen: eine mehrdeutige Anforderung, ein Zielkonflikt ohne klaren Gewinner, etwas Destruktives. Dafür hat er ask_human. Seine Anweisungen sagen ihm, nie nach etwas zu fragen, das er selbst nachschlagen kann, und er hat höchstens 5 Fragen pro Run, damit er dir die Arbeit nicht Frage für Frage zurückgeben kann.

Mitten in Schritt 2 findet der Agent eine STAGING_DATABASE_URL in der Konfiguration. Sie zu dokumentieren wäre hilfreich, nur braucht Staging einen VPN-Zugang, den neue Kolleginnen und Kollegen in ihrer ersten Woche nicht bekommen. Nichts im Repository sagt das, also fragt er.

Die Frage erscheint über dem Feed, mit Vorgeschlagene Antworten, wenn der Agent welche anbietet ("Staging weglassen", "Erwähnen, mit einem Hinweis zum VPN-Zugang"), und einem Feld für deine eigene Antwort (Cmd/Ctrl + Enter sendet sie). Alle, die das Projekt bearbeiten dürfen, können antworten, und der Feed hält fest, wer es getan hat. Der Agent liest The human answered: Leave staging out und macht weiter.

Eine Frage, die niemand innerhalb einer Stunde beantwortet, lässt den Run nicht fehlschlagen. Der Agent arbeitet nach eigenem Ermessen weiter und nennt in seinem Ergebnis die Annahme, die er getroffen hat. Das ist das Gegenteil des Plans, und der Unterschied liegt darin, was auf dem Spiel steht: Ein ungeprüfter Plan bedeutet, dass nichts vereinbart wurde, während eine unbeantwortete Frage nur eine weitere Entscheidung von der Art ist, die der Agent den ganzen Run über trifft.

Was Warten kostet

Während der Agent auf ein Plan-Review oder eine Antwort wartet, zeigt der Run Wartet auf Sie, und die Run-Liste führt ihn unter Braucht Sie. Ein Banner über dem Feed sagt, worauf er wartet, Wartet auf Ihre Planprüfung oder Der Agent hat eine Frage, und bringt dich direkt dorthin.

Die Wartezeit zählt nicht zum Zeitlimit des Runs. Seine Deadline verschiebt sich um die Wartezeit nach hinten, sodass ein Run mit einem Limit von 30 Minuten, der 20 Minuten auf dich gewartet hat, trotzdem 30 Minuten Arbeitszeit bekommt. Seinen Slot für gleichzeitige Runs behält er allerdings. Ein Run im Status Wartet auf Freigabe hat noch nicht begonnen und hält deshalb nichts, aber ein wartender Run steckt mitten in einer Konversation, mit offenem Workspace, bereit weiterzumachen, sobald deine Antwort ihn erreicht.

Der Diff, während er entsteht

Die Run-Seite hat jetzt zwei Ansichten: Aktivität, den Ereignis-Feed, und Änderungen. Änderungen listet jede Datei auf, die der Agent schreibt, sobald er sie schreibt, mit einem Status (Hinzugefügt, Geändert oder Blockiert) und den hinzugefügten und entfernten Zeilen, pro Datei und für den ganzen Run. Wähle eine Datei aus, um zu sehen, was jeder einzelne Schreibvorgang geändert hat (Bearbeitung 2 von 3), nicht nur den Endzustand.

Der Guard, die Konformitätsprüfung bei jedem Schreibvorgang, die jetzt im Worker läuft, taucht hier ebenfalls auf. Ein Schreibvorgang, den er abgelehnt hat, ist Blockiert: Der Diff zeigt, was der Agent schreiben wollte, zusammen mit der verletzten Regel, auch wenn dieser Inhalt die Datei nie erreicht hat. Ein Schreibvorgang, den er nur markiert hat, geht durch, mit einer Warnung an der Datei. Eine Ablehnung, die du früher in einem Tool-Ergebnis gefunden hast, ist jetzt ein Diff, den du lesen kannst.

Zwei Grenzen: Lange Diffs werden nach 600 Zeilen abgeschnitten, und Dateien über 128 KB erscheinen ohne Diff.

Ein Kommentar an Zeile 12

Zurück zu go build ./.... Du musst nicht auf den Pull Request warten. Klick in Änderungen auf die Zeilennummer, schreib den Kommentar und dann An den Agenten senden (Cmd/Ctrl + Enter). Bei seinem nächsten Schritt erhält der Agent ihn als Code-Review-Kommentar, mit der Datei, der Zeile und ihrem Inhalt:

[Review comment from a human operator on docs/setup.md, line 12 of the file as you wrote it]
> go build ./...
Use the make target instead, it sets the build tags.
Address the comment in that file, then carry on with your plan.

Er korrigiert die Zeile und kehrt dann zu seinem Schritt zurück. Unter der Zeile steht beim Kommentar Eingereiht, bis der Agent ihn aufnimmt, danach Zugestellt. Er erscheint auch in Aktivität, und jede Datei in der Liste zeigt, wie viele Kommentare sie hat. Die Korrektur kommt, wenn sie kommt, als nächste Bearbeitung der Datei, also ist der Diff, in dem du den Kommentar hinterlassen hast, auch der, in dem du sie prüfst.

Du kannst hinzugefügte, unveränderte und entfernte Zeilen kommentieren. Ein Kommentar an einer entfernten Zeile erreicht den Agenten als Kommentar zu "the lines you removed", und so sagst du ihm, dass er eine Prüfung wieder einbauen soll. Kommentare werden angenommen, solange der Agent arbeitet oder auf dich wartet, und ein wartender Agent liest sie, wenn er weitermacht. Ein Kommentar, der am Ende des Runs noch Eingereiht ist, zeigt Nicht zugestellt. Vom Guard blockierte Schreibvorgänge lassen sich nicht kommentieren.

Das Steuerungsfeld gibt es weiterhin, um den Agenten per Freitext umzulenken, ohne den Run abzubrechen ("Migration überspringen, konzentrier dich auf den Handler"). Ein Zeilenkommentar ist derselbe Mechanismus, an eine Zeile geheftet. Was er dir erspart, ist die Vorrede: "in docs/setup.md, wo du go build geschrieben hast" steht schon in der Nachricht.

Der Run, bei dem es nichts zu reviewen gab

Während ich Änderungen gebaut habe, habe ich einen Run gebeten, einem unserer Git-Repositories Dokumentation hinzuzufügen, und zugesehen, wie die Ansicht leer blieb. Keine Dateien, kein Diff, nichts zu kommentieren.

Das Projekt hatte kein verknüpftes Repository, also hatte Archyl nichts geklont. Was der Run hatte, war ein GitHub-Konnektor, und der Agent hat mit den Tools vor seiner Nase das Vernünftige getan: Er hat die Dateien mit dem Tool push_files des Konnektors direkt nach GitHub geschrieben. Nichts lief durch einen Workspace. Also lief nichts durch den Guard, nichts erschien in Änderungen, und die Review-Schleife, die ich gerade baute, hatte nichts zu reviewen.

Der Agent arbeitet jetzt in beiden Fällen in einem Workspace:

• Ein Repository ist mit dem Projekt verknüpft. Archyl klont es beim Start des Runs, wie bisher.
• Kein verknüpftes Repository, aber ein GitHub-Konnektor ist angebunden. Der Agent klont das Repository, um das es in der Aufgabe geht, selbst, indem er open_repository mit den Zugangsdaten des Konnektors aufruft, bevor er eine Datei anfasst. Das funktioniert nur mit dem gehosteten MCP-Server von GitHub (api.githubcopilot.com), und das Token braucht Zugriff auf das Repository.

Sobald ein Workspace offen ist, werden die Konnektor-Tools, die in ein Repository schreiben (push_files, create_or_update_file, delete_file, create_pull_request), abgelehnt, und der Agent liest:

a repository workspace is open: change files with write_file and edit_file instead. Archyl commits your changes and opens the pull request when the run ends.

Diese Regel sorgt dafür, dass jede Änderung durch den Guard läuft, in Änderungen erscheint und in einem einzigen Pull Request landet.

Wenn der Run endet

Archyl committet die Änderungen aus dem Workspace auf archyl/agent-<run id>, mit den ersten acht Zeichen der Run-ID, und öffnet einen Pull Request gegen den Branch, von dem der Klon ausging. Der Link steht oben in Änderungen (Pull Request öffnen) und im Ergebnis. Wie der Run endet, entscheidet, was veröffentlicht wird:

Auf GitLab ist der Entwurf ein Draft:-Merge-Request. Auf Bitbucket wird der Branch ohne Pull Request gepusht. Ein Run, der keine Dateien geändert hat, veröffentlicht nichts.

Deine Kommentare werden zum nächsten Run

Das Review hört nicht auf, wenn der Run aufhört. Der Pull Request ist offen, und du liest den finalen Diff in Änderungen. Ein Kommentar an einem beendeten Run hat keinen Agenten mehr, den er erreichen könnte, also wird er zur Notiz für den nächsten: Für die Fortsetzung merken hält ihn in deinem Browser fest. Eine Leiste über den Dateien zählt sie (3 Kommentare für eine Fortsetzung) und bietet Damit fortsetzen an.

Jeder beendete Run bietet, egal wie er ausgegangen ist, zwei Buttons. Erneut ausführen öffnet den Startdialog mit derselben Aufgabe und demselben Profil, für einen frischen Run von vorn: die richtige Wahl, wenn der erste Versuch in eine Richtung gegangen ist, auf der du nicht aufbauen willst. Fortsetzen startet einen neuen Run, der die Arbeit dieses Runs aufgreift, mit Anweisungen, die aus deinen Kommentaren für die Fortsetzung vorausgefüllt sind, falls du welche hinterlassen hast, einer pro Zeile:

- docs/setup.md:28 — Say that make seed needs the database container running.
- docs/setup.md:44 — Add how to run the tests for a single package.
- README.md:18 (removed line) — Keep the troubleshooting note for port 5432, setup.md doesn't have it.

Bearbeite sie nach Belieben. Das Profil ist standardmäßig das des Runs, und du kannst Konnektoren auswählen.

Gleicher Branch, gleicher Pull Request

Eine Fortsetzung ist mehr als ein frischer Run mit einem längeren Prompt. Sie startet auf dem Branch, den der vorherige Run veröffentlicht hat, committet darauf und fügt ihre Änderungen demselben Pull Request hinzu, statt einen weiteren zu öffnen. Hat der vorherige Run sein Repository über den GitHub-Konnektor geöffnet, öffnet die Fortsetzung es auf diesem Branch erneut, bevor der Agent startet.

Der Agent erfährt außerdem, worauf er aufbaut. Die vorherige Aufgabe, was dieser Run getan hat (seine Ergebnis-Zusammenfassung oder warum er gestoppt hat) und wo seine Arbeit liegt, stehen alle am Anfang seines Prompts (IDs, URL und Zusammenfassung sind Beispiele):

# Continuing a previous run
This run continues the work of run `4f1c2a9e-7b3d-4e0a-9c6f-2d8b1a5e3c70`. Build on what it did rather than starting over.

## What it was asked
Document how to set up and run the service locally.

## What it did
Added docs/setup.md with prerequisites, environment variables and the make targets, and linked it from the README. Left the staging database out, as answered.

Its changes are on the branch `archyl/agent-4f1c2a9e`, which your workspace starts from. Your changes are added to its pull request: https://github.com/acme/billing/pull/212. If the workspace could not start from that branch, the run feed says so and your changes go to a new pull request.

The task below is what the person wants now, often review comments on that work: address each of them.

Reviewer sehen einen Pull Request wachsen, nicht eine Spur davon. GitHubs Copilot cloud agent handhabt Nacharbeiten genauso: Du erwähnst @copilot in einem Kommentar zu einem Pull Request, und standardmäßig pusht er Commits auf den Branch dieses Pull Requests (GitHub Docs). Ein Pull Request pro Arbeitspaket ist die richtige Form, und Fortsetzungen halten sich daran.

Womit du an den Rändern rechnen solltest:

• Der Branch ist weg, zum Beispiel gemergt und gelöscht. Die Fortsetzung startet vom Standard-Branch und öffnet einen neuen Pull Request, und eine orangefarbene Zeile im Feed sagt das: "Der Branch archyl/agent-4f1c2a9e der vorherigen Ausführung konnte nicht ausgecheckt werden. Diese Ausführung startet vom Standard-Branch und eröffnet einen neuen Pull Request."
• Der Pull Request ist ein Entwurf. Er bleibt ein Entwurf. Markiere ihn als bereit zum Review, sobald die Arbeit erledigt ist.
• Nur Agenten-Branches. Archyl setzt auf Branches fort, die seine Agenten erstellt haben, also denen unter archyl/, und committet nie auf einen Branch, den ein Mensch angelegt hat.

Die beiden Runs verweisen aufeinander: Der neue zeigt Fortsetzung von, der vorherige Fortgesetzt in. Ein Run, der noch läuft, kann nicht fortgesetzt werden. Kommentiere stattdessen seine Zeilen.

Die Fortsetzung behält auch ihren Architekturkontext. Ihre Arbeitssitzung wird für die vorherige Aufgabe plus die Nacharbeit geöffnet, nicht für die Nacharbeit allein, sodass sie dieselben Architekturelemente und dasselbe Gedächtnis findet wie der Run, den sie fortsetzt. Das ist wichtiger, als es klingt. "Erwähne, dass make seed einen laufenden Datenbank-Container braucht" nennt überhaupt keinen Service, und eine Sitzung, die nur auf dieser Zeile geöffnet würde, hätte kaum etwas, woran sie anknüpfen könnte.

Was es nicht tut

Der Worker hat keine Shell. Er liest, schreibt, bearbeitet, listet und durchsucht Dateien, aber er kann das Projekt nicht bauen und die Tests nicht ausführen. In diesem Beispiel kann er das Makefile lesen, aber nicht make build ausführen, um zu prüfen, ob das Dokument stimmt. Ein sauberer Diff ist kein grüner Build, und diesen Job macht weiterhin die CI.

Ein Zeilenkommentar ist ein Hinweis, kein Gate. Es gibt keinen Status "erledigt", und nichts prüft, ob der Agent einen Kommentar umgesetzt hat. Du siehst seine nächste Bearbeitung im Diff und beurteilst sie.

Notizen für die Fortsetzung leben in einem Browser. Bis du den Run fortsetzt, sehen deine Teamkollegen die Kommentare nicht, die du dir für die Fortsetzung gemerkt hast. Kommentare an einen laufenden Agenten sind anders: Sie stehen für alle sichtbar im Feed.

Plan-Review setzt voraus, dass jemand da ist. Es ist eine Einstellung pro Profil, standardmäßig aus, und jeder Run auf diesem Profil hält sich daran, geplante Runs eingeschlossen. Ein Run um 3 Uhr nachts auf einem Profil mit aktiviertem Review wartet eine Stunde und schlägt dann fehl, ohne etwas zu ändern. Fragen warten ebenfalls eine Stunde, dann entscheidet der Agent allein.

Das Klonen über den Konnektor gibt es nur für GitHub. open_repository funktioniert mit dem gehosteten MCP-Server von GitHub. Für jeden anderen Host verknüpfst du das Repository mit dem Projekt.

Wo du anfängst

Nimm eine kleine Aufgabe, die du sowieso reviewen würdest, und starte sie auf einem Profil, bei dem Plan zuerst prüfen eingeschaltet ist. Lass die Run-Seite offen. Bearbeite den Plan, bevor du ihn freigibst, auch wenn du nur den Schritt entfernst, um den du nicht gebeten hättest. Kommentiere in Änderungen die erste Zeile, die du im Pull Request angemerkt hättest, und sieh zu, wie aus Eingereiht Zugestellt wird. Wenn der Run endet, hinterlass den Rest als Kommentare für die Fortsetzung und klick auf Fortsetzen.

Lass Plan-Review bei den Profilen aus, die deine Zeitpläne nutzen, es sei denn, jemand ist wach, um zu reviewen.

Pläne, Fragen, der Live-Diff, Zeilenkommentare und Fortsetzungen sind Teil der Managed Agent Runs in Archyl. Jede oben genannte Einstellung und Beschriftung steht in der Dokumentation zu Managed Agent Runs. Weiterlesen: Verwaltete Agenten unterstehen jetzt dem Harness, zum Guard und zu den Arbeitssitzungen, auf denen das aufbaut, und der Start der Managed Agent Runs.