Как описать ошибку разработчику: шаблон баг-репорта и помощь ИИ

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

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

Что такое баг-репорт и чем он отличается от просьбы о новой функции

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

Разница важна для маршрута. Дефект проверяют относительно уже обещанного поведения, а идею оценивают по ценности, стоимости и ограничениям. Если в одной заявке смешать падение формы, просьбу поменять цвет и предложение добавить оплату, её нельзя нормально проверить и закрыть. Правило простое: одна задача — одна наблюдаемая проблема. Соседние пожелания вынесите отдельно.

Что собрать до написания отчёта

Сначала остановитесь и сохраните состояние. Не перезагружайте страницу десять раз и не очищайте данные приложения, пока не записали, что произошло: после таких действий ошибка может исчезнуть вместе с доказательствами. Если сбой затрагивает деньги, публикацию, удаление или доступ к аккаунту, отдельно зафиксируйте номер операции, время с часовым поясом и безопасный идентификатор объекта.

• Место: адрес страницы, название раздела, экран приложения или команда бота.
• Время: дата, часы и минуты с часовым поясом — например, 12 октября 2026 года, 14:32 МСК.
• Начальное состояние: пользователь вошёл или нет, какой объект открыт, какие фильтры выбраны.
• Последовательность: каждое нажатие от известной точки до сбоя.
• Результат: точный текст сообщения, неверное число, пустой экран или другое наблюдаемое поведение.
• Окружение: устройство, ОС, браузер или версия приложения, тип сети.
• Масштаб: один пользователь или несколько, один объект или все, каждый раз или иногда.

Рекомендации Chromium по сообщениям об ошибках требуют краткого описания проблемы, подробных шагов воспроизведения, ожидаемого поведения и полезных снимков; для проблем совместимости нужен адрес страницы. Это хороший минимальный набор и для обычной коммерческой разработки. Если проблема касается отдельного URL, сначала убедитесь, что перед вами не обычная ошибка 404 из-за неверного адреса.

Как написать заголовок баг-репорта

Заголовок должен отличать проблему от сотни соседних задач. Формула: где + при каком действии + что происходит. Причину туда не добавляют, пока она не доказана. «База сломалась» — догадка; «в корзине после изменения количества итоговая сумма остаётся прежней» — наблюдение.

Не вставляйте в заголовок весь сценарий, номер телефона клиента или длинный текст исключения. Заголовок помогает найти и сгруппировать задачу; детали живут в полях ниже. Перед созданием проверьте поиск по трекеру: возможно, такой дефект уже зарегистрирован. Тогда полезнее добавить к существующей задаче своё окружение и новый пример, чем создавать дубль.

Как записать шаги воспроизведения

Шаги начинаются с состояния, которое может получить другой человек. «Открыть форму» недостаточно, если форм несколько; «ввести данные» недостаточно, если ошибка зависит от значения. Указывайте тестовые данные или их безопасный эквивалент. Один пункт — одно действие, без скачков вроде «создать заказ и оплатить».

1. Открыть страницу `/checkout` в Chrome 128 на Windows 11.
2. Войти тестовым покупателем без сохранённой карты.
3. Добавить один товар стоимостью 1 500 ₽ и перейти в корзину.
4. Выбрать доставку курьером и способ оплаты СБП.
5. Нажать «Оплатить» один раз.
6. Подождать 15 секунд, не обновляя страницу.
7. Зафиксировать, появился ли QR-код и изменился ли адрес страницы.

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

Не превращайте отчёт в инструкцию на пять экранов, если сбой удаётся сократить. Chromium советует по возможности приложить упрощённый тест. Для бизнеса это означает убрать лишние действия: если ошибка возникает без промокода, не включайте промокод в сценарий. Чем короче подтверждённый путь, тем легче найти границу дефекта.

Как разделить ожидаемый и фактический результат

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

Если ожидание основано только на вашем предположении, так и напишите: «Ожидал, потому что кнопка называется “Сохранить”». Разработчик сможет отличить техническую ошибку от спорного требования. Для сайта полезно приложить данные из Яндекс Вебмастера, если проблема связана с обходом, индексированием или кодом ответа, но не подменять ими воспроизведение в браузере.

Как указать окружение и масштаб проблемы

Окружение отвечает на вопрос «где именно это произошло». Для веб-сайта обычно достаточно системы, браузера с версией, адреса страницы, типа аккаунта и наличия расширений, VPN или блокировщика. Для мобильного приложения добавьте модель устройства, версию ОС, версию приложения и сеть. Для интеграции — название системы, среду, endpoint, безопасный идентификатор запроса и время.

• Веб: macOS 15.6, Safari 19.0, авторизованный администратор, приватное окно — работает, обычное — нет.
• Приложение: Android 16, версия 4.12.1, Wi-Fi; на мобильной сети результат тот же.
• API: production, `POST /orders`, статус 500, request ID `req_test_4821`, тело запроса обезличено.
• Контент: ошибка только у записей с длинным заголовком и не повторяется на коротком тестовом тексте.

Проверки на другом браузере, устройстве или аккаунте не обязательны пользователю поддержки, но резко сужают поиск. Сначала меняйте один фактор. Если одновременно сменить браузер, сеть и аккаунт, станет непонятно, что повлияло. Результат каждой проверки записывайте одной строкой: «Firefox 131 — повторяется», «гостевой режим — не повторяется».

Какие скриншоты, видео и логи приложить

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

