Как искать баг с Claude Code: от симптома до проверенного исправления

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

Разберём учебную ошибку интернет-магазина. Корзина стоит 5000 рублей, скидка составляет 15%, ожидаемый итог — 4250 рублей. В одном сценарии интерфейс показывает 0. Все данные, имена функций и фрагменты вывода ниже иллюстрируют метод. Фактическую причину в вашем проекте нужно устанавливать по его коду и наблюдениям.

Сначала соберите карточку сбоя

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

В нашем примере карточка выглядит так:

Поле	Учебные данные
Окружение	Тестовый магазин, текущая проверяемая версия
Шаги	Положить товар на 5000 ₽, применить промокод на 15%, открыть оформление
Ожидание	Итог 4250 ₽ без доставки
Факт	В интерфейсе итог 0 ₽
Повторяемость	С промокодом; без него итог 5000 ₽
Доказательства	Ответ API, время, идентификатор запроса, очищенный лог

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

Первый промпт:

Изучи карточку сбоя и связанные файлы. На этом этапе только исследование. Проследи путь суммы: позиции корзины → скидка → ответ API → состояние интерфейса → отображение.

Для каждого этапа укажи файл, функцию и ожидаемый формат значения. Раздели подтверждённые факты, гипотезы и недостающие данные. Предложи самый короткий эксперимент, который различит основные гипотезы.

Рабочий процесс от описания ошибки к исследованию и проверке приведён также в документации Claude Code. Агенту всё равно нужны доступ к нужной версии проекта и реальные входные данные.

Найдите первую границу, где меняется значение

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

В учебном сценарии предположим, что API возвращает { "total": 4250 }, а компонент читает response.totalAmount и подставляет ноль при отсутствии значения. Такой случай объясняет симптом. Но до просмотра фактического ответа и кода это только гипотеза.

Попросите Claude назвать доказательство для каждого вывода. «В коде есть значение по умолчанию» — наблюдение. «Именно оно сработало при данном запросе» — вывод, для которого нужен воспроизводимый запуск или узкий тест.

Полезный образец промежуточного отчёта:

Подтверждено: ответ тестового API содержит total = 4250.
Подтверждено: компонент читает totalAmount.
Гипотеза: отсутствующее поле приводит к резервному значению 0.
Проверка: передать зафиксированный ответ в функцию разбора и сравнить результат.

Такой отчёт помогает остановить преждевременную правку формулы скидки. Следующий шаг уже связан с конкретной границей данных.

Читайте stack trace вместе с вызывающим кодом

Stack trace показывает последовательность вызовов в момент ошибки. Начните с первого относящегося к приложению файла: откройте функцию, её вызывающую сторону и тип входных данных. Строка падения обозначает место обнаружения проблемы; некорректное значение могло появиться раньше.

Например, Cannot read properties of undefined при обращении к заказу требует выяснить, как заказ загружался. Возможны пустой ответ, ошибка авторизации, пропущенное поле или гонка запросов. Проверка наличия значения полезна, когда вы определили ожидаемое поведение для такого состояния.

Для TypeScript действуйте аналогично. Если параметр имеет тип string | undefined, найдите сценарий отсутствия строки и решите, что должна сделать система. Явная проверка значения позволяет уточнить тип; механизм называется narrowing и описан в руководстве TypeScript.

В примере магазина поле итоговой суммы должно быть обязательным в успешном ответе. Отсутствие поля разумно обрабатывать как ошибку контракта с понятным состоянием интерфейса. Выбор конкретного поведения зависит от правил проекта и согласуется отдельно.

Добавляйте логи под один вопрос

Если ответа API мало, определите точку наблюдения. Для нашей гипотезы достаточно увидеть названия полей ответа, полученное числовое значение и итог функции разбора. Полная корзина, адрес покупателя и платёжные данные для этого вопроса избыточны.

Для проверки гипотезы предложи узкое временное логирование: идентификатор запроса, имена полей ответа, наличие total, тип и значение суммы на входе и выходе функции разбора.

Используй тестовые данные. Исключи токены, cookies, адреса, контакты и платёжные реквизиты. Сначала покажи точки записи и diff. Укажи, какой вывод подтвердит гипотезу и какой потребует нового направления поиска.

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

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

Исправляйте подтверждённую причину

Допустим, тест функции разбора подтвердил рассогласование полей. Теперь можно менять обработчик ответа и связанные типы. Размер исправления должен следовать причине: смена одного поля иногда достаточна, иногда требуется общая схема проверки ответа на границе API.

До правки зафиксируйте воспроизводящий тест. Он должен получать тот самый формат ответа и проверять сумму 4250. Запуск на исходном коде должен показать ожидаемое падение; после патча тот же тест должен пройти.

На основании подтверждённой причины подготовь минимальное исправление. Добавь регрессионный тест на ответ API с total = 4250. Сначала покажи его падение на исходном коде, затем примени патч и повтори тест.

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

Здесь особенно полезен допустимый нулевой итог. В некоторых магазинах заказ может полностью оплачиваться бонусами. Проверка через простое условие истинности способна спутать корректный 0 с отсутствующим значением. Этот сценарий стоит обсудить через правила продукта.

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

Сборку и производительность проверяйте своими измерениями

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

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

Для медленного каталога, например, полезно отдельно измерить запрос сервера и построение списка. Ускорение компонента принесёт ограниченный эффект, если основное время занимает внешний сервис. Сравнение до и после проводите на сопоставимом наборе товаров.

Закройте исходный пользовательский путь

После целевого теста проверьте связанные проверки проекта, затем повторите карточку сбоя в нужном окружении. В нашем магазине это корзина на 5000 рублей, промокод 15%, итог 4250 и сохранение суммы после перехода к оформлению.

Составь итог проверки исправления. Отдельно укажи: воспроизведение исходного дефекта, регрессионный тест до и после, соседние сценарии, проверку браузера и окружение каждого запуска.

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

Локальный проход позволяет сказать «исправление проверено локально». После выпуска нужна проверка именно той версии и среды, где возникла жалоба, включая свежие логи и фактическое действие пользователя. Финальный ответ поддержки должен опираться на эту последнюю проверку и точно описывать подтверждённый результат.