На этой странице 4-фазная отладка первопричин: понимай ошибки до их исправления.
Метаданные навыка¶
| |
|---|---
|Источник| Встроенный (устанавливается по умолчанию)
|Путь| skills/software-development/systematic-debugging
|Версия| 1.1.0
|Автор| Hermes Agent (адаптировано из obra/superpowers)
|Лицензия| MIT
|Теги| debugging, troubleshooting, problem-solving, root-cause, investigation
|Связанные навыки| test-driven-development, writing-plans, subagent-driven-development
Справочник: полный SKILL.md¶
info Ниже приведено полное определение навыка, которое Hermes загружает при его активации. Это те инструкции, которые видит агент, когда навык активен.
Систематическая отладка¶
Обзор¶
Случайные исправления тратят время и создают новые ошибки. Быстрые заплатки маскируют глубинные проблемы. Основной принцип: ВСЕГДА находи первопричину, прежде чем пытаться исправить. Устранение симптомов — это провал. Нарушение буквы этого процесса означает нарушение духа отладки.
Железный закон¶
[code] НИКАКИХ ИСПРАВЛЕНИЙ БЕЗ ПРЕДВАРИТЕЛЬНОГО РАССЛЕДОВАНИЯ ПРИЧИН
[/code] Если вы не завершили Фазу 1, вы не можете предлагать исправления.
Когда использовать¶
Используйте для ЛЮБОЙ технической проблемы: * Падения тестов * Ошибки в продакшене * Неожиданное поведение * Проблемы с производительностью * Ошибки сборки * Проблемы интеграции
Используйте это ОСОБЕННО когда: * Цейтнот (в чрезвычайных ситуациях велик соблазн гадать) * «Одно быстрое исправление» кажется очевидным * Вы уже пробовали несколько исправлений * Предыдущее исправление не сработало * Вы не до конца понимаете проблему
Не пропускайте когда: * Проблема кажется простой (у простых ошибок тоже есть первопричины) * Вы спешите (поспешность гарантирует переделки) * Кто-то хочет, чтобы это было исправлено СЕЙЧАС (системный подход быстрее, чем хаотичные попытки)
Четыре фазы¶
Вы ДОЛЖНЫ завершить каждую фазу, прежде чем переходить к следующей.
Фаза 1: Расследование первопричины¶
ДО того, как пытаться ЧТО-ЛИБО исправить:
1\. Внимательно читайте сообщения об ошибках¶
- Не пропускайте ошибки и предупреждения
- Они часто содержат точное решение
- Читайте stack trace полностью
- Запоминайте номера строк, пути к файлам, коды ошибок
Действие: Используйте read_file для соответствующих исходных файлов. Используйте search_files для поиска строки ошибки в кодовой базе.
2\. Воспроизводите стабильно¶
- Можете ли вы вызвать её надёжно?
- Каковы точные шаги?
- Происходит ли это каждый раз?
- Если невоспроизводимо → собирайте больше данных, не гадайте
Действие: Используйте инструмент terminal для запуска падающего теста или воспроизведения ошибки:
[code]
# Запуск конкретного падающего теста
pytest tests/test_module.py::test_name -v
# Запуск с подробным выводом
pytest tests/test_module.py -v --tb=long
[/code]
3\. Проверьте недавние изменения¶
- Что изменилось, что могло это вызвать?
- Git diff, недавние коммиты
- Новые зависимости, изменения конфигурации
Действие:
[code]
# Недавние коммиты
git log --oneline -10
# Неотслеживаемые изменения
git diff
# Изменения в конкретном файле
git log -p --follow src/problematic_file.py | head -100
[/code]
4\. Собирайте улики в многокомпонентных системах¶
КОГДА система состоит из нескольких компонентов (API → сервис → БД, CI → сборка → развёртывание): ДО предложения исправлений добавьте диагностическую инструментовку: Для КАЖДОЙ границы компонента: * Логируйте, какие данные входят в компонент * Логируйте, какие данные выходят из компонента * Проверяйте распространение окружения/конфигурации * Проверяйте состояние на каждом уровне
Запустите один раз для сбора улик, показывающих, ГДЕ происходит сбой. ЗАТЕМ проанализируйте улики, чтобы определить отказавший компонент. ЗАТЕМ расследуйте этот конкретный компонент.
5\. Трассируйте поток данных¶
КОГДА ошибка находится глубоко в стеке вызовов: * Откуда берётся неверное значение? * Какая функция вызвала эту функцию с неверным значением? * Продолжайте трассировку вверх по потоку, пока не найдёте источник * Исправляйте в источнике, а не в симптоме
Действие: Используйте search_files для трассировки ссылок:
[code]
# Найдите, где вызывается функция
search_files("function_name(", path="src/", file_glob="*.py")
# Найдите, где устанавливается переменная
search_files("variable_name\\s*=", path="src/", file_glob="*.py")
[/code]
Контрольный список завершения Фазы 1¶
- Сообщения об ошибках полностью прочитаны и поняты
- Проблема стабильно воспроизведена
- Недавние изменения выявлены и проверены
- Улики собраны (логи, состояние, поток данных)
- Проблема локализована до конкретного компонента/кода
- Сформулирована гипотеза о первопричине
СТОП: Не переходите к Фазе 2, пока не поймёте, ПОЧЕМУ это происходит.
Фаза 2: Анализ паттернов¶
Найдите паттерн перед исправлением:
1\. Найдите работающие примеры¶
- Найдите похожий работающий код в той же кодовой базе
- Что работает, что похоже на то, что сломано?
Действие: Используйте search_files для поиска сопоставимых паттернов:
[code]
search_files("similar_pattern", path="src/", file_glob="*.py")
[/code]
2\. Сравните с эталонами¶
- Если реализуете паттерн, прочитайте эталонную реализацию ПОЛНОСТЬЮ
- Не просматривайте по диагонали — читайте каждую строку
- Полностью поймите паттерн перед применением
3\. Выявите различия¶
- Что отличается между работающим и сломанным?
- Перечислите все различия, какими бы малыми они ни были
- Не предполагайте, что «это не может иметь значения»
4\. Поймите зависимости¶
- Какие другие компоненты нужны этому?
- Какие настройки, конфигурация, окружение?
- Какие предположения он делает?
Фаза 3: Гипотеза и тестирование¶
Научный метод:
1\. Сформулируйте одну гипотезу¶
- Сформулируйте чётко: «Я думаю, что X является первопричиной, потому что Y»
- Запишите её
- Будьте конкретны, не расплывчаты
2\. Тестируйте минимально¶
- Сделайте НАИМЕНЬШЕЕ возможное изменение для проверки гипотезы
- Одну переменную за раз
- Не исправляйте несколько вещей одновременно
3\. Проверяйте перед продолжением¶
- Сработало? → Фаза 4
- Не сработало? → Сформулируйте НОВУЮ гипотезу
- НЕ добавляйте новые исправления поверх
4\. Когда вы не знаете¶
- Скажите «Я не понимаю X»
- Не притворяйтесь, что знаете
- Попросите пользователя о помощи
- Исследуйте дальше
Фаза 4: Реализация¶
Исправляйте первопричину, а не симптом:
1\. Создайте падающий тестовый пример¶
- Максимально простое воспроизведение
- Автоматизированный тест, если возможно
- ОБЯЗАТЕЛЬНО до исправления
- Используйте навык
test-driven-development
2\. Реализуйте одно исправление¶
- Устраните выявленную первопричину
- ОДНО изменение за раз
- Никаких улучшений «пока я здесь»
- Никакого совмещённого рефакторинга
3\. Проверьте исправление¶
[code]
# Запуск конкретного регрессионного теста
pytest tests/test_module.py::test_regression -v
# Полный прогон — без регрессий
pytest tests/ -q
[/code]
4\. Если исправление не работает — Правило трёх¶
- СТОП.
- Посчитайте: сколько исправлений вы уже попробовали?
- Если < 3: Вернитесь к Фазе 1, проанализируйте заново с новой информацией
- Если ≥ 3: СТОП и поставьте под вопрос архитектуру (шаг 5 ниже)
- НЕ пытайтесь сделать Исправление №4 без архитектурного обсуждения
5\. Если 3+ исправлений не сработали: Поставьте под вопрос архитектуру¶
Признак, указывающий на архитектурную проблему: * Каждое исправление выявляет новое общее состояние/связь в другом месте * Исправления требуют «масштабного рефакторинга» для реализации * Каждое исправление создаёт новые симптомы в другом месте
СТОП и поставьте под вопрос основы: * Здоров ли этот паттерн в принципе? * «Мы продолжаем его использовать просто по инерции»? * Стоит ли отрефакторить архитектуру вместо продолжения исправления симптомов?
Обсудите с пользователем, прежде чем пытаться сделать ещё исправления. Это НЕ провал гипотезы — это неправильная архитектура.
Красные флаги — СТОП и следуйте процессу¶
Если вы ловите себя на мысли: * «Быстрое исправление сейчас, расследование потом» * «Просто попробую изменить X и посмотреть, сработает ли» * «Внесу несколько изменений, запущу тесты» * «Пропущу тест, проверю вручную» * «Вероятно, это X, давайте исправим это» * «Я не до конца понимаю, но это может сработать» * «Паттерн говорит X, но я адаптирую его иначе» * «Вот основные проблемы: [перечисляет исправления без расследования]» * Предлагать решения до трассировки потока данных * «Ещё одна попытка исправления» (когда уже пробовали 2+) * Каждое исправление выявляет новую проблему в другом месте
ВСЁ это означает: СТОП. Вернитесь к Фазе 1. Если 3+ исправлений не сработали: Поставьте под вопрос архитектуру (Фаза 4, шаг 5).
Частые оправдания¶
| Оправдание | Реальность |
|---|---|
| «Проблема простая, процесс не нужен» | У простых проблем тоже есть первопричины. Для простых ошибок процесс быстр. |
| «Чрезвычайная ситуация, нет времени на процесс» | Систематическая отладка БЫСТРЕЕ, чем хаотичные догадки. |
| «Просто попробую это сначала, потом расследую» | Первое исправление задаёт паттерн. Делайте правильно с самого начала. |
| «Напишу тест после подтверждения, что исправление работает» | Непроверенные исправления недолговечны. Тест сначала доказывает его. |
| «Несколько исправлений сразу экономит время» | Невозможно изолировать, что сработало. Создаёт новые ошибки. |
| «Эталон слишком длинный, я адаптирую паттерн» | Частичное понимание гарантирует ошибки. Читайте его полностью. |
| «Я вижу проблему, давайте исправлю» | Видеть симптомы ≠ понимать первопричину. |
| «Ещё одна попытка исправления» (после 2+ неудач) | 3+ неудачи = архитектурная проблема. Поставьте под вопрос паттерн, не исправляйте снова. |
| ## Краткий справочник | |
| Фаза | Ключевые действия |
| --- | --- |
| 1. Первопричина | Читать ошибки, воспроизвести, проверить изменения, собрать улики, трассировать поток данных |
| 2. Паттерн | Найти работающие примеры, сравнить, выявить различия |
| 3. Гипотеза | Сформулировать теорию, тестировать минимально, одну переменную за раз |
| 4. Реализация | Создать регрессионный тест, исправить первопричину, проверить |
| ## Интеграция с Hermes Agent | |
| ### Инструменты расследования | |
| Используйте эти инструменты Hermes во время Фазы 1: | |
* search_files — Поиск строк ошибок, трассировка вызовов функций, поиск паттернов |
|
* read_file — Чтение исходного кода с номерами строк для точного анализа |
|
* terminal — Запуск тестов, проверка git-истории, воспроизведение ошибок |
|
* web_search/web_extract — Исследование сообщений об ошибках, документации библиотек |
С delegate_task¶
Для сложной отладки многокомпонентных систем назначайте подзадачи расследования:
[code]
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']
)
[/code]
С test-driven-development¶
При исправлении ошибок: 1. Напишите тест, который воспроизводит ошибку (RED) 2. Отлаживайте систематически, чтобы найти первопричину 3. Исправьте первопричину (GREEN) 4. Тест доказывает исправление и предотвращает регрессию
Реальное влияние¶
Из сессий отладки: * Систематический подход: 15–30 минут на исправление * Подход случайных исправлений: 2–3 часа хаотичных попыток * Процент успеха с первой попытки: 95% против 40% * Новые ошибки: почти ноль против частых
Никаких сокращений. Никаких догадок. Систематический подход всегда побеждает. * Метаданные навыка * Справочник: полный SKILL.md * Обзор * Железный закон * Когда использовать * Четыре фазы * Фаза 1: Расследование первопричины * 1\. Внимательно читайте сообщения об ошибках * 2\. Воспроизводите стабильно * 3\. Проверьте недавние изменения * 4\. Собирайте улики в многокомпонентных системах * 5\. Трассируйте поток данных * Контрольный список завершения Фазы 1 * Фаза 2: Анализ паттернов * 1\. Найдите работающие примеры * 2\. Сравните с эталонами * 3\. Выявите различия * 4\. Поймите зависимости * Фаза 3: Гипотеза и тестирование * 1\. Сформулируйте одну гипотезу * 2\. Тестируйте минимально * 3\. Проверяйте перед продолжением * 4\. Когда вы не знаете * Фаза 4: Реализация * 1\. Создайте падающий тестовый пример * 2\. Реализуйте одно исправление * 3\. Проверьте исправление * 4\. Если исправление не работает — Правило трёх * 5\. Если 3+ исправлений не сработали: Поставьте под вопрос архитектуру * Красные флаги — СТОП и следуйте процессу * Частые оправдания * Краткий справочник * Интеграция с Hermes Agent * Инструменты расследования * С delegate_task * С test-driven-development * Реальное влияние