Ralph-Loop – wenn ein Agent konvergiert statt „fertig“ zu sagen
Datum: 2026-01-01
Warum „fertig“ im Chat nicht reicht
Jeder, der mit KI-Agenten produktiv arbeitet, kennt den Moment: Der Chat sagt *„Alles erledigt“*, du commitest – und zehn Minuten später fällt dir auf, dass PHPUnit rot ist, ein Screen 500 liefert oder Translation-Keys fehlen. Das Problem ist nicht Faulheit des Modells, sondern fehlende Objektivität: Der Agent hat keinen maschinenlesbaren Beweis geliefert, dass wirklich nichts mehr offen ist.
Agentic Engineering braucht deshalb einen Mechanismus, der Konvergenz erzwingt – nicht Vertrauen. Dafür nutzen wir den Ralph-Loop.
Das Problem im Detail
| Symptom | Ursache ohne Ralph-Loop |
|---|---|
| „Tests sollten laufen“ | Kein erzwungener PHPUnit-Lauf |
| „Ich habe alle Screens geprüft“ | Keine curl-Liste, keine 200er |
| „Translations sind ok“ | Kein Key-Vergleich DE/EN |
| „Briefing ist synchron“ | Kein Abgleich Briefing ↔ PHP |
Ohne Loop endet die Arbeit, wenn das Sprachmodell es für sinnvoll hält – nicht wenn das Projekt objektiv grün ist.
Das Pattern: Ralph-Loop
Der Ralph-Loop startet einen spezialisierten Subagenten (z. B. `subagent-check-screens`) und wiederholt Runden, bis am Ende drei maschinenlesbare Marker ein eindeutiges Bild liefern:
| Marker | Bedeutung |
|---|---|
| `RALPH_LOOP_OPEN_FAILURES` | Anzahl offener Prüfobjekte nach Korrekturen in dieser Runde |
| `RALPH_LOOP_CHANGED_FILES` | Anzahl geänderter Dateien in dieser Runde |
| `RALPH_LOOP_CHANGED_FILE_LIST` | Kommaseparierte Liste oder `none` |
Wann ist wirklich grün?
Grün bedeutet ausschließlich:
- `RALPH_LOOP_OPEN_FAILURES=0`
- `RALPH_LOOP_CHANGED_FILES=0`
Alles andere → nächste Runde. Kein Bauchgefühl, kein „fast fertig“.
Ablauf einer Runde
001. CLI startet Subagent mit festem Scope (z. B. nur Translations).
002. Agent liest Skills, Rules und Briefings.
003. Agent korrigiert Verstöße physisch im Repo.
004. Agent meldet die drei Marker am Ende der Antwort.
005. Orchestrator wertet aus: konvergent oder nächste Runde.
So sieht es bei uns aus
php start-vendor-subagent-ralph-loop.php subagent-check-screens
Der `CLISubagentRalphLoopOrchestrator`:
001. Parst CLI-Argumente (`subagent-check-screens`, optional Zusatzkontext).
002. Legt Log-Ordner unter `logs-start-vendor-subagent-ralph-loop/` an.
003. Ruft den Cursor Agent headless auf.
004. Wertet Marker aus und startet bei Bedarf Runde 2, 3, … n.
Verschachtelte Loops (z. B. Deep-Check ruft Ralph pro 10er-Batch auf) nutzen Env-Flags wie `DEEP_CHECK_SUPPRESS_RALPH_LOOP_CLEAR`, damit Terminal-Output und Logs sauber bleiben.
Ralph-Loop vs. einmaliger Agent-Lauf
| Einmaliger Chat/CLI-Lauf | Ralph-Loop |
|---|---|
| Endet nach einer Antwort | Endet bei Konvergenz |
| Kein standardisiertes Grün | Marker = Grün/Rot |
| Schwer in CI nutzbar | Exit-Code + Logs |
| „Ich glaube, es passt“ | „OPEN_FAILURES=0“ |
Für Exploration reicht ein Lauf. Für Qualitätssicherung im Repo brauchst du den Loop.
Typische Subagents im Ralph-Loop
| Subagent | Wann starten |
|---|---|
| `subagent-check-screens` | Nach Screen-/Template-Änderungen |
| `subagent-check-translations` | Nach i18n oder Routing |
| `subagent-check-orchestrator` | Nach Orchestrator/Step-Services |
| `subagent-check-vendor-duplicates` | Nach Vendor-Updates |
| `subagent-fix-fehler-und-test` | Wenn curl/PHPUnit rot |
Jeder Subagent verweist auf `@skill-subagent-build` und die Rule `018-subagent-ralph-loop-output.mdc` für die Pflicht-Marker.
Anti-Patterns
001. Loop ohne Subagent-Scope – „Mach alles grün“ in einer Runde → wieder Monster-Prompt.
002. Marker ignorieren – Mensch sagt „passt schon“, obwohl `OPEN_FAILURES=3`.
003. Tests abschwächen – Rot wird grün gemacht, indem Assertions gelöscht werden (bei uns: verboten).
004. Keine Logs – Ohne `logs-start-vendor-subagent-ralph-loop/` kein Nachweis im Team.
005. Endlosschleife ohne Abbruch – Orchestrator braucht sinnvolle Abbruchkriterien bei harten Blockern.
Integration in den Development-Workflow
`start-vendor-development-workflow.php` und verwandte Scripts rufen Subagents und Tests in fester Reihenfolge auf. Der Ralph-Loop ist kein isoliertes Spielzeug, sondern Gate vor Commit/Push:
001. Code-Änderung
002. Relevanter Subagent im Ralph-Loop
003. PHPUnit (`start-vendor-phpunit-tests.php`)
004. Optional: `start-vendor-git-push.php`
So wird „fertig“ zur Pipeline-Entscheidung, nicht zur Chat-Meinung.
Häufige Fragen
Wie viele Runden sind normal?
Bei fokussiertem Scope oft 1–3. Bei großen Refactorings oder ersten Einrichtungen auch mehr – entscheidend ist Konvergenz, nicht die Rundenanzahl.
Muss jeder Subagent einen Ralph-Loop haben?
Prüf- und Fix-Agenten im produktiven Workflow: ja. Einmalige Recherche: optional.
Was, wenn OPEN_FAILURES nie 0 wird?
Blocker dokumentieren, Scope verkleinern oder Briefing/Architektur klären – nicht Marker weglassen.
Kann ich den Loop in CI laufen lassen?
Ja – headless `cursor agent`, Logs und Exit-Code sind dafür gedacht (siehe auch Cron/CI-Beitrag).
Verwandte Beiträge
| Beitrag | Thema |
|---|---|
| Subagents statt Monster-Prompt | Spezialisierung |
| Rules, Skills, Subagents | Steuerungsebenen |
| Deep-Check | 10er-Batches PHP |
| Cursor Agent per CLI | Headless Jobs |
| Von der IDE zum Nachtjob | Cron/CI |
Takeaway
Agentic Engineering braucht maschinenlesbares Grün/Rot – kein Bauchgefühl im Chat. Der Ralph-Loop mit `OPEN_FAILURES` und `CHANGED_FILES` macht aus „fertig“ eine prüfbare Aussage. Wer das ernst nimmt, committet seltener kaputten Code – und schläft besser vor dem Deploy.