Jak napsat dobré hlášení chyby (pro AI nebo vývojáře)

Dobré hlášení chyby umožní komukoli jinému, vývojáři nebo AI, vidět stejný problém, jaký jste viděli vy, aniž by se musel na cokoli ptát. Potřebuje konkrétní název, přesné kroky k reprodukci, to, co jste očekávali, co se skutečně stalo, případnou chybovou hlášku zkopírovanou doslova a místo, kde k chybě došlo: která stránka, prohlížeč, zařízení a uživatel. Jedna chyba na jedno hlášení, a pokud pomůže, přiložte snímek obrazovky.

Většina chyb se pochopí déle, než opraví. Jasné hlášení odstraní část s pochopením. To platí ještě víc u AI nástrojů: AI se nemůže doptat, co jste mysleli tím „pokladna je divná“, takže hádá, a špatný odhad může rozbít něco dalšího.

Šablona

Zkopírujte a vyplňte:

Název: [Co je špatně, kde] — např. „Rezervační formulář odmítá časy po 18:00“

Kroky k reprodukci:
1. ...
2. ...
3. ...

Očekáváno: [co by se mělo stát]
Skutečnost: [co se stalo místo toho]

Chybová hláška: [přesný text, pokud nějaký je]
Kde: [stránka/URL, prohlížeč, zařízení, přihlášen jako který uživatel]
Jak často: [pokaždé / občas / jednou]
Snímek obrazovky nebo nahrávka: [přiložena]

Zbytek tohoto průvodce vysvětluje jednotlivé části.

Krok 1: Nejdřív chybu zreprodukujte

Před psaním se pokuste chybu vyvolat znovu. Zjistíte, které kroky jsou podstatné a jestli se to děje pokaždé.

• Začněte z čistého stavu: obnovte stránku, nebo se odhlaste a znovu přihlaste.
• Zapisujte každé kliknutí a každý text, který napíšete.
• Pokuste se najít nejkratší cestu, která chybu vyvolá.
• Zkuste jiný prohlížeč nebo účet. Pokud se to děje jen jednomu uživateli, je to velká nápověda.

Více k tomu najdete v článku jak ladit aplikaci vytvořenou pomocí AI.

Krok 2: Napište konkrétní název

Název má říkat, co je špatně a kde, aby ten, kdo prochází seznam, poznal, o kterou chybu jde.

Krok 3: Vypište přesné kroky

Číslujte je. Buďte doslovní: která stránka, které tlačítko, co jste napsali.

1. Přihlaste se jako zákazník (testovací účet: customer@example.com).
2. Přidejte „Startovací sadu“ do košíku.
3. Zadejte slevový kód WELCOME10 a klikněte na Použít.
4. Klikněte na Pokladna.

Napsat jen „zkuste zaplatit se slevou“ vynechá detaily, které často rozhodují: který uživatel, který produkt, který kód a jestli byl kód nejdřív uplatněn.

Krok 4: Očekávané vs. skutečné

Toto je jádro hlášení. Uveďte obojí, protože rozdíl mezi nimi je ta chyba.

• Očekáváno: Stránka pokladny se otevře s 10% slevou zobrazenou v celkové ceně.
• Skutečnost: Tlačítko na vteřinu ukáže točící se kruh a pak se nic nestane. Bez slevového kódu pokladna funguje.

Bez údaje „očekáváno“ nemusí čtenář poznat, že chování je špatně. Bez údaje „skutečnost“ neví, na co se má dívat.

Krok 5: Chyby kopírujte přesně

Chybové hlášky jsou nejrychlejší cesta k příčině. Kopírujte je jako text, slovo od slova, neparafrázujte.

Kde je najdete:

• Na obrazovce: jakákoli zpráva, kterou aplikace ukáže.
• Konzole prohlížeče: otevřete nástroje pro vývojáře (F12, nebo pravé tlačítko → Prozkoumat) a podívejte se na záložku Console na červené řádky.
• Záložka Network: v nástrojích pro vývojáře najděte neúspěšný požadavek a poznamenejte si jeho URL a stavový kód (například POST /api/checkout → 500).
• Serverové logy, pokud k nim máte přístup.

