7 приёмов дебаггинга с Claude Code — от «почини баг» до корневой причины за 2 минуты
7 приёмов дебаггинга с Claude Code — от «почини баг» до корневой причины за 2 минуты
Три часа на один баг. Stack trace, который ведёт в никуда. Console.log, который врёт. Фикс, который работает локально и ломается в проде.
Знакомо? Claude Code может свернуть этот цикл до двух минут — но только если перестать писать fix the bug in my app и начать дебажить правильно.
TL;DR: 7 конкретных паттернов дебаггинга с Claude Code: от пайпинга сырых логов вместо пересказа ошибки — до хуков, которые автоматически логируют упавшие команды. Каждый приём с примером промпта и объяснением, когда он не работает.
Почему «fix the bug» не работает
Вот что происходит, когда пишешь Claude Code что-нибудь вроде fix the bug in my app:
- Claude читает каждый файл в проекте
- Тратит тысячи токенов на сканирование
- Галлюцинирует фикс, который чинит симптом, а не причину
По наблюдениям разработчиков на DEV.to, типичные «быстрые фиксы» от AI — это retry-цикл вместо починки таймаута, try/catch без понимания причины, null-чек без выяснения, откуда пришёл null. Все они проходят тесты. Все всплывают в проде в худшем виде.
Дебаггинг с AI — это не «скинь ошибку и жди». Это дисциплина. Вот 7 приёмов, которые её дают.
Приём 1: Хирургический промпт — ошибка + стектрейс + файлы
Вместо описания бага своими словами — дай Claude сырые данные и укажи, куда смотреть:
claude "I have a bug: TypeError: Cannot read properties of undefined (reading 'map'). Stack trace: at UserList.render (src/components/UserList.jsx:23). Here's what I know: the data loads correctly on first render but breaks on refresh. Check src/components/UserList.jsx and src/hooks/useUsers.js"
Три элемента, без которых Claude будет гадать:
- Точное сообщение об ошибке — не «что-то с базой», а полный текст
- Stack trace — весь, не только первую строку
- Подозреваемые файлы — сужают область поиска и экономят токены
По паттернам с DEV.to, этот подход работает потому, что stack trace показывает Claude путь через код, а указание файлов не даёт ему уйти в сканирование всего проекта.
Приём 2: Пайпинг вместо пересказа — 2>&1 | claude
Это, пожалуй, самый недооценённый трюк. Вместо того чтобы копировать ошибку, пересказывать её своими словами и терять детали — просто пайпни вывод команды прямо в Claude:
npm test 2>&1 | claude "fix the failing tests"
По эксперименту на BSWEN, разработчик сравнил два подхода на реальном баге:
- Пересказ своими словами: 12 минут, результат — generic-советы про изоляцию тестов
- Пайп сырого вывода: 30 секунд + 2 минуты анализа Claude, результат — точный фикс: «Строка 45 в test-setup.js — пропущен await»
Ключевой момент — 2>&1. Без этого в пайп попадает только stdout, а stderr (где живут сообщения об ошибках) улетает в терминал и теряется.
Ещё несколько полезных вариантов:
# Git конфликты git diff | claude "help resolve these merge conflicts" # Docker проблемы docker logs my-container 2>&1 | claude "explain what's going wrong" # Сохранить вывод + проанализировать npm test 2>&1 | tee test-output.log cat test-output.log | claude "fix the failing tests"
Приём 3: Гипотезы перед фиксом
Когда не понимаешь, что сломалось — не проси Claude чинить. Попроси его думать:
This function returns null when it shouldn't. Before fixing it, give me 3 possible root causes: Expected: user object with email field Actual: null [код функции]
Зачем это работает: Claude перестаёт хвататься за первый паттерн, который увидит в коде, и вместо этого рассуждает от симптомов. Ты выбираешь гипотезу, которая совпадает с твоим пониманием, и только потом разрешаешь фиксить.
Автор 5-шагового процесса на DEV.to идёт ещё дальше — просит Claude сначала выдвинуть гипотезы без чтения кода, а потом проверить их:
Here's the relevant code: [paste] We hypothesized these causes: [list from previous step] Which of these does the code actually support? What does the code show that our hypotheses missed?
Приём 4: «Объясни, потом чини»
Один приём, который радикально меняет качество фиксов. Добавь в промпт одну строку:
Explain what caused it before making any changes.
Без этого Claude иногда чинит симптом и идёт дальше. Добавил null-чек — ошибка ушла. Но почему приходит null — осталось загадкой. А через неделю тот же баг всплывает в другом месте.
С этой строкой Claude вынужден сначала построить модель проблемы, и только потом предложить решение. По опыту Gian Gallegos, это превращает дебаггинг из починки в обучение — ты начинаешь понимать свою кодовую базу лучше.
Приём 5: Стратегия логирования для плавающих багов
Баг воспроизводится через раз? Не проси Claude чинить — попроси расставить логи:
This function is behaving unexpectedly in production but I can't reproduce it locally. Where should I add logging to narrow down the cause? Don't fix it yet — just tell me what to log and where. [код функции]
Claude предложит точки для логирования на основе анализа кода — какие переменные проверить, в каком порядке, что сравнить между успешным и неуспешным запросами. Это часто быстрее, чем угадывать фикс.
Приём 6: Исключения и ограничения — расскажи, что ты уже проверил
Когда ты уже потратил час на баг, у тебя есть ценная информация — что точно не является причиной:
Bug: login form submits but user session isn't persisting. I've already checked: - Cookies are being set correctly (verified in DevTools) - The session middleware is loaded (confirmed in app.ts) - The database stores the session (checked manually) Something between session creation and the next request is losing it. Check src/middleware/auth.ts and src/lib/session.ts
Это экономит Claude десятки тысяч токенов на проверку того, что ты уже исключил, и направляет его к непроверенным участкам.
Для регрессий (сломалось после PR) — перечисли, что менял:
This was working before my last PR. The PR changed: - Added rate limiting middleware - Updated the user schema - Changed auth token validation Now I'm getting: [error] Which change most likely caused this and why?
Приём 7: Хук для автоматического логирования ошибок
Это продвинутый приём — настроить hook, который автоматически записывает каждую упавшую Bash-команду в лог:
{ "hooks": { "PostToolUse": [ { "matcher": "Bash", "hooks": [{ "type": "command", "command": "python .claude/hooks/log_failures.py" }] } ] } }
Скрипт .claude/hooks/log_failures.py:
import json, sys from pathlib import Path from datetime import datetime data = json.load(sys.stdin) if data.get("tool_name") == "Bash": result = data.get("tool_result", {}) if result.get("exit_code", 0) != 0: log = Path(".claude/debug.log") ts = datetime.now().strftime("%H:%M:%S") cmd = data.get("tool_input", {}).get("command", "")[:100] out = result.get("output", "")[:300] with log.open("a") as f: f.write(f"[{ts}] FAILED: {cmd}\nOutput: {out}\n\n") sys.exit(0)
По паттерну с DEV.to, это создаёт .claude/debug.log, который накапливает все ошибки за сессию. Удобно для post-mortem: можно скормить весь лог Claude и попросить найти закономерность.
Бонус: секция дебаггинга в CLAUDE.md
Если проект живой и баги повторяются — добавь в CLAUDE.md раздел с типичными паттернами ошибок:
## Common Error Patterns - `NullReferenceError` on user object: Usually means the Prisma query is missing `include: { profile: true }`. Check the repository layer. - `TimeoutError` on external calls: All external API calls need explicit timeout configuration. See `src/lib/http.ts` for the wrapper. ## Debugging Tools - Logs: `logs/app.log` (JSON format, use jq) - DB inspection: `npm run db:studio`
Claude прочитает это в начале сессии и сразу будет знать, куда смотреть при знакомых ошибках.
Подводные камни
Claude чинит симптомы, а не причины. Без инструкции «explain before fixing» типичный фикс — это null-чек или try/catch, который маскирует проблему. По наблюдениям builtbyzac, такие фиксы всплывают в проде через 2 дня в худшем виде: retry-цикл вместо починки таймаута, перехват исключения без понимания причины.
Пайпинг больших логов убивает контекст. Если npm test 2>&1 выдаёт 10 000 строк, Claude потратит весь контекст на парсинг мусора. Для длинных логов лучше сначала сохранить в файл (tee), потом отфильтровать нужное (grep -A5 "ERROR") и скормить только релевантную часть.
Несколько изменений за раз = непонятно, что починило. Если Claude предложил три фикса одновременно и баг ушёл — ты не знаешь, какой из трёх сработал. По опыту с BSWEN, правильный подход — тестировать гипотезы по одной, как в научном эксперименте.
Claude зацикливается на долгих сессиях. По наблюдениям разработчиков, на длинных задачах Claude попадает в два режима: бесконечный цикл (одна и та же ошибка, слегка разные подходы) или расширение scope (начинает рефакторить код вокруг бага). Если заметил — останови, дай /clear и переформулируй задачу узко.
Shared state между системами — не баг модели, а баг архитектуры. Разработчик на rentierdigital потратил три дня, обвиняя Claude в генерации «мусорного кода», пока не осознал: 5 систем писали в одно поле, каждый фикс ломал соседнюю систему. Модель была ни при чём — не было интеграционного теста, который прогоняет все трансформации последовательно.
Вердикт
Из всех 7 приёмов три дают максимальный эффект: пайпинг сырых логов (приём 2) убирает потерю информации при пересказе; гипотезы перед фиксом (приём 3) не дают Claude чинить симптомы; «объясни, потом чини» (приём 4) превращает дебаггинг из лотереи в понимание. Остальные — усилители: хук для логов полезен на больших проектах, секция в CLAUDE.md окупается при повторяющихся ошибках, а ограничения экономят токены на том, что ты уже проверил.
Главное правило: Claude Code — не телепат. Чем точнее входные данные, тем точнее диагноз. Stack trace → гипотезы → объяснение → фикс → тест. В этом порядке.
Как попробовать
- Прямо сейчас: в следующий раз, когда упадёт тест, вместо копипасты ошибки напиши
npm test 2>&1 | claude "fix the failing tests"— и сравни результат с обычным подходом - Добавь в CLAUDE.md раздел
## Common Error Patternsс 3-5 типичными ошибками вашего проекта - Попробуй промпт с гипотезами: при следующем непонятном баге напиши
Before fixing it, give me 3 possible root causes— это займёт 30 секунд, но сэкономит 30 минут - Установи хук для логов: скопируй скрипт
log_failures.pyиз приёма 7, через неделю у тебя будет картина типичных ошибок в проекте - Официальная документация Claude Code по best practices — раздел про дебаггинг
