Si të shkruash një raport të mirë gabimi (për AI ose një zhvillues)

Një raport i mirë gabimi lejon dikë tjetër — një zhvillues ose një AI — ta shohë të njëjtin problem që pe ti, pa të pyetur asgjë. Ai ka nevojë për një titull specifik, hapat e saktë për ta riprodhuar, atë që prisje, atë që ndodhi në të vërtetë, çdo mesazh gabimi të kopjuar fjalë për fjalë, dhe ku ndodhi: cila faqe, shfletues, pajisje dhe përdorues. Një gabim për raport, me një pamje ekrani nëse ndihmon.

Shumica e gabimeve kërkojnë më shumë kohë për t'u kuptuar sesa për t'u rregulluar. Një raport i qartë e heq pjesën e kuptimit. Kjo ka rëndësi edhe më shumë me mjetet AI: një AI nuk mund të të pyesë se çfarë do të thoshe me "checkout është i çuditshëm", kështu që merr një supozim — dhe një supozim i gabuar mund të prishë diçka tjetër.

Shablloni

Kopjoje dhe plotëso:

Titulli: [Çfarë është e gabuar, ku] — p.sh. "Formulari i rezervimit refuzon orët pas 18:00"

Hapat për riprodhim:
1. ...
2. ...
3. ...

Pritet: [çfarë duhet të ndodhë]
Ndodh: [çfarë ndodhi në vend të kësaj]

Mesazhi i gabimit: [teksti i saktë, nëse ka]
Ku: [faqja/URL, shfletuesi, pajisja, i kyçur si cili përdorues]
Sa shpesh: [çdo herë / ndonjëherë / një herë]
Pamje ekrani ose regjistrim: [bashkëngjitur]

Pjesa tjetër e udhëzuesit shpjegon secilën pjesë.

Hapi 1: Riprodhoje fillimisht

Përpara se ta shkruash, provo ta shkaktosh gabimin përsëri. Do të mësosh cilat hapa kanë rëndësi, dhe nëse ndodh çdo herë.

Fillo nga një gjendje e pastër: rifresko, ose dil dhe hyr përsëri.
Shëno çdo klikim dhe çdo gjë që shkruan.
Provo të gjesh rrugën më të shkurtër që e shkakton.
Provo një shfletues ose llogari tjetër. Nëse ndodh vetëm për një përdorues, kjo është një shenjë e madhe.

Për më shumë rreth kësaj, shih si të korrigjosh një aplikacion të ndërtuar me AI.

Hapi 2: Shkruaj një titull specifik

Titulli duhet të thotë çfarë është e gabuar dhe ku, që dikush që shikon një listë të dijë cili gabim është.

I dobët	I fortë
Checkout i prishur	Butoni i checkout nuk bën asgjë kur shporta ka një kod zbritjeje
Problem në celular	Kartat e çmimeve dalin jashtë ekranit në telefona më të ngushtë se 400px
Gabim në ruajtje	Ruajtja e një profili me emoji në emër shfaq "500 Internal Server Error"

Hapi 3: Listo hapat e saktë

Numëroji. Ji i saktë: cila faqe, cili buton, çfarë shkruate.

Hyr si klient (llogari testimi: customer@example.com).
Shto "Starter kit" në shportë.
Shkruaj kodin e zbritjes WELCOME10 dhe kliko Apply.
Kliko Checkout.

"Provo të bësh checkout me një kod" lë jashtë detajet që shpesh kanë rëndësi: cili përdorues, cili produkt, cili kod, nëse u aplikua më parë.

Hapi 4: Pritet kundrejt ndodhi

Kjo është thelbi i raportit. Thuaji të dyja, sepse diferenca është gabimi.

Pritet: faqja e checkout hapet me zbritjen 10% të shfaqur në total.
Ndodh: butoni shfaq një spinner për një sekondë, pastaj asgjë nuk ndodh. Pa kod zbritjeje, checkout funksionon.

Pa "pritet", lexuesi mund të mos e dijë që sjellja është e gabuar. Pa "ndodh", nuk e di çfarë të kërkojë.

Hapi 5: Kopjo gabimet saktë

Mesazhet e gabimit janë rruga më e shpejtë drejt shkakut. Kopjoji si tekst, fjalë për fjalë — mos i parafrazo.

Ku t'i gjesh:

Në ekran: çdo mesazh që shfaq aplikacioni.
Konsola e shfletuesit: hap mjetet e zhvilluesit (F12, ose kliko djathtas → Inspect) dhe shiko skedën Console për rreshta të kuq.
Skeda Network: në mjetet e zhvilluesit, gjej kërkesën që dështoi dhe shëno URL-në dhe kodin e statusit (për shembull POST /api/checkout → 500).
Regjistrat e serverit, nëse ke akses.

Një rresht si TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 shpesh të drejton direkt te problemi.

Hapi 6: Shto kontekst

Ku: URL-ja e faqes, mjedisi (preview, staging ose live).
Kush: cili përdorues ose rol — admin, anëtar, i shkyçur.
Pajisja dhe shfletuesi: "Safari në iPhone" kundrejt "Chrome në Windows" mund të ketë rëndësi.
Të dhënat: çdo gjë e pazakontë për regjistrimin — tekst shumë i gjatë, karaktere të veçanta, një numër i madh artikujsh.
Kur filloi: "pas ndryshimit të djeshëm te kodet e zbritjes" është ari.
Sa shpesh: çdo herë, ose një herë në dhjetë përpjekje.

