Триаж ошибок с Claude Code: практический цикл для быстрых исправлений

Что такое триаж ошибок и зачем нужен цикл

Баги кажутся случайными, когда каждый отчёт превращается в разовое расследование. Вы ковыряете код, пробуете несколько идей и надеетесь, что проблема исчезнет. Иногда это срабатывает, но вы мало чему учитесь, и та же проблема появляется снова в другой форме.

Триаж — это противоположность. Это быстрый способ уменьшить неопределённость. Цель не в том, чтобы сразу исправить всё. Цель — превратить смутную жалобу в чёткое тестируемое утверждение, а затем сделать минимальное изменение, которое докажет, что это утверждение стало ложным.

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

Вот реалистичный пример. Пользователь говорит: «Кнопка Сохранить иногда ничего не делает». Без цикла вы могли бы копаться в UI‑коде и менять тайминги, состояние или сетевые вызовы. С циклом вы сначала превращаете «иногда» в «всегда при этих условиях», например: «После редактирования заголовка и быстрого переключения вкладок Сохранить остаётся отключённой». Это уже прогресс.

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

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

Выигрыш — небольшое, безопасное исправление, которое можно объяснить, защитить и удержать от регресса.

Настройте рабочее пространство для триажа (до правки кода)

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

«Когда я делаю X, я ожидаю Y, но получаю Z.»

Если вы не можете написать это, у вас пока не баг — у вас загадка.

Соберите базовую информацию заранее, чтобы не возвращаться к ней снова и снова. Эти детали превращают подсказки в тестируемые, а не в расплывчатые советы: версия приложения или коммит (и где он запускается: локально, стейдж, прод), детали окружения (ОС, браузер/устройство, флаги фич, регион), точные входы (поля формы, тело API, действия пользователя), кто это видит (все, роль, один аккаунт/тенант) и что значит «ожидается» (текст, состояние UI, код статуса, бизнес‑правило).

Затем сохраните доказательства, пока они свежи. Одна метка времени может сэкономить часы. Снимите логи вокруг события (клиент и сервер, если возможно), делайте скриншоты или короткие записи, сохраняйте request ID или trace ID, точные временные метки (с часовым поясом) и самый маленький фрагмент данных, который триггерит проблему.

Пример: сгенерированное Koder.ai React‑приложение показывает «Payment succeeded», но заказ остаётся «Pending». Зафиксируйте роль пользователя, точный ID заказа, тело ответа API и строки серверного лога для того request ID. Теперь вы можете попросить Claude сосредоточиться на одном потоке вместо расплывчатых предположений.

И, наконец, установите правило остановки. Решите, что будет считаться «исправлено», прежде чем начинать кодить: конкретный тест, изменение состояния UI, отсутствие ошибки в логах, плюс короткий чеклист валидации, который вы будете выполнять каждый раз. Это не даст вам «исправить» симптом и выпустить новый баг.

Превратите баг‑репорт в точный вопрос для Claude

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

Начните с однословного резюме, которое называет фичу и отказ. Хорошо: «Сохранение черновика иногда удаляет заголовок на мобильных». Плохо: «Черновики сломаны». Это предложение становится якорем для всего потока триажа.

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

Простая структура, которую можно вставить:

• Резюме (одно предложение)
• Наблюдаемое поведение (что произошло, включая текст ошибки)
• Ожидаемое поведение (что должно было случиться)
• Шаги воспроизведения (пронумерованные, минимальные)
• Окружение (версия/коммит, устройство, ОС, браузер, флаги)

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

Claude также полезен как «очиститель отчётов». Вставьте оригинал (включая текст со скриншотов, логи и фрагменты чатов), затем попросите:

"Перепишите это как структурированный чеклист. Отметьте противоречия. Перечислите топ‑5 недостающих фактов в виде вопросов да/нет. Пока не делайте предположений о причинах."

Если коллега говорит «Он падает случайно», подтолкните его к тестируемости: «Падает 2/10 на iPhone 14, iOS 17.2, при двойном тапе Save». Теперь это можно воспроизвести целенаправленно.

