Систематическая отладка
Железное правило
НИКАКИХ ФИКСОВ БЕЗ ПОНИМАНИЯ ПРИЧИНЫ
Рандомные фиксы тратят время и создают новые баги. Если не прошёл Фазу 1 - нельзя предлагать решения.
Когда использовать
Любая техническая проблема:
- Крон не запустился / выдал ошибку
- Скрипт падает
- Gateway не отвечает
- Docker контейнер упал
- Память не ищет нужное
- Бот не отправляет сообщения
- Любое "раньше работало, теперь нет"
Особенно когда: под давлением, "очевидный фикс" напрашивается, уже пробовал 2+ решения.
Четыре фазы
Фаза 1: Расследование причины
ПЕРЕД любым фиксом:
Прочитай ошибку целиком
- Не пропускай стектрейсы и warnings
- Часто ответ прямо в тексте ошибки
- Запиши: файл, строка, код ошибки
Воспроизведи
- Можешь повторить проблему?
- Какие точные шаги?
- Если не воспроизводится - собирай больше данных, не гадай
Что изменилось?
git diff, последние коммиты- Обновление платформы? (проверь версию)
- Новые зависимости, конфиг?
memory/progress-log.md - что делалось недавно
Проследи поток данных
Для многокомпонентных систем (крон → gateway → агент → tool → результат):
На каждом стыке:
- Что входит?
- Что выходит?
- Где ломается?
Фаза 2: Анализ паттерна
- Найди рабочий пример - похожий скрипт/крон который работает
- Сравни - что отличается между рабочим и сломанным?
- Проверь зависимости - всё ли на месте (docker, npm, пути, права)?
Фаза 3: Гипотеза и тест
- Сформулируй гипотезу - "Я думаю причина в X потому что Y"
- Минимальный тест - ОДНО изменение, ОДНА переменная
- Проверь - сработало → Фаза 4. Нет → новая гипотеза
- НЕ лепи фиксы поверх - если не сработало, откати и думай заново
Фаза 4: Реализация фикса
- Фикси причину, не симптом
- Одно изменение за раз
- Проверь - проблема ушла? Ничего другого не сломалось?
- Запиши -
bash scripts/progress-log.sh + daily notes если важное
- Если 3+ фикса не сработали - СТОП. Проблема архитектурная. Обсуди с Алексеем.
Красные флаги - ОСТАНОВИСЬ
Если ловишь себя на мысли:
- "Быстрый фикс, потом разберусь"
- "Попробую поменять X, вдруг поможет"
- "Добавлю несколько изменений сразу"
- "Не совсем понимаю, но может сработает"
- "Ещё один фикс..." (когда уже 2+ не сработали)
→ СТОП. Вернись к Фазе 1.
Наши типичные проблемы и где искать
| Проблема |
Первым делом проверь |
| Крон не запустился |
Проверь cron list → consecutiveErrors, lastStatus |
| Gateway не отвечает |
Проверь gateway status, порт |
| Скрипт не найден |
Путь, chmod +x, shebang |
| Docker упал |
docker ps -a, docker logs <name> |
| Память не ищет |
sqlite3 <path>/memory.sqlite "SELECT count(*) FROM chunks;" |
| Бот молчит |
message tool → проверь to, channel |
| После обновления |
Проверь health-check, перезапусти сервисы |
1---2name: systematic-debugging3description: Систематическая отладка при любых багах, ошибках, неожиданном поведении. Используй ПЕРЕД предложением фиксов. Триггеры: 'не работает', 'баг', 'ошибка', 'сломалось', 'debug', 'почему не', 'странное поведение', 'крон не запустился', 'скрипт падает'.4---56# Систематическая отладка78## Железное правило910```11НИКАКИХ ФИКСОВ БЕЗ ПОНИМАНИЯ ПРИЧИНЫ12```1314Рандомные фиксы тратят время и создают новые баги. Если не прошёл Фазу 1 - нельзя предлагать решения.1516## Когда использовать1718Любая техническая проблема:19- Крон не запустился / выдал ошибку20- Скрипт падает21- Gateway не отвечает22- Docker контейнер упал23- Память не ищет нужное24- Бот не отправляет сообщения25- Любое "раньше работало, теперь нет"2627**Особенно** когда: под давлением, "очевидный фикс" напрашивается, уже пробовал 2+ решения.2829## Четыре фазы3031### Фаза 1: Расследование причины3233**ПЕРЕД любым фиксом:**34351. **Прочитай ошибку целиком**36 - Не пропускай стектрейсы и warnings37 - Часто ответ прямо в тексте ошибки38 - Запиши: файл, строка, код ошибки39402. **Воспроизведи**41 - Можешь повторить проблему?42 - Какие точные шаги?43 - Если не воспроизводится - собирай больше данных, не гадай44453. **Что изменилось?**46 - `git diff`, последние коммиты47 - Обновление платформы? (проверь версию)48 - Новые зависимости, конфиг?49 - `memory/progress-log.md` - что делалось недавно50514. **Проследи поток данных**52 Для многокомпонентных систем (крон → gateway → агент → tool → результат):53 ```54 На каждом стыке:55 - Что входит?56 - Что выходит?57 - Где ломается?58 ```5960### Фаза 2: Анализ паттерна61621. **Найди рабочий пример** - похожий скрипт/крон который работает632. **Сравни** - что отличается между рабочим и сломанным?643. **Проверь зависимости** - всё ли на месте (docker, npm, пути, права)?6566### Фаза 3: Гипотеза и тест67681. **Сформулируй гипотезу** - "Я думаю причина в X потому что Y"692. **Минимальный тест** - ОДНО изменение, ОДНА переменная703. **Проверь** - сработало → Фаза 4. Нет → новая гипотеза714. **НЕ лепи фиксы поверх** - если не сработало, откати и думай заново7273### Фаза 4: Реализация фикса74751. **Фикси причину, не симптом**762. **Одно изменение за раз**773. **Проверь** - проблема ушла? Ничего другого не сломалось?784. **Запиши** - `bash scripts/progress-log.sh` + daily notes если важное795. **Если 3+ фикса не сработали** - СТОП. Проблема архитектурная. Обсуди с Алексеем.8081## Красные флаги - ОСТАНОВИСЬ8283Если ловишь себя на мысли:84- "Быстрый фикс, потом разберусь"85- "Попробую поменять X, вдруг поможет"86- "Добавлю несколько изменений сразу"87- "Не совсем понимаю, но может сработает"88- "Ещё один фикс..." (когда уже 2+ не сработали)8990→ СТОП. Вернись к Фазе 1.9192## Наши типичные проблемы и где искать9394| Проблема | Первым делом проверь |95|----------|---------------------|96| Крон не запустился | Проверь cron list → consecutiveErrors, lastStatus |97| Gateway не отвечает | Проверь gateway status, порт |98| Скрипт не найден | Путь, chmod +x, shebang |99| Docker упал | `docker ps -a`, `docker logs <name>` |100| Память не ищет | `sqlite3 <path>/memory.sqlite "SELECT count(*) FROM chunks;"` |101| Бот молчит | message tool → проверь to, channel |102| После обновления | Проверь health-check, перезапусти сервисы |
AlekseiUL