Claude Code voor CI-fouten: prompts voor kleine fixes + tests

Wat er misgaat wanneer CI faalt en AI gokt

Een CI-fout is meestal niet mysterieus. De log vertelt je waar het stopte, welk commando faalde en het foutbericht. Een goede run bevat een stacktrace, een compilerfout met bestand en regelnummer, of een testrapport dat toont welke assertie faalde. Soms krijg je zelfs een diff-achtige hint zoals "expected X, got Y" of een duidelijke falende stap zoals "lint", "build" of "migrate database".

Het echte probleem is dat mensen (en AI) de log vaak behandelen als achtergrondruis. Als je een lange log plakt en vraagt om "een fix", springen veel modellen naar een bekend verklaarpatroon in plaats van de laatste betekenisvolle regels te lezen. Het gokken wordt erger als de fout er bekend uitziet ("module not found", "timeout", "permission denied"). Je eindigt met een grote herschrijving, een nieuwe dependency of een "probeer alles te updaten"-antwoord dat niet overeenkomt met de werkelijke fout.

Het doel is niet "maak het op de een of andere manier groen". Het is eenvoudiger:

• Lees de falende output.
• Identificeer de kleinste wijziging die de falende stap laat slagen.
• Laat alles anders ongewijzigd.

In de praktijk is de "kleinst mogelijke fix" meestal een van de volgende: een paar regels code wijzigen op één plek, een ontbrekende import of verkeerde pad, een configwaarde die duidelijk onjuist is voor de CI-omgeving, of het terugdraaien van een per ongeluk breaking change in plaats van het herontwerpen van de code.

Een follow-up test is ook belangrijk. Eén keer CI groen is niet hetzelfde als herhaling voorkomen. Als de fout voortkwam uit een edge case (null input, timezone, afronding, permissies), voeg dan een regressietest toe die faalt vóór de fix en slaagt erna. Dat verandert een eenmalige redding in een vangrail.

Wat je moet verzamelen voordat je om hulp vraagt

De meeste slechte fixes beginnen met ontbrekende context. Als je alleen de laatste rode regel plakt, moet het model raden wat er eerder gebeurde, en raden leidt vaak tot herschrijvingen.

Streef ernaar voldoende detail te geven zodat iemand de fout kan volgen vanaf de eerste echte fout tot het eind, en vervolgens zo min mogelijk hoeft te veranderen.

Kopieer dit in je bericht (woordelijk waar mogelijk):

• De volledige falende log vanaf de eerste foutregel tot het einde (niet alleen de laatste stacktrace).
• Het exacte commando dat CI draaide (bijvoorbeeld go test ./..., npm test, flutter test, golangci-lint run).
• De bestandsroutes genoemd in de fout, plus relevante config (testconfig, linterconfig, buildscripts).
• Wat er recent veranderde: PR-diff samenvatting, dependency bumps, CI-config edits.
• Of het flaky is: twee of drie mislukte runs en één geslaagde run als je die hebt.

Voeg beperkingen toe in gewone woorden. Als je een piepkleine fix wilt, zeg dat: geen refactors, geen gedragswijzigingen tenzij noodzakelijk, houd de patch beperkt tot het falende gebied.

Een simpel voorbeeld: CI faalt op een lint-stap na een dependency bump. Plak de lint-output vanaf de eerste waarschuwing, voeg het commando dat CI gebruikte toe en noem de enkele packageversiewijziging. Dat is genoeg om een eénderige config-aanpassing of een kleine codewijziging voor te stellen, in plaats van het herformatteren van de halve repo.

Als je iets copy-paste-achtigs wilt, is deze structuur meestal genoeg:

CI command:

Failing output (full):

Recent changes:

Constraints (smallest fix, no refactor):

Flaky? (runs attached):

Promptregels die het dwingen de falende output te lezen

Wanneer een model de mist in gaat bij een CI-breuk, komt dat meestal doordat je prompt het laat raden. Jouw taak is het model te dwingen zijn werk te tonen met de exacte falende output, en zich vervolgens te committeren aan de kleinste wijziging die het job laat slagen.

Regels die het model eerlijk houden

Eis bewijs en een klein plan. Een goede prompt dwingt vijf dingen af:

• Quoteer de exacte falende regels uit de CI-log (errors, stacktrace, bestand:regel) en zeg expliciet "Ik gebruik deze regels."
• Geef een één-zins diagnose, zonder geaarzel.
• Stel een minimaal patchplan voor met 1–3 edits, en noem de exacte bestanden die geraakt worden.
• Vermijd niet-gerelateerde wijzigingen (geen formattering, hernoemingen, refactors, dependency bumps) tenzij jij het goedkeurt.
• Noem waar het onzeker over is en het ene stukje info dat het zou bevestigen.