Řádek jako TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 často přímo ukáže na problém.

Krok 6: Přidejte kontext

• Kde: URL stránky, prostředí (náhled, staging nebo živá verze).
• Kdo: který uživatel nebo role — administrátor, člen, odhlášený.
• Zařízení a prohlížeč: „Safari na iPhonu“ oproti „Chrome na Windows“ může hrát roli.
• Data: cokoli neobvyklého na záznamu — velmi dlouhý text, speciální znaky, velký počet položek.
• Kdy to začalo: „po včerejší změně slevových kódů“ je zlato.
• Jak často: pokaždé, nebo jednou z deseti pokusů.

Krok 7: Ukažte to

Snímek obrazovky s vyznačeným problémem nebo krátká nahrávka obrazovky odstraní nejasnosti, zvlášť u chyb rozvržení. Pokud váš AI nástroj přijímá obrázky, přiložte jeden. Ořízněte vše soukromé, včetně klíčů a cizích dat.

Psaní hlášení pro AI tvůrce

Stejná struktura funguje i jako prompt. Pomohou dvě doplnění:

• Řekněte, co se nesmí změnit, aby oprava nezpůsobila nový problém.
• Požádejte o ověření opravy, ne jen o její napsání.

Přihlášen jako zákazník, se „Startovací sadou“ v košíku a uplatněným kódem WELCOME10, kliknutí na Pokladna nic neudělá. Očekáváno: stránka pokladny se otevře s 10% slevou na celkové ceně. Skutečnost: krátký točící se kruh a pak nic. Záložka network ukazuje, že POST /api/checkout vrátil 500. Pokladna bez kódu funguje. Najděte příčinu a opravte ji tak, aby se nezměnil výpočet cen u objednávek bez kódu. Potom ověřte pokladnu s procentuálním kódem, s kódem na pevnou částku a bez kódu.

Pokud si nejste jisti příčinou, požádejte nejdřív o diagnózu:

Zatím neměňte kód. Jaké jsou na základě tohoto hlášení pravděpodobné příčiny a co by potvrdilo každou z nich?

Časté chyby

• „Je to rozbité.“ Žádné kroky, žádný očekávaný výsledek, nic, s čím by se dalo pracovat.
• Více chyb v jednom hlášení. Některé se opraví, jiné se ztratí.
• Parafrázované chybové hlášky. „Nějaká undefined věc“ skryje to užitečné.
• Chybějící uživatel nebo role. Mnoho chyb se týká jen administrátorů nebo jen nových uživatelů.
• Popis jen požadované opravy („přidej kontrolu null“) místo problému.
• Sdílení tajných údajů na snímcích obrazovky nebo ve vložených logách.

Kontrolní seznam

• Chybu jsem zreprodukoval a našel nejkratší kroky.
• Název říká, co je špatně a kde.
• Kroky jsou očíslované a doslovné.
• Jsou uvedeny očekávaný i skutečný výsledek.
• Chybové hlášky jsou zkopírované přesně, s případným selhaným požadavkem a stavovým kódem.
• Jsou uvedeny stránka, prostředí, uživatel, zařízení a prohlížeč.
• Uvedl jsem, jak často se to děje a kdy to začalo.
• Snímek obrazovky nebo nahrávka je přiložena, soukromá data odstraněna.
• Jedna chyba na jedno hlášení.

Hlášení chyb agentovi Mythex

V projektu Mythex je hlášení samo promptem. Pomohou několik funkcí:

• Přiložte snímek obrazovky náhledu nebo chybové obrazovky — až 5 souborů na zprávu.
• /fix zaměří agenta na opravu chyby; režim Plan mu dovolí chybu nejdřív prozkoumat, než začne měnit kód.
• /test nechá agenta zreprodukovat postupy přímo v náhledu a nahlásit, co vidí.
• Revert to this point vrátí zpět opravu, která věci zhoršila.

Stránka ladění pomocí promptů v dokumentaci používá stejnou strukturu kroky / očekáváno / skutečnost. Smyčku oprava-a-ověření kolem toho popisuje článek jak iterovat na aplikaci vytvořené pomocí AI.

Otázky