Ralph-Schleifen in Claude Code: Verifizierer, Budgets und Stoppbedingungen

Eine Ralph-Schleife besteht aus drei Dingen: einer Aufgabe, einem Verifizierer und einem Budget. Das ist das ganze Muster. Geoffrey Huntley benannte es nach der Simpsons-Figur, die einfach weitermacht, egal ob etwas funktioniert oder nicht, und die Analogie stimmt. Das Risiko besteht nicht darin, dass Claude zu früh stoppt. Das Risiko ist, dass er den Status als erfolgreich deklariert, obwohl ein fehlerhafter Zustand vorliegt, dein Token-Budget aufgebraucht wird oder beides. Dieser Beitrag behandelt, wie du jedes der drei Elemente präzise definierst, die richtige Implementierung für deine Situation wählst und die Schleife sicher stoppt, wenn sie tatsächlich fertig ist. Der agentic development workflow ist eine separate Aufgabe; dieser Beitrag beschränkt sich streng auf die Iteration bis eine Bedingung erfüllt ist.

Definiere das Ziel, den Verifizierer und das Budget

Bevor du einen einzigen Befehl schreibst, schreib drei Sätze. Wie sieht „fertig" aus? Wie überprüfst du das mechanisch? Und wie viele Iterationen bist du bereit zu bezahlen?

Das Ziel muss maschinell überprüfbar sein. „Der Code ist gut" ist kein Ziel. „Alle Tests in npm test bestehen und git status ist clean" ist ein Ziel. Der Unterschied ist wichtig, weil ein Verifizierer nur das bewerten kann, das er beobachten kann. Wenn deine Vollendungsbedingung davon abhängt, dass eine Person etwas betrachtet, hast du keinen Verifizierer; du hast einen Review-Schritt, und diese beiden Dinge sollten nicht in derselben Schleife sein.

Der Verifizierer ist nicht Claudes eigene Meinung. Das ist der Teil, den die meisten Menschen falsch verstehen. Wie es ein Hacker News-Kommentator ausdrückte: „Wenn die KI denkt, dass die Dinge funktionieren, wird sie COMPLETE sagen, selbst wenn du das nicht für vollständig halten würdest." Von dem Modell generiertes DONE ist ein Signal, kein Verifizierer. Ein echter Verifizierer ist ein externer Prozess: dein Test-Runner, dein Linter, ein curl gegen einen Live-Endpoint, der den erwarteten Status-Code zurückgibt. Er läuft nach jeder Iteration und produziert ein deterministisches Wahr/Falsch. Baue das zuerst.

Das Budget ist dein Sicherheitsventil. Wähle eine Zahl, deren Verbrauch du dir wirklich leisten kannst. Die frankbria/ralph-claude-code Community-Implementierung erfordert sowohl heuristische Vollendungsindikatoren (zwei oder mehr) als auch ein explizites EXIT_SIGNAL: true im RALPH_STATUS Block des Modells, bevor es exitiert. Dieses Dual-Condition-Design existiert genau, weil einzelne Signale unzuverlässig sind. Dein --max-iterations sollte für den ersten Lauf konservativ sein. Du kannst ihn erhöhen, sobald du gesehen hast, wie weit die Schleife tatsächlich kommt.

Um es klar zu sagen, dein Setup vor dem Ausführen sollte beantworten:

• Welcher Shell-Befehl gibt Exit-Code 0 zurück, nur wenn die Aufgabe wirklich vollständig ist?
• Wie viele Iterationen werde ich maximal zulassen?
• Welche Datei oder welches Log zeichnet Iterations-Ergebnisse auf, damit ich sie später überprüfen kann?

Wähle die Loop-Implementierung

Claude Code 2.1 enthält drei eingebaute Primitives, die die meisten Ralph-Anwendungsfälle ohne Plugin abdecken. Der Awesome Claude Guide dokumentiert alle drei:

1. /goal arbeitet über Turns hinweg weiter, bis eine Bedingung verifiziert wird. Nutzt ein separates kleineres Modell (standardmäßig Haiku, pro Ranjan Kumars Beitrag), um das Session-Transkript nach jedem Turn zu lesen und eine Frage zu beantworten: Wurde das Ziel erfüllt? Falls nein, macht Claude einen weiteren Turn. Falls ja, wird die Schleife gelöscht.
2. /loop führt einen Prompt in festen oder selbstgesteuerten Intervallen erneut aus. Esc zum Beenden. Nützlich für Polling-Aufgaben.
3. /batch verteilt eine große Änderung auf 5 bis 30 parallele Worktree-Agenten. Eine ganz andere Sache; nicht das, was du für eine einzelne abgegrenzte Aufgabe brauchst.

