Hogyan írj jó hibajelentést (AI-nak vagy fejlesztőnek)

Egy jó hibajelentés lehetővé teszi, hogy valaki más – egy fejlesztő vagy egy AI – lássa ugyanazt a problémát, amit te láttál, anélkül hogy bármit kérdezne tőled. Kell hozzá egy konkrét cím, a hiba újrateremtésének pontos lépései, az, amit vártál, az, ami ténylegesen történt, a hibaüzenet szó szerinti másolata, és az, hogy hol történt: melyik oldalon, böngészőben, eszközön és felhasználóval. Egy hiba legyen egy jelentésben, és ha segít, csatolj képernyőképet.

A legtöbb hibát tovább tart megérteni, mint kijavítani. Egy világos jelentés kiveszi a megértést a folyamatból. Az AI-eszközöknél ez még fontosabb: az AI nem tud visszakérdezni, mire gondoltál a „furcsa a fizetés” alatt, ezért találgat – és a rossz tipp más dolgot is elronthat.

A sablon

Másold ki, és töltsd ki:

Cím: [Mi a baj, és hol] – pl. „A foglalási űrlap 18 óra után is elutasítja az időpontokat”

Lépések a reprodukáláshoz:
1. ...
2. ...
3. ...

Várt: [mi kellene történjen]
Tényleges: [mi történt helyette]

Hibaüzenet: [pontos szöveg, ha van]
Hol: [oldal/URL, böngésző, eszköz, melyik felhasználóval bejelentkezve]
Milyen gyakran: [mindig / néha / egyszer]
Képernyőkép vagy felvétel: [csatolva]

Az útmutató többi része minden részt elmagyaráz.

1. lépés: Először próbáld újra előidézni

Mielőtt írnál, próbáld újra előidézni a hibát. Megtudod, mely lépések számítanak, és hogy mindig előfordul-e.

• Tiszta állapotból indulj: frissíts, vagy jelentkezz ki, majd be.
• Jegyezd le minden kattintást és minden begépelt dolgot.
• Keresd meg a legrövidebb utat, amely kiváltja.
• Próbálj második böngészőt vagy fiókot. Ha csak egy felhasználónál fordul elő, az nagy nyom.

Ezzel kapcsolatban lásd: hogyan hibakeress AI-val épített appot.

2. lépés: Írj konkrét címet

A címnek meg kell mondania, mi a baj és hol, hogy aki listát böngész, tudja, melyik hibáról van szó.

3. lépés: Sorold fel a pontos lépéseket

Számozd őket. Légy szó szerinti: melyik oldal, melyik gomb, mit gépeltél be.

1. Jelentkezz be ügyfélként (teszt-fiók: customer@example.com).
2. Tedd a „Starter kit” terméket a kosárba.
3. Add meg a WELCOME10 kedvezménykódot, és kattints az Alkalmaz gombra.
4. Kattints a Fizetés gombra.

Az, hogy „próbálj kóddal fizetni”, kihagyja a részleteket, amelyek gyakran számítanak: melyik felhasználó, melyik termék, melyik kód, és hogy előbb alkalmazták-e.

4. lépés: Várt és tényleges

Ez a jelentés magja. Mondd ki mindkettőt, mert a különbség maga a hiba.

• Várt: a fizetési oldal megnyílik, és az összegben látszik a 10%-os kedvezmény.
• Tényleges: a gomb egy másodpercig töltőképernyőt mutat, aztán semmi nem történik. Kedvezménykód nélkül a fizetés működik.

A „várt” nélkül az olvasó nem biztos, hogy tudja, hogy a viselkedés hibás. A „tényleges” nélkül pedig nem tudja, mit keressen.

5. lépés: Másold le pontosan a hibákat

A hibaüzenetek a leggyorsabb út az okhoz. Másold szövegként, szó szerint – ne fogalmazd át.

Hol találod őket:

• A képernyőn: bármilyen üzenet, amelyet az app megjelenít.
• A böngésző konzolján: nyisd meg a fejlesztői eszközöket (F12, vagy jobb klikk → Vizsgálat), és nézd a Konzol fület a piros sorokért.
• Hálózat fül: a fejlesztői eszközökben keresd meg a sikertelen kérést, és jegyezd fel az URL-jét és a státuszkódot (például POST /api/checkout → 500).
• Szerver-naplók, ha van hozzáférésed.

