{/ Эта страница автоматически создается на основе файла SKILL.md навыка с помощью сайта site/scripts/generate-skill-docs.py. Редактируйте исходный код SKILL.md, а не эту страницу. /}

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

4-этапная отладка первопричин: выясните ошибки, прежде чем их исправлять.

Метаданные навыков


Источник	В комплекте (устанавливается по умолчанию)
Путь	`навыки/разработка программного обеспечения/систематическая отладка`
Версия	`1.1.0`
Автор	Агент Гермеса (адаптировано из обры/сверхспособностей)
Лицензия	Массачусетский технологический институт
Платформы	Linux, MacOS, Windows
Теги	`отладка`, `устранение неполадок`, `решение проблем`, `основная причина`, `расследование`
Сопутствующие навыки	`разработка-на основе тестирования`, `написание-планов`, `разработка-под агентом`

Ссылка: полная версия SKILL.md:::информация

Ниже приведено полное определение навыка, которое Гермес загружает при активации этого навыка. Это то, что агент видит в качестве инструкций, когда навык активен.

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

Обзор

Случайные исправления тратят время и создают новые ошибки. Быстрые исправления маскируют основные проблемы.

Основной принцип: ВСЕГДА находите основную причину, прежде чем пытаться ее исправить. Устранение симптомов - сбой.

Нарушение буквы этого процесса — нарушение духа отладки.

Железный закон

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Если вы не завершили этап 1, вы не можете предлагать исправления.

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

Используйте для ЛЮБОЙ технической проблемы: - Неудачные тесты - Ошибки в производстве - Неожиданное поведение - Проблемы с производительностью - Ошибки сборки - Проблемы интеграции

Используйте это ОСОБЕННО, когда: - В условиях нехватки времени (чрезвычайные ситуации делают догадки заманчивыми) - «Всего одно быстрое решение» кажется очевидным - Вы уже попробовали несколько исправлений - Предыдущее исправление не сработало - Вы не до конца понимаете суть вопроса

Не пропускайте, если: - Проблема кажется простой (простые ошибки тоже имеют коренные причины) - Вы спешите (спешка гарантирует переделку) - Кто-то хочет, чтобы это исправили СЕЙЧАС (систематически быстрее, чем трясти)

Четыре фазы

Вы ДОЛЖНЫ завершить каждый этап, прежде чем переходить к следующему.

Этап 1: Исследование первопричин

ПЕРЕД попыткой ЛЮБОГО исправления:

1. Внимательно читайте сообщения об ошибках

Не пропускайте прошлые ошибки или предупреждения.
Они часто содержат точное решение
Полностью прочитать трассировку стека
Обратите внимание на номера строк, пути к файлам, коды ошибок.

Действие: Используйте read_file для соответствующих исходных файлов. Используйте search_files, чтобы найти строку ошибки в базе кода.

2. Постоянное воспроизводство

Можете ли вы вызвать его надежно?
Каковы точные шаги?
Это происходит каждый раз?
Если невозможно воспроизвести → собрать больше данных, не гадать

Действие: Используйте инструмент «терминал», чтобы запустить неудачный тест или вызвать ошибку:

# Run specific failing test
pytest tests/test_module.py::test_name -v

# Run with verbose output
pytest tests/test_module.py -v --tb=long

3. Проверьте последние изменения

Что изменилось, что могло вызвать это?
Git diff, последние коммиты
Новые зависимости, изменения конфигурации

Действие:

# Recent commits
git log --oneline -10

# Uncommitted changes
git diff

# Changes in specific file
git log -p --follow src/problematic_file.py | head -100

4. Сбор доказательств в многокомпонентных системах

КОГДА система состоит из нескольких компонентов (API → сервис → база данных, CI → сборка → развертывание):

ПРЕЖДЕ ЧЕМ предлагать исправления, добавьте диагностические инструменты:

Для КАЖДОЙ границы компонента: - Записывать, какие данные поступают в компонент - Запишите, какие данные выходят из компонента. - Проверка распространения среды/конфигурации. - Проверьте состояние на каждом уровне

Бегите один раз, чтобы собрать доказательства, показывающие, ГДЕ он сломался. ЗАТЕМ проанализируйте доказательства, чтобы определить неисправный компонент. ЗАТЕМ исследуйте этот конкретный компонент.

