Ralph Loop: zo laat je een coding agent gecontroleerd doorwerken

Een coding agent die na één antwoord stopt, is soms te snel klaar. Een coding agent die zonder grens blijft proberen, is juist gevaarlijk. Een Ralph Loop lost dat praktische probleem op met een eenvoudige gedachte: laat de agent één klein werkitem uitvoeren, controleer het resultaat en geef alleen concrete feedback voor een volgende ronde.

De kern is dus niet “zet AI in een oneindige lus”. De kern is: itereren met een verificatiepoort en een harde limiet. In dit artikel bouw je dat denkmodel op voor een fictieve TypeScript-migratie. Het is een neutrale demo, geen claim over een persoonlijk klantproject of een uitgevoerde benchmark.

Wat is een Ralph Loop?

Ralph is een techniek voor continue agentiteratie. Geoffrey Huntley beschrijft de eenvoudigste vorm als een Bash-lus die dezelfde opdracht opnieuw aan een coding agent voert. De oorspronkelijke uitleg van Huntley benadrukt ook de keerzijde: de aanpak werkt alleen wanneer je de agent goed stuurt met specificaties, tests en feedback.

De open-source Vercel Labs-implementatie ralph-loop-agent maakt het patroon explicieter. Daar is sprake van een buitenste lus rond een normale tool-lus, met een functie die controleert of de taak echt klaar is. De repository noemt de package experimenteel; behandel de API daarom als een voorbeeld en controleer de versie voordat je haar in productie gebruikt.

Een gewone tool-lus beantwoordt meestal de vraag: “Heeft het model zijn tools aangeroepen?” Een Ralph Loop stelt de strengere vraag: “Is het werkresultaat werkelijk correct, getest en binnen de afgesproken grenzen?”

Eerst het mentale model: één taak, één ronde, één controle

Teken de workflow voordat je code schrijft:

Zonder deze onderdelen krijg je vooral een chatbot die vaker achter elkaar wordt aangeroepen. Dat is geen gecontroleerde engineeringworkflow.

Stap 1: maak de opdracht klein genoeg

Begin niet met “moderniseer de hele repository”. Geef de agent één werkitem dat je achteraf kunt aanwijzen in de diff.

Een goede eerste opdracht kan zijn:

Migreer alleen de functie parseUserId in src/users/parse-user-id.ts.

Klaar wanneer:
1. de bestaande tests blijven slagen;
2. de nieuwe randgevallen voor lege en ongeldige invoer zijn toegevoegd;
3. de publieke functienaam niet verandert;
4. alleen src/users/parse-user-id.ts en de bijbehorende test zijn gewijzigd.

Stop en rapporteer wanneer de opdracht een productbeslissing of een extra bestand vereist.

Dit lijkt misschien overdreven precies. In werkelijkheid geef je de agent hiermee een meetlat. Je voorkomt dat een model een brede herstructurering uitvoert terwijl je alleen een kleine migratie wilde.

Gebruik bij grotere projecten een lijst met kleine werkitems. Laat de agent per ronde het belangrijkste resterende item kiezen, maar laat de controle bepalen of dat item echt klaar is. Zo blijft planning gescheiden van uitvoering.

Stap 2: leg context en repositoryregels vast

Een agent ziet niet automatisch waarom een bestand bestaat. Zet daarom de vaste kennis in bestanden die iedere ronde opnieuw beschikbaar zijn:

AGENTS.md
├── projectdoel en verboden wijzigingen
├── build- en testcommando's
├── architectuurregels
└── veilige omgang met secrets en externe systemen

specs/
└── parse-user-id.md

fix-plan.md
└── kleine werkitems op volgorde van belangrijkheid

De specificatie beschrijft wat de functie moet doen. AGENTS.md beschrijft hoe je in deze repository werkt. Het fix-plan beschrijft wat daarna komt. Meng die drie niet tot één enorme prompt; korte, stabiele context is makkelijker te controleren en kost iedere iteratie minder tokens.

Een nuttige regel is: zoek eerst in de repository voordat je concludeert dat iets niet bestaat. Een coding agent kan anders dezelfde functie opnieuw bouwen op een andere plek. Laat iedere ronde de huidige implementatie, tests en git-diff lezen voordat er een wijziging wordt gemaakt.

Stap 3: voeg backpressure toe

Het moeilijke deel van een Ralph Loop is niet de lus. Het moeilijke deel is een goede tegenkracht. Na iedere wijziging moet de agent bewijs leveren.

Gebruik bijvoorbeeld deze volgorde:

1. formatteer en typecheck de gewijzigde code;
2. draai de unit-tests voor het werkitem;
3. draai daarna de relevante repositorychecks;
4. controleer de diff op onverwachte bestanden, secrets en generated output;
5. laat pas daarna een eventuele releasegate beslissen.

Een foutmelding moet bruikbaar zijn. “Tests failed” geeft de volgende ronde weinig richting. “parseUserId.test.ts: expected INVALID_ID for empty input, received undefined” is concrete feedback.

Een gemiddelde score is geen vervanging voor een harde veiligheidscheck. Eén ongeoorloofde schrijfactie, secret of falende autorisatietest moet de release blokkeren, ook wanneer de rest er goed uitziet.

