Систематическая отладка

Обзор

Случайные фиксы тратят время и создают новые баги. Быстрые патчи маскируют настоящие проблемы.

Главный принцип: ВСЕГДА находи корневую причину до попытки исправления. Фикс симптома — это провал.

Нарушение буквы этого процесса — это нарушение его духа.

Железный закон

НЕТ ФИКСОВ БЕЗ РАССЛЕДОВАНИЯ КОРНЕВОЙ ПРИЧИНЫ

Если не завершил Фазу 1 — нельзя предлагать фиксы.

Когда использовать

Для ЛЮБОЙ технической проблемы:

• Падения скриптов / тестов
• Баги в поведении
• Неожиданное поведение
• Проблемы производительности
• Ошибки интеграции
• Эндпоинт возвращает неожиданный ответ
• Тест проходит локально, падает в CI

Используй ОСОБЕННО когда:

• Давит время («нужно быстро починить»)
• «Очевидный быстрый фикс» кажется понятным
• Уже попробовал несколько фиксов
• Предыдущий фикс не помог
• До конца не понимаешь проблему

Не пропускай когда:

• Проблема кажется простой (у простых багов тоже есть корневые причины)
• Торопишься (спешка гарантирует переделку)

Четыре фазы

Каждую фазу нужно завершить до перехода к следующей.

Фаза 1: Расследование корневой причины

ДО любой попытки фикса:

1. Внимательно прочитай сообщения об ошибках
   • Не пролистывай ошибки и предупреждения
   • Они часто содержат точное решение
   • Читай stack trace полностью
   • Замечай номера строк, пути к файлам, коды ошибок
2. Воспроизведи стабильно
   • Можешь вызвать проблему надёжно?
   • Каковы точные шаги?
   • Это происходит каждый раз?
   • Не воспроизводится → собери больше данных, не угадывай
3. Проверь последние изменения
   • Что изменилось и могло вызвать это?
   • Последние правки кода, конфигов, шаблонов
   • Изменения во внешних системах (БД, очереди, внешние API, инфраструктура)

4. Собери доказательства в многокомпонентных системах

   Когда система имеет несколько компонентов (например, источник данных → обработчик → хранилище):

   Для каждой границы между компонентами:
     - Зафиксируй что входит в компонент
     - Зафиксируй что выходит из компонента
     - Проверь состояние на каждом слое
   
   Запусти один раз чтобы собрать доказательства ГДЕ ломается
   ПОТОМ проанализируй доказательства чтобы найти сломанный компонент
   ПОТОМ исследуй именно этот компонент

   Пример сбора доказательств по слоям — см. references/debug-commands.md

5. Прослеживай поток данных

   Когда ошибка глубоко в цепочке вызовов:

   • Откуда берётся плохое значение?
   • Что передало это плохое значение?
   • Продолжай трассировать вверх пока не найдёшь источник
   • Исправляй в источнике, а не в симптоме

Фаза 2: Анализ паттернов

Найди паттерн до исправления:

1. Найди рабочие примеры
   • Найди похожие рабочие конфигурации в том же проекте
   • Что работает среди похожего на сломанное?
2. Сравни с референсами
   • Если реализуешь паттерн — прочитай референсную реализацию ПОЛНОСТЬЮ
   • Не пролистывай — читай каждую строку
   • Пойми паттерн полностью до применения
3. Выяви различия
   • Что отличается между рабочим и сломанным?
   • Перечисли каждое различие, каким бы мелким оно ни было
   • Не предполагай «это не может иметь значения»
4. Пойми зависимости
   • Что ещё нужно этому компоненту?
   • Какие настройки, конфиги, предположения?

Фаза 3: Гипотеза и тестирование

Научный метод:

1. Сформулируй одну гипотезу
   • Сформулируй чётко: «Думаю X является корневой причиной потому что Y»
   • Запиши
   • Будь конкретным, не расплывчатым
2. Тестируй минимально
   • Сделай НАИМЕНЬШЕЕ возможное изменение для проверки гипотезы
   • Одна переменная за раз
   • Не исправляй несколько вещей одновременно
3. Верифицируй до продолжения
   • Сработало? Да → Фаза 4
   • Не сработало? Сформулируй НОВУЮ гипотезу
   • НЕ добавляй ещё фиксы сверху
4. Когда не знаешь
   • Скажи «Не понимаю X»
   • Не притворяйся что знаешь
   • Попроси помощи
   • Исследуй больше

Фаза 4: Реализация

Исправляй корневую причину, а не симптом:

1. Создай воспроизводящий тест
   • Простейшее возможное воспроизведение
   • Используй скилл unit-test-writer для написания падающего теста
   • ОБЯЗАТЕЛЕН до исправления
2. Реализуй одно исправление
   • Адресуй выявленную корневую причину
   • ОДНО изменение за раз
   • Никаких «пока я здесь» улучшений
   • Никакого связанного рефакторинга
3. Верифицируй исправление
   • Тест теперь проходит?
   • Другие тесты не сломались?
   • Проблема действительно решена?
   • Используй скилл verification-before-completion перед заявлением о готовности
4. Если исправление не работает
   • СТОП
   • Посчитай: сколько фиксов попробовано?
   • Если < 3: вернись к Фазе 1, проанализируй с новой информацией
   • Если ≥ 3: СТОП и ставь под сомнение архитектуру (шаг 5)
   • НЕ пробуй Фикс №4 без обсуждения архитектуры

5. Если 3+ фикса не помогли: ставь под сомнение архитектуру

   Паттерн указывающий на архитектурную проблему:

   • Каждый фикс обнаруживает новую проблему в другом месте
   • Фиксы требуют «масштабного рефакторинга»
   • Каждый фикс создаёт новые симптомы в другом месте

   СТОП и ставь под сомнение фундаментальное:

   • Этот паттерн фундаментально верен?
   • Стоит ли рефакторить архитектуру vs продолжать фиксить симптомы?

   Обсуди с пользователем до следующих попыток фикса

Красные флаги — СТОП и следуй процессу

Если ловишь себя на мысли:

• «Быстрый фикс сейчас, разберёмся потом»
• «Просто попробую изменить X и посмотрю»
• «Добавлю несколько изменений, запущу тесты»
• «Наверное это X, исправлю»
• «Не полностью понимаю, но это может сработать»
• «Вот основные проблемы: [перечисляет фиксы без расследования]»
• Предлагаешь решения до трассировки потока данных
• «Ещё одна попытка» (когда уже попробовано 2+)
• Каждый фикс обнаруживает новую проблему в другом месте

ВСЁ ЭТО означает: СТОП. Вернись к Фазе 1.

Типичные рационализации

Краткая справка