Dann gibt es noch den Plugin-Pfad und die reine Bash-Schleife. Hier unterscheiden sie sich auf eine Weise, die für deine Arbeit wirklich zählt.

Das Plugin (ralph-wiggum@claude-plugins-official oder der Community-Fork) läuft in einer einzelnen Sitzung mit einem Stop-Hook. Wenn Claude versucht zu beenden, fängt der Hook es ab und füttert den Prompt zurück. Der Kontext sammelt sich über Iterationen hinweg an. Das ist praktisch, bedeutet aber, dass der Kontextfenster bei Iteration 15 bereits Reste jeden früheren Versuchs mit sich trägt, was die Qualität jeder neuen Runde beeinträchtigen kann.

Der reine Bash-Ansatz, der PROMPT.md in claude -p innerhalb einer while-Schleife piped, startet jedes Mal einen völlig neuen Prozess. Wie Steve Kinney anmerkt: „Jeder claude -p Aufruf erhält ein vollständig sauberes Kontextfenster. Das ist genau der Sinn dieser Technik – Kontextverfall vermeiden, indem man absichtlich von vorne anfängt." Der Nachteil: Du verlierst das implizite Gedächtnis daran, was versucht wurde, also müssen deine PROMPT.md und Task-State-Dateien den gesamten Kontext explizit zwischen Iterationen tragen.

Welche solltest du wählen? Wenn deine Aufgabe kurz ist (unter 10 Iterationen erwartet) und der Kontext handhabbar bleibt, ist /goal mit einem Turn-Limit die Option mit dem geringsten Aufwand. Wenn die Aufgabe lang ist oder Kontextqualität ein Anliegen ist, ist die Fresh-Context-Bash-Schleife zuverlässiger. Der Tests- und AI-Coding-Tools-Post zeigt, wie du deine Test-Suite strukturierst, damit der Verifier sauber in beiden Fällen laufen kann.

Eine Aufgabe mit begrenzten Iterationen ausführen

Hier ist ein anschauliches Setup für eine abgegrenzte Aufgabe mit dem /goal-Primitiv:

/goal Alle Tests in npm test bestehen und git status ist sauber, oder nach 20 Turns beenden

Diese einzelne Zeile gibt Claude eine überprüfbare Endbedingung und ein hartes Limit. Der Haiku-Evaluator liest das Transkript nach jeder Runde und prüft beide Bedingungen. Die Klausel „oder nach 20 Turns beenden" ist dein Budget-Schutzgeländer.

Für einen Bash-Loop-Ansatz ist die Struktur des Geocodio-Teams ein gutes Vorbild. Sie verwenden eine JSON-Datei (eine einfache prd.json), wobei jede Aufgabe ein „passes": false-Feld hat. Jede Iteration findet die höchstpriorisierte Story mit passes: false, implementiert sie, führt den Verifier aus und setzt das Flag bei Erfolg auf true. Die while-Schleife beendet sich, wenn jede Story passes: true hat. Ihr Artikel ist allein wegen der Akzeptanzkriterien-Struktur lesenswert.

Der nummerierte Ablauf für eine Fresh-Context-Bash-Schleife sieht so aus:

1. PROMPT.md mit der aktuellen Aufgabe, dem Verifier-Befehl und dem Pass/Fail-Log-Pfad schreiben.
2. Die while-Schleife starten, PROMPT.md in claude -p pipen.
3. Claude liest Anweisungen, führt eine Arbeitseinheit aus, committed zu git.
4. Der Verifier wird ausgeführt. Exit-Code 0 bedeutet Bestätigung; alles andere bedeutet Fehler.
5. Das Ergebnis (Iterationsnummer, bestanden/fehlgeschlagen, Token-Kosten falls verfügbar) in eine Datei protokollieren.
6. Wenn alle Aufgaben bestanden sind, schreibe das Stop-Signal und beende. Andernfalls zurück zu Schritt 2.

Halte jede Iteration auf eine Arbeitseinheit beschränkt. Zu viel pro Schleife zu versuchen ist, wie du in einen halbfertigen Zustand gerätst, den der Verifier nicht saubär evaluieren kann.

Mangelnden Fortschritt und falsche Fertigstellung erkennen

Zwei Fehlermodi sind weitaus häufiger als Endlosschleifen: Die Schleife macht über Iterationen hinweg keinen Fortschritt, und das Modell erklärt einen gebrochenen Zustand für erfolgreich.

