/continuous-refactoring.de

Playbook: Ein Run

Das Playbook für Menschen. Die Skills erledigen die Arbeit; dieses Dokument erklärt, wie du einen Run steuerst – was du im Aufruf sagen kannst, was du unterwegs entscheidest und wie ein Run endet.

Was ein Run ist

Ein Aufruf von /continuous-refactoring ist ein Run. Er führt von den offenen Refactoring-Tickets deines Projekts zu genau einem geöffneten Merge Request:

Abgleich → Track wählen → Scan (nur wenn nötig) → Tickets anlegen → Ticket auswählen → Design → Umsetzung → Merge Request

Ein Run endet, sobald der Merge Request offen ist. Mehr Arbeit ist ein weiterer Aufruf, kein längerer Run – deshalb funktionieren ein wöchentlicher Rhythmus und ein spontaner Aufruf gleichermaßen, und beide laufen dieselbe Kette.

Die Suite behält zwischen zwei Runs nichts. Jeder Run durchsucht deinen Tracker und deine Forge von Neuem: was offen ist, was im Review ist, was gemergt wurde, was du abgelehnt hast. Hast du ein Ticket von Hand geschlossen, etwas außerhalb der Suite gemergt oder ein Tool selbst eingerichtet, findet der nächste Run das einfach so vor.

Auf einem Projekt, das die Suite noch nicht kennt, beginnt der Run mit einem kurzen Onboarding: wo deine Tickets liegen und wie ein paar Operationen dort funktionieren. Die Antwort wird als ein Abschnitt in docs/agents/issue-tracker.md geschrieben; committe diese Datei. Der Run endet dort: Er meldet das Onboarding als abgeschlossen, weist auf die Änderungen in deinem Arbeitsverzeichnis hin und empfiehlt, sie zu committen und den Skill erneut aufzurufen.

Das Onboarding fragt auch, ob dein Projekt Code außerhalb davon Stabilität verspricht – den Nutzern deines Pakets, den Addons deiner Anwendung – und wo dieses Versprechen steht. Ein Projekt, das onboardet wurde, bevor es diese Frage gab, wird einmal zu Beginn seines nächsten Runs gefragt, und der Run geht weiter. Die Antwort entscheidet, ob die Suite eine alte API löschen darf, die sie ersetzt hat, oder sie behalten und so als deprecated markieren muss, wie dein Versprechen es sagt.

Der Aufruf

Sag in eigenen Worten nach dem Befehl, was du willst. Die Suite gibt in einem Satz wieder, was sie verstanden hat.

Du sagst Was sie tut
nichts einen interaktiven Run über alles
„mach das selbst“, „ohne zu fragen“ einen autonomen Run: Jede Entscheidung folgt der eigenen Empfehlung der Suite
einen Track – „arbeite an Guardrails“ diesen Track, egal was die Suite empfohlen hätte; der Run endet, wenn dieser Track nichts zu bearbeiten hat
ein Ticket – „Ticket 42“ genau dieses Ticket: Der Run schaut sich kein anderes Ticket an, den Abgleich eingeschlossen, und endet, falls es sich als nicht mehr nötig herausstellt
eine Einschränkung – „nur die Rector-Tools“ Scan, Anlegen und Auswahl bleiben innerhalb davon
„scanne nochmal“ der Track wird gescannt, obwohl er schon gescannt wurde
ein Tool auf Anfrage – „richte Semgrep ein“ dieses Tool wird gescannt und vorgeschlagen, obwohl die Suite es nie ungefragt anbietet; „scanne inklusive der Tools auf Anfrage“ beurteilt alle

Das lässt sich kombinieren: „mach Guardrails selbst, nur die Sicherheits-Tools“.

Entscheidungspunkte

An jedem Glied der Kette legt die Suite drei Dinge vor: was sie gefunden hat, die Optionen und die eine, die sie empfiehlt, mit der Begründung in wenigen Worten. Nichts wird in deinen Tracker, deine Forge oder dein Repository geschrieben, was nicht aus einem Entscheidungspunkt folgt.

  • In einem interaktiven Run antwortest du. „Ja“ nimmt die Empfehlung.
  • Sag an beliebiger Stelle „mach ab hier selbst weiter“, und der Run ist ab der nächsten Entscheidung autonom. So begleitest du nur die Entscheidungen, die dir wichtig sind.
  • In einem autonomen Run schreibt die Suite bei jeder Entscheidung trotzdem auf, was sie gefunden hat, und nennt dann die Empfehlung, die sie genommen hat. Gefragt wird nichts, aber das Gespräch liest sich wie ein interaktiver Run – du kannst also hinterher sehen, warum es so gelaufen ist.
  • Wurde ein Run ohne den Hinweis auf Autonomie gestartet und niemand antwortet, endet er an diesem Entscheidungspunkt. Was du hinterher vorfindest, ist der Bericht – Befunde, Optionen, Empfehlung –, und nichts wurde geschrieben. Ein unbeaufsichtigter Aufruf ist deshalb standardmäßig sicher; sag „mach das selbst“ im Aufruf, damit er arbeitet.

