Bug Fix Task

Диагностика бага

Исследуй заявленную проблему, найди корневую причину и сформируй задачу на исправление с планом работы через TDD.

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

Процесс

1. Зафиксируй проблему

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

Если пользователь еще не описал проблему, задай только один вопрос:

Что именно не работает или выглядит неправильно?

Не задавай цепочку уточняющих вопросов на старте. После краткого описания сразу переходи к исследованию.

Зафиксируй:

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

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

2. Исследуй кодовую базу и найди причину

Изучи кодовую базу, чтобы понять не только симптом, но и причину проблемы.

Цель исследования:

• где проявляется баг: входная точка, экран, API-ответ, обработчик события, команда, интеграция;
• какой путь выполнения задействован: от входа в систему до места сбоя;
• почему возникает ошибка: корневая причина, а не поверхностный симптом;
• какой связанный код уже существует: похожие сценарии, соседние модули, существующие тесты, повторяющиеся паттерны.

Проверь:

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

Если есть доступные тесты, запусти релевантные тесты или определи, какие тесты должны падать.

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

3. Определи подход к исправлению

На основе диагностики определи:

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

Не предлагай исправление, которое лечит только симптом.

Плохой подход:

Добавить проверку на null в месте падения.

Хороший подход:

Гарантировать, что сценарий обработки неполных данных возвращает корректное состояние ошибки и не передает невалидные данные дальше по контракту.

4. Составь TDD-план исправления

Сформируй конкретный упорядоченный список циклов RED → GREEN.

Каждый цикл должен быть узким вертикальным срезом:

• RED — какой тест нужно написать, чтобы зафиксировать сломанное или отсутствующее поведение;
• GREEN — какое минимальное изменение нужно сделать, чтобы этот тест прошел.

Правила:

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

Тест должен выглядеть как спецификация поведения.

Хорошая формулировка:

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

Плохая формулировка:

RED: написать тест, который проверяет, что метод validateInput вызван один раз.

5. Учитывай устойчивость задачи

Итоговая задача должна оставаться полезной даже после существенного рефакторинга кодовой базы.

Описывай:

• поведение;
• контракты;
• пользовательский или системный результат;
• условия воспроизведения;
• ожидаемые результаты;
• проверяемые критерии.

Не привязывай итоговую задачу к хрупким деталям:

• конкретным путям к файлам;
• номерам строк;
• приватным методам;
• внутреннему порядку вызовов;
• временной структуре классов;
• фрагментам кода, которые могут быстро устареть.

Хорошая задача читается как спецификация.

Плохая задача читается как краткое описание будущего diff.

6. Сформируй задачу на исправление

После диагностики сформируй готовую задачу по шаблону ниже и запиши ее в markdown-файлы в каталог docs/bug-fix в корневой директории проекта.

Проблема

Опиши баг или проблему.

Включи:

• что происходит сейчас;
• что должно происходить;
• как воспроизвести проблему, если способ известен;
• где проявляется проблема: пользовательский интерфейс, API, данные, интеграция, фоновый процесс, тесты или другое;
• какое влияние проблема оказывает на пользователя, систему или процесс.

Анализ корневой причины

Опиши результаты исследования.

Включи:

• какой путь выполнения задействован;
• какой контракт, сценарий или инвариант нарушается;
• почему текущее поведение приводит к ошибке;
• какие факторы способствуют проблеме;
• почему это именно корневая причина, а не только симптом.

Не включай конкретные пути к файлам, номера строк и хрупкие детали текущей реализации.

Классификация

Укажи тип проблемы:

• регрессия;
• недостающая функциональность;
• ошибка в требованиях;
• ошибка интеграции;
• ошибка обработки данных;
• архитектурный дефект;
• проблема производительности;
• проблема надежности;
• другое.

Кратко объясни классификацию.

План исправления через TDD

Составь нумерованный список циклов RED → GREEN.

1. RED: написать тест, который проверяет <ожидаемое поведение>. GREEN: выполнить минимальное изменение, чтобы это поведение стало корректным.

2. RED: написать тест, который проверяет <следующее важное поведение>. GREEN: выполнить минимальное изменение, чтобы этот тест прошел.

3. RED: написать тест, который проверяет <краевой случай или регрессию>. GREEN: выполнить минимальное изменение, чтобы этот сценарий был обработан корректно.

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

Критерии приемки

• Проблема воспроизводится тестом до исправления.
• Исправление устраняет корневую причину, а не только симптом.
• Основной сценарий работает корректно.
• Краевые случаи обработаны предсказуемо.
• Новые тесты проходят.
• Существующие тесты продолжают проходить.
• Поведение проверяется через публичные интерфейсы, а не через детали реализации.

Риски и проверки

Опиши:

• какие соседние сценарии могут быть затронуты;
• какие регрессии важно предотвратить;
• какие ручные проверки нужны, если автоматических тестов недостаточно;
• какие логи, метрики или наблюдаемые признаки стоит проверить после исправления.

Открытые вопросы

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

Не останавливай работу из-за этих вопросов, если можно сформировать безопасный план исправления.

Финальный ответ пользователю

После формирования задачи дай:

1. готовую задачу на исправление;
2. краткое резюме корневой причины в одно-два предложения;
3. краткий список TDD-циклов;
4. явное указание, какие части анализа подтверждены кодом, а какие являются предположениями.