systematic-debugging

name	systematic-debugging
description	Используй при любой ошибке, падении теста или неожиданном поведении — до того как предлагать фиксы

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

Обзор

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

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

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

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

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

Если не завершил Фазу 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.

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

Отговорка	Реальность
«Проблема простая, процесс не нужен»	У простых проблем тоже есть корневые причины. Процесс быстр для простых багов.
«Срочно, нет времени на процесс»	Систематическая отладка БЫСТРЕЕ чем угадывание.
«Сначала попробую, потом разберусь»	Первый фикс задаёт паттерн. Делай правильно с начала.
«Вижу проблему, исправлю»	Видеть симптомы ≠ понимать корневую причину.
«Ещё одна попытка» (после 2+ неудач)	3+ неудачи = архитектурная проблема. Ставь под сомнение паттерн.

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

Фаза	Ключевые действия	Критерий успеха
1. Корневая причина	Читай ошибки, воспроизводи, проверяй изменения, собирай доказательства	Понимаю ЧТО и ПОЧЕМУ
2. Паттерны	Найди рабочие примеры, сравни	Выявлены различия
3. Гипотеза	Сформулируй теорию, тестируй минимально	Подтверждена или новая гипотеза
4. Реализация	Создай тест, исправь, верифицируй	Баг решён, тесты проходят