Die Erkennung von Fehlschlag erfordert den Vergleich von etwas Konkretem zwischen Iteration N und Iteration N+1. Ein git diff ist das einfachste Signal. Wenn git diff HEAD~1 nach einer Iteration, die keinen bestandenen Verifier produziert hat, leer ist, dreht sich die Schleife. Du solltest das sofort anzeigen, anstatt drei weitere Iterationen zu verbrennen und zu hoffen, dass sich etwas ändert.

Falsche Completion ist kniffliger. Das Modell wird DONE, COMPLETE oder EXIT_SIGNAL: true in Fällen produzieren, in denen dein tatsächlicher Verifier einen Exit-Code ungleich Null zurückgeben würde. Die frankbria-Implementierung mit ihrer Dual-Condition-Prüfung (zwei-plus heuristische Indikatoren und das explizite Signal) ist eine vernünftige Entschärfung. Aber die bessere Lösung ist: Lass die Schleife niemals nur basierend auf der Modellausgabe beenden. Das Verifier-Skript läuft unabhängig davon, was das Modell sagt, und die Schleife wird fortgesetzt, wenn der Verifier fehlschlägt – Punkt.

Achte auf eine verwandte Falle: Der Verifier selbst gibt ein falsches positives Ergebnis zurück. Wenn deine Test-Suite Flaky Tests hat, die manchmal ohne dass der zugrunde liegende Bug behoben wurde bestehen, wirst du eine falsche Completion bekommen, die das Modell nicht einmal verursacht hat. Das ist der nächste Abschnitt.

Handle Flaky Tests und Failed Verifiers

Flaky Tests sind der Feind jeder automatisierten Schleife. Ein Test, der 80 % der Zeit besteht, wird schließlich einen Loop-Exit beim 20 % auslösen, wo er es nicht sollte. Und weil jede Iteration Token kostet, ist ein falscher Exit gefolgt von einer Neuausführung teuer.

Die Entschärfung ist nicht kompliziert, erfordert aber etwas vorbereitende Arbeit:

• Führe dein Verifier-Kommando drei Mal hintereinander aus, bevor du auf einen Erfolg vertraust. Wenn es einmal von drei fehlschlägt, behandle es als Fehler.
• Trenne deine „ist die Arbeit erledigt"-Tests von deinen „funktioniert die Umgebung"-Tests. Netzwerkabhängige Tests, zeitungsensible Assertions und alles, das externen Status erfordert, sollten nicht im Verifier sein, der den Loop-Exit kontrolliert.
• Protokolliere jeden Verifier-Lauf mit seiner Ausgabe. Wenn die Schleife stoppt und etwas sieht falsch aus, du wünschst dir die vollständige Verifier-Ausgabe der finalen Iteration, nicht nur den Exit-Code.

Wenn der Verifier selbst fehlschlägt (stürzt ab, läuft aus der Zeit oder gibt einen unerwarteten Error-Code zurück, der kein Test-Fehler ist), behandle das als Loop-Halt, nicht als Loop-Fortsetzung. Der Versuch, durch einen defekten Verifier zu iterieren, wird nur Iterationen erzeugen, die nicht evaluiert werden können.

Claude Code Hooks lassen dich Scripts an bestimmten Stellen im Session-Lebenszyklus anfügen. Der Claude Code Hooks-Guide deckt den Mechanismus im Detail ab. Für Ralph-Schleifen ist der relevante Hook derjenige, der aktiviert wird, wenn Claude versucht, zu beenden: Fange ihn ab, führe deinen Verifier aus, und erlaube den Exit nur, wenn der Verifier besteht. Wenn du den Plugin-Pfad verwendest, ist das bereits verdrahtet. Wenn du auf der Bash-Schleife bist, passiert die Exit-Entscheidung in deinem Shell-Skript statt in einem Hook.

Kosten erfassen und sicher beenden

Du solltest wissen, was jede Iteration kostet, bevor die Schleife fertig ist. Du brauchst keine exakten Zahlen in Echtzeit, aber du brauchst eine Log-Datei, die die Iterationsnummer, das Verifier-Ergebnis und genug Token-Informationen aufzeichnet, um die Ausgaben hinterher zu schätzen.

Der Alibaba Cloud Community-Beitrag zu Ralph-Schleifen identifiziert drei Stoppbedingungen, die es wert sind, in jede Implementierung eingebaut zu werden:

• Erfolg: Der Verifier gibt 0 zurück und alle Aufgaben haben passes: true.
• No-Progress-Halt: zwei oder mehr aufeinanderfolgende Iterationen ohne git diff und keine Verifier-Verbesserung.
• Budget-Erschöpfung: Der Iterationszähler erreicht --max-iterations unabhängig vom Verifier-Status.