5. Отслеживание потока данных

Ошибка WHEN находится глубоко в стеке вызовов:

Откуда берется плохая ценность?
Что вызвало эту функцию с плохим значением?
Продолжайте отслеживать вверх по течению, пока не найдете источник.
Устраняйте источник, а не симптом.

Действие: Используйте search_files для отслеживания ссылок:

# Find where the function is called
search_files("function_name(", path="src/", file_glob="*.py")

# Find where the variable is set
search_files("variable_name\\s*=", path="src/", file_glob="*.py")

Контрольный список завершения этапа 1

[ ] Сообщения об ошибках полностью прочитаны и поняты.
[ ] Проблема воспроизводится последовательно
[ ] Недавние изменения выявлены и рассмотрены
[ ] Собранные доказательства (журналы, состояние, поток данных)
[ ] Проблема связана с конкретным компонентом/кодом
[ ] Сформирована гипотеза о первопричине

СТОП: Не переходите к этапу 2, пока не поймете, ПОЧЕМУ это происходит.

Этап 2: Анализ закономерностей

Найдите закономерность, прежде чем исправлять:

1. Найдите рабочие примеры

Найдите аналогичный рабочий код в той же базе кода.
Что работает и похоже на то, что сломано?

Действие: Используйте search_files, чтобы найти сопоставимые шаблоны:

search_files("similar_pattern", path="src/", file_glob="*.py")

2. Сравнение со ссылками

При реализации шаблона ПОЛНОСТЬЮ прочтите эталонную реализацию.
Не бегло бегло читать каждую строчку.
Полностью понять рисунок перед применением

3. Выявите различия

Чем отличается работающее от сломанного?
Перечислите все различия, даже самые незначительные.
Не думайте, что «это не имеет значения».

4. Понимание зависимостей

Какие еще компоненты для этого нужны?
Какие настройки, конфиг, окружение?
Какие предположения это делает?

Этап 3: гипотеза и проверка

Научный метод:

1. Сформируйте единую гипотезу

Четко сформулируйте: «Я думаю, что X является основной причиной, потому что Y»
Запиши это
Будьте конкретны, а не расплывчаты.

2. Тестируйте минимально

Внесите МАЛЕНЬКОЕ возможное изменение, чтобы проверить гипотезу.
Одна переменная за раз
Не чините несколько вещей одновременно

3. Проверьте, прежде чем продолжить

Это сработало? → Этап 4
Не сработало? → Сформировать НОВУЮ гипотезу
НЕ добавляйте больше исправлений сверху.

4. Когда ты не знаешь

Скажите: «Я не понимаю X»
Не притворяйся, что знаешь
Попросить пользователя о помощи
Исследуйте больше

Этап 4: Реализация

Устраняйте причину, а не симптом:

1. Создайте неудачный тестовый пример

Простейшее возможное воспроизведение
Автоматический тест, если это возможно.
ОБЯЗАТЕЛЬНО иметь перед ремонтом
Используйте навык «разработки через тестирование».

2. Внедрение одного исправления

Устранить выявленную основную причину
ОДНО изменение за раз
Никаких улучшений «пока я здесь»
Никакого комплексного рефакторинга

3. Проверьте исправление

# Run the specific regression test
pytest tests/test_module.py::test_regression -v

# Run full suite — no regressions
pytest tests/ -q

4. Если исправление не работает — правило трех

СТОП.
Подсчитайте: сколько исправлений вы попробовали?
Если < 3. Вернитесь к этапу 1, повторите анализ с новой информацией.
Если ≥ 3: ОСТАНОВИТЕСЬ и проверьте архитектуру (шаг 5 ниже)
НЕ пытайтесь исправить № 4 без обсуждения архитектуры.

5. Если не удалось исправить 3+ исправлений: архитектура вопроса

Шаблон, указывающий на архитектурную проблему: - Каждое исправление показывает новое общее состояние/связь в другом месте. - Для реализации исправлений требуется «массовый рефакторинг». - Каждое исправление создает новые симптомы в другом месте.

СТОП и вопросы к основам: - Эта закономерность принципиально обоснована? - Мы «держимся этого по чистой инерции»? - Должны ли мы реорганизовать архитектуру или продолжать исправлять симптомы?

Обсудите с пользователем, прежде чем пытаться исправить ситуацию.

