«Почини, тут что-то сломалось» — и агент лепит заплатку, а баг возвращается. Отладка — это метод, а не угадайка. Разберём, что дать агенту на входе и как заставить его искать корневую причину, а не симптом.
Когда что-то падает, рука сама тянется написать агенту «почини, тут ошибка». Иногда срабатывает. Чаще — Claude навешивает локальную заплатку, баг исчезает с экрана, а через день вылезает в другом месте, потому что настоящая причина так и осталась нетронутой. Отладка — это дисциплина: дать факты, найти источник, починить именно его, проверить. Этот гайд про то, как гонять Claude Code по этому маршруту, а не по угадайке.
Что узнаешь из гайда
Часть 1 · Проблема
Главное
Без фактуры агент гадает. «Почини, тут ошибка» не говорит, где упало и как повторить, поэтому Claude хватается за ближайшую заплатку, а не за источник.
Расшифруем пару слов для тех, кто из вайбкодинга. Баг — это поведение программы, которого ты не ждал: упало, выдало не то, зависло. Отладка (дебаг) — процесс поиска причины бага и его исправления. Стек-трейс — список вызовов функций в момент падения; он показывает точное место, где код споткнулся.
Когда ты пишешь голое «почини», агент видит только что «плохо», но не видит ни где, ни как воспроизвести. Дальше он делает разумное в условиях неизвестности: предполагает причину и лепит локальную защиту вокруг места, которое кажется виноватым. Симптом уходит — причина остаётся. Отсюда правило: отладка начинается не с просьбы починить, а с подачи фактов.
Агент чинит ровно то, что ты ему показал. Покажи симптом — получишь заплатку.
Часть 2 · Вход
Главное
Три вещи решают почти всё: полный текст ошибки со стек-трейсом, команда воспроизведения и пометка, баг стабильный или плавающий.
Стек-трейс показывает, где упало. Команда воспроизведения даёт агенту способ повторить баг самому и проверить фикс. Пометка про стабильность подсказывает направление: стабильный баг — это логика, плавающий — часто гонка, состояние окружения или зависимость от данных. Вот как выглядит хороший промт на отладку:
Падает при сохранении профиля. Ошибка и стек-трейс:
TypeError: Cannot read properties of undefined (reading 'id')
at saveProfile (app/actions/profile.ts:42)
at handleSubmit (components/profile-form.tsx:88)
Воспроизводится так: открыть /profile, очистить поле «город»,
нажать «Сохранить». Баг стабильный, повторяется каждый раз.
Найди корневую причину и почини её, а не симптом.
Сначала покажи, где источник, потом правь.Заметь последние две строки: просьба найти именно корневую причину и показать источник до правки. Это и отделяет отладку от угадайки. Подробнее про то, как вообще формулировать задачи агенту, — в гайде про промптинг для Claude Code.
Важно
Не пересказывай ошибку своими словами — копируй текст и стек-трейс целиком. «Что-то с профилем не сохраняется» и точный TypeError с номером строки — это два разных уровня входных данных. Агент работает ровно настолько точно, насколько точен след, который ты ему дал.
Часть 3 · Причина
Главное
Корневая причина — настоящий источник бага, а не место, где он проявился. Ошибка часто вылетает в одном месте, а виновата правка слоем выше.
Разберём на примере выше. Ошибка вылетает в saveProfile на строке 42: код читает .id у чего-то, что оказалось undefined. Соблазн — обернуть это место проверкой «если не undefined». Симптом уйдёт. Но почему туда вообще пришёл undefined? Может, форма отправляет пустой город как undefined вместо пустой строки, и корень — в компоненте формы, а не в экшене сохранения.
| Подход | Что делает | Чем кончится |
|---|---|---|
| Заплатка | Глушит симптом в месте падения | Баг вернётся в другом виде |
| Корневой фикс | Чинит источник слоем выше | Класс багов закрыт |
Поэтому в промт и зашивают «найди и почини корневую причину, заплатки в дочернем коде не предлагай». А чтобы агент не лез сразу править — просят сначала показать цепочку: вот источник, вот доказательство. Удобно делать это в режиме плана — пусть распишет диагноз до того, как тронет файлы.
На сложном баге проси Claude думать тщательнее — для этого в формулировку добавляют слова вроде «подумай как следует» (расширенное мышление). Агент выделит больше внимания на анализ цепочки вызовов и реже схватится за первую попавшуюся гипотезу.
Часть 4 · Маршрут
Хорошая отладка идёт по одному и тому же маршруту — от ошибки до проверенного фикса. Это ровно тот путь, которым работает встроенный у Claude Code разбор багов: захватить ошибку, воспроизвести, изолировать, починить минимально, проверить.
Пример: отдельный «дебаггер»
Этот маршрут можно зашить в субагента-дебаггера: отдельный агент, который всегда работает по схеме «захвати ошибку → воспроизведи → изолируй → минимальный фикс → проверь» и в ответе даёт причину, доказательство и тест. Как заводить таких — в гайде про субагентов Claude Code.
Коротко
Часть 5 · Проверка
Главное
Фикс не готов, пока не воспроизведён повторно: баг ушёл, соседнее не сломалось. «Должно работать» — это не проверка.
Главная ловушка — поверить агенту на слово. Он говорит «починил», но проверка — это прогон тех же шагов воспроизведения, что упали в начале. Поэтому команду воспроизведения дают не только для диагноза, но и для верификации: тот же путь, теперь без ошибки.
# После фикса проси повторить тот же путь и прогнать проверки:
Повтори шаги воспроизведения и убедись, что баг ушёл.
Прогони тесты и линт. Покажи, что соседнее не отвалилось.Когда отладку агенту не доверяют
Не отдавай агенту вслепую баги в чувствительных местах — оплата, права доступа, безопасность, удаление данных. Тут фикс читают глазами всегда, даже если тесты зелёные. И не принимай правку, где причина «непонятна, но теперь работает»: это не починенный баг, а отложенный. Работай на ветке, чтобы любую правку можно было откатить — об этом гайд про безопасный воркфлоу с Git.
Коротко
Вопросы
Отладка с Claude Code — это не «почини, тут что-то сломалось», а структурный разбор: даёшь агенту текст ошибки, стек-трейс и команду, которой баг воспроизводится, и просишь найти корневую причину, а не залатать симптом. Claude умеет трассировать проблему по коду от сообщения об ошибке до её источника, объяснить причину и предложить минимальный фикс. Чем больше фактуры на входе, тем точнее диагноз.
Дай три вещи: полный текст ошибки со стек-трейсом, шаги или команду воспроизведения и уточнение, баг стабильный или плавающий. Стек-трейс показывает, где упало; шаги воспроизведения позволяют агенту повторить проблему; пометка про стабильность подсказывает, искать ли гонку или состояние окружения. Без этого агент гадает, с этим — трассирует по реальному следу.
Корневая причина — это настоящий источник бага, а не место, где он проявился. Часто ошибка вылетает в одном месте, а виновата правка слоем выше: неверные данные, пропущенная проверка, сломанный контракт. Если чинить симптом локальной заплаткой, баг вернётся в другом виде. Поэтому Claude Code просят найти и исправить именно корневую причину, а заплатки в дочернем коде — отклонять.
Прямо проси чинить корневую причину, а не симптом, и требуй объяснить диагноз перед правкой. Полезная схема — сначала режим плана: пусть агент покажет, где он видит источник и почему, и только потом правит. Так ты отлавливаешь случаи, когда он хочет повесить try/catch вокруг симптома вместо того, чтобы исправить причину уровнем выше. Фикс принимают только с понятной цепочкой «вот источник, вот доказательство».
Читать дальше
Отладка, промптинг, безопасный Git и субагенты — это рабочая база, на которой стоит ИИ-офис. Разборы реальных багов и живое сообщество вайбкодеров — в Telegram.
Зайти в Telegram ИИ-офисаА готовые навыки для Claude Code — в маркетплейсе скилов.