systematic-debugging

systematic-debugging — навык для разбора любой технической проблемы до внесения исправления: ошибки тестов, production-баги, неожиданное поведение, проблемы производительности, сборки и интеграций. Его центральное правило — сначала найти первопричину, а не маскировать симптом. Поэтому навык не предлагает начинать с очевидного патча: если первая фаза расследования не завершена, исправление ещё не считается обоснованным. Первая из четырёх фаз — исследование первопричины. Сначала нужно полностью прочитать сообщение об ошибке и stack trace, зафиксировать пути, номера строк и коды. Затем проблему следует воспроизвести с точными шагами; если она непостоянна, навык требует собрать дополнительные данные вместо догадки. После этого проверяются недавние изменения: diff, новые зависимости, конфигурация и различия среды. Для системы из нескольких компонентов предлагается добавить наблюдение на каждой границе, записать вход и выход данных, проверить передачу конфигурации и состояние каждого слоя. При глубокой ошибке нужно проследить поток значения назад до места, где оно стало неверным. Вторая фаза — поиск закономерности. Полезно найти похожий рабочий пример в том же коде, полностью прочитать эталонную реализацию, перечислить различия и проверить зависимости, настройки и предположения. Третья фаза превращает наблюдение в проверяемую гипотезу: формулируется одно конкретное объяснение, выбирается минимальный тест и меняется только одна переменная. Успех нужно проверить до перехода дальше; неудача означает новую гипотезу, а не наращивание нескольких исправлений поверх старого. Четвёртая фаза — реализация. Сначала создаётся простейший failing test или воспроизводимый сценарий, затем вносится одно исправление первопричины без сопутствующего рефакторинга. После этого проверяются тесты, отсутствие регрессий и реальное исчезновение проблемы. Если исправление не помогло, процесс возвращается к расследованию. После трёх и более неудачных попыток навык предлагает остановиться и обсудить архитектуру: повторяющаяся связь между компонентами может быть системной причиной, а не серией независимых симптомов. Практическая ценность навыка — в порядке действий и критериях остановки: читать факты, воспроизводить, сравнивать рабочее и сломанное, формулировать одну гипотезу, проверять её малым экспериментом и только потом менять код. Ограничение также явно задано источником: этот workflow требует доступа к ошибкам, истории изменений, окружению и минимальному воспроизводимому тесту. Он не обещает автоматическое исправление и не заменяет специализированный тестовый процесс; его задача — не дать поспешному патчу скрыть источник сбоя или создать новые симптомы.