Miten kirjoittaa hyvä bugiraportti (tekoälylle tai kehittäjälle)

Hyvä bugiraportti antaa jollekulle — kehittäjälle tai tekoälylle — mahdollisuuden nähdä saman ongelman kuin sinä, kysymättä sinulta mitään. Se tarvitsee tarkan otsikon, tarkat vaiheet ongelman toistamiseen, odotetun ja todellisen tuloksen, virheviestin kopioituna sanasta sanaan ja tiedon siitä, missä se tapahtui: mikä sivu, selain, laite ja käyttäjä. Yksi bugi per raportti, ja kuvakaappaus, jos siitä on apua.

Useimmat bugit vievät enemmän aikaa ymmärtää kuin korjata. Selkeä raportti poistaa ymmärtämisen osuuden. Tämä on vielä tärkeämpää tekoälytyökaluilla: tekoäly ei voi kysyä tarkentavaa kysymystä siitä, mitä tarkoitit sanoessasi „kassa on outo”, joten se arvaa — ja väärä arvaus voi rikkoa jotain muuta.

Pohja

Kopioi tämä ja täytä:

Otsikko: [Mikä on vialla, missä] — esim. „Varauslomake hylkää kellonajat klo 18 jälkeen”

Vaiheet toistamiseen:
1. ...
2. ...
3. ...

Odotettu: [mitä pitäisi tapahtua]
Todellinen: [mitä tapahtui sen sijaan]

Virheviesti: [tarkka teksti, jos on]
Missä: [sivu/URL, selain, laite, kirjautunut käyttäjä]
Kuinka usein: [joka kerta / joskus / kerran]
Kuvakaappaus tai tallenne: [liitetty]

Loppu opas selittää jokaisen osan.

Vaihe 1: Toista se ensin

Ennen kirjoittamista yritä saada bugi tapahtumaan uudelleen. Opit, mitkä vaiheet ovat olennaisia ja tapahtuuko se joka kerta.

• Aloita puhtaasta tilasta: päivitä sivu tai kirjaudu ulos ja sisään.
• Merkitse ylös jokainen klikkaus ja jokainen kirjoittamasi asia.
• Etsi lyhin polku, joka laukaisee bugin.
• Kokeile toista selainta tai tiliä. Jos se tapahtuu vain yhdelle käyttäjälle, se on iso vihje.

Lisää tästä katso miten debugata tekoälyllä rakennettu sovellus.

Vaihe 2: Kirjoita tarkka otsikko

Otsikon pitäisi kertoa, mikä on vialla ja missä, jotta listaa selaava tietää, mistä bugista on kyse.

Vaihe 3: Listaa tarkat vaiheet

Numeroi ne. Ole kirjaimellinen: mikä sivu, mikä painike, mitä kirjoitit.

1. Kirjaudu asiakkaana (testitili: customer@example.com).
2. Lisää „Starter kit” ostoskoriin.
3. Syötä alennuskoodi WELCOME10 ja klikkaa Käytä.
4. Klikkaa Kassa.

„Kokeile maksamista koodilla” jättää pois yksityiskohdat, joilla usein on merkitystä: mikä käyttäjä, mikä tuote, mikä koodi ja tuliko se ensin käytettyä.

Vaihe 4: Odotettu vs. todellinen

Tämä on raportin ydin. Kerro molemmat, sillä ero on bugi.

• Odotettu: kassasivu avautuu ja kokonaissummassa näkyy 10 % alennus.
• Todellinen: nappi näyttää latauskehää sekunnin ajan, eikä sitten mitään tapahdu. Ilman alennuskoodia kassa toimii.

Ilman „odotettua” lukija ei välttämättä tiedä, että käytös on väärin. Ilman „todellista” hän ei tiedä, mitä etsiä.

Vaihe 5: Kopioi virheet tarkasti

Virheviestit ovat nopein tie syyhyn. Kopioi ne tekstinä sanasta sanaan — älä muotoile uudelleen.

Mistä niitä löytyy:

• Näytöllä: mikä tahansa sovelluksen näyttämä viesti.
• Selaimen konsoli: avaa kehittäjätyökalut (F12 tai hiiren oikea painike → Tarkista) ja katso Console-välilehti punaisten rivien varalta.
• Network-välilehti: kehittäjätyökaluissa etsi epäonnistunut pyyntö ja kirjaa sen URL ja tilakoodi (esimerkiksi POST /api/checkout → 500).
• Palvelinlokit, jos sinulla on pääsy.

