¶Playbook: Der Housekeeping-Track

Das Playbook für Menschen. Der Skill erledigt die Arbeit; dieses Dokument erklärt, wie du Housekeeping steuerst – die Vorlage, das stehende Ticket, den Rhythmus und die Ideen, die du darauf hinterlässt.

¶Was es ist

Wiederkehrende Wartung: Dependency-Aktualität, ein Audit der Abhängigkeiten auf bekannte Schwachstellen, Tooling-Deprecation-Cleanup, ein Secret-Scan über die Git-Historie, eine Nachprüfung des Qualitäts-Toolings des Projekts – plus die kleinen Refactoring-Ideen, die bei anderer Arbeit aufkommen.

Es besteht aus zwei Dingen in deinem Projekt:

• Die Housekeeping-Vorlage – eine Datei in deinem Repository, die die wiederkehrenden Aufgaben und den Rhythmus auflistet. Sie wird geteilt und gereviewt wie Code.
• Das Housekeeping-Ticket – ein offenes Ticket, aus der Vorlage erstellt, das sagt, ab wann es fällig ist. Seine letzte Aufgabe ist „das nächste Housekeeping-Ticket anlegen“, so trägt sich der Zyklus selbst: Es ist immer eines offen, und das offene Ticket ist der gesamte Zustand.

Ein bearbeitetes Ticket ist ein Zyklus. Er endet mit einem Merge Request, der enthält, was sich geändert hat – oder, wo nichts geändert werden musste, mit dem geschlossenen Ticket und einem Kommentar, der das sagt.

¶Zwei Wege hinein

• /continuous-housekeeping führt Housekeeping aus und sonst nichts. Es braucht keine Track-Wahl, deshalb ist es das, was du in einen Zeitplan einhängst. Es folgt denselben zwei Modi wie jeder Run: Es fragt bei jeder Entscheidung oder entscheidet selbst, wenn du das im Aufruf sagst.
• /continuous-refactoring empfiehlt Housekeeping bei der Track-Wahl, wenn sein Ticket fällig ist oder es noch nicht eingerichtet ist.

¶Einrichten

Der erste Aufruf, der keinen Housekeeping-Mechanismus findet, schlägt einen vor, als einen einzigen Entscheidungspunkt:

• die Vorlage, mit einem empfohlenen Pfad und den Aufgaben: der Secret-Scan, die Nachprüfung des Toolings, das Dependency-Audit und eine Aufgabe für jedes bereits eingerichtete Tool, das wiederkehrende Aufmerksamkeit braucht;
• den Rhythmus – daily, weekly, monthly oder deine eigenen Worte (every 3 days, monthly on the 1st). Die Empfehlung leitet sich davon ab, wie aktiv das Repository in den letzten 90 Tagen war;
• das erste Ticket, fällig ab heute;
• eine Zeile für deine AGENTS.md (unten). Diese wird in jedem Modus bei dir erfragt; ein autonomer Run, der keine Antwort bekommt, lässt sie weg und sagt das.

Was du bestätigst, wird auf dem Branch des ersten Tickets committet. Du wählst, wie es geliefert wird: mit dem ersten Zyklus, der dann im selben Aufruf läuft und dessen Merge Request das Setup mitbringt – oder das Setup allein, in einem Merge Request, der das Ticket nennt, ohne es zu schließen; das Ticket bleibt offen, und ein späterer Aufruf bearbeitet seinen ersten Zyklus, sobald du das Setup gemergt hast. Die Vorlage wird dir vollständig gezeigt, bevor du zustimmst, und ein älteres Ticket zur Einführung von Housekeeping, das die Suche findet, wird mit einem Vorschlag dafür genannt. Bis du es mergst, ist der Mechanismus noch nicht auf deinem Default-Branch; ein Aufruf dazwischen sagt dir, dass das Setup auf diesen Merge wartet.

Eine bestehende Datei, die bereits wiederkehrende Wartungsaufgaben auflistet, wird als Vorlage vorgeschlagen, ihre Aufgaben bleiben erhalten.

¶Rhythmus und Fälligkeit

Jedes Ticket nennt das Datum, ab dem es fällig ist, in einer eigenen Zeile. Ein Aufruf vor diesem Datum findet nichts zu bearbeiten und endet mit Nennung des Datums – ein täglicher geplanter Aufruf bei wöchentlichem Rhythmus ist also harmlos. Um ein Ticket früher zu bearbeiten, sag „jetzt“ im Aufruf oder nenne das Ticket.

Das nächste Ticket ist einen Rhythmus nach dem Tag fällig, an dem der Zyklus bearbeitet wurde, nicht nach dem alten Fälligkeitsdatum. Ändere den Rhythmus, indem du die Zeile in der Vorlage bearbeitest; das nächste daraus erstellte Ticket folgt ihr.

Mehrere Vorlagen mit unterschiedlichen Rhythmen können nebeneinander existieren – etwa eine wöchentliche und eine monatliche –, jede mit ihrem eigenen offenen Ticket. Bitte im Aufruf um eine weitere („eine monatliche neben der wöchentlichen“). Der Secret-Scan, die Tooling-Nachprüfung, das Dependency-Audit und die eigenen Aufgaben der Tools bleiben in der ersten Vorlage; eine weitere enthält die Aufgaben, die du nennst.

¶Was ein Zyklus bearbeitet

