Как да напишете добър доклад за грешка (за ИИ или разработчик)

Добрият доклад за грешка позволява на някой друг — разработчик или ИИ — да види същия проблем, който видяхте вие, без да ви задава въпроси. Той има нужда от конкретно заглавие, точните стъпки за възпроизвеждане, какво сте очаквали, какво се случи всъщност, всяко съобщение за грешка, копирано дума по дума, и къде се случи: коя страница, браузър, устройство и потребител. Една грешка на доклад, със снимка на екрана, ако помага.

Повечето грешки отнемат повече време за разбиране, отколкото за поправка. Ясният доклад премахва частта с разбирането. Това е още по-важно при инструментите с ИИ: ИИ не може да зададе допълнителен въпрос за това какво сте имали предвид с „плащането е странно“, затова налага догадка — а грешната догадка може да счупи друго нещо.

Шаблонът

Копирайте го и попълнете:

Заглавие: [Какво не е наред, къде] — напр. „Формата за резервации отхвърля часове след 18:00“

Стъпки за възпроизвеждане:
1. ...
2. ...
3. ...

Очаквано: [какво трябва да се случи]
Реално: [какво се случи вместо това]

Съобщение за грешка: [точният текст, ако има]
Къде: [страница/URL, браузър, устройство, влязъл като кой потребител]
Колко често: [всеки път / понякога / веднъж]
Снимка или запис: [приложени]

Останалата част от ръководството обяснява всяка част.

Стъпка 1: Първо възпроизведете грешката

Преди да пишете, опитайте да предизвикате грешката отново. Ще разберете кои стъпки са важни и дали се случва всеки път.

• Започнете от чисто състояние: презаредете или излезте и влезте отново.
• Отбележете всяко кликване и всяко нещо, което въвеждате.
• Опитайте да намерите най-краткия път, който я предизвиква.
• Пробвайте втори браузър или акаунт. Ако се случва само за един потребител, това е голяма следа.

За повече по темата вижте как да откриете грешки в приложение, създадено с ИИ.

Стъпка 2: Напишете конкретно заглавие

Заглавието трябва да казва какво не е наред и къде, за да може някой, който преглежда списък, да разбере коя грешка е.

Стъпка 3: Изброете точните стъпки

Номерирайте ги. Бъдете буквални: коя страница, кой бутон, какво сте въвели.

1. Влезте като клиент (тестов акаунт: customer@example.com).
2. Добавете „Starter kit“ в количката.
3. Въведете промо кода WELCOME10 и натиснете Apply.
4. Натиснете Checkout.

„Пробвай да платиш с код“ пропуска подробностите, които често са важни: кой потребител, кой продукт, кой код, дали първо е приложен.

Стъпка 4: Очаквано срещу реално

Това е сърцевината на доклада. Посочете и двете, защото разликата е самата грешка.

• Очаквано: страницата за плащане се отваря с показана 10% отстъпка в общата сума.
• Реално: бутонът показва въртящ се индикатор за секунда, после нищо не се случва. Без промо код плащането работи.

Без „очаквано“ четящият може да не знае, че поведението е грешно. Без „реално“ не знае какво да търси.

Стъпка 5: Копирайте грешките точно

Съобщенията за грешка са най-бързият път до причината. Копирайте ги като текст, дума по дума — не ги преразказвайте.

Къде да ги намерите:

• На екрана: всяко съобщение, което приложението показва.
• Конзолата на браузъра: отворете инструментите за разработчици (F12 или десен клик → Inspect) и погледнете раздела Console за червени редове.
• Раздела Network: в инструментите за разработчици намерете неуспешната заявка и отбележете URL-а и кода на състоянието (например POST /api/checkout → 500).
• Сървърните логове, ако имате достъп.

Ред като TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 често сочи право към проблема.

Стъпка 6: Добавете контекст

• Къде: URL на страницата, средата (преглед, стейджинг или на живо).
• Кой: кой потребител или роля — администратор, член, неизлязъл.
• Устройство и браузър: „Safari на iPhone“ срещу „Chrome на Windows“ може да има значение.
• Данни: нещо необичайно в записа — много дълъг текст, специални знаци, голям брой елементи.
• Кога започна: „след вчерашната промяна в промо кодовете“ е ценна информация.
• Колко често: всеки път или веднъж от десет опита.

Стъпка 7: Покажете го

Снимка на екрана с обиколен проблем или кратък запис на екрана премахва двусмислието — особено при грешки в оформлението. Ако инструментът ви с ИИ приема изображения, прикачете една. Изрежете всичко лично, включително ключове и данни на други хора.

Писане на доклади за грешки към инструмент с ИИ

Същата структура работи и като подканва. Две допълнения помагат:

• Кажете какво не бива да се променя, за да не създаде поправката нов проблем.
• Помолете да провери поправката, не само да я напише.

Влязъл като клиент, със „Starter kit“ в количката и приложен код WELCOME10, натискането на Checkout не прави нищо. Очаквано: страницата за плащане се отваря с 10% отстъпка от общата сума. Реално: кратък индикатор, после нищо. Раздел Network показва, че POST /api/checkout върна 500. Плащане без код работи. Намери причината и я поправи, без да променяш как се изчисляват цените за поръчки без код. После провери плащане с процентен код, код с фиксирана сума и без код.

Ако не сте сигурни каква е причината, първо поискайте диагноза:

Още не променяй кода. Въз основа на този доклад, кои са вероятните причини и какво би потвърдило всяка от тях?

Честите грешки

• „Счупено е.“ Без стъпки, без очакван резултат, нищо за действие.
• Няколко грешки в един доклад. Някои се оправят, други се губят.
• Преразказани грешки. „Някакъв undefined“ скрива полезната част.
• Липсващ потребител или роля. Много грешки засягат само администраторите или само нови потребители.
• Описание само на желаната поправка („добави проверка за null“) вместо на проблема.
• Споделяне на тайни данни в снимки на екрана или поставени логове.

Контролен списък

• Възпроизведох грешката и намерих най-кратките стъпки.
• Заглавието казва какво не е наред и къде.
• Стъпките са номерирани и буквални.
• Посочени са и очакваното, и реалното.
• Съобщенията за грешка са копирани точно, с неуспешната заявка и кода на състоянието.
• Включени са страница, среда, потребител, устройство и браузър.
• Казал съм колко често се случва и кога е започнало.
• Приложена е снимка или запис, с премахнати лични данни.
• Една грешка на доклад.

Докладване на грешки към агента на Mythex

В проект на Mythex докладът е подканата. Няколко функции помагат:

• Прикачете снимка на екрана на прегледа или на екрана с грешка — до 5 файла на съобщение.
• /fix насочва агента към поправка на грешка; режимът Plan му позволява да проучи, преди да редактира.
• /test кара агента да възпроизведе потоците в самия преглед и да докладва какво вижда.
• Върни към тази точка отменя поправка, която е влошила нещата.

Страницата в документацията отстраняване на грешки с подканвания използва същата структура стъпки / очаквано / реално. За цикъла поправка-и-проверка около нея вижте как да итерирате приложение, създадено с ИИ.

Въпроси