Budget-Erschöpfung ist kein Fehlermodus, es ist ein geplanter Stopp. Wenn es auslöst, sollte die Schleife eine Zusammenfassung schreiben von dem, was bestanden hat, was nicht, und was die letzte Iteration versucht hat. Das gibt dir eine saubere Übergabe für eine manuelle Überprüfung oder eine neue Schleife mit einem überarbeiteten Prompt.

Etwas, das du explizit einbauen solltest: eine Unterscheidung zwischen „Schleife gestoppt, weil sie erfolgreich war" und „Schleife gestoppt, weil sie das Limit erreicht hat". Wenn du zu einem Terminal zurückkehrst und siehst „Schleife gestoppt bei Iteration 20", musst du wissen, welches von den beiden es war. Ein einzelnes Flag in der Log-Datei, STOP_REASON: BUDGET_EXHAUSTED versus STOP_REASON: SUCCESS, ist alles, was es braucht.

Wenn du diese Arbeit im großen Maßstab machst oder einen verwalteten Setup anstelle von handgeschriebenen Skripten möchtest, deckt die agentic engineering work ab, wie ein produktionsreifer Loop-Setup mit angemessener Observability aussieht.

FAQ

Ist `/goal` tatsächlich eine Ralph-Schleife, oder ist es etwas anderes?

Sie teilen das gleiche Prinzip (iterieren, bis eine Bedingung erfüllt ist), unterscheiden sich aber in der Architektur. /goal läuft innerhalb einer einzelnen persistenten Session; eine klassische Ralph-Bash-Schleife spawnt bei jeder Iteration einen frischen Prozess. Wie Ranjan Kumar dokumentiert, verwendet /goal ein separates Haiku-Modell, um das Transkript nach jedem Turn auszuwerten. Die Bash-Schleife wertet nichts aus, dein Shell-Skript macht die Überprüfung. Beide sind gültig; wähle basierend darauf, ob Kontext-Akkumulation ein Problem für deine Aufgabe ist.

Kann ich die `DONE`-Ausgabe des Modells selbst als Verifier verwenden?

Nein. Die Ausgabe des Modells ist ein Signal, das du als einen Input nutzen kannst, aber es kann nicht die einzige Exitbedingung sein. Ein Modell gibt Abschlussmarkierungen aus, wenn es glaubt, dass die Aufgabe erledigt ist – das ist nicht dasselbe wie wenn sie tatsächlich erledigt ist. Kombiniere jedes modellgenerierte Signal mit einem externen Befehl, der den tatsächlichen Zustand des Systems überprüft.

Was passiert mit der Schleife, wenn Claude Code den Kontext während der Ausführung komprimiert?

In einer persistenten Sitzungsschleife (Plugin oder /goal) erfolgt die Komprimierung automatisch, wenn der Kontext zu lang wird, und die Qualität dieser Komprimierung ist inkonsistent. Ein Hacker-News-Kommentator beobachtete, dass „Claude-Code-Komprimierungen so minderwertig sind, dass es im Grunde dasselbe ist wie den Verlauf alle paar Runden zu löschen." Die Fresh-Context-Bash-Schleife umgeht dies vollständig, da jede Iteration sauber beginnt. Falls du den Plugin-Pfad verfolgst und lange Jobs leitest, achte auf verminderte Ausgabequalität nach Komprimierungspunkten.

Wie klein sollte die Arbeitseinheit jeder Iteration sein?

So klein wie möglich, während es trotzdem sinnvoll bleibt. Eine Aufgabe pro Iteration ist das richtige mentale Modell. Der Geocodio-Ansatz (eine Story aus prd.json pro Schleife) und die Beschreibung des Hacker-News-Kommentators („es wählt die wichtigste Aufgabe, erledigt sie und beendet seine Schleife") weisen beide auf die gleiche Antwort hin: kleine, verifizierbare Blöcke sind weitaus zuverlässiger als große ehrgeizige Iterationen.

Brauche ich überhaupt ein Plugin?

Für die meisten Aufgaben nein. Das eingebaute /goal-Primitive mit einer Turn-Obergrenze deckt den häufigen Fall ab. Greif zum Plugin (ralph-wiggum@claude-plugins-official oder frankbria/ralph-claude-code), wenn du speziell das Verhalten der Stop-Hook-Interception oder die Dual-Condition-Exit-Logik möchtest, die diese Implementierungen bieten. Installiere kein Plugin nur, weil du es in einem Tutorial gesehen hast.

Die schärfste Einschränkung in diesem gesamten Muster: ein modellgeneriertes Abschluss­signal ist keine Verifikation. Baue die externe Prüfung zuerst auf, vor allem anderen, und lass jede andere Entscheidung von dort folgen.