Onzekerheid is prima. Verborgen onzekerheid is wat tijd verspilt.

Klaar-om-te-plakken promptfragment

Plak dit bovenaan je CI-vraag:

Use ONLY the evidence in the CI output below.
1) Quote the exact failing lines you are using.
2) Give ONE sentence: the most likely cause.
3) Propose the smallest fix: 1-3 edits, with file paths.
4) Do NOT do formatting/renames/refactors or "cleanup".
5) List uncertainties + the one extra detail that would confirm the diagnosis.

Als de log zegt "expected 200, got 500" plus een stacktrace naar user_service.go:142, duwt deze structuur het antwoord richting die functie en een kleine guard- of error-handlingwijziging, niet het herontwerpen van de endpoint.

Een copy-paste prompttemplate voor CI-fouten

De snelste overwinningen komen van een prompt die het quoten van logs afdwingt, binnen beperkingen blijft en stopt zodra iets ontbreekt.

You are helping me fix a CI failure.

Repo context (short):
- Language/framework:
- Test/build command that failed: <PASTE THE EXACT COMMAND>
- CI environment (OS, Node/Go/Python versions, etc.):

Failing output (verbatim, include the first error and 20 lines above it):
<PASTE LOG>

Constraints:
- Propose the smallest possible code change that makes CI pass.
- Do NOT rewrite/refactor unrelated code.
- Do NOT touch files you do not need for the fix.
- If behavior changes, make it explicit and justify why it is correct.

Stop rule (no guessing):
- If the log is incomplete or you need more info (missing stack trace, config, versions, failing test name), STOP and ask only the minimum questions needed.

Your response format (follow exactly):
1) Evidence: Quote the exact log lines that matter.
2) Hypothesis: Explain the most likely cause in 2-4 sentences.
3) Smallest fix: Describe the minimal change and why it addresses the evidence.
4) Patch: Provide a unified diff.
5) Follow-up: Tell me the exact command(s) to rerun locally to confirm.

Then, write ONE regression test (or tweak an existing one) that would fail before this fix and pass after it, to prevent the same failure class.
- Keep the test focused. No broad test suites.
- If a test is not feasible, explain why and propose the next-best guardrail (lint rule, type check, assertion).

Twee details die heen-en-weer verminderen:

• Voeg het exacte falende commando en de eerste fout toe (niet alleen de eindsamenvatting).
• Als er meerdere fouten zijn, zeg welke je eerst wilt fixen (gewoonlijk de vroegste echte fout in de log).

Hoe te pushen voor de kleinste fix, niet een herschrijving

De snelste manier om tijd te verliezen is akkoord gaan met een "opschoon"-wijzigingenset die vijf dingen tegelijk verandert. Definieer "minimaal" vooraf: de kleinste diff die de falende job groen maakt, met het laagste risico en de snelste verificatie.

Een simpele regel werkt goed: fix eerst het symptoom, beslis daarna of een bredere refactor de moeite waard is. Als de log naar één bestand, één functie, één ontbrekende import of één edge case wijst, richt je daar. Vermijd "while we're here"-edits.

Als je echt alternatieven nodig hebt, vraag om twee en alleen twee: "veiligste minimale fix" versus "snelste minimale fix." Je wilt trade-offs, geen menu.

Eis ook lokale verificatie die overeenkomt met CI. Vraag om hetzelfde commando dat de pipeline draait (of het dichtstbijzijnde equivalent), zodat je in minuten kunt bevestigen:

# run the same unit test target CI runs
make test
# or the exact script used in CI
npm test

Als het antwoord een grote wijziging voorstelt, druk dan terug met: "Laat de kleinste patch zien die de falende assertie oplost, zonder niet-gerelateerde formattering of hernoemingen."

Prompten voor een follow-up test die herhaling voorkomt

Een fix zonder test is een gok dat je het probleem niet opnieuw tegenkomt. Vraag altijd om een follow-up test die vóór de fix faalt en erna slaagt.

Wees specifiek over wat "goed" betekent:

• Als de fout een unit test crash was, wil je waarschijnlijk een nieuwe test of een strengere assertie.
• Als de fout een build-, lint- of formattingregel was, wil je een check die die regel afdwingt zodat dezelfde foutklasse niet terugkomt.