Az olyan sor, mint a TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48, gyakran pontosan a problémára mutat.

6. lépés: Adj kontextust

• Hol: az oldal URL-je, a környezet (előnézet, staging vagy éles).
• Ki: melyik felhasználó vagy szerep – admin, tag, kijelentkezett.
• Eszköz és böngésző: a „Safari iPhone-on” és a „Chrome Windowson” számíthat.
• Adatok: bármi szokatlan a rekordban – nagyon hosszú szöveg, speciális karakterek, sok elem.
• Mikor kezdődött: a „tegnapi kedvezménykód-változtatás után” aranyat ér.
• Milyen gyakran: mindig, vagy tízből egyszer.

7. lépés: Mutasd meg

A bekarikázott képernyőkép vagy egy rövid képernyőfelvétel megszünteti a kétértelműséget – különösen az elrendezési hibáknál. Ha az AI-eszközöd fogad képeket, csatolj egyet. Vágd ki a privát részeket, köztük a kulcsokat és mások adatait.

Hibajelentések írása AI-builderhez

Ugyanaz a szerkezet promptként is működik. Két kiegészítés segít:

• Mondd meg, mi ne változzon, hogy a javítás ne okozzon újabb problémát.
• Kérd meg, hogy ellenőrizze a javítást, ne csak írja meg.

Ügyfélként bejelentkezve, a „Starter kit” a kosárban és a WELCOME10 kód alkalmazva, a Fizetés gombra kattintva nem történik semmi. Várt: a fizetési oldal megnyílik 10%-os kedvezménnyel az összegből. Tényleges: rövid töltőképernyő, aztán semmi. A hálózati fülön a POST /api/checkout 500-zal tért vissza. Kód nélkül a fizetés működik. Keresd meg az okot és javítsd ki úgy, hogy ne változtasd meg az árkalkulációt kód nélküli rendeléseknél. Utána ellenőrizd a fizetést százalékos kóddal, fix összegű kóddal és kód nélkül.

Ha bizonytalan vagy az okban, kérj előbb diagnózist:

Még ne változtass a kódon. Ez a jelentés alapján melyek a valószínű okok, és mi igazolná mindegyiket?

Gyakori hibák

• „Elromlott.” Nincsenek lépések, nincs várt eredmény, nincs mire reagálni.
• Több hiba egy jelentésben. Némelyiket megjavítják, a többi elvész.
• Átfogalmazott hibaüzenetek. Az „valami undefined dolog” elrejti a hasznos részt.
• A felhasználó vagy a szerep hiánya. Sok hiba csak adminokat vagy csak új felhasználókat érint.
• Csak a kívánt javítás leírása („adj hozzá null-ellenőrzést”) a probléma helyett.
• Titkok megosztása képernyőképekben vagy beillesztett naplókban.

Ellenőrzőlista

• Újra előidéztem a hibát, és megtaláltam a legrövidebb lépéseket.
• A cím megmondja, mi a baj és hol.
• A lépések számozottak és szó szerintiek.
• Mind a várt, mind a tényleges eredmény le van írva.
• A hibaüzenetek pontosan vannak másolva, a sikertelen kéréssel és a státuszkóddal együtt.
• Benne van az oldal, a környezet, a felhasználó, az eszköz és a böngésző.
• Leírtam, milyen gyakran fordul elő, és mikor kezdődött.
• Képernyőkép vagy felvétel van csatolva, a privát adatok eltávolításával.
• Egy jelentés, egy hiba.

Hibajelentés a Mythex ágensének

A Mythex-projektben a jelentés maga a prompt. Néhány funkció segít:

• Csatolj képernyőképet az előnézetről vagy a hibaképernyőről – üzenetenként legfeljebb 5 fájl.
• A /fix a hiba javítására fókuszálja az ágenst; a Plan mód lehetővé teszi, hogy a szerkesztés előtt vizsgálódjon.
• A /test arra kéri az ágenst, hogy reprodukálja a folyamatokat magában az előnézetben, és jelentse, mit lát.
• A Visszaállítás erre a pontra visszavon egy javítást, amely rontott a helyzeten.

A dokumentáció promptokkal történő hibakeresés oldala ugyanazt a lépések / várt / tényleges szerkezetet használja. A köré épülő javítás-és-ellenőrzés körről lásd: hogyan iterálj AI-val épített appon.

Kérdések