# Systematic Debugging

> Систематическая отладка при любых багах, ошибках, неожиданном поведении. Используй ПЕРЕД предложением фиксов. Триггеры: 'не работает', 'баг', 'ошибка', 'сломалось', 'debug', 'почему не', 'странное поведение', 'крон не запустился', 'скрипт падает'.

- Skill: `alekseiul/systematic-debugging` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add alekseiul/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alekseiul/systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: AlekseiUL (https://skillmd.com/u/alekseiul)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alekseiul/systematic-debugging

---


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

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

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

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

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

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

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

## Четыре фазы

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

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

1. **Прочитай ошибку целиком**
   - Не пропускай стектрейсы и warnings
   - Часто ответ прямо в тексте ошибки
   - Запиши: файл, строка, код ошибки

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

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

4. **Проследи поток данных**
   Для многокомпонентных систем (крон → 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 <name>` |
| Память не ищет | `sqlite3 <path>/memory.sqlite "SELECT count(*) FROM chunks;"` |
| Бот молчит | message tool → проверь to, channel |
| После обновления | Проверь health-check, перезапусти сервисы |