sxivansx/loop-engineering

Loop Engineering

Richten Sie einen Loop ein: ein autonomes System, das den Agenten promptet, sodass Sie es nicht tun müssen. Sie definieren das Ziel und die Stopp-Bedingung einmal; der Loop findet Arbeit, erledigt sie, prüft sie, notiert, was passiert ist, und läuft erneut, bis das Ziel erreicht ist. Diese Fähigkeit richtet diesen Loop in Ihrem bestehenden Projekt ein: Sie liest, wie Sie bereits testen, bauen und Arbeit verfolgen, und passt den Loop an Ihre Konventionen an, anstatt generische aufzuzwingen.

Ein Loop besteht aus sechs Grundbausteinen. Richten Sie nur diejenigen ein, die das Ziel benötigt.

Grundbaustein	Rolle im Loop	Claude Code Mechanismus
Auslöser	startet jeden Zyklus, nach einem Zeitplan oder einem Ereignis	/goal (Arbeit über mehrere Sitzungen hinweg, bis eine Bedingung erfüllt ist), /loop, geplante Tasks, Hooks, GitHub Actions
Zustand	der Speicher des Loops zwischen den Zyklen, auf der Festplatte	eine Markdown-Datei (LOOP.md) oder ein Issue-Tracker via MCP
Entdeckung	findet heraus, woran in diesem Zyklus gearbeitet werden soll	ein Triage-Schritt, der CI, Issues, Diffs oder eine Warteschlange liest
Maker	erledigt eine Einheit der Arbeit	ein Subagent in .claude/agents/
Prüfer	verifiziert den Maker, unabhängig	ein anderer Subagent in .claude/agents/
Stopp-Bedingung	die Regel, die den Loop beendet	eine überprüfbare Prüfung, die der Prüfer durchführt

Fügen Sie für jeden Loop, der unbeaufsichtigt läuft, einen Monitor hinzu: einen Überwachungsagenten, der den Loop als Ganzes beobachtet und ihn bei Abweichung (vom Ziel entfernen), Drehen (kein Nettofortschritt) oder Überschreiten einer Grenze (zu viele Zyklen, zu lange) stoppt. Maker und Prüfer halten jedes Element korrekt; der Monitor hält den gesamten Loop auf das Ziel ausgerichtet, damit er nicht leise abweicht und stundenlang läuft.

Zwei weitere optionale Erweiterungen: Worktrees (git worktree) isolieren parallele Maker, damit sie nicht dieselben Dateien bearbeiten, und MCP-Konnektoren erlauben dem Loop, echte Werkzeuge zu nutzen (PR öffnen, Ticket aktualisieren, Status melden). Fügen Sie sie hinzu, wenn das Ziel Parallelität oder externe Seiteneffekte erfordert.

Einrichtungsprozedur

Dies läuft innerhalb eines bestehenden Projekts. Befolgen Sie diese Schritte, wenn sie aufgerufen werden. Bestätigen Sie mit dem Benutzer, bevor irgendetwas mit Seiteneffekten passiert: geplante Jobs, Pushes, Ticket-Schreibvorgänge, Deployments.

1. Lesen Sie zuerst das Projekt. Bevor Sie etwas gerüsten, lernen Sie das Repository: wie es Tests, Build und Lint ausführt (prüfen Sie package.json, Makefile, CI-Konfiguration, CLAUDE.md); welche Konventionen und vorhandenen Skills oder .claude/agents/ es bereits hat; und woher die Arbeit kommt (CI, ein Issue-Tracker, ein Backlog, eine Warteschlange). Der Loop muss zu diesem Projekt passen. Verwenden Sie seine echten Befehle und Konventionen wieder, erfinden Sie keine neuen.

2. Legen Sie das Ziel und die Stopp-Bedingung fest. Fragen Sie den Benutzer nach dem einen Ziel des Loops und der überprüfbaren Bedingung, die „erledigt“ bedeutet (Tests beenden mit Exit 0, die Warteschlange ist leer, null fehlgeschlagene Prüfungen). Ein Loop ohne Stopp-Bedingung ist das Einzige, das Sie niemals ausliefern dürfen. Wenn der Benutzer keine nennen kann, setzen Sie eine begrenzte Fallback-Lösung (stopp nach N Zyklen) und sagen Sie dies laut. In Claude Code macht /goal <Bedingung> dies ausführbar: Claude arbeitet über mehrere Sitzungen hinweg, bis die Bedingung erfüllt ist, und /goal clear beendet es vorzeitig.