Eine Änderung wartet immer auf dich, auch in einem autonomen Run: eine Änderung an der AGENTS.md deines Projekts.

Was du in einem Run entscheidest

Entscheidungspunkt Was vorgelegt wird Empfohlen
Onboarding (nur wenn der Tracker-Abschnitt fehlt oder unvollständig ist) der Tracker, wo Merge Requests liegen, jede Operation und woher ihre Antwort kam, und ob ihre Such- und Merge-Request-Befehle geantwortet haben den Abschnitt schreiben
BC-Versprechen (nur wenn der Abschnitt noch keine Antwort hat) die Dokumente, die sich wie ein Versprechen an Code außerhalb des Projekts lesen, mit einer Zeile aus jedem dieses Dokument, ein anderes, keins oder im nächsten Run erneut fragen
Abgleich Merge Requests offener Tickets, die gemergt oder geschlossen wurden, und abgelehnte Arbeit, deren Blocker inzwischen erfüllt ist das Ticket eines gemergten schließen; eine Ablehnung festhalten, wo die Kommentare sagen, dass die Änderung nicht gewollt ist; das Ticket behalten, wo sie einen Mangel nennen; dich fragen, wo ein Merge Request ohne Begründung geschlossen wurde
Track-Wahl pro Track, wie viele Tickets bearbeitbar, im Review, blockiert, wartend sind der erste Track in der festen Reihenfolge, der etwas zu bearbeiten hat (Track-Playbook)
Tickets anlegen (nach einem Scan) ein Vorschlag pro Tool, das weder eingerichtet noch abgelehnt ist, blockierte eingeschlossen, jeweils mit bestehenden Tickets zum Thema alle anlegen, jedes mit seiner offenen Frage am Ticket, wo eine bleibt; du kannst einige, keine anlegen oder ein Tool endgültig ablehnen
Auswahl Tickets, deren Tool sich als bereits eingerichtet herausstellt, Tickets, die nicht bearbeitet werden können, und warum, der Rest in Reihenfolge die erste Gruppe mit einer Notiz schließen, das erste der übrigen bearbeiten
Wer plant, wer umsetzt die Skills, die dein Projekt dafür anbietet die eigenen deines Projekts; das Verfahren der Suite nur als Rückfall
Der Plan der Plan vollständig: was sich ändert, die Slices, die Befehle, die zeigen, dass er erledigt ist, und bei einem strukturellen Ticket der Test, der zuerst das heutige Verhalten festhält ihn auf das Ticket posten; wo dein Tracker-Abschnitt sagt, wie ein Ticket als bereit zur Umsetzung markiert wird, tut die Suite das direkt danach, außer es folgt eine offene Frage
Kommentare auf einem offenen Merge Request (nur wenn du ein Ticket im Review nennst) jeder Kommentar mit dem, was die Suite daraus macht: beheben, verwerfen, fragen wie sortiert weitermachen; den Kommentar eines Menschen verwirft die Suite nie, und der Kommentar eines Bots zu Sicherheit, Daten oder Berechtigungen wird erfragt, nicht verworfen
Der Merge Request Branch, Commits, die gelaufenen Checks, Titel und Beschreibung pushen und öffnen

Ein Entscheidungspunkt, bei dem es nichts zu entscheiden gibt, ist ein Satz statt einer Frage.

Tickets, die auf dich warten

Zwei Befunde am Design-Schritt beenden einen Run, statt zu raten:

  • Eine Entscheidung, die schwer rückgängig zu machen ist und eine echte Abwägung verlangt. In einem interaktiven Run wirst du gefragt. Ein autonomer Run plant mit einer Voreinstellung, hinterlässt die Frage als Kommentar auf dem Ticket, der mit Open question beginnt, und endet.
  • Die Arbeit geht nicht, ohne das Verhalten zu ändern. Ein Refactoring erhält, was die Anwendung tut. Die Suite hinterlässt diesen Befund als offene Frage auf dem Ticket: als Refactoring ablehnen oder zu Feature-Arbeit machen. Ein autonomer Run lehnt ein Ticket nie nach eigenem Urteil ab.

Ein Drittes lässt ein Ticket warten: ein Fix, der nicht hält, bei der Umsetzung. Kommt derselbe fehlschlagende Check oder Review-Befund nach zwei Versuchen wieder, hört die Suite auf, behält den Branch bei sich, ohne ihn zu pushen, und hinterlässt die Schilderung auf dieselbe Weise auf dem Ticket.

