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.

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

| Проблема | Первым делом проверь | |----------|---------------------| | Крон не запустился | Проверь cron list → consecutiveErrors, lastStatus | | Gateway не отвечает | Проверь gateway status, порт | | Скрипт не найден | Путь, chmod +x, shebang | | Docker упал | docker ps -a, docker logs | | Память не ищет | sqlite3 /memory.sqlite "SELECT count(*) FROM chunks;" | | Бот молчит | message tool → проверь to, channel | | После обновления | Проверь health-check, перезапусти сервисы |

Source & license

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

• Author: AlekseiUL
• Source: AlekseiUL/sprut-agent-kit
• License: MIT
• Homepage: https://t.me/Sprut_AI

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