invincible04/awesome-loop-engineering

Loop Engineering

Hilf dem Benutzer, sich selbst als das Wesen zu ersetzen, das einen Coding-Agenten promptet. Das Ergebnis ist ein kleines System, das Arbeit entdeckt, sie einem Maker übergibt, das Ergebnis mit einem separaten Checker verifiziert, aufschreibt, was erledigt ist, entscheidet, was als Nächstes kommt, und so lange wiederholt, bis ein Ziel erreicht ist – dann stoppt es aus einem ehrlichen Grund.

Deine Aufgabe in diesem Skill ist es nicht, den Loop in einem Durchgang für sie zu schreiben. Es ist, zu interviewen, den Vertrag zu entwerfen, dann zu scaffolden, sodass sie am Ende einen Loop haben, den sie tatsächlich ausführen und dem sie vertrauen können.

Was ein Loop ist und was nicht

Ein Loop ist kein Cron-Job. Ein Cron-Job wiederholt blind. Ein Loop entdeckt Arbeit, verifiziert sie mit einem separaten Checker, persistiert den Zustand, entscheidet, was als Nächstes kommt, und stoppt aus einem Grund. Wenn das Ding, das du baust, nicht von selbst aufhören kann, ist es ein Bug, kein Loop.

Baue zuerst Stopp-Bedingungen. Sie sind es, die dem Benutzer erlauben, wegzugehen.

Schritt 0: Entscheide, ob ein Loop überhaupt das richtige Werkzeug ist

Bevor du etwas entwirfst, wende diesen Test an. Ein Loop lohnt sich nur, wenn beide Bedingungen zutreffen:

1. Es gibt ein klares, maschinenprüfbares Erfolgskriterium (ein Test besteht, ein Build ist grün, ein Schema validiert, eine Rubrik gibt PASS zurück).
2. Es zu erreichen, erfordert mühsames Ausprobieren, das der Benutzer sonst von Hand erledigen würde, Runde für Runde.

Wenn der Benutzer nicht sagen kann, wie eine Maschine wüsste, dass die Arbeit erledigt ist, stoppe und sage es. Ein Loop ohne verifizierbare Done-Bedingung konvergiert nicht; er thrash und verbrennt Tokens. Hilf ihnen, zuerst einen prüfbaren Proxy zu finden, oder empfehle, dass sie weiter von Hand prompten. Baue keinen Loop, um das Verständnis der Arbeit zu vermeiden.

Gute Loop-Kandidaten: Fehlgeschlagene CI beheben, ein Issue-Postfach triagieren, Abhängigkeitsupgrades mit einer soliden Testsuite, Performance-Tuning mit einem Benchmark, flaky Tests jagen, Doc-Builds, die grün bleiben müssen. Schlechte Kandidaten: Offenes Design, alles, wo „gut“ eine Frage des Geschmacks ohne Proxy ist, einmalige Aufgaben.

Schritt 1: Befrage den Benutzer (fülle den Loop-Vertrag)

Stelle diese Fragen. Beginne mit der Verifikationsfrage – sie ist diejenige, die entscheidet, ob der Loop lebensfähig ist. Frage nicht alle elf auf einmal; frage in kleinen Batches und erschließe so viel wie möglich sicher aus dem Repository.

