Как написать хороший отчёт об ошибке (для ИИ или разработчика)

Хороший отчёт об ошибке позволяет другому человеку — разработчику или ИИ — увидеть ту же проблему, что видели вы, не задавая вам вопросов. Ему нужны конкретный заголовок, точные шаги для воспроизведения, что вы ожидали, что произошло на самом деле, текст любой ошибки, скопированный дословно, и место, где это случилось: какая страница, браузер, устройство и пользователь. Одна ошибка — один отчёт, со скриншотом, если он поможет.

Большинство ошибок дольше понять, чем исправить. Ясный отчёт снимает часть с пониманием. Это важно ещё больше при работе с ИИ-инструментами: ИИ не может задать уточняющий вопрос о том, что вы имели в виду под «оплата какая-то странная», поэтому он угадывает — а неверная догадка может сломать что-то ещё.

Шаблон

Скопируйте и заполните:

Заголовок: [Что не так, где] — например, «Форма записи отклоняет время после 18:00»

Шаги для воспроизведения:
1. ...
2. ...
3. ...

Ожидалось: [что должно было произойти]
Фактически: [что произошло вместо этого]

Текст ошибки: [точный текст, если есть]
Где: [страница/URL, браузер, устройство, вход под каким пользователем]
Как часто: [каждый раз / иногда / один раз]
Скриншот или запись: [приложены]

Остальная часть руководства объясняет каждый пункт.

Шаг 1: Сначала воспроизведите ошибку

Прежде чем писать, попробуйте вызвать ошибку снова. Вы поймёте, какие шаги важны и происходит ли она каждый раз.

Начните с чистого состояния: обновите страницу или выйдите и войдите снова.
Запишите каждый клик и всё, что вводили.
Постарайтесь найти самый короткий путь, который вызывает ошибку.
Попробуйте другой браузер или аккаунт. Если ошибка возникает только у одного пользователя, это важная подсказка.

Подробнее об этом см. как отлаживать приложение, созданное с помощью ИИ.

Шаг 2: Напишите конкретный заголовок

Заголовок должен говорить, что не так и где, чтобы тот, кто просматривает список, сразу понимал, о какой ошибке речь.

Слабо	Сильно
Оплата не работает	Кнопка оплаты ничего не делает, когда в корзине есть промокод
Проблема на мобильных	Карточки тарифов выходят за экран телефонов шире 400 пикселей
Ошибка при сохранении	Сохранение профиля с эмодзи в имени показывает «500 Internal Server Error»

Шаг 3: Перечислите точные шаги

Нумеруйте их. Будьте буквальны: какая страница, какая кнопка, что вы ввели.

Войдите как клиент (тестовый аккаунт: customer@example.com).
Добавьте «Стартовый набор» в корзину.
Введите промокод WELCOME10 и нажмите Применить.
Нажмите Оформить заказ.

«Попробуйте оформить заказ с кодом» пропускает детали, которые часто важны: какой пользователь, какой товар, какой код, был ли он сначала применён.

Шаг 4: Ожидаемое и фактическое

Это ядро отчёта. Укажите оба, потому что разница и есть ошибка.

Ожидалось: страница оформления открывается с учётом скидки 10% в итоговой сумме.
Фактически: кнопка на секунду показывает спиннер, а затем ничего не происходит. Без промокода оформление работает.

Без «ожидалось» читатель может не знать, что поведение неверно. Без «фактически» он не знает, что искать.

Шаг 5: Копируйте ошибки точно

Текст ошибки — самый быстрый путь к причине. Копируйте его как текст, дословно, не перефразируя.

Где их найти:

На экране: любое сообщение, которое показывает приложение.
Консоль браузера: откройте инструменты разработчика (F12 или правый клик → «Просмотреть код») и посмотрите вкладку 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: Покажите проблему

Скриншот с обведённой проблемой или короткая запись экрана устраняет двусмысленность — особенно для ошибок вёрстки. Если ваш ИИ-инструмент принимает изображения, прикрепите одно. Обрежьте всё личное, включая ключи и данные других людей.

Как писать отчёты об ошибках для конструктора с ИИ

Та же структура работает как промпт. Два дополнения помогают:

Скажите, что нельзя менять, чтобы исправление не вызвало новую проблему.
Попросите проверить исправление, а не только написать его.

Вошедший как клиент, с «Стартовым набором» в корзине и применённым кодом WELCOME10, при нажатии Оформить заказ ничего не происходит. Ожидалось: страница оформления открывается со скидкой 10% от итога. Фактически: короткий спиннер, затем ничего. На вкладке Network видно, что POST /api/checkout вернул 500. Оформление без кода работает. Найди причину и исправь её, не меняя расчёт цен для заказов без кода. Затем проверь оформление с процентным кодом, кодом с фиксированной суммой и без кода.

Если не уверены в причине, сначала попросите диагноз:

Пока не меняй код. Исходя из этого отчёта, какие вероятные причины и что подтвердит каждую из них?

Частые ошибки

«Всё сломано». Нет шагов, нет ожидаемого результата, не на что опереться.
Несколько ошибок в одном отчёте. Некоторые исправят, другие потеряются.
Перефразированные ошибки. «Какой-то undefined» прячет полезную часть.
Не указан пользователь или роль. Многие ошибки касаются только администраторов или только новых пользователей.
Описание только желаемого исправления («добавь проверку на null») вместо проблемы.
Передача секретов в скриншотах или вставленных логах.

Чек-лист

Я воспроизвёл ошибку и нашёл самые короткие шаги.
В заголовке сказано, что не так и где.
Шаги пронумерованы и буквальны.
Указаны и ожидаемое, и фактическое.
Тексты ошибок скопированы точно, включая неудавшийся запрос и код статуса.
Указаны страница, окружение, пользователь, устройство и браузер.
Я написал, как часто это происходит и когда началось.
Прикреплён скриншот или запись без личных данных.
Одна ошибка — один отчёт.

Сообщение об ошибках агенту Mythex

В проекте Mythex сам отчёт и есть промпт. Несколько функций помогают:

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

Страница документации отладка с помощью промптов использует ту же структуру «шаги / ожидалось / фактически». О цикле исправления и проверки см. как итеративно дорабатывать приложение, созданное с помощью ИИ.

Вопросы

Что должно быть в отчёте об ошибке?

Конкретный заголовок, точные шаги для воспроизведения проблемы, что вы ожидали, что произошло на самом деле, текст любой ошибки дословно, где это произошло (страница, браузер, устройство, пользователь), а также скриншот или запись, если они помогут.

Как написать отчёт об ошибке для конструктора приложений с ИИ?

Используйте ту же структуру, что и для разработчика: шаги, ожидаемый результат, фактический результат и точный текст ошибки. Добавьте, что нельзя менять, и попросите исправить, а затем проверить исправление. Расплывчатые запросы вроде «всё сломано» приводят к догадкам.

Что делать, если не получается воспроизвести ошибку?

Всё равно сообщите о ней, но укажите это. Опишите, что вы делали, во сколько это произошло, какой аккаунт пользователя использовали и какую ошибку видели. Отметьте, как часто это случается, например один раз из десяти попыток, поскольку периодические ошибки часто указывают на проблемы с таймингом или данными.

Нужно ли объединять несколько ошибок в один отчёт?

Нет. Одна ошибка — один отчёт, чтобы каждую можно было исправить, проверить и закрыть отдельно. Если вы считаете, что две проблемы связаны, укажите это в каждом отчёте.