Шаг 1 — Надёжно воспроизведите баг

Если вы не можете заставить баг происходить по требованию, дальнейшие шаги — гадания.

Начните с воспроизведения в наименьшем окружении, которое всё ещё показывает проблему: локальная dev‑сборка, минимальная ветка, крошечный набор данных и как можно меньше сервисов включено.

Запишите точные шаги так, чтобы кто‑то другой мог повторить без вопросов. Сделайте их удобными для копирования: команды, ID и примеры payload‑ов должны быть точными.

Простой шаблон захвата:

• Настройка: ветка/коммит, флаги, состояние БД (пусто, seed, копия прод)
• Шаги: пронумерованные действия с точными входами
• Ожидаемое vs фактическое: что вы ожидали и что случилось
• Доказательства: текст ошибки, скриншоты, временные метки, request ID
• Частота: всегда, иногда, только при первом запуске, только после рефреша

Частота меняет стратегию. «Всегда» — отличные баги для быстрой итерации. «Иногда» часто указывает на тайминг, кеширование, состояния гонки или скрытое состояние.

Когда у вас есть заметки по воспроизведению, попросите Claude предложить быстрые зондовые проверки, которые уменьшат неопределённость без переписывания приложения. Хорошие зонды маленькие: один целевой лог рядом с границей отказа (входы/выходы/ключевое состояние), debug‑флаг для отдельного компонента, способ форсировать детерминизм (фиксированный seed, фиксированное время, один воркер), крошечный seed‑датасет или одиночная пара запрос/ответ для воспроизведения.

Пример: флоу регистрации иногда падает. Claude может предложить логировать сгенерированный ID пользователя, результат нормализации email и детали ошибки уникального ключа, затем прогнать тот же payload 10 раз. Если падение только в первый раз после деплоя — намёк на миграции, подготовку кеша или отсутствие seed‑данных.

Шаг 2 — Минимизируйте до маленького повторяемого кейса

Хорошая репродукция полезна. Минимальная репродукция — мощная. Она ускоряет понимание бага, упрощает отладку и снижает риск «случайного» фикса.

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

Потом уменьшите данные. Если нужен большой payload — попробуйте самый маленький, который всё ещё ломается. Если требуется список из 500 элементов — проверьте 5, потом 2, потом 1. Удаляйте поля по одному. Цель — как можно меньше движущихся частей.

Практический метод — “remove half and retest”:

• Разрежьте шаги наполовину и проверьте
• Если баг остаётся — продолжайте с оставшейся половиной
• Если нет — верните половину и урежьте по‑другому
• Повторяйте, пока нельзя убрать ничего лишнего

Пример: страница оформления заказа иногда падает при применении купона. Вы выясняете, что это происходит только когда в корзине есть хотя бы один товар со скидкой, код купона в нижнем регистре и доставка стоит «самовывоз». Это ваш минимальный кейс: один товар со скидкой, один код в нижнем регистре, опция самовывоза.

Когда минимальный кейс ясен, попросите Claude сделать небольшой scaffold для репродукции: минимальный тест, который вызывает проблемную функцию с маленькими входами, короткий скрипт, который бьёт по одному endpoint с сокращённым payload, или небольшой UI‑тест, посещающий один маршрут и выполняющий одно действие.

Шаг 3 — Определите вероятные корневые причины (с доказательствами)

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

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

Отображение симптомов на компоненты

Переведите то, что вы видите, в то, где это может происходить. UI‑симптом не всегда означает баг в UI.

Пример: React‑страница показывает тост «Saved», но запись потом пропадает. Это может указывать на (1) состояние UI, (2) поведение API или (3) путь записи в БД.

Постройте доказательства для каждой гипотезы

Попросите Claude объяснить вероятные режимы отказа простыми словами, а затем спросите, какое доказательство подтвердит каждую. Цель — превратить «возможно» в «проверь эту конкретную вещь».

Три типичные гипотезы и доказательства, которые нужно собрать:

• Несоответствие UI/состояния: клиент обновляет локальное состояние до подтверждения сервера. Доказательство: снимок состояния до и после действия и сравнение с реальным ответом API.
• Пограничный случай в API: хендлер возвращает 200, но молча не делает работу (валидация, парсинг ID, флаг фич). Доказательство: лог запрос/ответ с correlation ID и проверка, что хендлер дошёл до вызова записи с ожидаемыми входами.
• БД или тайминг: транзакция откатывается, возникает конфликт, или чтение после записи отдаётся из кеша/реплики. Доказательство: просмотр SQL‑запроса, числа затронутых строк и кодов ошибок; логирование границ транзакций и поведения retry.

Держите заметки сжато: симптом, гипотеза, доказательство, вердикт. Когда одна гипотеза совпадает с фактами, можно фиксировать регрессионный тест и править только необходимое.

Шаг 4 — Добавьте регрессионный тест, который падает по нужной причине

Хороший регрессионный тест — ваш ремень безопасности. Он доказывает, что баг существует, и подсказывает, когда вы его действительно исправили.

Начните с выбора наименьшего теста, который соответствует реальной ошибке. Если баг проявляется только при совместной работе нескольких частей, unit‑тест может это пропустить.

Выберите уровень теста, соответствующий багу

Unit‑тест для одной функции. Интеграционный — для границ между частями (хендлер + БД, UI + API). End‑to‑end — только если нужен полный флоу.

Прежде чем просить Claude написать тест, сформулируйте минимальный кейс как строгое ожидаемое поведение. Пример: «Когда пользователь сохраняет пустой заголовок, API должен вернуть 400 с сообщением ‘title required’». Тогда тест имеет ясную цель.

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

Проверьте набросок (не доверяйте вслепую)

Быстро прогоните:

• Убедитесь, что тест падает на текущем коде по ожидаемой причине (а не из‑за отсутствующего фixture или неверного импорта).
• Проверьте, что утверждения специфичны (точный код статуса, сообщение, текст на экране).
• Убедитесь, что тест покрывает один баг, а не набор поведений.
• Название фокусируется на пользовательском опыте: «отклоняет пустой заголовок при сохранении», а не «обрабатывает валидацию».

Когда тест падает по правильной причине, можно смело двигаться к узкому исправлению.

Шаг 5 — Внедрите узкое исправление

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

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

Если вы просите Claude помочь, запросите два варианта исправления и сравните их по охвату и риску. Пример: React‑форма падает на пустом поле —

• Вариант A: добавить guard в submit‑handler и показать ошибку.
• Вариант B: рефакторнуть состояние так, чтобы поле никогда не было пустым.

Вариант A обычно предпочтительнее в триаже: меньше, проще на ревью и с меньшим риском побочных эффектов.

Чтобы сделать исправление узким, затрагивайте минимум файлов, предпочитайте локальные правки рефакторингу, добавляйте guards и валидацию там, где попадает плохое значение, и фиксируйте поведение одним явным до/после. Оставляйте комментарии только если причина неочевидна.

Конкретный пример: Go API паникует, если опциональный query‑param отсутствует. Узкое исправление — обработать пустую строку в handler’е (парсить с дефолтом или возвращать 400 с понятным сообщением). Не меняйте общие утилиты парсинга, пока тест не покажет, что баг действительно там.

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

Шаг 6 — Валидируйте исправление с помощью чётких проверок

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

Сначала прогоните регрессионный тест, который вы добавили. Если он проходит — запустите «ближайших соседей»: тесты в том же файле, модуле и всё, что покрывает те же входы. Баги часто прячутся в общих хелперах, парсинге, граничных проверках или кешировании, так что релевантные падают рядом.

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

Простой чеклист валидации

• регрессионный тест проходит, плюс связанные тесты в той же области
• ручные шаги больше не триггерят баг
• обработка ошибок осталась понятной (сообщения, коды статуса, retry)
• краевые случаи работают (пустой ввод, макс. размер, необычные символы)
• нет явного падения производительности (лишние циклы, лишние вызовы, медленные запросы)