1. Ziel. Was ist die wiederkehrende Arbeit, die du immer wieder von Hand erledigst? Was soll der Loop wahr machen?
2. Done-Bedingung (zuerst fragen, hart fragen). Wie würde eine Maschine wissen, dass es erledigt ist, ohne dass ein Mensch hinsieht? Nenne den genauen Befehl oder die Prüfung.
3. Auslöser. Was startet einen Durchlauf: ein Zeitplan (alle N Minuten/nächtlich) oder ein Ereignis (Push, neues Issue, Webhook, CI-Fehler)?
4. Entdecken / Aufnehmen. Wie wählt ein Durchlauf aus, woran er arbeitet? (CI-Status lesen, Issue-Tracker abfragen, eine fix_plan.md lesen, Alarme scannen)
5. Arbeitsbereich. Wo handelt er, und was ist streng tabu? (ein Git-Worktree oder eine Sandbox; niemals force-push, Secrets anfassen, Dependencies ändern, Produktion treffen)
6. Kontext. Was muss jeder Durchlauf lesen, um das Projekt nicht von null ableiten zu müssen? (eine SKILL.md / AGENTS.md, das Pflichtenheft, die Memory-Datei)
7. Delegation. Welcher Agent erledigt die Arbeit (der Maker), und welcher separate prüft sie (der Checker)? Sie dürfen nicht derselbe Aufruf sein.
8. Verifikation. Welche Tore müssen durchlaufen werden, damit „erledigt“ wahr ist? (Unit-Tests, Lint, Typen, eine LLM-als-Richter Rubrik, die PASS/FAIL mit Beweisen zurückgibt)
9. Memory / Zustand. Wo wird der Fortschritt gespeichert, sodass ein Durchlauf nach einem Neustart fortgesetzt werden kann? (eine Markdown-Datei, ein Issue-Tracker, ein state.json auf der Festplatte)
10. Budget. Die harten Obergrenzen: maximale Iterationen, maximale Laufzeit, maximale Tokens und eine Dollargrenze, falls eine Berechtigung Geld ausgeben kann.
11. Übergabe. Wann eskaliert er an einen Menschen, anstatt weiterzumachen? (mehrdeutig, hohes Risiko oder derselbe Fehler zweimal ohne neue Beweise)

Halte die Antworten in templates/loop-contract.template.md fest. Wenn der Benutzer #2 nicht mit einer konkreten Prüfung beantworten kann, kehre zu Schritt 0 zurück.

Schritt 2: Schreibe den Loop-Vertrag

Fülle die Vorlage in eine echte loop-contract.md im Repository des Benutzers. Dies ist das Design-Artefakt, aus dem der Loop gebaut und gegen das er geprüft wird. Halte es kurz und konkret. Jedes Feld sollte einen Befehl, einen Pfad oder eine Zahl nennen, keine Stimmung.

Schritt 3: Wähle die kleinste Form, die zum Werkzeug passt

Bilde den Vertrag auf den Agenten des Benutzers ab. Wähle den einfachsten Mechanismus, der ihn erfüllt; greife nicht zur Multi-Agenten-Orchestrierung, wenn ein /goal ausreicht. Siehe reference/tool-mapping.md für Details.

• Claude Code: /goal für die verifizierte Stopp-Bedingung, Sub-Agenten in .claude/agents/ für Maker/Checker-Trennung, Hooks oder eine geplante Aufgabe für den Auslöser, claude -p ... --output-format json für unbeaufsichtigte Durchläufe.
• Codex: der Reiter „Automations“ für den Auslöser, codex exec --json für unbeaufsichtigte Durchläufe, codex exec resume --last zum Fortsetzen, Sub-Agenten für den Checker.
• Greenfield / von Grund auf: eine Ralph-artige Bash-Schleife, while :; do cat PROMPT.md | agent; done, mit einer Aufgabe pro Runde und einer fix_plan.md. Am besten, wenn es noch keine Codebasis zu zerstören gibt; kombiniere es mit einem Tor und einem Budget, damit es stoppen kann. Siehe reference/ralph.md.

Schritt 4: Scaffolde die Dateien

Generiere konkrete, ausführbare Artefakte (passe die Namen an den Stack des Benutzers an):

• Der Maker-Prompt mit den nicht verhandelbaren Regeln (siehe Gesetze unten).
• Der Verifizierer: entweder ein Shell-Tor (der genaue Test-/Lint-Befehl) oder ein Checker-Prompt, der PASS/FAIL plus Beweise zurückgibt und ESCALATE (eskalieren) kann. Beginne mit reference/verifier-rubric.md.
• Die Memory-Datei (fix_plan.md oder state.json), die ein Durchlauf zuerst liest und zuletzt schreibt.
• Der Runner: die while-Schleife, Cron-Zeile, GitHub Action oder Automation, die ihn auslöst, einschließlich des Tors („Wenn der Build bereits grün ist, tue nichts“) und des Budget-Limits.

Schritt 5: Härte den Loop, bevor du ihn laufen lässt