Ein Ticket wartet, bis dieser Kommentar beantwortet ist. Antworte mit einem Kommentar auf dem Ticket – jeder neuere Kommentar, der nicht ein weiterer Plan oder eine weitere Frage der Suite ist, beendet das Warten, egal wer ihn geschrieben hat, und der nächste Run liest ihn: Er lässt den Plan stehen, plant neu auf dem Weg, den du genannt hast, hält deine Ablehnung fest oder fragt noch einmal. Es gibt kein Label zu setzen oder zu entfernen.

Wie ein Run endet

  • Ein Merge Request ist offen – reviewe und merge ihn.
  • Ein Branch wurde dir übergeben – es gibt keine Forge, oder du wolltest selbst pushen. Sein Name steht in einem Kommentar auf dem Ticket.
  • Eine offene Frage steht auf dem Ticket – antworte dort.
  • Nichts ist bearbeitbar – jedes offene Ticket ist im Review, blockiert oder wartend.
  • „Safety Net is waiting for merges“ – ein autonomer Run hat im Safety Net nichts Bearbeitbares gefunden, während das Safety Net unfertig ist. Der Bericht listet, was im Review ist. Merge, oder nenne einen anderen Track.
  • Niemand hat auf einen Entscheidungspunkt eines interaktiven Runs geantwortet.

Jeder Run schließt mit zwei Zeilen. Status beginnt damit, wie viele Dinge auf dich warten oder dass keines wartet, und sagt, was passiert ist und wo er endete; Next sagt, was du jetzt tun kannst, und für jedes Wartende, was die Suite empfiehlt und was passiert, wenn du nicht antwortest. Wo sich eine Aussage nicht bestätigen ließ – CI läuft noch, Checks nicht lesbar –, sagt der Bericht das.

Regelmäßig laufen lassen

Die Suite plant nichts selbst ein. Richte deinen eigenen Scheduler (einen Cronjob, /schedule, /loop) auf /continuous-refactoring mach das selbst und auf /continuous-housekeeping mach das selbst, so oft es passt. Soll ein Agent Runs nacheinander aufrufen und dazwischen jeden Merge Request prüfen, siehe das Driver-Playbook.

Nichts begrenzt, wie viele Merge Requests gleichzeitig offen sind. Wiederholt aufgerufen endet Safety Net bei „jedes bearbeitbare Tool hat ein Ticket und einen offenen Merge Request“ – von dort ist der nächste Schritt deiner: reviewen und mergen. Nebeneinander geöffnete Merge Requests können miteinander kollidieren; das aufzulösen ist ebenfalls deine Sache.

Steuern, woran gearbeitet wird

  • Eine Priorität. Wo dein Tracker-Abschnitt sagt, wie ein Ticket als priorisiert markiert wird, kommt ein so markiertes Ticket innerhalb seines Tracks zuerst.
  • Deine eigenen Tickets. Ein Ticket, das du geschrieben hast, wird bearbeitet, wenn dein Tracker-Abschnitt sagt, wie Refactoring-Tickets markiert werden, und es diese Markierung trägt – oder wenn du es im Aufruf nennst.
  • Fokusbereiche und Refactoring-Ziel. Zwei Zeilen in deiner AGENTS.md – Focus areas: order intake, billing und Refactoring goal: convert legacy procedural code to OOP – sagen, wo eine Erkundung zuerst hinschaut und auf welche Form sich der Code zubewegen soll.
  • Ablehnen. Lehne ein Tool beim Anlegen oder bei der Auswahl ab, und es wird mit deiner Begründung an dem Ort festgehalten, den dein Projekt nennt, und nicht wieder vorgeschlagen. Die Tickets, die davon abhingen, sind ein eigener Entscheidungspunkt.

Häufige Fehler

  • Darauf warten, dass die Suite in einem Aufruf mehr macht. Ein Run endet bei einem Merge Request. Ruf erneut auf.
  • Einen unbeaufsichtigten Run starten, ohne es zu sagen. Er endet am ersten Entscheidungspunkt, absichtlich.
  • Eine offene Frage im Gespräch eines späteren Runs beantworten. Antworte auf dem Ticket; dort schaut der nächste Run nach.
  • Bei jedem Run einen Scan erwarten. Ein Track wird einmal gescannt; danach sind seine Tickets der Stand. Bitte um einen Scan, oder lass die Nachprüfung im Housekeeping finden, was sich geändert hat.
  • Reviews zu einer Note zusammenfassen. Das eigene Review der Suite hält zwei Achsen getrennt – tut die Änderung, was der Plan sagt, und folgt sie den Standards des Projekts –, damit ein Fehler auf der einen sichtbar bleibt, wenn die andere in Ordnung ist.