Это НЕ неудачная гипотеза — это неправильная архитектура.

Красные флажки — ОСТАНОВИТЕСЬ и следуйте процессу

Если вы поймаете себя на мысли: - «Пока быстрое решение, разберёмся позже» - «Просто попробуйте изменить X и посмотрите, сработает ли это» - «Добавить несколько изменений, запустить тесты» - «Пропустите тест, я проверю вручную» - «Наверное, это Х, позвольте мне это исправить» - «Я не совсем понимаю, но это может сработать» - «Шаблон говорит X, но я адаптирую его по-другому» - «Вот основные проблемы: [перечисляет исправления без исследования]» - Предложение решений перед отслеживанием потока данных. - "Еще одна попытка исправления" (когда уже пробовали 2+) - Каждое исправление обнаруживает новую проблему в другом месте

ВСЕ это означает: СТОП. Вернитесь к этапу 1.

Если не удалось исправить более 3 исправлений: Проверьте архитектуру (этап 4, шаг 5).

Распространенные рационализации

Извините	Реальность
«Проблема проста, не нужен процесс»	У простых проблем тоже есть коренные причины. Процесс быстрый для простых ошибок.
«Чрезвычайная ситуация, нет времени на процесс»	Систематическая отладка происходит БЫСТРЕЕ, чем переборка методом догадок и проверок.
«Сначала попробуйте, а потом исследуйте»	Первое исправление устанавливает шаблон. Сделайте это с самого начала.
«Я напишу тест после подтверждения работы исправления»	Непроверенные исправления не приживаются. Тест сначала это доказывает.
«Несколько исправлений одновременно экономят время»	Не могу выделить то, что сработало. Вызывает новые ошибки.
«Ссылка слишком длинная, адаптирую шаблон»	Частичное понимание гарантирует ошибки. Прочтите полностью.
«Я вижу проблему, позвольте мне ее решить»	Видеть симптомы ≠ понимать первопричину.
«Еще одна попытка исправления» (после 2+ неудач)	3+ неудачи = архитектурная проблема. Ставьте под сомнение шаблон, не исправляйте его снова.

Краткий справочник

Фаза	Ключевые виды деятельности	Критерии успеха
1. Основная причина	Чтение ошибок, воспроизведение, проверка изменений, сбор доказательств, отслеживание потока данных	Понять ЧТО и ПОЧЕМУ
2. Узор	Найдите рабочие примеры, сравните, выявите различия	Знайте, что отличается
3. Гипотеза	Теория форм, проверяйте минимум, по одной переменной за раз	Подтвержденная или новая гипотеза
4. Реализация	Создать регрессионный тест, устранить основную причину, проверить	Ошибка устранена, все тесты пройдены

Интеграция агента Гермеса

Инструменты расследования

Используйте эти инструменты Hermes на этапе 1:

search_files — поиск строк ошибок, отслеживание вызовов функций, поиск шаблонов.
read_file — Чтение исходного кода с номерами строк для точного анализа.
terminal — Запуск тестов, проверка истории git, воспроизведение ошибок
web_search/web_extract — Исследуйте сообщения об ошибках, библиотечную документацию.

С делегатом_задачи

Для сложной многокомпонентной отладки отправляйте субагенты расследования:

delegate_task(
    goal="Investigate why [specific test/behavior] fails",
    context="""
    Follow systematic-debugging skill:
    1. Read the error message carefully
    2. Reproduce the issue
    3. Trace the data flow to find root cause
    4. Report findings — do NOT fix yet

    Error: [paste full error]
    File: [path to failing code]
    Test command: [exact command]
    """,
    toolsets=['terminal', 'file']
)

С разработкой через тестирование

При исправлении ошибок: 1. Напишите тест, воспроизводящий ошибку (КРАСНЫЙ). 2. Систематически проводите отладку, чтобы найти основную причину. 3. Устраните основную причину (ЗЕЛЕНЫЙ) 4. Тест подтверждает исправление и предотвращает регрессию.

Влияние на реальный мир

Из сеансов отладки: - Системный подход: 15-30 минут на исправление - Случайный подход к исправлениям: 2-3 часа возни. - Процент исправлений с первого раза: 95% против 40% - Введены новые ошибки: около нуля против обычных.

** Никаких ярлыков. Никаких догадок. Системность всегда побеждает.**