3. Schreiben Sie die Zustandsdatei. Kopieren Sie ${CLAUDE_SKILL_DIR}/templates/LOOP.md in das Stammverzeichnis des Repositorys und füllen Sie Ziel, Stopp-Bedingung, Kadenz und das menschliche Tor aus. Sie hat drei lebende Abschnitte, die der Loop pflegt: ## Offen (gefunden, nicht erledigt), ## Erledigt (mit dem Nachweis, der es verifiziert hat), ## Blockiert (benötigt einen Menschen), plus einen ## Regeln-Abschnitt, der das dauerhafte Anweisungsset ist, dem jeder Agent im Loop folgt. Der Loop liest dies zuerst jeden Zyklus und schreibt es zuletzt.

4. Erstellen Sie den Maker-Subagenten. Kopieren Sie ${CLAUDE_SKILL_DIR}/templates/loop-maker.md nach .claude/agents/loop-maker.md und weisen Sie es auf die Konventionen und den Testbefehl hin, die Sie in Schritt 1 gefunden haben. Es erledigt genau ein Element aus ## Offen, folgt den vorhandenen Skills und Konventionen des Projekts und markiert seine eigene Arbeit nie als erledigt. Wenn eine Datei mit diesem Namen bereits existiert, aktualisieren Sie sie, anstatt blind zu überschreiben.

5. Erstellen Sie den Prüfer-Subagenten. Kopieren Sie ${CLAUDE_SKILL_DIR}/templates/loop-checker.md nach .claude/agents/loop-checker.md. Es ist ein anderer Agent als der Maker, es führt die tatsächliche Verifikation des Projekts aus (den echten Test-, Build- oder Lint-Befehl aus Schritt 1, nicht eine Beschreibung davon), und es ist der einzige Agent, der ein Element nach ## Erledigt verschieben darf.

6. Erstellen Sie den Monitor-Subagenten (empfohlen für jeden unbeaufsichtigten Loop). Kopieren Sie ${CLAUDE_SKILL_DIR}/templates/loop-monitor.md nach .claude/agents/loop-monitor.md und führen Sie es alle paar Zyklen oder mit einem langsameren Timer als dem Loop aus. Es beobachtet den Loop als Ganzes und nicht einzelne Elemente: Es prüft, ob der Loop immer noch auf das Ziel zusteuert, und stoppt den Loop und eskaliert an einen Menschen bei Abweichung (Arbeit, die nicht dem Ziel dient), Drehen (kein Nettofortschritt, Elemente springen zwischen Offen und Blockiert) oder Überschreiten einer Grenze. Dies verhindert, dass ein Loop leise abweicht und stundenlang läuft.

7. Legen Sie die Kadenz für Code-Review und Sicherheitsaudit fest (fragen Sie den Benutzer). Fragen Sie, wie oft der Loop jedes durchführen soll, und notieren Sie beides in LOOP.md. Bieten Sie klare Optionen an und schließen Sie immer nie ein:

   • Code-Review (/code-review): jede Änderung, vor jedem PR oder Merge, alle N Zyklen, wöchentlich oder nie.
   • Sicherheitsaudit (/security-review): jede Änderung, vor jedem PR oder Merge, wöchentlich, monatlich oder nie.

   Mit der gewählten Kadenz führt der Loop diesen integrierten Durchlauf aus und fügt die Ergebnisse als neue Arbeitselemente in ## Offen ein, sodass der Maker sie repariert und der Prüfer die Reparatur verifiziert. Wenn der Benutzer „nie“ wählt, überspringen Sie diesen Durchlauf vollständig und notieren Sie „nie“ in LOOP.md, damit der Loop ihn nicht wieder einführt.

8. Definieren Sie die Entdeckung. Schreiben Sie den Triage-Schritt, der ## Offen jeden Zyklus aus den tatsächlichen Quellen der Arbeit dieses Projekts füllt (CI-Status, offene Issues, aktuelle Commits, eine Arbeitswarteschlange), und wie er Erkenntnisse in diskrete, einzeln überprüfbare Elemente umwandelt. Machen Sie es so deterministisch wie möglich.

9. Wählen Sie Isolation (optional). Wenn mehr als ein Maker pro Zyklus läuft, geben Sie jedem seinen eigenen git worktree und Branch, damit sie nie dieselbe Datei beschreiben. Ein Worktree pro Element.

10. Verdrahten Sie Konnektoren (optional). Wenn der Loop PRs öffnen, Tickets aktualisieren oder Status melden muss, verbinden Sie den passenden MCP-Server. Andernfalls bleibt die Ausgabe des Loops lokal und ein Mensch leitet sie weiter.