Hapi 7: Tregoje

Një pamje ekrani me problemin e rrethuar, ose një regjistrim i shkurtër ekrani, e heq paqartësinë — veçanërisht për gabimet e paraqitjes. Nëse mjeti yt AI pranon imazhe, bashkëngjite një. Pritini çdo gjë private, përfshi çelësat dhe të dhënat e personave të tjerë.

Shkrimi i raporteve të gabimeve për një builder AI

E njëjta strukturë funksionon si kërkesë. Dy shtesa ndihmojnë:

Thuaj çfarë nuk duhet të ndryshojë, që rregullimi të mos shkaktojë një problem të ri.
Kërkoji të verifikojë rregullimin, jo vetëm ta shkruajë.

Si klient, me "Starter kit" në shportë dhe kodin WELCOME10 të aplikuar, kur kliko Checkout nuk bën asgjë. Pritet: faqja e checkout hapet me 10% zbritje në total. Ndodh: një spinner i shkurtër, pastaj asgjë. Skeda network tregon që POST /api/checkout ktheu 500. Checkout pa kod funksionon. Gjej shkakun dhe rregulloje pa ndryshuar mënyrën si llogariten çmimet për porositë pa kod. Pastaj kontrollo checkout me një kod përqindjeje, një kod me shumë fikse dhe pa kod.

Nëse nuk je i sigurt për shkakun, kërko një diagnozë më parë:

Mos ndrysho kodin ende. Bazuar në këtë raport, cilat janë shkaqet e mundshme, dhe çfarë do të konfirmonte secilin prej tyre?

Gabimet e zakonshme

"Është prishur." Pa hapa, pa rezultat të pritur, pa asgjë për të vepruar.
Disa gabime në një raport. Disa rregullohen, të tjerët humbasin.
Gabime të parafrazuara. "Diçka undefined" fsheh pjesën e dobishme.
Mungesa e përdoruesit ose rolit. Shumë gabime prekin vetëm adminët, ose vetëm përdoruesit e rinj.
Përshkrimi vetëm i rregullimit që do ("shto një kontroll null") në vend të problemit.
Ndarja e sekreteve në pamje ekrani ose regjistra të ngjitur.

Lista kontrolluese

E riprodhova gabimin dhe gjeta hapat më të shkurtër.
Titulli thotë çfarë është e gabuar dhe ku.
Hapat janë të numëruar dhe të saktë.
Përshkruhen si pritet ashtu edhe ajo që ndodh.
Mesazhet e gabimit janë kopjuar saktë, me çdo kërkesë që dështoi dhe kodin e statusit.
Përfshihen faqja, mjedisi, përdoruesi, pajisja dhe shfletuesi.
Kam thënë sa shpesh ndodh dhe kur filloi.
Një pamje ekrani ose regjistrim është bashkëngjitur, me të dhënat private të hequra.
Një gabim për raport.

Raportimi i gabimeve te agjenti i Mythex

Në një projekt Mythex, raporti është kërkesa. Disa veçori ndihmojnë:

Bashkëngjit një pamje ekrani të preview-it ose ekranit të gabimit — deri në 5 skedarë për mesazh.
/fix e drejton agjentin të rregullojë një gabim; modaliteti Plan e lë të hetojë përpara se të ndryshojë.
/test e bën agjentin të riprodhojë rrjedhat në vetë preview-in dhe të raportojë çfarë sheh.
Revert to this point anulon një rregullim që përkeqësoi gjërat.

Faqja e dokumentacionit korrigjimi me kërkesa përdor të njëjtën strukturë hapa / pritet / ndodh. Për ciklin e rregullimit dhe kontrollit përreth, shih si të përsëritësh ndryshimet në një aplikacion të ndërtuar me AI.

Pyetje

Çfarë duhet të përfshijë një raport gabimi?

Një titull specifik, hapat e saktë për riprodhimin e problemit, çfarë prisje, çfarë ndodhi në të vërtetë, çdo mesazh gabimi fjalë për fjalë, ku ndodhi (faqja, shfletuesi, pajisja, përdoruesi), dhe një pamje ekrani ose regjistrim nëse ndihmon.

Si shkruaj një raport gabimi për një builder aplikacionesh AI?

Përdor të njëjtën strukturë si për një zhvillues: hapat, rezultatin e pritur, atë aktual dhe gabimin e saktë. Shto çfarë nuk duhet të ndryshojë, dhe kërkoji të rregullojë dhe pastaj të verifikojë rregullimin. Kërkesat e paqarta si 'është prishur' çojnë në supozime.

Çfarë bëj nëse nuk mund ta riprodhoj gabimin?

Raporto gjithsesi, por thuaje këtë. Përfshi çfarë po bëje, orën kur ndodhi, llogarinë e përdoruesit dhe çdo gabim që pe. Shëno sa shpesh ndodh, për shembull një herë në dhjetë përpjekje, sepse gabimet e përsëritura shpesh tregojnë probleme kohe ose të dhënash.

A duhet të vendos disa gabime në një raport të vetëm?

Jo. Një gabim për raport, që secili të mund të rregullohet, testohet dhe mbyllet veçmas. Nëse mendon që dy probleme lidhen, thuaje këtë në secilin raport.