Диагностика Claude Code подчиняется одному правилу: менять одну переменную за шаг. Соблазн снести весь ~/.claude или переустановить систему при первой же проблеме силён, но вреден - он уничтожает улики и не даёт понять причину. Прежде чем что-то удалять, фиксируют симптом, версию, провайдера и чистое сравнение. Диагностика - это сужение, а не сброс: каждый шаг должен отсекать один класс причин, а не обнулять всё окружение сразу.
Пятиминутный triage даёт первую картину. В shell выполняют claude --version, claude doctor и пробный claude --safe-mode; в интерактивной сессии - /status, /doctor, /context, /mcp, /permissions, /sandbox. Записывают точную ошибку, код выхода, время, команду, текущий каталог, провайдера и модель, воспроизводимость - с redacted-секретами до сохранения лога. Это не бюрократия: без зафиксированного симптома любое "исправление" - гадание, а сравнить "до" и "после" будет не с чем.
Симптом почти всегда указывает на первый разделитель. Полезно один раз свести это в дерево: не устанавливается - PATH и claude doctor; auth loop и 401/403 - /status и конфликтующие credentials; 5xx и 429 - error reference и квота провайдера; настройка игнорируется - Setting sources и precedence; hook не срабатывает - claude --debug и case матчера; MCP отсутствует - расположение и approval; резко упало качество - сравнение модели, провайдера, контекста и версии. К этой карте возвращаются, чтобы не гадать, а идти от симптома к нужному слою.
| Симптом | Первый разделитель |
|---|---|
| Не устанавливается / command not found | PATH, claude doctor, install troubleshooting |
| Auth loop / 401 / 403 | /status, конфликтующие credentials/provider vars |
| 5xx / 429 / timeout | Error reference, квота провайдера, retry |
| Setting игнорируется | /status Setting sources, JSON syntax, precedence |
| Hook не срабатывает | claude --debug, case матчера, расположение файла |
| MCP отсутствует | .mcp.json location/type, approval, /mcp, health |
| Резко упало качество | Сравнение model/provider/context/style/version |
Лестница чистой конфигурации - это метод сужения до минимального виновника. Сначала обычный прогон подтверждает симптом. Затем safe mode отключает кастомизации, сохранив core, auth, модель и permissions. Bare -p даёт явный минимальный контекст для automation-симптома. Новый временный репозиторий отделяет project-конфиг и данные. Другая сеть или провайдер (если разрешено) отделяет транспорт. И только потом компоненты возвращают по одному: settings, память, hooks, MCP, plugin - пока симптом не вернётся.
Помогают этому флаги, а не переименование файлов. --setting-sources и явный --settings позволяют делать bisection, не трогая пользовательские файлы; перед любым изменением сохраняют копии или diff и не удаляют OAuth-состояние наугад. Полезно один раз увидеть команды triage рядом. Смысл лестницы в том, что каждая ступень отсекает целый слой возможных причин, и к моменту, когда виновник найден, вы точно знаете, что именно его вызывает, - а не просто "стало работать после переустановки".
Большая часть проблем - это типовые ошибки расположения, и их стоит знать наперёд. Настройки положили в ~/.claude.json вместо ~/.claude/settings.json; MCP - в .claude/.mcp.json вместо корневого .mcp.json; mcpServers записали в settings.json; матчер написали строчными bash вместо case-sensitive Bash; skill создали как name.md вместо name/SKILL.md; project MCP не одобрен. Каждая из них выглядит как загадочный баг, а на деле - путаница расположения.
Производительность лечат так же адресно. При context thrashing просят читать конкретные диапазоны, делают /compact с фокусом, выносят чтение больших файлов в субагент; большие build-каталоги добавляют в gitignore и deny; safe mode находит тяжёлый plugin, MCP или hook. Отдельная осторожность с /heapdump: снимок содержит полный разговор и credentials, поэтому его никогда не прикладывают публично - для отчёта безопаснее документированный diagnostics-JSON после проверки.
Отчёт о баге тоже делают по правилам. Воспроизводимый product-баг отправляют через /feedback или официальные GitHub issues, приложив версию, ОС, категорию провайдера, минимальные шаги, санитизированный debug-фрагмент и сравнение safe и bare. Проблемы биллинга и аккаунта идут в поддержку Anthropic, а не в публичный issue. Типичный провал диагностики - снести ~/.claude до фиксации симптома и потерять и улики, и причину; правильный ход - менять одну переменную за шаг, идти по лестнице и исправлять ровно одну причину с регрессионной проверкой.
# Пятиминутный triage
claude --version
claude doctor
claude --safe-mode
# в сессии: /status /doctor /context /mcp /permissions /sandbox
# лестница: normal -> safe-mode -> bare -p -> temp repo -> сеть -> компоненты по одному