11. Legen Sie den Auslöser fest. Wählen Sie den leichtesten Mechanismus, der zur Kadenz passt:

    • Laufen, bis das Ziel erreicht ist, in dieser Sitzung → /goal <Stopp-Bedingung> (Claude arbeitet über mehrere Sitzungen hinweg, bis die Bedingung wahr ist; /goal clear beendet es vorzeitig)
    • Nach einer Kadenz wiederholen, auf Abruf → /loop
    • Periodisch und unbeaufsichtigt → ein geplanter Task (oder Cron / eine GitHub Action für loops auf CI-Seite)
    • Auf ein Ereignis reagieren (Push, PR, Dateiänderung) → ein Hook oder eine GitHub Action

    Bestätigen Sie mit dem Benutzer, bevor Sie einen geplanten Job erstellen.

12. Trockentest, Verifikation, dann Aktivieren. Führen Sie einen Zyklus manuell durch. Lesen Sie alles, was er produziert hat. Bestätigen Sie, dass der Prüfer tatsächlich schlechte Ausgaben blockiert und dass der Zustand geschrieben wurde. Erst dann schalten Sie den Auslöser ein.

Leitplanken (nicht verhandelbar)

• Der Prüfer ist niemals der Maker. Der Agent, der den Code geschrieben hat, darf ihn nicht für korrekt erklären.
• Die Stopp-Bedingung ist überprüfbar, nicht Bauchgefühl. „Sieht erledigt aus“ ist keine Stopp-Bedingung. Ein Befehl, der mit Exitcode 0 endet, ist es.
• Der Zustand wird jeden Zyklus geschrieben. Wenn der Loop vergisst, was er versucht hat, wiederholt er sich. Das Modell vergisst; die Datei nicht.
• Ein menschliches Tor bleibt bei allem Irreversiblen bestehen. Ausliefern, Deployen, Löschen, Geld ausgeben. Der Loop entwirft, eine Person bestätigt. Ein unbeaufsichtigter Loop macht unbeaufsichtigte Fehler.
• Blockiert ist besser als Raten. Wenn der Loop nicht verifizieren oder fortfahren kann, schreibt er in ## Blockiert und stoppt dieses Element. Er liefert keine Schätzung aus.
• Ein langer Loop wird überwacht und begrenzt. Jeder unbeaufsichtigte Loop läuft mit einem Monitor und einer Begrenzung. Wenn er vom Ziel abweicht oder die Begrenzung überschreitet, stoppt der Monitor ihn und eskaliert. Ein Loop darf niemals ewig in die falsche Richtung laufen.

Wie der Loop nach der Einrichtung aussieht

Ihr-Projekt/
├── LOOP.md                   # Ziel, Stopp-Bedingung, Grenzen, Regeln, Offen/Erledigt/Blockiert
├── .claude/
│   └── agents/
│       ├── loop-maker.md      # erledigt eine Einheit Arbeit
│       ├── loop-checker.md    # verifiziert sie, unabhängig
│       └── loop-monitor.md    # beobachtet den gesamten Loop auf Abweichung + Ausbruch
└── (Auslöser: /goal, /loop, ein geplanter Task oder eine GitHub Action)

Anti-Patterns: Liefern Sie diese nicht aus

• Ein Loop ohne Stopp-Bedingung (läuft ewig, verbrennt Tokens).
• Ein Agent, der seine eigene Arbeit schreibt und benotet.
• Ein Loop ohne Zustandsdatei (leitet alles neu ab, wiederholt Arbeit, vergisst, was fehlgeschlagen ist).
• Ein unbeaufsichtigter Loop ohne Monitor oder Begrenzung (weicht vom Ziel ab und läuft stundenlang, bevor es jemand bemerkt).
• Unbeaufsichtigtes Ausliefern ohne menschliches Tor bei irreversiblen Aktionen.
• Ein Loop, der viele unabhängige Jobs trägt. Ein Loop, ein Ziel, eine Stopp-Bedingung. Teilen Sie den Rest in ihre eigenen Loops auf.

Dateien in dieser Fähigkeit

• templates/LOOP.md: die Zustandsdatei, die in das Ziel-Repository kopiert werden soll.
• templates/loop-maker.md: die Maker-Subagenten-Definition.
• templates/loop-checker.md: die Prüfer-Subagenten-Definition.
• templates/loop-monitor.md: die Monitor-Subagenten-Definition (Schutz vor Abweichung und Ausbruch).
• examples/keep-ci-green.md: ein vollständig ausgearbeiteter Loop, vom Ziel bis zum Auslöser.