Отладка с Claude Code: от симптома к root cause

Сильная отладка начинается не с редактирования, а с воспроизводимого симптома и цепочки доказательств до первопричины.

Краткий ответ

Сильная отладка начинается не с редактирования, а с воспроизводимого симптома и цепочки доказательств до первопричины. Claude Code удобен тем, что может запустить падающую команду, изучить стек, проследить данные по нескольким файлам и закрепить исправление тестом.

Зафиксируйте наблюдаемое поведение

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

Официальный workflow предлагает сначала поделиться ошибкой, затем запросить варианты исправления и только после выбора применить решение.

Сузьте область экспериментов

Попросите агента найти минимальный воспроизводимый путь. Временно добавленные логи должны отвечать конкретному вопросу и быть удалены из production-кода, если не несут постоянной наблюдаемости. Меняйте одну переменную за раз: иначе неизвестно, какое действие повлияло на результат.

Для каждого вывода полезно спрашивать: «Какие данные это подтверждают и что могло бы его опровергнуть?»

Исправляйте причину, а не маскируйте симптом

Повторный retry, лишняя проверка на null или увеличенный timeout могут скрыть дефект. Root cause объясняет весь наблюдаемый сценарий и предсказывает поведение после изменения. Если агент предлагает несколько вариантов, сравните их по корректности, области и риску регрессии.

Regression-тест

Лучший тест падает на прежней реализации по той же причине, что и пользовательский сценарий, и проходит после минимального исправления. Он не должен быть привязан к случайной внутренней детали. После него запустите соседние проверки: первопричина могла затрагивать общую функцию.

Практика: диагностический prompt

> Команда npm test падает с приложенным стеком только при повторном запуске набора. Сначала воспроизведи и установи, какое состояние протекает между тестами. Не меняй код до подтверждённой причины. Предложи два варианта, выбери минимальный, добавь regression-тест и покажи результаты одиночного и повторного запуска.

Оцените, доказана ли именно утечка состояния.

Частые вопросы

Стоит ли сразу просить «починить ошибку»?

Для простой локальной проблемы это допустимо, но в критериях всё равно нужны воспроизведение и проверка. Для сложной ошибки лучше явно отделить исследование.

Что делать с огромным логом?

Сохранить его в файл, указать временной диапазон и ключевой симптом, затем использовать поиск и выборочное чтение вместо вставки всего вывода.

Если тест проходит один раз, исправление готово?

Не обязательно. Для плавающего дефекта нужны повторения, контроль конкурентности или детерминированный тест причины.

Что важно запомнить

Симптом, гипотеза и root cause — разные сущности.
Минимальное воспроизведение сокращает пространство поиска.
Исправление должно объяснять весь сценарий.
Regression-тест сохраняет найденное знание в проекте.

https://yadro-code.ru/lessons/without-university/claude-code-workflows/claude-code-15