Ako napísať dobré hlásenie chyby (pre AI alebo vývojára)

Dobré hlásenie chyby umožní niekomu inému — vývojárovi alebo AI — vidieť ten istý problém, aký ste videli vy, bez toho, aby sa musel na čokoľvek pýtať. Potrebuje konkrétny názov, presné kroky na zopakovanie, čo ste očakávali, čo sa skutočne stalo, každú chybovú správu skopírovanú slovo po slove a to, kde sa to stalo: na ktorej stránke, v akom prehliadači, na akom zariadení a u akého používateľa. Jedna chyba na jedno hlásenie, a ak pomôže, aj snímka obrazovky.

Väčšinu chýb je dlhšie pochopiť než opraviť. Jasné hlásenie odstráni časť s pochopením. To platí ešte viac pri nástrojoch s AI: AI sa nedokáže spýtať, čo ste mysleli pod „pokladňa je divná“, takže tipuje — a zlý odhad môže pokaziť niečo iné.

Šablóna

Skopírujte ju a vyplňte:

Názov: [Čo nie je v poriadku, kde] — napr. „Formulár rezervácie odmieta časy po 18:00“

Kroky na zopakovanie:
1. ...
2. ...
3. ...

Očakávané: [čo by sa malo stať]
Skutočné: [čo sa stalo namiesto toho]

Chybová správa: [presný text, ak nejaký je]
Kde: [stránka/URL, prehliadač, zariadenie, prihlásený ako ktorý používateľ]
Ako často: [zakaždým / niekedy / raz]
Snímka alebo nahrávka: [priložená]

Zvyšok tohto sprievodcu vysvetľuje každú časť.

Krok 1: Najprv to zopakujte

Skôr než začnete písať, skúste chybu vyvolať znova. Zistíte, ktoré kroky sú dôležité a či sa to stáva zakaždým.

Začnite z čistého stavu: obnovte stránku alebo sa odhláste a znova prihláste.
Zapisujte každé kliknutie a každý text, ktorý napíšete.
Hľadajte najkratšiu cestu, ktorá chybu spustí.
Skúste iný prehliadač alebo účet. Ak sa to deje len jednému používateľovi, je to veľká stopa.

Viac na túto tému nájdete v ako ladiť aplikáciu vytvorenú AI.

Krok 2: Napíšte konkrétny názov

Názov má povedať, čo nie je v poriadku a kde, aby niekto pri prechádzaní zoznamu vedel, o ktorú chybu ide.

Slabý	Silný
Pokladňa nefunguje	Tlačidlo pokladne nič neurobí, keď je v košíku zľavový kód
Problém na mobile	Karty cien pretekajú cez obrazovku na telefónoch užších ako 400 px
Chyba pri uložení	Uloženie profilu s emoji v mene zobrazí „500 Internal Server Error“

Krok 3: Vypíšte presné kroky

Číslujte ich. Buďte doslovní: ktorá stránka, ktoré tlačidlo, čo ste napísali.

Prihláste sa ako zákazník (testovací účet: customer@example.com).
Pridajte „Starter kit“ do košíka.
Zadajte zľavový kód WELCOME10 a kliknite na Použiť.
Kliknite na Pokladňa.

„Skús sa objednať so zľavovým kódom“ vynecháva podrobnosti, ktoré často rozhodujú: ktorý používateľ, ktorý produkt, ktorý kód a či sa kód najprv uplatnil.

Krok 4: Očakávané verzus skutočné

Toto je jadro hlásenia. Uveďte oboje, pretože rozdiel je práve chyba.

Očakávané: Stránka pokladne sa otvorí so zľavou 10 % zobrazenou v sume.
Skutočné: Tlačidlo na sekundu ukáže točiace sa koliesko a potom sa nestane nič. Bez zľavového kódu pokladňa funguje.

Bez „očakávaného“ čitateľ nemusí vedieť, že správanie je zlé. Bez „skutočného“ nevie, čo má hľadať.

Krok 5: Chyby kopírujte presne

Chybové správy sú najrýchlejšou cestou k príčine. Kopírujte ich ako text, slovo po slove — nič neparafrázujte.

Kde ich nájsť:

Na obrazovke: každá správa, ktorú aplikácia zobrazí.
Konzola prehliadača: otvorte nástroje pre vývojárov (F12 alebo pravé tlačidlo → Preskúmať) a pozrite sa na záložku Console na červené riadky.
Záložka Network: v nástrojoch pre vývojárov nájdite zlyhanú požiadavku a poznačte si jej URL a stavový kód (napríklad POST /api/checkout → 500).
Serverové logy, ak k nim máte prístup.

Riadok ako TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 často priamo ukáže na problém.

Krok 6: Pridajte kontext

Kde: URL stránky, prostredie (náhľad, staging alebo produkcia).
Kto: ktorý používateľ alebo rola — admin, člen, odhlásený.
Zariadenie a prehliadač: „Safari na iPhone“ oproti „Chrome na Windows“ môže byť dôležité.
Dáta: čokoľvek nezvyčajné na zázname — veľmi dlhý text, špeciálne znaky, veľa položiek.
Kedy to začalo: „po včerajšej zmene zľavových kódov“ je zlato.
Ako často: zakaždým alebo raz z desiatich pokusov.

