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

Обзор

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

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

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

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

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

Если вы не завершили Фазу 1, вы не можете предлагать исправления.

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

Используйте для ЛЮБОЙ технической проблемы:

• Падения тестов
• Баги в продакшене
• Неожиданное поведение
• Проблемы производительности
• Падения сборки
• Проблемы интеграции

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

• Цейтнот (в авралах велик соблазн гадать)
• «Всего одна быстрая правка» кажется очевидной
• Вы уже пробовали несколько правок
• Предыдущая правка не сработала
• Вы не до конца понимаете проблему

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

• Проблема кажется простой (у простых багов тоже есть корневые причины)
• Вы спешите (спешка гарантирует переделку)
• Менеджер хочет «починить СЕЙЧАС» (систематика быстрее, чем метание)

Четыре фазы

Вы ОБЯЗАНЫ завершить каждую фазу, прежде чем переходить к следующей.

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

ПЕРЕД любой попыткой исправления:

1. Внимательно читайте сообщения об ошибках
   • Не проскакивайте мимо ошибок и предупреждений
   • Часто в них точное решение
   • Читайте стек-трейсы полностью
   • Отмечайте номера строк, пути файлов, коды ошибок
2. Воспроизводите стабильно
   • Можете ли вы вызвать это надёжно?
   • Каковы точные шаги?
   • Происходит ли каждый раз?
   • Если не воспроизводится → собирайте больше данных, не гадайте
3. Проверьте недавние изменения
   • Что изменилось, что могло это вызвать?
   • Git diff, недавние коммиты
   • Новые зависимости, изменения конфига
   • Различия в окружении
4. Собирайте доказательства в многокомпонентных системах

   КОГДА в системе несколько компонентов (CI → сборка → подпись, API → сервис → база данных):

   ПЕРЕД предложением исправлений добавьте диагностическую инструментацию:

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

   Пример (многослойная система):

   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"
   
   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   Это показывает: какой слой ломается (secrets → workflow ✓, workflow → build ✗)

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

   КОГДА ошибка глубоко в стеке вызовов:

   См. root-cause-tracing.md в этом каталоге — полная техника обратной трассировки.

   Кратко:

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

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

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

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

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

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

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

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

Чините корневую причину, а не симптом:

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

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

   • Каждая правка вскрывает новое разделяемое состояние/связанность/проблему в другом месте
   • Правки требуют «массивного рефакторинга»
   • Каждая правка порождает новые симптомы в другом месте

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

   • Этот паттерн вообще принципиально верен?
   • Мы держимся за него «просто по инерции»?
   • Стоит ли рефакторить архитектуру, а не продолжать чинить симптомы?

   Обсудите с вашим партнёром-человеком перед новыми попытками исправления.

   Это НЕ провалившаяся гипотеза — это неверная архитектура.

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

Если ловите себя на мыслях:

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

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

Если провалились 3+ правки: поставьте под вопрос архитектуру (см. Фазу 4.5)

Сигналы вашего партнёра-человека, что вы делаете это неправильно

Следите за такими перенаправлениями:

• «А это вообще происходит?» — вы предположили без проверки
• «А это нам покажет…?» — стоило добавить сбор доказательств
• «Хватит гадать» — вы предлагаете правки без понимания
• «Ультра-подумай над этим» — ставьте под вопрос фундамент, а не только симптомы
• «Мы застряли?» (с раздражением) — ваш подход не работает

Когда видите это: СТОП. Вернитесь к Фазе 1.

Частые самооправдания

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

Когда процесс показывает «корневой причины нет»

Если систематическое расследование показывает, что проблема действительно средовая, зависящая от тайминга или внешняя:

1. Вы завершили процесс
2. Задокументируйте, что исследовали
3. Реализуйте подходящую обработку (повтор, таймаут, сообщение об ошибке)
4. Добавьте мониторинг/логирование для будущих расследований

Но: 95% случаев «корневой причины нет» — это незавершённое расследование.

Вспомогательные техники

Эти техники — часть систематической отладки, доступны в этом каталоге:

• root-cause-tracing.md — трассировка багов назад по стеку вызовов к исходному триггеру
• defense-in-depth.md — добавление валидации на нескольких слоях после нахождения корневой причины
• condition-based-waiting.md — замена произвольных таймаутов опросом по условию

Связанные скиллы:

• superpowers:test-driven-development — для создания падающего теста (Фаза 4, шаг 1)
• superpowers:verification-before-completion — проверить, что правка сработала, прежде чем заявлять об успехе

Эффект в реальном мире

Из сессий отладки:

• Систематический подход: 15–30 минут на исправление
• Подход случайных правок: 2–3 часа метаний
• Доля исправлений с первого раза: 95% против 40%
• Внесено новых багов: почти ноль против частого