Kako napisati dobro poročilo o napaki (za AI ali razvijalca)

Dobro poročilo o napaki omogoča, da nekdo drug – razvijalec ali AI – vidi isto težavo, kot ste jo videli vi, ne da bi vas moral karkoli vprašati. Potrebuje konkreten naslov, natančne korake za ponovitev, kaj ste pričakovali, kaj se je dejansko zgodilo, morebitno sporočilo o napaki, prepisano dobesedno, in kje se je zgodilo: katera stran, brskalnik, naprava in uporabnik. Ena napaka na poročilo, s posnetkom zaslona, če pomaga.

Večina napak traja dlje, da jih razumemo, kot da jih popravimo. Jasno poročilo odstrani del razumevanja. To je še posebej pomembno pri orodjih z AI: AI ne more postaviti dodatnega vprašanja o tem, kaj ste mislili z »blagajna je nekam čudna«, zato ugiba – in napačen namig lahko pokvari še kaj drugega.

Predloga

Kopirajte in izpolnite:

Naslov: [Kaj je narobe, kje] – npr. »Obrazec za rezervacije zavrne čase po 18. uri«

Koraki za ponovitev:
1. ...
2. ...
3. ...

Pričakovano: [kaj bi moralo biti]
Dejansko: [kaj se je zgodilo namesto tega]

Sporočilo o napaki: [natančno besedilo, če obstaja]
Kje: [stran/URL, brskalnik, naprava, prijavljen kot kateri uporabnik]
How often: [vsakič / včasih / enkrat]
Posnetek zaslona ali posnetek: [priložen]

Preostali del vodnika razlaga posamezne dele.

1. korak: najprej ponovite napako

Preden pišete, poskusite napako sprožiti znova. Naučili se boste, kateri koraki so pomembni in ali se pojavi vsakič.

• Začnite iz čistega stanja: osvežite stran ali se odjavite in prijavite.
• Zapišite vsak klik in vsako vneseno besedilo.
• Poskusite najti najkrajšo pot, ki jo sproži.
• Poskusite drug brskalnik ali račun. Če se pojavi samo pri enem uporabniku, je to velik namig.

Za več o tem glejte kako odpraviti napake v aplikaciji, ustvarjeni z AI.

2. korak: napišite konkreten naslov

Naslov naj pove, kaj je narobe in kje, da nekdo, ki pregleduje seznam, takoj ve, za katero napako gre.

3. korak: navedite natančne korake

Oštevilčite jih. Bodite dobesedni: katera stran, kateri gumb, kaj ste vtipkali.

1. Prijavite se kot stranka (testni račun: customer@example.com).
2. Dodajte »Začetni komplet« v košarico.
3. Vnesite kodo za popust WELCOME10 in kliknite Uporabi.
4. Kliknite Blagajna.

»Poskusite plačati s kodo« izpusti podrobnosti, ki pogosto so pomembne: kateri uporabnik, kateri izdelek, katera koda, ali je bila najprej uporabljena.

4. korak: pričakovano proti dejanskemu

To je jedro poročila. Navedite oboje, ker je razlika napaka.

• Pričakovano: stran blagajne se odpre s 10-odstotnim popustom, prikazanim v znesku.
• Dejansko: gumb za eno sekundo prikaže krogec za nalaganje, nato se ne zgodi nič. Brez kode za popust blagajna deluje.

Brez »pričakovanega« bralec morda ne bo vedel, da je vedenje napačno. Brez »dejanskega« ne bo vedel, kaj iskati.

5. korak: napake prepišite natančno

Sporočila o napakah so najhitrejša pot do vzroka. Kopirajte jih kot besedilo, dobesedno – ne parafrazirajte.

Kje jih najti:

• Na zaslonu: katero koli sporočilo, ki ga aplikacija prikaže.
• Konzola brskalnika: odprite orodja za razvijalce (F12 ali desni klik → Preglej) in poglejte zavihek Console za rdeče vrstice.
• Zavihek Network: v orodjih za razvijalce poiščite neuspešno zahtevo in zapišite njen URL in statusno kodo (na primer POST /api/checkout → 500).
• Dnevniki strežnika, če imate dostop.