1. Die wiederkehrenden Aufgaben des Tickets, der Reihe nach. Jede wird auf dem Ticket abgehakt, mit ihrem Ergebnis in einer Zeile, sodass das Ticket der Nachweis des Zyklus ist und ein unterbrochener Zyklus dort weitermacht, wo er aufgehört hat.
2. Aufgaben, die dem Ticket fehlen: eine, die die Vorlage seitdem dazubekommen hat, eine stehende Aufgabe, die einer früher geschriebenen Vorlage fehlt (etwa das Dependency-Audit), oder eine für ein Tool, das eingerichtet ist, während die Vorlage keine Aufgabe dafür hat – so bekommt ein Tool, das du von Hand eingerichtet hast, seine wiederkehrende Prüfung.
3. Die Ideen, die als Kommentare auf dem Ticket hinterlassen wurden.

Bevor irgendetwas davon gemacht wird, wird der Zyklus als ein Entscheidungspunkt vorgelegt: die Aufgaben, die neuen und jede Idee mit dem, was die Suite daraus macht.

¶Ideen als Kommentare

Jeder – du oder ein Agent mitten in Feature-Arbeit – kann eine Refactoring-Idee als Kommentar auf dem offenen Housekeeping-Ticket hinterlassen. Der Zyklus sortiert jede ein:

Ein Kommentar am Ende des Zyklus sagt, was aus jeder Idee geworden ist.

¶Die Zeile in der AGENTS.md

Refactoring ideas. When you notice a possible refactoring while doing other work, ask the human whether to note it. Once they agree, post it as a comment on the open Housekeeping ticket: where it is, what would change, and why. When two Housekeeping tickets are open, ask the human which one, and recommend the younger.

Sinngemäß: Bemerkt ein Agent bei anderer Arbeit ein mögliches Refactoring, fragt er dich, ob er es notieren soll. Stimmst du zu, postet er es als Kommentar auf das offene Housekeeping-Ticket: wo es ist, was sich ändern würde und warum. Sind zwei Housekeeping-Tickets offen, fragt er dich, welches, und empfiehlt das jüngere.

Die Zeile macht das Housekeeping-Ticket zu dem Ort, an dem Ideen aus der Feature-Arbeit landen, statt verloren zu gehen. Ein Agent fragt dich vor dem Kommentieren, weil ein Kommentar in deinem Tracker ein Schreibvorgang ist, um den du nicht gebeten hast.

¶Der Secret-Scan

Der erste Zyklus scannt die gesamte Git-Historie; jeder spätere scannt die Commits, die seit dem vorherigen Scan hinzugekommen sind. Er nutzt den Secret-Scanner, den dein Projekt bereits einsetzt, mit dessen eigener Liste bekannter Befunde. Ohne einen führt der Agent einen eigenen Scanner aus (etwa gitleaks), ohne deinem Projekt etwas hinzuzufügen; nur wo keiner laufen kann, wird die Aufgabe als nicht ausgeführt abgehakt und im nächsten Zyklus erneut versucht. Ein Befund wird nur mit seiner Fundstelle gemeldet – der Wert des Secrets wird nirgends geschrieben. Wo Leute außerhalb des Projekts den Tracker lesen können, ist die Empfehlung, für einen Befund kein Ticket anzulegen und es dir im Gespräch zu sagen.

¶Die Nachprüfung des Toolings

Ein Scan von Safety Net und Guardrails, Tools mit offenem Ticket eingeschlossen: Ist jedes bisher eingerichtete Tool noch vorhanden, und gibt es ein weiteres einzurichten? Lücken gehen durch denselben Entscheidungspunkt wie die Vorschläge jedes Scans.

¶Das Ergebnis lesen

Reviewe den Merge Request des Zyklus wie jeden anderen: ein Commit pro Aufgabe, die etwas geändert hat, einer oder mehrere pro Idee. Eine Aufgabe ohne sauberen Weg – ein Security-Advisory ohne gepatchte Version, ein Update, das sich nicht grün machen lässt – wird nicht erzwungen: Der Branch behält nur, was grün ist, die Aufgabe wird mit dem Befund abgehakt, und der Rest wird als gewöhnliches Ticket vorgeschlagen, über das du entscheidest.

Housekeeping hält aktuell, was das Projekt schon hat. Ein Tool, das dem Projekt fehlt, ist ein Ticket der Tooling-Tracks, nie etwas, das ein Zyklus installiert.

¶Housekeeping-Hinweise in gewöhnlichen Merge Requests

Ein Merge Request, der ein Tool einrichtet – etwa Semgrep –, kann der Housekeeping-Vorlage auch eine wiederkehrende Aufgabe hinzufügen. Seine Beschreibung sagt das in einer Zeile. Das ist der eigene Beitrag des Tools zu künftigen Zyklen, keine zweite Entscheidung.

¶Häufige Fehler

• Den Merge Request des Setups ungemergt lassen. Bis er gemergt ist, gibt es keine Vorlage auf dem Default-Branch, und spätere Aufrufe warten darauf.
• Das Fälligkeitsdatum bearbeiten, um einen Zyklus zu überspringen. Ändere stattdessen den Rhythmus in der Vorlage; das Datum wird geschrieben, wenn das nächste Ticket erstellt wird.
• Ein großes Refactoring in einen Kommentar packen und erwarten, dass es im Zyklus erledigt wird. Es wird ein eigenes Ticket.
• Einen Befund ohne sauberen Fix als etwas behandeln, das durchgedrückt werden muss. Er wird dir absichtlich als Ticket übergeben.