Systematic Debugging

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

Четыре фазы

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

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

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

1. Внимательно прочитай сообщения об ошибках

• Не пролистывай ошибки и предупреждения
• Они часто содержат точное решение
• Читай stack trace полностью
• Замечай номера строк, пути к файлам, коды ошибок

1. Воспроизведи стабильно

• Можешь вызвать проблему надёжно?
• Каковы точные шаги?
• Это происходит каждый раз?
• Не воспроизводится → собери больше данных, не угадывай

1. Проверь последние изменения

• Что изменилось и могло вызвать это?
• Последние правки кода, конфигов, шаблонов
• Изменения во внешних системах (БД, очереди, внешние API, инфраструктура)

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

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

``` Для каждой границы между компонентами:

• Зафиксируй что входит в компонент
• Зафиксируй что выходит из компонента
• Проверь состояние на каждом слое

Запусти один раз чтобы собрать доказательства ГДЕ ломается ПОТОМ проанализируй доказательства чтобы найти сломанный компонент ПОТОМ исследуй именно этот компонент ```

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

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

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

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

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

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

1. Найди рабочие примеры

• Найди похожие рабочие конфигурации в том же проекте
• Что работает среди похожего на сломанное?

1. Сравни с референсами

• Если реализуешь паттерн — прочитай референсную реализацию ПОЛНОСТЬЮ
• Не пролистывай — читай каждую строку
• Пойми паттерн полностью до применения

1. Выяви различия

• Что отличается между рабочим и сломанным?
• Перечисли каждое различие, каким бы мелким оно ни было
• Не предполагай «это не может иметь значения»

1. Пойми зависимости

• Что ещё нужно этому компоненту?
• Какие настройки, конфиги, предположения?

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

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

1. Сформулируй одну гипотезу

• Сформулируй чётко: «Думаю X является корневой причиной потому что Y»
• Запиши
• Будь конкретным, не расплывчатым

1. Тестируй минимально

• Сделай НАИМЕНЬШЕЕ возможное изменение для проверки гипотезы
• Одна переменная за раз
• Не исправляй несколько вещей одновременно

1. Верифицируй до продолжения

• Сработало? Да → Фаза 4
• Не сработало? Сформулируй НОВУЮ гипотезу
• НЕ добавляй ещё фиксы сверху

1. Когда не знаешь

• Скажи «Не понимаю X»
• Не притворяйся что знаешь
• Попроси помощи
• Исследуй больше

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

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

1. Создай воспроизводящий тест

• Простейшее возможное воспроизведение
• Используй скилл unit-test-writer для написания падающего теста
• ОБЯЗАТЕЛЕН до исправления

1. Реализуй одно исправление

• Адресуй выявленную корневую причину
• ОДНО изменение за раз
• Никаких «пока я здесь» улучшений
• Никакого связанного рефакторинга

1. Верифицируй исправление

• Тест теперь проходит?
• Другие тесты не сломались?
• Проблема действительно решена?
• Используй скилл verification-before-completion перед заявлением о готовности

1. Если исправление не работает

• СТОП
• Посчитай: сколько фиксов попробовано?
• Если < 3: вернись к Фазе 1, проанализируй с новой информацией
• Если ≥ 3: СТОП и ставь под сомнение архитектуру (шаг 5)
• НЕ пробуй Фикс №4 без обсуждения архитектуры

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: megamott
• Source: megamott/vibe-skills
• License: MIT

Install and usage instructions live in the source repository linked above.