<img src="../banner.png" width="100%" alt="bugsweep banner">

Русский — Официальная русская версия bugsweep.

/bugsweep — Систематический workflow поиска багов (Русский)

Итеративная охота за багами со сходящимся критерием остановки. Масштабируется с размером кодовой базы, эскалирует, если поиск выглядит поверхностным, и предотвращает повторения благодаря отслеживанию областей.

1. Расчет базовой нормы (base_rate)

LOC = productive source lines (src/, lib/ — excluding tests, configs, docs, generated)
x = max(1, ceil(LOC / 1500))
base_rate = x * 3

LOC	x	Базовая норма (Base rate)
~1500	1	3
~3000	2	6
~4500	3	9
~10000	7	21

Отчет пользователю: "Кодовая база: {LOC} LOC → базовая норма = {base_rate} чистых проходов поиска."

2. Цикл поиска

counter = 0
target = base_rate
any_bug_found = False
checked = []  # (area_name, type: code|task)

LOOP:
  area = pick_new_area()  # see area rules
  checked.append(area)

  Perform a thorough bug search

  IF bug found:
    any_bug_found = True
    Fix following bugfix-protocol (phases 4+5)
    Review: see model rule (newer model classes: no external review needed)
    Commit + push
    counter = 0  # RESET
  ELSE:
    counter += 1
    Report: "✓ Clean: {area} — {counter}/{target}"

  IF counter >= target:
    IF NOT any_bug_found:
      # Doubling escalation: not a single bug → search too shallow?
      target = base_rate * 2
      any_bug_found = True  # escalate only ONCE
      Report: "⚠ No bug in {base_rate} passes → target doubled to {target}."
      CONTINUE LOOP
    ELSE:
      GOTO final verification

Практические заметки по циклу поиска (на основе реальных свипов)

• Репозитории без git: Там, где нет git (например, папки проектов с облачной синхронизацией), версионная резервная копия заменяет "commit + push": создайте file_<ts>.bak перед первым исправлением. Внимание — резервная копия до исправления НЕ является бэкапом вашей работы: после последнего исправления сделайте свежий бэкап _FINAL_, иначе сбой синхронизации может уничтожить всю сессию исправлений.
• Множество багов известно заранее: Если на старте уже известно N багов (например, из предыдущего запуска), подход "для каждого бага: исправить → проверить → коммит → сброс" непрактичен. Обработайте известные баги как ЕДИНЫЙ блок исправлений (общая проверка в конце) и начните отсчет базовой нормы / цикла поиска с первого ВНОВЬ найденного бага. Логика сброса по-прежнему применяется к багам, найденным во время свипа.
• Один и тот же баг в нескольких местах: Найденный дефект (например, неверный regex, ошибочное предположение о формате) часто копируется в других местах. После каждого исправления ищите такой же паттерн в других локациях — это ценная отдельная "область".

3. Правила областей (защита от имитации)

"Область" — это либо фокус кода, либо задача (цель кода).

Фокус кода

• Может быть расширен (больше файлов) или смещен (другая часть) между проходами
• НЕ ДОЛЖЕН быть точно таким же набором, как в предыдущем проходе
• ОК: проход 1 = maintenance.py, проход 5 = maintenance.py + orchestrator.py (расширен)
• НЕ ОК: проход 1 = maintenance.py, проход 5 = maintenance.py (идентичен)

Задача (цель)

• Может быть сделана более детализированной (проверить подфункцию) или более широкой (связанные функции вместе)
• НЕ ДОЛЖНА быть точно такой же задачей
• ОК: проход 1 = "потокобезопасность в watchdog", проход 5 = "потокобезопасность во всем трее" (более широкая)
• ОК: проход 1 = "обнаружение процессов", проход 5 = "сопоставление маркеров хранилища внутри обнаружения процессов" (более детализированная)
• НЕ ОК: проход 1 = "потокобезопасность в watchdog", проход 5 = "потокобезопасность в watchdog" (идентичная)

Именование

• Область ДОЛЖНА быть названа ДО начала поиска (без назначений задним числом)
• Формат: "{name}" ({type}: code|task)

4. Финальная верификация

Когда counter >= target И any_bug_found:

Шаг A — фаза 5 bugfix-protocol:

• Полный набор тестов пройден (pytest)
• Фактически выполнить измененный путь исполнения хотя бы один раз — не ограничиваясь тестами. Зеленые юнит-тесты на коде, который никогда не вызывает измененное место — это ложная безопасность. Запустите реально измененный путь (пробный запуск dry run, дымовой запуск smoke run, вызов из CLI) и проверьте отсутствие трассировок ошибок (tracebacks), ошибок сигнатуры или именования. py_compile или простой import проверяют только синтаксис — но не то, исполняется ли путь.
• Каждое исправление имеет хотя бы один тест, который его затрагивает — исправление без теста, который реально активирует измененную ветку, считается неверифицированным (для путей оркестрации/сети при необходимости комбинируйте моки и dry run).
• Проверка типов (если настроена)
• Линтер (если настроен)
• Проверены граничные случаи исправлений текущей сессии

Шаг B — ревью (правило моделей):

• Более новые классы моделей (например, Claude 5 / класс Fable): внешнее ревью от советника или второй модели НЕ требуется. Шаг A (тесты + реальный дымовой запуск) является верификацией. Опционально, при реальной неуверенности: свежий субагент для ревью — но эмпирически проверьте его выводы (протестируйте на неизмененном коде), прежде чем считать их багами. Контекст (опыт свипа 2026-06-11): второй рецензент был недоступен, замещающий субагент выдал 1 замечание (уверенность 85%), которое тест опроверг как не-баг — внешнее ревью не изменило результат.
• Более старые модели: итоговое обсуждение с советником (резервный вариант: вторая модель в качестве рецензента); советник подтверждает или указывает на пробелы.

Если во время верификации найден баг: → Исправить + протестировать + коммит → СБРОС: counter = 0, target = base_rate (свежая базовая норма, БЕЗ удвоения) → Возврат в цикл поиска (список checked сохраняется, any_bug_found = True)

Если верификация прошла успешно: → ГОТОВО. Commit + push. Вывести протокол.

5. Протокол (в конце)

## Bug Sweep Result

- **Codebase:** {LOC} LOC
- **Base rate:** {base_rate} (escalated: {target})
- **Areas checked:** {len(checked)}
- **Bugs found:** {count}
- **Resets:** {reset_count}
- **Doubling triggered:** yes/no
- **Fixes:**
  - {title} — {commit_hash}
  - ...
- **Final test suite:** {passed}/{total} green
- **Review verdict:** self-verification (newer model class) / advisor confirmed / gaps named

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

• После разработки функционала (гарантия качества)
• Перед релизом (приемочный свип)
• Периодически в качестве гигиенической проверки
• Когда пользователь вводит /bugsweep

Взаимодействие с другими навыками

• bugfix-protocol: процедура исправления (фазы 4+5) для каждого найденного бага
• systematic-debugging: для трудновоспроизводимых багов внутри свипа
• code-review: может использоваться в качестве области-задачи

---

История изменений

1.1.0 (2026-06-13)

• Перенесено правило моделей для шага B (из локальной установки навыка, состояние от 2026-06-11): более новые классы моделей самопроверяются с помощью тестов и реального дымового запуска, внешнее ревью не требуется; поле протокола "Review verdict" соответственно расширено

1.0.0 (2026-06-13)

• Первая публикация в библиотеке навыков (адаптировано из локальной установки навыка, состояние от 2026-06-01)