Een goede bugrapportage schrijven (voor AI of een developer)

Een goede bugrapportage laat iemand anders — een developer of een AI — hetzelfde probleem zien dat jij zag, zonder dat die jou iets hoeft te vragen. Ze heeft een specifieke titel nodig, de exacte stappen om het te reproduceren, wat je verwachtte, wat er werkelijk gebeurde, elke foutmelding woord voor woord gekopieerd, en waar het gebeurde: welke pagina, browser, apparaat en gebruiker. Eén bug per rapport, met een screenshot als dat helpt.

De meeste bugs kosten meer tijd om te begrijpen dan om op te lossen. Een helder rapport haalt het begrijpen weg. Dit is nog belangrijker bij AI-tools: een AI kan geen vervolgvraag stellen over wat je bedoelde met ‘afrekenen is raar’, dus gokt hij — en een verkeerde gok kan iets anders breken.

De sjabloon

Kopieer dit en vul het in:

Titel: [Wat er mis is, waar] — bijv. „Boekingsformulier wijst tijden na 18:00 af”

Stappen om te reproduceren:
1. ...
2. ...
3. ...

Verwacht: [wat zou moeten gebeuren]
Werkelijk: [wat er in plaats daarvan gebeurde]

Foutmelding: [exacte tekst, indien aanwezig]
Waar: [pagina/URL, browser, apparaat, ingelogd als welke gebruiker]
Hoe vaak: [elke keer / soms / één keer]
Screenshot of opname: [bijgevoegd]

De rest van deze gids legt elk onderdeel uit.

Stap 1: reproduceer het eerst

Probeer de bug opnieuw te laten gebeuren voordat je schrijft. Dan leer je welke stappen ertoe doen, en of het elke keer gebeurt.

Begin vanuit een schone staat: ververs, of log uit en weer in.
Noteer elke klik en elke tekst die je typt.
Zoek het kortste pad dat de bug veroorzaakt.
Probeer een tweede browser of account. Als het alleen bij één gebruiker gebeurt, is dat een grote aanwijzing.

Voor meer hierover, zie hoe je een met AI gebouwde app debugt.

Stap 2: schrijf een specifieke titel

De titel moet zeggen wat er mis is en waar, zodat iemand die een lijst doorloopt weet welke bug het is.

Zwak	Sterk
Afrekenen kapot	Afrekenknop doet niets wanneer de winkelwagen een kortingscode heeft
Mobiel probleem	Prijskaarten lopen buiten het scherm op telefoons smaller dan 400px
Fout bij opslaan	Een profiel opslaan met een emoji in de naam toont „500 Internal Server Error”

Stap 3: geef exacte stappen

Nummer ze. Wees letterlijk: welke pagina, welke knop, wat je typte.

Log in als klant (testaccount: customer@example.com).
Voeg het „Starterspakket” toe aan de winkelwagen.
Voer de kortingscode WELCOME10 in en klik op Toepassen.
Klik op Afrekenen.

„Probeer af te rekenen met een code” laat de details weg die vaak ertoe doen: welke gebruiker, welk product, welke code, en of die eerst is toegepast.

Stap 4: verwacht versus werkelijk

Dit is de kern van het rapport. Noem beide, want het verschil is de bug.

Verwacht: de afrekenpagina opent met de 10% korting in het totaal.
Werkelijk: de knop toont een seconde een spinner, en daarna gebeurt er niets. Zonder kortingscode werkt afrekenen.

Zonder ‘verwacht’ weet de lezer misschien niet dat het gedrag fout is. Zonder ‘werkelijk’ weet hij niet waar hij naar moet zoeken.

Stap 5: kopieer fouten exact

Foutmeldingen zijn de snelste weg naar de oorzaak. Kopieer ze als tekst, woord voor woord — parafraseer niet.

Waar je ze vindt:

Op het scherm: elke melding die de app toont.
Browserconsole: open de ontwikkelaarstools (F12, of rechtsklik → Inspecteren) en kijk op het tabblad Console naar rode regels.
Netwerktabblad: zoek in de ontwikkelaarstools het mislukte verzoek en noteer de URL en statuscode (bijvoorbeeld POST /api/checkout → 500).
Serverlogs, als je er toegang toe hebt.

Een regel als TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 wijst vaak meteen naar het probleem.

Stap 6: voeg context toe

Waar: de URL van de pagina, de omgeving (preview, staging of live).
Wie: welke gebruiker of rol — beheerder, lid, niet ingelogd.
Apparaat en browser: „Safari op iPhone” versus „Chrome op Windows” kan ertoe doen.
Gegevens: alles wat ongewoon is aan het record — heel lange tekst, speciale tekens, een groot aantal items.
Wanneer het begon: „na de wijziging van gisteren aan kortingscodes” is goud waard.
Hoe vaak: elke keer, of één keer op de tien pogingen.

