Prompt-naar-PR-werkstroom met Claude Code: kleine diffs

Waarom Prompt-naar-PR beter is dan grote one-shot prompts

Grote one-shot prompts leiden vaak tot grote, rommelige veranderingen: tientallen bestanden aangepast, niet-gerelateerde refactors en code die je niet hebt kunnen doorgronden. Zelfs als de output technisch correct is, voelt review riskant omdat het moeilijk is te zien wat er veranderde en waarom.

Kleine diffs voorkomen dat. Als elke wijziging beperkt en gefocust is, kun je het in enkele minuten lezen, fouten vroeg vangen en voorkomen dat je iets breekt dat je niet had willen aanraken. Reviewers vertrouwen kleine PR's meer, dus merges gaan sneller en met minder heen-en-weer.

Prompt-naar-PR is een eenvoudige lus:

• Vraag om één kleine wijziging met duidelijke grenzen.
• Controleer de diff en bevestig dat het overeenkomt met de bedoeling.
• Draai je gebruikelijke checks (tests, lint, build).
• Als er iets faalt, herprompt met de exacte fout en context.
• Herhaal tot het klaar is om te mergen.

Deze cadans verandert fouten in snelle feedback in plaats van een verrassing op het einde. Als je Claude Code vraagt om een validatieregel aan te passen, houd het dan bij die ene regel. Als een test faalt, plak de falende output en vraag om de kleinst mogelijke fix die de test doet slagen, niet een herschrijving van het hele module.

Eén ding verandert niet: jij blijft verantwoordelijk voor de uiteindelijke code. Behandel het model als een lokale pair-programmeur die snel typt, niet als autopilot. Jij beslist wat erin komt, wat eruit blijft en wanneer het veilig is om de PR te openen.

Bereid je repo en lokale pairing-setup voor

Begin vanaf een schone basislijn. Als je branch achterloopt of tests al falen, wordt elke suggestie giswerk. Pull de laatste wijzigingen, rebase of merge zoals je team prefereert en zorg dat de huidige staat gezond is voordat je iets vraagt.

Een “lokale pair-programmeur”-setup betekent dat Claude Code bestanden in je repo bewerkt terwijl jij de controle houdt over het doel, de randvoorwaarden en elke diff. Het model kent je codebase niet tenzij je die laat zien, dus wees expliciet over bestanden, beperkingen en verwacht gedrag.

Voordat je de eerste prompt stuurt, bepaal waar checks draaien. Als je tests lokaal kunt draaien, krijg je feedback in minuten, wat iteraties klein houdt. Als sommige checks alleen in CI draaien (bepaalde lintregels, lange suites, build-stappen), bepaal wanneer je op CI vertrouwt zodat je niet na elke kleine wijziging hoeft te wachten.

Een eenvoudige pre-flight:

• Werk je branch bij en bevestig dat de app buildt of start.
• Draai de snelle checks lokaal (lint, unit tests, typecheck).
• Noteer welke checks CI-only zijn en hoe lang ze meestal duren.
• Bevestig dat je de issue kunt reproduceren of de ontbrekende feature duidelijk kunt zien.
• Zorg dat je wijzigingen makkelijk ongedaan kunt maken (schone status, kleine commits).

Houd een klein scratchpad open tijdens het werken. Schrijf beperkingen neer zoals “geen API-wijzigingen”, “gedrag backward compatible houden”, “raak alleen X-module aan”, plus beslissingen die je neemt. Als een test faalt, plak je het exacte faalbericht daar ook. Dat scratchpad wordt de beste input voor je volgende prompt en voorkomt dat de sessie afdrijft.

Schrijf prompts die natuurlijk naar kleine diffs leiden

Kleine diffs beginnen met een prompt die opzettelijk smal is. De snelste route naar mergebare code is één wijziging die je in een minuut kunt reviewen, niet een refactor die je een uur moet begrijpen.