Een nuttig patroon is deze vier dingen te eisen: waar je de test plaatst, hoe je hem noemt, welk gedrag hij moet dekken, en een korte uitleg waarom hij toekomstige regressies voorkomt.

Klaar-om-te-plakken toevoeging:

• Schrijf één regressietest die faalt op de huidige main-branch en slaagt na je fix.
• Maak hem gericht op dezelfde foutklasse, niet enkel de exacte regel die brak.
• Zet de test in: <pad of folder>. Volg naamgeving: <jouw conveniëntie>.
• Als dit een lint/build-regel is, voeg add of pas een check aan die de regel afdwingt.
• Voeg 2–3 zinnen toe: waarom deze test een soortgelijke bug later zou vangen.

Voorbeeld: CI toont een panic wanneer een API-handler een lege string ID ontvangt. Vraag niet om "een test voor deze regel." Vraag om een test die ongeldige IDs (leeg, whitespace, verkeerd formaat) dekt. De kleinste fix kan een guard-clausule zijn die een 400-response retourneert. De regressietest zou gedrag voor meerdere ongeldige inputs asserten, zodat de volgende keer iemand parsing refactort, CI meteen faalt.

Als je project al testconventies heeft, beschrijf die. Als niet, vraag om nabijgelegen tests in dezelfde package/folder te spiegelen en houd de nieuwe test klein en leesbaar.

Een stapsgewijze workflow die je kunt hergebruiken

1) Geef de fout zoals hij is

Plak de CI-logsectie die de fout bevat en 20–40 regels erboven. Plak ook het exacte falende commando dat CI draaide en belangrijke omgevingsdetails (OS, runtime-versies, belangrijke flags).

Vraag het vervolgens het falen in gewone taal te herhalen en wijs naar de regel(s) in de output die het bewijzen. Als het de log niet kan citeren, heeft het hem niet echt gelezen.

2) Eis eerst de kleinste patch

Vraag om de kleinste mogelijke codewijziging die het falende commando laat slagen. Druk op refactors. Laat het vóór het toepassen opsommen:

• De bestanden die het zal aanraken
• Het exacte gedrag dat verandert
• Wat het niet verandert

3) Draai hetzelfde commando opnieuw, houd de lus klein

Pas de patch toe en draai lokaal exact het falende commando (of in dezelfde CI-job als dat je enige optie is). Als het nog steeds faalt, plak alleen de nieuwe falende output en herhaal. Kleine context houdt het antwoord gefocust.

4) Voeg een regressietest toe voor de foutklasse

Als het groen is, voeg één follow-up test toe die vóór de patch faalde en erna slaagt. Houd het gericht: één test, één reden.

Draai het commando opnieuw met de nieuwe test om te bevestigen dat je de fout niet alleen hebt gefilterd.

5) Eindig met een nette PR-pakket

Vraag om een korte commit message en een PR-beschrijving die bevat wat faalde, wat veranderde, hoe je het verifieerde en welke test een herhaling voorkomt. Reviewers gaan sneller als de redenering duidelijk is.

Een realistisch voorbeeld: van falende output naar fix en test

Een veelvoorkomende fout: alles werkte lokaal, maar een kleine wijziging maakt tests kapot op de CI-runner. Hier een simpel voorbeeld uit een Go-API waar een handler begon een datum-only waarde (2026-01-09) te accepteren, maar de code nog steeds alleen volledige RFC3339-timestamps parseerde.

Dit is het soort snippet om te plakken (houd het kort, maar includeer de foutregel):

--- FAIL: TestCreateInvoice_DueDate (0.01s)
    invoice_test.go:48: expected 201, got 400
    invoice_test.go:49: response: {"error":"invalid due_date: parsing time \"2026-01-09\" as \"2006-01-02T15:04:05Z07:00\": cannot parse \"\" as \"T\""}
FAIL
exit status 1
FAIL	app/api	0.243s

Gebruik nu een prompt die bewijs afdwingt, een minimale fix en een test:

You are fixing a CI failure. You MUST use the log to justify every claim.

Context:
- Language: Go
- Failing test: TestCreateInvoice_DueDate
- Log snippet:
<PASTE LOG>

Task:
1) Quote the exact failing line(s) from the log and explain the root cause in 1-2 sentences.
2) Propose the smallest possible code change (one function, one file) to accept both RFC3339 and YYYY-MM-DD.
3) Show the exact patch.
4) Add one regression test that fails before the fix and passes after.
Return your answer with headings: Evidence, Minimal Fix, Patch, Regression Test.

