Bug Fix Protocol

Structured protocol for fixing bugs with AI agents. Prevents hallucinations and fix loops by enforcing step-by-step diagnosis before code changes.

borodich@borodich

Install

openclaw skills install @borodich/bug-fix-protocol

BUG-FIX-PROTOCOL Skill

Source: https://github.com/CodeAlive-AI/ai-driven-development/blob/main/BUG-FIX-PROTOCOL.md
Concept by Rodion Mostovoy

Core Philosophy

Тест-система = страховочная сетка (safety net)

Баг на проде = баг тест-системы в первую очередь
Каждый баг-фикс = два фикса: код + патч тест-системы
"Тесты" — это не только unit-тесты. Это всё:
- Unit / Integration / E2E тесты
- PRD assessment (соответствие продукт-требованиям)
- Review спеки и документации
- Code review
- Статический анализ (linters, type checkers)
- Визуальные тесты

⚠️ ГЛАВНОЕ ПРАВИЛО

НИКОГДА не фиксить баг без воспроизведения через тест.

Если воспроизвести через тест невозможно — скажи явно с обоснованием. Но не фикси молча.

8-Шаговый Протокол (Чеклист)

[ ] Шаг 1 — Понять баг

Разберись, что именно сломалось
Придумай способ воспроизведения
Непонятно → спроси, не гадай
Не трогай код, пока не понял проблему

[ ] Шаг 2 — Воспроизвести через тест

Напиши тест, который падает на баге
Тест должен быть красным ДО фикса
Если воспроизвести через тест невозможно — скажи явно с обоснованием
Не переходи к шагу 3 без красного теста (или явного объяснения почему нельзя)

[ ] Шаг 3 — Найти корневую причину

Ищи корень, не симптом
Задай себе "почему?" минимум 3 раза
Не фиксируй то, что видишь — найди то, что это вызвало

[ ] Шаг 4 — Спроектировать правильный фикс

Придумай грамотный фикс, не костыль
Оцени scope изменений
Большой рефакторинг → остановись, спроси перед началом
Фикс должен решать корень, не симптом

[ ] Шаг 5 — Применить минимальные правки

Чини с минимальными изменениями
Не затрагивай части кода, не связанные с багом
Каждое изменение должно быть обосновано

[ ] Шаг 6 — Проверить тесты

Запусти тест из шага 2 → должен быть зелёным
Запусти соседние/связанные тесты → не сломались?
Запусти полный test suite если возможно
Только зелёный suite → идём дальше

[ ] Шаг 7 — Deep Review: похожие проблемы

Раз тест-система не поймала этот баг — похожие проблемы могут быть везде
Проведи поиск аналогичных паттернов в кодовой базе
Проверь похожие модули/компоненты
Задокументируй находки

[ ] Шаг 8 — Аудит тест-системы

Разберись, почему тест-система упустила этот баг
Улучши тест-систему чтобы предотвратить класс подобных багов
Это обязательный шаг, не опциональный

Шаблон: Документация баг-фикса

markdown

## Bug Fix: [краткое название]

### Что сломалось
[Описание симптома с точки зрения пользователя/системы]

### Как воспроизводится
[Шаги воспроизведения или ссылка на тест]

### Корневая причина
[Настоящая причина, не симптом]

### Решение
[Что было изменено и почему именно так]

### Тест
- Файл: `path/to/test_file`
- Тест: `test_name`
- Статус до фикса: 🔴 RED
- Статус после фикса: 🟢 GREEN

### Deep Review
[Что проверили в похожих местах, что нашли]

### Патч тест-системы
[Что добавили/улучшили в тест-системе]

Шаблон: Аудит тест-системы после бага