Een goede prompt noemt één doel, één gebied van de codebase en één verwacht resultaat. Als je niet kunt aangeven waar de wijziging moet landen (bestand, map of module), zal het model gokken en zal de diff uitslaan.

Een prompt-vorm die wijzigingen compact houdt:

• Doel: het ene gedrag dat je wilt veranderen.
• Locatie: het bestand(en) of component dat je aangeraakt wilt hebben.
• Beperkingen: wat er niet mag veranderen.
• Acceptatie: hoe “klaar” eruitziet.
• Diff-grootte: vraag expliciet om de kleinste wijziging die werkt.

Grenzen zijn het geheime wapen. In plaats van “fix de login-bug”, geef aan wat stabiel moet blijven: “Verander de API-vorm niet”, “Hernoem geen publieke functies”, “Geen formatting-only edits”, “Vermijd nieuwe dependencies.” Dat vertelt je pair-programmeur waar hij niet slim moet doen.

Als de wijziging nog steeds onduidelijk voelt, vraag dan om eerst een plan vóór code. Een kort plan dwingt het werk in stappen te verdelen en geeft je de kans een kleine eerste stap goed te keuren.

Goal: Fix the null crash when rendering the profile header.
Location: src/components/ProfileHeader.tsx only.
Constraints: Do not change styling, props, or any exported types.
Expected outcome: If user.name is missing, show "Anonymous" and no crash.
Diff constraint: Minimal diff. No refactors. No unrelated formatting.
If unclear: First reply with a 3-step plan, then wait for approval.

Als je in een team werkt, voeg dan ook review-beperkingen toe: “Houd het onder ~30 regels gewijzigd” of “Één bestand alleen tenzij absoluut noodzakelijk.” Dat maakt de diff makkelijker te scannen en scherpt vervolgp prompts aan als iets faalt.

Kies de juiste eenheid van werk voor elke iteratie

Houd elke lus gefocust op één kleine, testbare wijziging. Als je het doel in één zin kunt beschrijven en kunt voorspellen welke bestanden zullen veranderen, is het de juiste grootte.

Goede eenheden van werk zijn onder meer: één bug in één pad oplossen (met een reproducerende test en een guard), één test aanpassen voor één gedrag, een gedrag-behoudende refactor (hernoemen, functie extract, duplicatie verwijderen) of het verbeteren van één foutmelding of validatieregel.

Timebox elke loop. Tien tot twintig minuten is meestal genoeg om een duidelijke prompt te schrijven, de diff toe te passen en een snelle check te draaien. Als je na 20 minuten nog steeds aan het verkennen bent, verklein de eenheid of schakel naar enkel onderzoek (notities, logging, failing test) en stop daar.

Definieer “klaar” voordat je begint:

• De wijziging blijft binnen de bedoelde bestanden en gedrag.
• Eén check bewijst dat het werkt (test, lint of een simpele run-stap).
• Geen nieuwe waarschuwingen of luidruchtige formatting-wijzigingen.
• De diff is makkelijk uit te leggen in twee zinnen.

Als de scope begint te groeien, stop vroeg. Als je jezelf hoort zeggen “terwijl we hier toch bezig zijn”, heb je net de volgende iteratie gevonden. Leg het vast als een follow-up, commit de huidige kleine diff en blijf vooruitgaan.

Review de diff vóór je checks draait

Lees de diff zoals een reviewer voordat je tests of builds runt. Hier blijft de workflow schoon of glijdt stilletjes af naar “waarom raakte het dat bestand?”.

Begin met Claude Code te vragen de wijzigingen samen te vatten in platte taal: welke bestanden, welke gedragswijziging en wat het níet heeft veranderd. Als het dat niet duidelijk kan uitleggen, doet de diff waarschijnlijk te veel.

Lees hem daarna zelf. Snel scannen op scope, daarna lezen op intentie. Je zoekt naar drift: ongerelateerde formatting, extra refactors, hernoemde symbolen of wijzigingen die je niet vroeg.