Een goed antwoord wijst naar de parsing-layout mismatch en maakt vervolgens een kleine wijziging in één functie (bijvoorbeeld parseDueDate in invoice.go) om eerst RFC3339 te proberen en terug te vallen op 2006-01-02. Geen refactor, geen nieuwe packages.

De regressietest is de vangrail: zend due_date: "2026-01-09" en verwacht 201. Als iemand later parsing "opschoont" en de fallback verwijdert, faalt CI meteen met dezelfde foutklasse.

Veelgemaakte fouten die tijd kosten (en hoe ze te vermijden)

De snelste manier om een uur te verliezen is een uitgeknipte weergave van het probleem te geven. CI-logs zijn ruisig, maar het nuttige gedeelte is vaak 20 regels boven de eindfout.

Een valkuil is alleen de laatste rode regel plakken (bijvoorbeeld "exit 1") terwijl de echte oorzaak eerder zat (een ontbrekende env var, een falende snapshot, of de eerste test die crasht). Oplossing: includeer het falende commando plus het logvenster waar de eerste echte fout verschijnt.

Een andere tijdverspilling is het model toestaan "op te ruimen" onderweg. Extra formattering, dependency bumps of refactors maken het lastiger te reviewen en makkelijker om iets anders te breken. Oplossing: zet de scope vast op de kleinste mogelijke codewijziging en verwerp alles niet-gerelateerd.

Enkele patronen om op te letten:

• Alleen de laatste foutregel plakken: includeer het falende commando en de eerste fout.
• Het laten wijzigen van dependencies of niet-gerelateerde bestanden: eis een minimale diff en een reden voor elk bestand dat geraakt wordt.
• Instemmen met een fix die niet geverifieerd is tegen het CI-commando: draai exact hetzelfde commando en bevestig.
• Een test schrijven die nog steeds slaagt wanneer de bug terugkomt: eis een test die faalt op de oude code en slaagt op de fix.
• Flaky tests en echte regressies mengen: beslis of het nondeterministisch is (timing, netwerk, order) of stabiele logica en handel ernaar.

Als je flakiness vermoedt, plak er geen pleister overheen met retries. Verwijder de willekeur (vaste tijd, seeded RNG, geïsoleerde temp-mappen) zodat het signaal duidelijk is.

Snelle checks voordat je de fix pusht

Voordat je pusht, doe een korte sanity-check. Doel is te verzekeren dat de wijziging echt, minimaal en reproduceerbaar is, niet een gelukstreffer.

• Bewijs: citeert de verklaring de exacte falende regels?
• Scope: zijn wijzigingen beperkt tot wat nodig is om deze fout te stoppen?
• Causaliteit: legt het uit waarom deze wijziging de fout van falen naar slagen verandert?
• Repro: heb je exact het CI-commando opnieuw gedraaid (zelfde flags, dezelfde werkmap)?
• Regressie: faalt de nieuwe test vóór de fix en slaagt erna?

Draai tenslotte een iets bredere set dan alleen de falende job (bijv. lint plus unittests). Een veelvoorkomend valkuil is een fix die de originele job groen maakt maar een ander target breekt.

Volgende stappen: maak deze workflow een gewoonte

Als je wilt dat dit week na week tijd bespaart, behandel je prompt en responsformaat als teamproces. Het doel is herhaalbare inputs, herhaalbare outputs en minder "mystery fixes" die iets anders breken.

Zet je beste prompt om in een gedeeld snippet en pin die in teamchat. Het doel is dat iedereen hetzelfde format gebruikt: (1) bewijs, (2) één-regel oorzaak, (3) kleinste wijziging, (4) follow-up test, (5) hoe lokaal te verifiëren. Reviewers vinden het makkelijker omdat ze weten waar ze moeten kijken.

Een lichtgewicht habit-loop die in de meeste teams werkt:

• Sla de prompt op als repo-snippet en pin het in teamchat.
• Label CI-fouten op type (lint, unit, integration, packaging, deploy).
• Als een label terugkeert, voeg één test of check toe die het eerder had kunnen vangen.
• Houd risicovolle experimenten omkeerbaar zodat je snel kunt terugdraaien.

Als je een chat-first workflow verkiest voor bouwen en itereren, kun je dezelfde fix-en-test-lus in Koder.ai draaien, gebruik snapshots tijdens experimenten en exporteer de bron wanneer je klaar bent om te mergen.