Rivi kuten TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 osoittaa usein suoraan ongelmaan.

Vaihe 6: Lisää kontekstia

• Missä: sivun URL, ympäristö (esikatselu, testi vai tuotanto).
• Kuka: mikä käyttäjä tai rooli — ylläpitäjä, jäsen, kirjautumaton.
• Laite ja selain: „Safari iPhonella” vs. „Chrome Windowsilla” voi olla ratkaisevaa.
• Data: kaikki epätavallinen tietueessa — hyvin pitkä teksti, erikoismerkit, suuri määrä kohteita.
• Milloin se alkoi: „eilisen muutoksen jälkeen alennuskoodeihin” on kultaa.
• Kuinka usein: joka kerta tai kerran kymmenestä.

Vaihe 7: Näytä se

Kuvakaappaus, jossa ongelma on ympyröity, tai lyhyt näyttötallenne poistaa epäselvyyden — erityisesti ulkoasubugeissa. Jos tekoälytyökalusi hyväksyy kuvia, liitä yksi. Rajaa pois kaikki yksityinen, mukaan lukien avaimet ja muiden ihmisten tiedot.

Bugiraportit tekoälyrakentajalle

Sama rakenne toimii kehotteena. Kaksi lisäystä auttaa:

• Kerro, mitä ei saa muuttua, jotta korjaus ei aiheuta uutta ongelmaa.
• Pyydä varmistamaan korjaus, ei vain kirjoittamaan sitä.

Kirjautuneena asiakkaana, „Starter kit” ostoskorissa ja koodi WELCOME10 käytettynä, „Kassa”-painike ei tee mitään. Odotettu: kassasivu avautuu ja loppusummasta on 10 % alennus. Todellinen: lyhyt latauskehä ja sitten ei mitään. Network-välilehdellä POST /api/checkout palautti 500. Kassa ilman koodia toimii. Etsi syy ja korjaa se muuttamatta, miten hinnat lasketaan tilauksille ilman koodia. Tarkista sitten kassa prosenttialennuskoodilla, kiinteällä alennuskoodilla ja ilman koodia.

Jos et ole varma syystä, pyydä ensin diagnoosi:

Älä vielä muuta koodia. Mitkä ovat tämän raportin perusteella todennäköiset syyt, ja mikä vahvistaisi kunkin?

Yleisiä virheitä

• „Se on rikki.” Ei vaiheita, ei odotettua tulosta, ei mitään toimittavaa.
• Useita bugeja yhdessä raportissa. Osa korjataan, osa katoaa.
• Virheiden parafrasointi. „Joku undefined-juttu” piilottaa hyödyllisen osan.
• Käyttäjän tai roolin puuttuminen. Monet bugit koskevat vain ylläpitäjiä tai vain uusia käyttäjiä.
• Vain halutun korjauksen kuvaaminen („lisää null-tarkistus”) ongelman sijaan.
• Salaisuuksien jakaminen kuvakaappauksissa tai liitetyissä lokeissa.

Tarkistuslista

• Toistin bugin ja löysin lyhimmät vaiheet.
• Otsikko kertoo, mikä on vialla ja missä.
• Vaiheet on numeroitu ja kirjaimellisia.
• Odotettu ja todellinen on kummatkin kerrottu.
• Virheviestit on kopioitu tarkasti, mukaan lukien epäonnistunut pyyntö ja tilakoodi.
• Sivu, ympäristö, käyttäjä, laite ja selain on mukana.
• Olen kertonut, kuinka usein se tapahtuu ja milloin se alkoi.
• Kuvakaappaus tai tallenne on liitetty, yksityiset tiedot poistettuna.
• Yksi bugi per raportti.

Bugien raportointi Mythexin agentille

Mythex-projektissa raportti on kehote. Muutama ominaisuus auttaa:

• Liitä kuvakaappaus esikatselusta tai virhenäytöstä — enintään 5 tiedostoa per viesti.
• /fix kohdistaa agentin bugin korjaamiseen, ja Suunnittele-tila antaa sen tutkia ennen muokkaamista.
• /test pyytää agenttia toistamaan kulut esikatselussa ja raportoimaan, mitä se näkee.
• Palauta tähän kohtaan kumoaa korjauksen, joka pahensi tilannetta.

Dokumentaation virheenkorjaus kehotteilla -sivu käyttää samaa vaiheet / odotettu / todellinen -rakennetta. Korjaus- ja tarkistuskierrokseen sen ympärillä katso miten iteroida tekoälyllä rakennettua sovellusta.

Kysymykset