Een korte pre-check:

• Komen de gewijzigde bestanden overeen met wat je vroeg?
• Zijn er drive-by edits (whitespace-churn, ongerelateerde refactors)?
• Heeft het nieuwe gedrag geïntroduceerd dat je niet vroeg?
• Is er een nieuwe dependency of config-wijziging die een echte reden nodig heeft?
• Zou een reviewer dit begrijpen zonder vijf andere bestanden te lezen?

Als de diff groter is dan verwacht, probeer het dan niet weg te testen. Draai terug en herprompt voor een kleinere stap. Bijvoorbeeld: “Voeg alleen een falende test toe die de bug reproduceert. Geen refactors.” Kleine diffs houden fouten makkelijker te interpreteren en maken de volgende prompt preciezer.

Draai checks na elke kleine wijziging

Kleine diffs renderen alleen wanneer je ze meteen verifieert. Het doel is een strakke lus: een beetje veranderen, een beetje checken, fouten vangen terwijl de context vers is.

Begin met de snelste check die je kan vertellen “dit is kapot.” Als je formatting of imports veranderde, draai eerst lint of formatter. Als je bedrijfslogica aanraakte, voer de kleinste unit tests uit die het bestand of pakket dekken. Als je types of build-config bewerkte, doe een snelle compile.

Een praktische volgorde:

• Lint of format.
• Gerichte unit tests voor het gebied dat je veranderde.
• Build of typecheck om te bevestigen dat alles nog past.
• Langzamere suites (integration, end-to-end) nadat de basis slaagt.

Als iets faalt, leg dan twee dingen vast voordat je iets probeert te fixen: het exacte commando dat je draaide en de volledige foutoutput (kopieer het exact). Dat record houdt de volgende prompt specifiek en voorkomt “het faalt nog steeds”-lussen.

Houd de scope strak. Als lint faalt en tests faalden, fix eerst lint, draai opnieuw en behandel dan tests. Meng geen “snel schoonmaken” met een crashfix in dezelfde beurt.

Herprompt met fouten tot de checks groen zijn

Wanneer checks falen, behandel de foutoutput als je volgende prompt. De snelste lus is: plak de fout, krijg een diagnose, pas een minimale fix toe, run opnieuw.

Plak fouten woordelijk, inclusief commando en volledige stacktrace. Vraag eerst naar de meest waarschijnlijke oorzaak, niet een menu met opties. Claude Code werkt beter als het zich kan vastklampen aan exacte regelnummers en meldingen in plaats van te gokken.