Vrstica, kot je TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48, pogosto kar neposredno kaže na težavo.

6. korak: dodajte kontekst

• Kje: URL strani, okolje (predogled, testno ali živo).
• Kdo: kateri uporabnik ali vloga – skrbnik, član, odjavljen.
• Naprava in brskalnik: »Safari na iPhonu« proti »Chrome v Windowsih« je lahko pomembno.
• Podatki: vse nenavadno o zapisu – zelo dolgo besedilo, posebni znaki, veliko elementov.
• Kdaj se je začelo: »po včerajšnji spremembi kod za popust« je zlato.
• Kako pogosto: vedno ali enkrat na deset poskusov.

7. korak: pokažite

Posnetek zaslona z označeno težavo ali kratek posnetek zaslona odpravi dvoumnost – zlasti pri napakah v postavitvi. Če vaše orodje z AI sprejema slike, jo priložite. Obrežite vse zasebno, vključno s ključi in podatki drugih ljudi.

Pisanje poročil o napakah za graditelja z AI

Enaka struktura deluje tudi kot poziv. Dve dodatki pomagata:

• Povejte, kaj se ne sme spremeniti, da popravek ne povzroči nove težave.
• Prosite, naj popravek preveri, ne samo napiše.

Prijavljen kot stranka, z »Začetnim kompletom« v košarici in uporabljeno kodo WELCOME10, klik na Blagajna ne naredi ničesar. Pričakovano: stran blagajne se odpre z 10 % popusta na znesek. Dejansko: kratek krogec za nalaganje, nato nič. Zavihek Network kaže, da je POST /api/checkout vrnil 500. Blagajna brez kode deluje. Poiščite vzrok in ga popravite, ne da bi spremenili, kako se računajo cene za naročila brez kode. Nato preverite blagajno s kodo za odstotek, kodo za fiksni znesek in brez kode.

Če niste prepričani o vzroku, najprej zahtevajte diagnozo:

Zaenkrat ne spreminjaj kode. Glede na to poročilo, kateri so verjetni vzroki in kaj bi potrdilo vsakega od njih?

Pogoste napake

• »Nekaj je pokvarjeno.« Ni korakov, ni pričakovanega rezultata, ni česa, na kar bi lahko ukrepali.
• Več napak v enem poročilu. Nekatere se odpravijo, druge se izgubijo.
• Parafrazirane napake. »Neka nedefinirana stvar« skrije koristni del.
• Manjkajoč uporabnik ali vloga. Številne napake vplivajo samo na skrbnike ali samo na nove uporabnike.
• Opisovanje samo želenega popravka (»dodaj preverjanje null«) namesto težave.
• Deljenje skrivnosti na posnetkih zaslona ali prilepljenih dnevnikih.

Kontrolni seznam

• Napako sem ponovil in našel najkrajše korake.
• Naslov pove, kaj je narobe in kje.
• Koraki so oštevilčeni in dobesedni.
• Navedeno je pričakovano in dejansko.
• Sporočila o napakah so prepisana natančno, z morebitno neuspešno zahtevo in statusno kodo.
• Vključeni so stran, okolje, uporabnik, naprava in brskalnik.
• Povedal sem, kako pogosto se pojavi in kdaj se je začelo.
• Priložen je posnetek zaslona ali posnetek, zasebni podatki pa so odstranjeni.
• Ena napaka na poročilo.

Prijava napak agentu Mythexa

V projektu Mythex je poročilo hkrati poziv. Nekatere funkcije pomagajo:

• Priložite posnetek zaslona predogleda ali zaslona z napako – do 5 datotek na sporočilo.
• /fix osredotoči agenta na odpravljanje napake; način Plan mu omogoča raziskavo, preden ureja.
• /test naj agent sam ponovi tokove v predogledu in poroča, kaj vidi.
• Vrni na to točko razveljavi popravek, ki je stvari poslabšal.

Stran dokumentacije odpravljanje napak s pozivi uporablja isto strukturo korakov, pričakovanega in dejanskega. Za zanko popravljanja in preverjanja okoli tega glejte kako iterirati aplikacijo, ustvarjeno z AI.

Vprašanja