Führe den Benutzer durch reference/hardening-checklist.md, bevor der erste unbeaufsichtigte Durchlauf erfolgt. Führe immer zuerst einen Trockenlauf mit einem knappen Budget und einer sandboxierten Berechtigung durch, bevor du hochskalierst.

Die vier ehrlichen Stopp-Bedingungen

Jeder Loop muss genau aus einem dieser Gründe stoppen können und sagen, welcher es ist:

• Ziel erreicht: Der separate Verifizierer bestätigt die Done-Bedingung.
• Budget erschöpft: Eine Iterations-, Token-, Zeit- oder Dollargrenze wurde ausgelöst.
• Stillstand: Derselbe Fehler zweimal ohne neue Beweise (stoppe das Thrashing).
• Braucht einen Menschen: Hohes Risiko oder mehrdeutig, also eskaliert er. Dies ist ein Erfolgszustand, kein Fehler.

Die nicht verhandelbaren Gesetze

Backe die Regeln 1–5 in die Anweisungen jedes Makers ein. Die Regeln 6–7 können nicht in einen Maker eingebaut werden – sie sind Eigentum des Entwicklers, also stelle sicher, dass der Benutzer sie einhält.

1. Der Maker benotet niemals seine eigene Arbeit. Ein separater Checker entscheidet über „erledigt“. Das Modell, das den Code geschrieben hat, ist viel zu großzügig, wenn es seine eigenen Hausaufgaben benotet.
2. Schwäche oder lösche niemals einen Test oder verenge eine Prüfung, um ihn bestehen zu lassen. Behebe die Ursache. Wenn der Test falsch ist, eskaliere; bearbeite ihn nicht stillschweigend.
3. Ein Loop, der nicht stoppen kann, ist ein Bug. Verdrahte die vier Stopp-Bedingungen vor dem ersten Lauf.
4. Memory lebt auf der Festplatte, nicht im Kontext. Lese es jede Runde zuerst, schreibe es zuletzt. Der Agent vergisst zwischen Durchläufen; das Repository nicht.
5. Behebe nur die Ursache; erweitere den Umfang nicht. Kleinste Änderung, die richtig sein könnte.
6. Die Verifikation bleibt die Verantwortung des Entwicklers. „Erledigt“ ist eine Behauptung, kein Beweis. Der Verifizierer ist das Asset, das der Benutzer besitzt; der Maker ist eine Ware, die mit jeder Modellversion kostenlos besser wird.
7. Die Flotte skaliert auf die Review-Rate des Benutzers, nicht auf die Spuranzahl des Werkzeugs. Der Mensch ist der serielle Engpass. Normalerweise ist die richtige Anzahl paralleler Agenten eine niedrige einstellige Zahl.

Was der Loop nie für dich tut

Sage dies dem Benutzer deutlich, damit er die richtige Aufgabe behält:

• Verifikation. Ein Loop, der unbeaufsichtigt läuft, ist auch ein Loop, der unbeaufsichtigt Fehler macht. Der separate Checker gibt „erledigt“ eine Bedeutung; es macht es nicht sicher.
• Verständnis. Je schneller der Loop liefert, desto schneller wächst die Verständnisschuld. Plane Zeit ein, um zu lesen, was er gebaut hat.
• Absicht. Warum diese Arbeit wichtig ist und was „gut“ bedeutet, muss von einem Menschen kommen. Der Loop kennt den Unterschied nicht zwischen „ihn nutzen, um bei verstandener Arbeit schneller zu werden“ und „ihn nutzen, um das Verständnis der Arbeit zu vermeiden“. Du tust es.

Baue den Loop. Aber baue ihn wie jemand, der vorhat, der Entwickler zu bleiben, nicht nur die Person, die auf Start drückt.

Weiterführendes Lesen (optional)

Wenn der Benutzer die Theorie hinter diesen Schritten im Detail haben möchte – die Loop-Anatomie und der 11-teilige Vertrag, /goal vs /loop, Memory, Token-Ökonomie und die Orchestrierungssteuer sowie die Risiken – verweise sie auf das Awesome Loop Engineering Handbuch: https://github.com/invincible04/awesome-loop-engineering (lesbar online unter https://invincible04.github.io/awesome-loop-engineering/).