Voeg één zin toe over wat je al geprobeerd hebt zodat het je niet in cirkels stuurt. Herhaal beperkingen die ertoe doen (“Verander geen publieke API's”, “Houd huidig gedrag, fix alleen de crash”). Vraag dan om de kleinste patch die de check doet slagen.

Een goede failure-prompt bevat:

• De exacte falende output (woordelijk).
• Het bestand(en) en de betrokken regels.
• Wat je in de laatste diff veranderde.
• Wat je al geprobeerd hebt.
• Een verzoek om de kleinste patch die de check doet slagen.

Als de voorgestelde fix gedrag verandert, vraag dan om een test die het nieuwe gedrag bewijst. Als een handler nu 400 teruggeeft in plaats van 500, vraag om één gerichte test die faalt op de oude code en slaagt met de fix. Dat houdt het werk eerlijk en maakt de PR vertrouwder.

Stop zodra checks groen zijn en de diff nog steeds één idee bevat. Als het model ongewenst andere code verbetert, herprompt met: “Los alleen de falende test op. Geen cleanup.”

Maak de PR makkelijk te reviewen en mergen

Een PR wordt het snelst gemerged als duidelijk is wat er veranderde, waarom en hoe te bewijzen dat het werkt. Met deze workflow moet de PR lezen als een kort verhaal: kleine stappen, duidelijke redenen.

Houd commits aligned met je iteraties. Als je om één gedragswijziging vroeg, maak dat één commit. Als je daarna een falende test fixte, maak dat de volgende commit. Reviewers kunnen het pad volgen en vertrouwen dat je geen extra wijzigingen hebt binnengesmokkeld.

Schrijf commit-berichten voor intentie, niet voor bestandsnamen. “Fix login redirect when session expires” is beter dan “Update auth middleware.” Als het bericht de gebruikersimpact noemt, hoeven reviewers minder te raden.

Vermijd het mixen van refactors met gedragsveranderingen in dezelfde commit. Als je variabelen wil hernoemen of helpers wilt verplaatsen, doe dat apart (of sla het nu over). Ruis vertraagt review.

In de PR-beschrijving: hou het kort en concreet:

• Wat veranderde (1–2 zinnen).
• Waarom het veranderde (de bug of vereiste).
• Hoe te testen (exacte stappen, inclusief flags of benodigde data).
• Wat je niet veranderde (om verwachtingen te scheppen).
• Eventueel risico of rollback-opmerking (wat er zou breken als dit fout is).

Voorbeeld: een billing-pagina crash door een null customer record. Commit 1 voegt een guard en een duidelijke error state toe. Commit 2 voegt een test toe voor de null-case. De PR-beschrijving zegt: “Open Billing, laad een klant zonder profiel, bevestig dat de pagina de nieuwe lege state toont.” Dat is het soort PR dat reviewers snel kunnen goedkeuren.

Veelvoorkomende valkuilen die je vertragen

Deze cadans breekt wanneer scope stilletjes uitbreidt. Een prompt die begint als “fix deze falende test” verandert in “verbeter foutafhandeling in de hele module” en plots review je een grote diff met onduidelijke intentie. Hou het strak: één doel, één wijzigingsset, één set checks.

Een andere vertraging is het accepteren van mooier ogende refactors alleen omdat ze er goed uitzien. Hernoemingen, bestandsverplaatsingen en stijlwijzigingen creëren ruis in review en maken het moeilijker de echte gedragsverandering te zien.

Veelvoorkomende valkuilen:

• Het model ongerelateerde bestanden laten aanraken “terwijl het er toch is.”
• Symptomen fixen (extra null-checks) in plaats van de echte oorzaak waar de test op wijst.
• Alleen de laatste regels van logs plakken en de eerste fout verbergen.
• Een snelle diff-scan overslaan voordat je checks draait.
• Herprompten met “het faalt nog steeds” in plaats van het exacte commando en de output.

Een concreet voorbeeld: een test faalt met “expected 400, got 500.” Als je alleen het einde van de stacktrace plakt, krijg je vaak generieke try/catch-voorstellen. Plak je de volledige testoutput, dan zie je mogelijk het echte probleem: een missende validatie-branch. Dat leidt tot een kleine, gerichte diff.

Voordat je commit, lees de diff als een reviewer. Vraag: dient elke regel het verzoek en kan ik het in één zin uitleggen? Zo niet, revert de extra wijzigingen en herprompt met een smallere taak.

Voorbeeld: bugfix tot mergebare PR in een paar loops

Een gebruiker meldt: “De instellingenpagina reset soms naar de defaults na het saven.” Je pulled main, draait tests en ziet één falen. Of er zijn geen tests, alleen een duidelijke repro.

Behandel het als een lus: één kleine vraag, één kleine diff, daarna checks.

Eerst: geef Claude Code de kleinst mogelijke nuttige context: falende testoutput (of stappen om te reproduceren), het bestandspad dat je vermoedt en het doel (“houd gedrag hetzelfde behalve fix de reset”). Vraag om een diagnose en een minimale patch, geen refactor.

Werk daarna in korte loops:

1. Loop 1 (minimale patch): Pas de kleinste wijziging toe die plausibel de bug repareert. Houd het strak: een guard condition, een missende null-check, een verkeerd default-waarde of een verkeerde dependency-lijst.

Draai checks nadat je de diff hebt reviewed.

2. Loop 2 (terugvoeren van exacte failure): Als tests falen, kopieer dan de exacte falende output terug naar Claude Code. Voeg bestandsnaam, regelnummer en de assertieboodschap toe. Vraag: “Wat is de kleinste wijziging om deze failure te fixen zonder scope te vergroten?”

Als checks slagen maar je zorgen hebt over regressies, voeg dan coverage toe.

3. Loop 3 (testaanpassing of nieuwe test): Voeg een test toe die faalt zonder de patch en slaagt met de patch. Houd het gefocust op de bug. Draai checks opnieuw.

Rond af met een korte PR-beschrijving: wat de bug was, waarom het gebeurde en wat veranderde. Voeg een reviewer-opmerking toe zoals “raakt alleen X-bestand” of “één test toegevoegd voor de reset-case” zodat review veilig aanvoelt.

Snelle checklist voordat je de PR opent

Net voordat je een pull request opent, doe één laatste controle zodat het werk makkelijk te reviewen en veilig te mergen is.

• De diff komt overeen met het oorspronkelijke doel en is klein genoeg om in enkele minuten te begrijpen.
• Je draaide de relevante checks (tests, lint, typecheck, build) en ze slagen. Als je team CI gebruikt, bevestig dat dezelfde set daar zal draaien.
• De wijziging heeft het juiste vangnet: een test voor de bug of feature wanneer praktisch, of een duidelijke reden waarom een test niet nodig is.
• De PR-beschrijving is specifiek: wat veranderde, waarom en exacte stappen om te verifiëren.
• Geen drive-by edits: ongerelateerde formatting, stijl-only hernoemingen of refactors die niet nodig zijn.

Een kort voorbeeld: als je een login-bug fixeerde maar ook 20 bestanden reformateerde, maak de formatting-revert. Je reviewer moet zich op de login-fix concentreren, niet afvragen wat er nog meer veranderde.

Als een item faalt, doe nog één kleine loop: maak een kleine diff, draai checks opnieuw en werk de PR-notities bij. Die laatste loop bespaart vaak uren heen-en-weer.

Volgende stappen: maak deze cadans een gewoonte

Consistentie verandert een goede sessie in een betrouwbare workflow. Kies een standaardlus en voer die elke keer op dezelfde manier uit. Na een week merk je dat je prompts korter worden en je diffs makkelijker te reviewen.

Een eenvoudige routine:

• Kies één kleine uitkomst (één bug, één edge-case, één functie).
• Vraag om één kleine diff en een korte uitleg van wat veranderde.
• Lees de diff zoals een reviewer en draai vervolgens lokale checks.
• Herprompt met de exacte failure-output en bestandsnamen.
• Stop zodra checks groen zijn en de wijziging duidelijk is.

Een persoonlijk prompt-template helpt je gedisciplineerd te blijven: “Verander alleen wat nodig is. Raak maximaal 2 bestanden aan. Houd publiek gedrag hetzelfde tenzij ik anders zeg. Zeg me het commando om te draaien en wat succes eruitziet.”

Als je bouwt binnen Koder.ai, kun je dezelfde lus in de chatinterface gebruiken. Planning mode is goed om het kleinste mergebare stukje te bepalen (inputs, outputs en acceptatiechecks) en snapshots en rollback helpen je snel te herstellen wanneer een experiment ontspoort.

Zodra de wijziging stabiel is, exporteer je de broncode om je gebruikelijke lokale tooling, CI en team-review in je normale repo uit te voeren. Deploy wanneer je echte wereldvalidatie nodig hebt, zoals het controleren van een flow end-to-end.

Maak de lus je standaard. Kleine prompts, kleine diffs, frequente checks en snelle correcties leveren PR's op die in het beste geval saai zijn.