Krok 7: Ukážte to

Snímka obrazovky s označeným problémom alebo krátka nahrávka obrazovky odstráni nejasnosti — najmä pri chybách rozloženia. Ak váš AI nástroj prijíma obrázky, pripojte jeden. Orežte všetko súkromné vrátane kľúčov a dát iných ľudí.

Písanie hlásení chýb pre AI builder

Rovnaká štruktúra funguje aj ako zadanie. Dva doplnky pomáhajú:

Povedzte, čo sa nesmie zmeniť, aby oprava nespôsobila nový problém.
Požiadajte o overenie opravy, nie len o jej napísanie.

Prihlásený ako zákazník, s „Starter kit“ v košíku a uplatneným kódom WELCOME10, kliknutie na Pokladňa nič neurobí. Očakávané: stránka pokladne sa otvorí so zľavou 10 % z celkovej sumy. Skutočné: krátke točenie kolieska, potom nič. Záložka network ukazuje, že POST /api/checkout vrátil 500. Pokladňa bez kódu funguje. Nájdi príčinu a oprav ju bez zmeny výpočtu cien pre objednávky bez kódu. Potom over pokladňu s percentuálnym kódom, kódom s pevnou sumou a bez kódu.

Ak si nie ste istí príčinou, najprv si vyžiadajte diagnózu:

Zatiaľ kód nemeň. Podľa tohto hlásenia, aké sú pravdepodobné príčiny a čo by potvrdilo každú z nich?

Časté chyby

„Je to rozbité.“ Žiadne kroky, žiadny očakávaný výsledok, nič na konanie.
Viac chýb v jednom hlásení. Niektoré sa opravia, iné sa stratia.
Parafrázované chyby. „Nejaká undefined vec“ skryje užitočnú časť.
Chýbajúci používateľ alebo rola. Mnohé chyby ovplyvnia len adminov alebo len nových používateľov.
Opisovanie len opravy, ktorú chcete („pridaj kontrolu null“) namiesto problému.
Zdieľanie tajomstiev na snímkach obrazovky alebo vložených logoch.

Kontrolný zoznam

Chybu som zopakoval a našiel najkratšie kroky.
Názov hovorí, čo nie je v poriadku a kde.
Kroky sú očíslované a doslovné.
Sú uvedené očakávané aj skutočné správanie.
Chybové správy sú skopírované presne, vrátane zlyhanej požiadavky a stavového kódu.
Sú uvedené stránka, prostredie, používateľ, zariadenie a prehliadač.
Uviedol som, ako často sa to deje a kedy to začalo.
Je priložená snímka alebo nahrávka so odstránenými súkromnými dátami.
Jedna chyba na jedno hlásenie.

Hlásenie chýb agentovi Mythex

V projekte Mythex je hlásenie samo zadaním. Pomáha niekoľko funkcií:

Pripojte snímku náhľadu alebo obrazovky s chybou — až 5 súborov na správu.
/fix nasmeruje agenta na opravu chyby; režim Plan mu umožní problém preskúmať skôr, než začne upravovať.
/test nechá agenta zopakovať toky priamo v náhľade a nahlásiť, čo vidí.
Vrátiť na tento bod vráti späť opravu, ktorá veci zhoršila.

Stránka dokumentácie ladenie pomocou promptov používa rovnakú štruktúru kroky / očakávané / skutočné. Slučku oprava-a-kontrola okolo nej nájdete v ako iterovať na aplikácii vytvorenej AI.

Otázky

Čo má obsahovať hlásenie chyby?

Konkrétny názov, presné kroky na zopakovanie problému, čo ste očakávali, čo sa skutočne stalo, každú chybovú správu doslova, kde sa to stalo (stránka, prehliadač, zariadenie, používateľ) a snímku obrazovky alebo nahrávku, ak pomôže.

Ako napísať hlásenie chyby pre AI builder?

Použite rovnakú štruktúru ako pre vývojára: kroky, očakávaný a skutočný výsledok a presnú chybu. Pridajte, čo sa nesmie zmeniť, a požiadajte ho, aby chybu opravil a potom aj overil opravu. Vágne zadania typu „je to rozbité“ vedú k dohadom.

Čo ak sa chybu nedarí zopakovať?

Nahláste ju aj tak, ale uveďte to. Napíšte, čo ste robili, kedy sa to stalo, s akým používateľským účtom a akú chybu ste videli. Poznačte, ako často sa to deje, napríklad raz z desiatich pokusov, pretože občasné chyby často súvisia s načasovaním alebo dátami.

Mám do jedného hlásenia dať viac chýb?

Nie. Jedna chyba na jedno hlásenie, aby sa dala opraviť, otestovať a uzavrieť samostatne. Ak si myslíte, že spolu súvisia dva problémy, napíšte to do každého hlásenia.