alekseiul/sprut-agent-kit/systematic-debugging

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

Железное правило

НИКАКИХ ФИКСОВ БЕЗ ПОНИМАНИЯ ПРИЧИНЫ

Рандомные фиксы тратят время и создают новые баги. Если не прошёл Фазу 1 - нельзя предлагать решения.

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

Любая техническая проблема:

• Крон не запустился / выдал ошибку
• Скрипт падает
• Gateway не отвечает
• Docker контейнер упал
• Память не ищет нужное
• Бот не отправляет сообщения
• Любое "раньше работало, теперь нет"

Особенно когда: под давлением, "очевидный фикс" напрашивается, уже пробовал 2+ решения.

Четыре фазы

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

ПЕРЕД любым фиксом:

1. Прочитай ошибку целиком

• Не пропускай стектрейсы и warnings
• Часто ответ прямо в тексте ошибки
• Запиши: файл, строка, код ошибки

1. Воспроизведи

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

1. Что изменилось?

• git diff, последние коммиты
• Обновление платформы? (проверь версию)
• Новые зависимости, конфиг?
• memory/progress-log.md - что делалось недавно

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

Для многокомпонентных систем (крон → gateway → агент → tool → результат): ``` На каждом стыке:

• Что входит?
• Что выходит?
• Где ломается?

```

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

1. Найди рабочий пример - похожий скрипт/крон который работает
2. Сравни - что отличается между рабочим и сломанным?
3. Проверь зависимости - всё ли на месте (docker, npm, пути, права)?

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

1. Сформулируй гипотезу - "Я думаю причина в X потому что Y"
2. Минимальный тест - ОДНО изменение, ОДНА переменная
3. Проверь - сработало → Фаза 4. Нет → новая гипотеза
4. НЕ лепи фиксы поверх - если не сработало, откати и думай заново

Фаза 4: Реализация фикса

1. Фикси причину, не симптом
2. Одно изменение за раз
3. Проверь - проблема ушла? Ничего другого не сломалось?
4. Запиши - bash scripts/progress-log.sh + daily notes если важное
5. Если 3+ фикса не сработали - СТОП. Проблема архитектурная. Обсуди с Алексеем.

Красные флаги - ОСТАНОВИСЬ

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

• "Быстрый фикс, потом разберусь"
• "Попробую поменять X, вдруг поможет"
• "Добавлю несколько изменений сразу"
• "Не совсем понимаю, но может сработает"
• "Ещё один фикс..." (когда уже 2+ не сработали)

→ СТОП. Вернись к Фазе 1.

Наши типичные проблемы и где искать