Лог или консоль прикладывают текстом либо файлом, а не фотографией монитора: тогда по сообщению можно искать. Оставьте несколько строк до и после события, время, уровень ошибки и correlation/request ID. Не отправляйте гигабайтный журнал целиком, если известна минута сбоя. Разработчик попросит расширенный диапазон, если он понадобится.

Перед отправкой проверьте вложения. Руководство OWASP по журналированию рекомендует удалять, маскировать или защищать идентификаторы сессий, токены доступа, пароли, строки подключения, ключи, платёжные и чувствительные персональные данные. Тот же принцип действует для скриншотов: закройте номера телефонов, адреса, документы и чужую переписку. Пошаговый способ подготовить файл разобран в статье об обезличивании документов, а защита аккаунтов — в материале о двухфакторной аутентификации.

Готовый шаблон баг-репорта

Скопируйте блок и заполните только известные поля. Неизвестное пометьте «не проверял», а не угадывайте. Приоритет и исполнителя лучше назначает человек, который видит влияние на бизнес и загрузку команды.

Заголовок: [экран] + [действие] + [неверный результат]

Где произошло:
URL или раздел:
Дата и время с часовым поясом:
Окружение: устройство, ОС, браузер/версия приложения, тип аккаунта

Предусловия:
1. …

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

Ожидаемый результат:
…

Фактический результат:
…

Повторяемость:
… попыток из …

Масштаб и влияние:
Кого затрагивает:
Есть ли обходной путь:

Вложения:
скриншот/видео, безопасный фрагмент лога, request ID

Что уже проверено:
…

В GitHub Issue Forms эти части можно превратить в обязательные поля: текущее и ожидаемое поведение, шаги, окружение и вложения. Форма полезна, когда команда снова и снова задаёт одни вопросы. Но обязательность должна быть разумной: посетителю интернет-магазина незачем узнавать версию Node.js, а внутреннему разработчику она может быть критична.

Как нейросеть помогает оформить ошибку

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

Ты — редактор баг-репорта. Преобразуй мои заметки в структуру: заголовок, предусловия, шаги, ожидалось, получилось, окружение, повторяемость, влияние, вложения, что проверить дополнительно. Не придумывай факты и причину ошибки. Если данных не хватает, поставь пометку «нужно уточнить» и после отчёта задай не больше пяти конкретных вопросов. Удали эмоциональные оценки, но сохрани точные сообщения системы. Вот обезличенные заметки: [вставьте текст].

После ответа сравните каждое утверждение с исходными заметками. Нейросеть способна незаметно заменить «два раза из пяти» на «ошибка повторяется стабильно», назвать предполагаемую причину установленной или придумать шаг между действиями. Такая гладкость вреднее неровного текста. Подход к проверке утверждений разобран в статье о фактчекинге. Если отчёты собирает автоматический ИИ-агент, разрешите ему читать только необходимые поля и оставьте отправку человеку.

Как определить влияние без спора о приоритете

Автор отчёта описывает влияние, а не требует метку «критично» заглавными буквами. Укажите, какая операция заблокирована, сколько известных пользователей затронуто, есть ли обходной путь, теряются ли деньги или данные и когда наступает крайний срок. Команда уже сопоставит ущерб с другими задачами.

Если речь идёт о безопасности, не публикуйте доказательства в общем трекере и не проверяйте уязвимость на чужих данных. Используйте закрытый канал, указанный владельцем продукта. Пароль, код подтверждения или токен не становятся допустимым вложением даже при высоком приоритете.

Пример: превращаем «форма не работает» в задачу

Исходное сообщение: «На сайте опять всё сломалось, форма не работает, срочно почините». Из него неизвестно, какая форма, что сделал человек и что увидел. После короткого воспроизведения получается заявка:

Заголовок: в форме обратного звонка отправка номера с пробелами возвращает пустую ошибку

Где: `/callback`, 12 октября 2026 года, 15:18 МСК
Окружение: iPhone 16, iOS 20.0, Safari; новый посетитель

Шаги:
1. Открыть форму обратного звонка.
2. Ввести тестовый номер в формате `+7 900 000 00 00`.
3. Оставить имя пустым — поле помечено как необязательное.
4. Нажать «Отправить».

Ожидалось: появляется подтверждение, заявка видна менеджеру.
Получилось: кнопка гаснет на секунду, под полем появляется пустая красная строка, заявки нет.
Повторяемость: 4 из 4; без пробелов номер отправляется.
Влияние: посетитель не понимает причину отказа; обход — удалить пробелы.
Вложения: 18-секундная запись экрана, время события, request ID из ответа поддержки.

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

Частые ошибки при описании дефекта

• Сразу объяснять причину. «Сервер не принимает запрос» может оказаться блокировщиком в браузере. Сначала опишите наблюдение.
• Смешивать несколько проблем. Нельзя проверить задачу, где одновременно не открывается меню, неверна цена и нужна новая кнопка.
• Пропускать исходное состояние. Роль, авторизация, выбранный объект и данные часто определяют результат.
• Писать шаги по памяти через день. Записывайте во время повторения и отмечайте, если порядок не подтверждён.
• Присылать только скриншот. Картинка показывает результат, но не путь к нему.
• Отправлять секреты. Пароли, cookie, токены и персональные данные удаляют до загрузки в трекер или нейросеть.
• Считать исправлением исчезновение ошибки. После ответа разработчика повторите те же шаги и пограничные варианты.
• Оценивать человека вместо продукта. Формулировка «разработчик опять сломал» не добавляет данных и мешает совместной проверке.

Чек-лист перед отправкой