Stap 4: bouw de buitenste lus met grenzen

Onderstaande code is een illustratie van het patroon met de experimentele Vercel-library. De namen en API-versie moet je vóór gebruik controleren; de code is hier niet uitgevoerd.

import {
  RalphLoopAgent,
  iterationCountIs,
  tokenCountIs,
  costIs,
} from "ralph-loop-agent";

const agent = new RalphLoopAgent({
  model: process.env.AGENT_MODEL,
  instructions: [
    "Werk aan precies één item uit fix-plan.md.",
    "Lees eerst AGENTS.md, de relevante spec en de huidige git diff.",
    "Wijzig geen secrets, deploymentconfiguratie of bestanden buiten de scope.",
    "Draai de relevante tests na iedere wijziging.",
  ].join("\n"),
  tools: {
    readFile,
    writeFile,
    runTests,
    inspectDiff,
  },
  stopWhen: [
    iterationCountIs(8),
    tokenCountIs(100_000),
    costIs(5.00),
  ],
  verifyCompletion: async ({ result }) => {
    const checks = await Promise.all([
      testsPass("src/users/parse-user-id.test.ts"),
      diffContainsOnlyAllowedFiles([
        "src/users/parse-user-id.ts",
        "src/users/parse-user-id.test.ts",
      ]),
      noSecretsDetected(),
      completionChecklistIsComplete(),
    ]);

    return {
      complete: checks.every(Boolean),
      reason: checks.every(Boolean)
        ? "Werkitem en releasechecks zijn geslaagd."
        : "Een controle faalde; lees de testuitvoer en herstel alleen dit werkitem.",
    };
  },
});

const result = await agent.loop({
  prompt: "Voer het volgende kleine werkitem uit en rapporteer de controles.",
});

if (result.completionReason !== "verified") {
  throw new Error("Niet automatisch mergen: de loop stopte zonder verificatie.");
}

Het belangrijke detail zit in verifyCompletion. Niet de tekst “klaar” beëindigt de loop, maar een verzameling controleerbare voorwaarden. De Vercel-repository documenteert naast een iteratielimiet ook token- en kostenlimieten en geeft de reden van een mislukte verificatie door aan de volgende iteratie.

Gebruik in je eigen implementatie minstens:

• een maximumaantal iteraties;
• een token- of kostenbudget;
• een time-out;
• een stop bij herhaalde identieke fouten;
• een diff- en secretcontrole;
• een expliciete status voor verified, max-iterations en aborted.

Een budgetstop is geen succesvolle afronding. Het betekent: stop, bewaar de staat en laat een mens of een volgende gecontroleerde run bepalen wat er nu gebeurt.

Stap 5: maak retries veilig

Een loop kan dezelfde opdracht meerdere keren proberen. Dat is prima voor een formatter of een lokale test. Het is riskant voor externe acties.

Maak daarom onderscheid tussen:

Schrijfacties buiten de repository moeten idempotent zijn: dezelfde request mag niet twee keer een bestelling, deployment of migratie uitvoeren. Als dat niet kan, zet die actie achter een menselijk besluitpunt.

Log per iteratie minimaal een run-ID, werkitem-ID, agentversie, prompt- of specversie, gewijzigde bestanden, testuitkomst, token- of kostenband en stopreden. Bewaar niet standaard volledige klantinhoud of secrets in de trace.

Wanneer is een Ralph Loop een goed idee?

Een Ralph Loop past goed bij een afgebakende greenfield-taak, een migratie met duidelijke invarianten, een testreparatie of een reeks kleine refactors in een geïsoleerde branch. Je krijgt vooral voordeel wanneer de computer zelf kan vaststellen of een stap geslaagd is.

Wees terughoudend bij:

• onduidelijke product- of architectuurbeslissingen;
• grote bestaande repositories met veel verborgen afhankelijkheden;
• security-, privacy- of betaalacties;
• wijzigingen waarbij de echte succesmaatstaf alleen menselijk oordeel is;
• werk zonder betrouwbare tests of rollback.

De oorspronkelijke Ralph-uitleg waarschuwt zelf dat de techniek vooral aantrekkelijk is voor greenfield-werk en dat senior engineeringsturing nodig blijft. Dat is een nuttige grens: een loop maakt uitvoering herhaalbaar, maar neemt verantwoordelijkheid niet weg.

Samenvatting

Een Ralph Loop is geen vrijbrief om een coding agent onbeperkt code te laten produceren. Het is een gecontroleerde buitenste lus:

1. kies één klein werkitem;
2. geef de agent stabiele specificaties;
3. laat tests en statische checks slechte output tegenhouden;
4. geef concrete feedback voor de volgende ronde;
5. stop bij een bewezen completion criteria of een harde budgetgrens;
6. merge of deploy pas na een aparte releasegate.

Wil je een coding-agentworkflow ontwerpen die sneller werkt én reviewbaar blijft? Bespreek een gecontroleerde aanpak met een AI engineer. Bekijk ook de bredere uitleg over coding agents en AI-agenten in productie.