Если хотите помочь себе сфокусироваться, попросите Claude сделать короткий план валидации, основанный на вашем изменении и падающем сценарии. Укажите, какой файл меняли, что хотели изменить и что могло бы пострадать. Лучшие планы — короткие и выполнимые: 5–8 проверок, которые можно закончить за несколько минут.

И, наконец, зафиксируйте, что вы валидировали в PR или заметках: какие тесты запускали, какие ручные шаги пробовали и что не проверяли (например, «мобильная версия не тестировалась»). Это делает исправление более надёжным и понятным в будущем.

Распространённые ошибки и ловушки (и как их избегать)

Самый быстрый способ потерять время — принять «фикс», пока вы не можете воспроизвести баг по требованию. Если вы не можете заставить его падать надёжно, вы не знаете, что именно улучшилось.

Практическое правило: не просите фиксаций, пока не сможете описать повторяемую настройку (точные шаги, входы, окружение и что считается «неправильным»). Если репорт расплывчат — потратьте первые минуты на превращение его в чеклист, который вы можете прогнать дважды и получить одинаковый результат.

Ловушки, которые замедляют

Чинить без воспроизводимого кейса. Требуйте минимального скрипта «падает всегда». Если он «иногда», фиксируйте тайминг, размер данных, флаги и логи, пока он не перестанет быть случайным.

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

Позволять Claude догадываться. Claude может предложить правдоподобные причины, но вам нужны доказательства. Попросите 2–3 гипотезы и точные наблюдения, которые подтвердят или опровергнут каждую (строка лога, breakpoint, результат запроса).

Регрессионные тесты, которые проходят по неправильной причине. Тест может «проходить», потому что он никогда не попадает на проблемный путь. Убедитесь, что тест падал до фикса и падал с ожидаемым сообщением/ассертом.

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

Быстрая проверка перед закрытием

Запустите новый регрессионный тест и оригинальные шаги воспроизведения до и после изменения. Если баг в checkout происходил только при применении промокода после смены доставки — оставьте эту полную последовательность как «истину», даже если минимизированный тест короче.

Если ваша валидация опирается на «выглядит нормально», добавьте одно конкретное подтверждение (лог, метрика или конкретный вывод), чтобы следующий человек быстро проверил результат.

Короткий чеклист, шаблоны промптов и следующие шаги

Когда вы ограничены во времени, маленький повторяемый цикл побеждает героическое дебажение.

Одностраничный чеклист триажа

• Воспроизведите: получите надёжную репроду и зафиксируйте входы, окружение и ожидаемое vs фактическое
• Минимизируйте: сократите до самого малого набора шагов или теста, который ещё падает
• Объясните: перечислите 2–3 вероятные корневые причины и доказательства для каждой
• Зафиксируйте: добавьте регрессионный тест, который падает по правильной причине
• Исправьте и проверьте: сделайте самое узкое изменение и прогоните короткий чеклист валидации

Запишите финальное решение в несколько строчек, чтобы следующий человек (часто вы из будущего) мог доверять ему. Полезный формат: «Root cause: X. Trigger: Y. Fix: Z. Why safe: W. Что мы не меняли: Q.»

Шаблоны промптов, которые можно вставить

• «У меня есть этот баг‑репорт и логи — задавай только недостающие вопросы, нужные для надёжной репродукции.»
• «Помоги минимизировать: предложи меньший тест‑кейс и скажи, что убирать первым, по одному изменению.»
• «Ранжируй вероятные корневые причины и укажи точные файлы, функции или условия, которые это подтверждают.»
• «Напиши регрессионный тест, который падает только из‑за этого бага. Объясни, почему он падает по правильной причине.»
• «Предложи самое узкое исправление и список проверок (unit, integration, manual), которые докажут, что мы не поломали соседние вещи.»

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

Если вы создаёте приложения с Koder.ai (koder.ai), Planning Mode поможет вам наметить изменение до правки кода, а снапшоты/откат упростят эксперименты, пока вы разбираетесь с трудной репродукцией. После валидации можно экспортировать исходники или развернуть обновлённое приложение, в том числе с кастомным доменом, если нужно.