Баг: воспроизвести, починить, закрепить тестом

У агента с багами характерная слабость: он охотно «чинит» то, что не воспроизвёл. Правка выглядит разумно, тесты зелёные, а у пользователя всё по-прежнему. Защищает от этого старый порядок: воспроизвести → понять → починить → закрепить. С агентом он работает даже лучше, чем без него, — если его соблюдать.

Начните с отчёта, а не с гипотезы

Отдайте агенту баг-репорт как есть: шаги, ожидаемое и фактическое поведение, окружение, логи, скриншот (codex -i screenshot.png "..." или вставка картинки в composer). Не подсказывайте причину, даже если она кажется очевидной: агент начнёт подтверждать вашу версию вместо того, чтобы искать.

Пример с сайта на OctoberCMS:

Баг из Kaiten: на странице мероприятия кнопка «Записаться» пропадает
у части пользователей за день до события, хотя запись открыта до начала.
Жалобы в основном вечером. В логах ошибок пусто.

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

Деталь «вечером» здесь важна: похоже на часовые пояса, сравнение дат в UTC и в локальном времени. Но пусть агент придёт к этому через код, а не через вашу подсказку.

Воспроизведение — обязательный шаг

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

Напиши тест, воспроизводящий баг: событие завтра в 10:00 по Москве,
текущее время — сегодня 22:00 по Москве, кнопка должна быть видна.
Запусти тест и покажи, что он падает и с каким сообщением.

Проверьте две вещи. Первая — тест действительно падает. Вторая — падает по той же причине, что и баг, а не из-за опечатки в фикстуре. Сообщение должно говорить о видимости кнопки, а не о Class not found.

Если тестом баг не поймать — например, он в мобильном приложении и зависит от состояния устройства, — договоритесь о другом способе: скрипт, который вызывает API в нужной последовательности, или точные шаги для проверки на эмуляторе. Главное, чтобы воспроизведение было до правки. Подробнее о воспроизведении и баг-репортах — в курсе для тестировщиков: «Воспроизведение багов».

Объяснение и минимальная правка

Когда баг воспроизведён, просите не правку, а объяснение:

Тест падает. Объясни причину по коду, с файлами и строками.
Если гипотез несколько — перечисли и проверь каждую, прежде чем выбрать.
Потом предложи минимальную правку.

«Минимальная» — ключевое слово. Агент любит заодно отрефакторить соседний метод, переименовать переменные, поправить форматирование. В диффе багфикса это шум: он мешает ревьюеру и прячет саму правку. Если по пути агент нашёл ещё что-то, пусть запишет отдельным пунктом, а не чинит сразу.

Если причина неочевидна и нужны логи, стек-трейсы, отладочный вывод — это отдельная техника, ей посвящён урок «Отладка».

Правило: тест не трогать

Самый опасный сценарий — агент «чинит» баг, изменив ожидание в тесте. Формально всё зелёное. Запретите это явно, лучше сразу в AGENTS.md:

## Тесты
- Если тест падает, чини код, а не тест. Менять ожидания в существующих
  тестах — только с явного согласия и с объяснением почему.

После правки проверьте дифф: изменились ли файлы в tests/, кроме нового теста на баг? Если да — выясните зачем.

Закрепление и поиск похожих мест

Тест позеленел. Дальше три шага.

1. Весь набор тестов. Правка сравнения дат может сломать что-то ещё. Пусть агент запустит полный набор или хотя бы весь затронутый модуль, если полный прогон долгий.
2. Тест остаётся в репозитории. Это регрессионный тест, он не даст багу вернуться. Имя должно говорить, что проверяется: test_signup_button_visible_evening_before_event_in_local_timezone.
3. Похожие места. В гайде «How OpenAI uses Codex» описан приём: после исправления спросить агента, где ещё может прятаться такой же баг.

Причина бага — сравнение now() в UTC с датой события в локальном времени.
Найди в проекте другие места с тем же шаблоном. Не исправляй, дай список
с файлами и оценкой риска.

Список превращается в отдельные задачи или идёт в этот же MR — решаете вы.

Коммит, который объясняет

Хорошее сообщение коммита для багфикса отвечает на вопрос «почему», а не «что». Агент пишет такие сообщения хорошо, если у него есть контекст, — а после воспроизведения и объяснения он у него есть:

Сделай коммит: в заголовке — номер задачи и суть, в теле — причина бага,
как его воспроизвести, что изменено.

Через полгода тот, кто откроет git blame на этой строке, поймёт, почему она такая.