Як написати хороший звіт про помилку (для ШІ або розробника)

Добрий звіт про помилку дає змогу іншій людині — розробнику або ШІ — побачити ту саму проблему, яку побачили ви, і не ставити жодних додаткових запитань. Йому потрібні конкретний заголовок, точні кроки для відтворення, очікуваний результат, фактичний результат, текст помилки, скопійований дослівно, і місце, де це сталося: яка сторінка, браузер, пристрій і користувач. Одна помилка на звіт, а за потреби — скріншот.

Більшість помилок займає більше часу на розуміння, ніж на виправлення. Зрозумілий звіт прибирає частину з розумінням. З інструментами ШІ це важить ще більше: ШІ не може поставити уточнювальне запитання про те, що ви мали на увазі під словами «оплата якась дивна», тож він здогадується — а хибна здогадка може зламати щось інше.

Шаблон

Скопіюйте й заповніть:

Title: [Що не так, де] — наприклад, «Форма бронювання відхиляє час після 18:00»

Steps to reproduce:
1. ...
2. ...
3. ...

Expected: [що має статися]
Actual: [що сталося натомість]

Error message: [точний текст, якщо є]
Where: [сторінка/URL, браузер, пристрій, під яким користувачем]
How often: [щоразу / іноді / один раз]
Screenshot or recording: [додано]

Решта посібника пояснює кожну частину.

Крок 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 змушує агента відтворити потоки прямо в попередньому перегляді та повідомити, що він бачить.
• Revert to this point скасовує виправлення, яке погіршило ситуацію.

Сторінка документації налагодження за допомогою промптів використовує ту саму структуру «кроки / очікувано / фактично». Про цикл виправлення й перевірки див. як ітерувати застосунок, створений ШІ.

Запитання