Stap 7: laat het zien

Een screenshot met het probleem omcirkeld, of een korte schermopname, haalt de dubbelzinnigheid weg — vooral bij lay-outbugs. Als je AI-tool afbeeldingen accepteert, voeg er dan een toe. Snij alles bij wat privé is, inclusief sleutels en gegevens van anderen.

Bugrapporten schrijven voor een AI-builder

Dezelfde structuur werkt als prompt. Twee toevoegingen helpen:

Zeg wat niet mag veranderen, zodat de fix geen nieuw probleem veroorzaakt.
Vraag om de fix te verifiëren, niet alleen te schrijven.

Ingelogd als klant, met het „Starterspakket” in de winkelwagen en de code WELCOME10 toegepast, doet er niets wanneer ik op Afrekenen klik. Verwacht: de afrekenpagina opent met 10% korting op het totaal. Werkelijk: een korte spinner, en daarna niets. Het netwerktabblad toont dat POST /api/checkout een 500 teruggaf. Afrekenen zonder code werkt. Zoek de oorzaak en los die op zonder te veranderen hoe prijzen worden berekend voor bestellingen zonder code. Controleer daarna het afrekenen met een percentagecode, een code met een vast bedrag en zonder code.

Weet je de oorzaak niet zeker, vraag dan eerst om een diagnose:

Wijzig nog geen code. Wat zijn op basis van dit rapport de waarschijnlijke oorzaken, en wat zou elk ervan bevestigen?

Veelgemaakte fouten

„Het is kapot.” Geen stappen, geen verwacht resultaat, niets om op te handelen.
Meerdere bugs in één rapport. Sommige worden opgelost, andere gaan verloren.
Geparafraseerde fouten. „Een of ander undefined ding” verbergt het nuttige deel.
De gebruiker of rol vergeten. Veel bugs treffen alleen beheerders, of alleen nieuwe gebruikers.
Alleen de gewenste fix beschrijven („voeg een null-controle toe”) in plaats van het probleem.
Geheimen delen in screenshots of geplakte logs.

Checklist

Ik heb de bug gereproduceerd en de kortste stappen gevonden.
De titel zegt wat er mis is en waar.
De stappen zijn genummerd en letterlijk.
Verwacht en werkelijk zijn beide vermeld.
Foutmeldingen zijn exact gekopieerd, met het mislukte verzoek en de statuscode.
Pagina, omgeving, gebruiker, apparaat en browser zijn opgenomen.
Ik heb gezegd hoe vaak het gebeurt en wanneer het begon.
Een screenshot of opname is bijgevoegd, met privégegevens verwijderd.
Eén bug per rapport.

Bugs melden aan de agent van Mythex

In een Mythex-project is het rapport de prompt. Een paar functies helpen:

Voeg een screenshot toe van de preview of het foutscherm — tot 5 bestanden per bericht.
/fix richt de agent op het oplossen van een bug; de Plan-modus laat hem onderzoeken voordat hij bewerkt.
/test laat de agent flows in de preview zelf reproduceren en melden wat hij ziet.
Terugzetten naar dit punt draait een fix terug die het erger heeft gemaakt.

De pagina debuggen met prompts in de docs gebruikt dezelfde structuur van stappen / verwacht / werkelijk. Voor de fix-en-controle-lus eromheen, zie hoe je itereert op een met AI gebouwde app.

Veelgestelde vragen

Wat hoort er in een bugrapport?

Een specifieke titel, de exacte stappen om het probleem te reproduceren, wat je verwachtte, wat er werkelijk gebeurde, elke foutmelding woord voor woord, waar het gebeurde (pagina, browser, apparaat, gebruiker), en een screenshot of opname als dat helpt.

Hoe schrijf ik een bugrapport voor een AI-app-builder?

Gebruik dezelfde structuur als voor een developer: stappen, verwacht, werkelijk en de exacte fout. Voeg toe wat niet mag veranderen, en vraag de AI om de fix te maken en daarna te verifiëren. Vage prompts als ‘het is kapot’ leiden tot gissingen.

Wat als ik de bug niet kan reproduceren?

Meld hem toch, maar zeg erbij dat je hem niet kunt reproduceren. Voeg toe wat je aan het doen was, het tijdstip, het gebruikersaccount en elke fout die je zag. Noteer hoe vaak het gebeurt, bijvoorbeeld één keer op de tien pogingen, omdat wisselende bugs vaak op timing- of gegevensproblemen wijzen.

Moet ik meerdere bugs in één rapport zetten?

Nee. Eén bug per rapport, zodat elke bug apart kan worden opgelost, getest en gesloten. Denk je dat twee problemen verband houden, zeg dat dan in elk rapport.