SpyBara
Go Premium

debug-your-config.md 2026-08-03 20:02 UTC to 2026-08-04 22:59 UTC

32 added, 32 removed.

2026
Fri 7 07:00 Thu 6 15:02 Wed 5 22:02 Tue 4 22:59 Mon 3 20:02 Sun 2 19:00

Отладка конфигурации

Диагностируйте, почему CLAUDE.md, параметры, hooks, MCP серверы или skills не вступают в силу. Используйте /context, /doctor, /hooks и /mcp, чтобы увидеть, что действительно загрузилось.

Когда Claude игнорирует инструкцию или функция, которую вы настроили, не появляется, причина обычно в том, что файл не загрузился, загрузился из другого места, чем вы ожидали, или его переопределил другой файл. Это руководство показывает, как проверить, что Claude Code действительно загрузил, чтобы вы могли сузить, какой из этих вариантов применяется.

Для проблем с установкой, аутентификацией и подключением см. Troubleshooting установки и входа вместо этого.

Посмотрите, что загрузилось в контекст

Команда /context показывает всё, что занимает контекстное окно для текущей сессии, разбитое по категориям: системный prompt, файлы памяти, skills, пользовательские subagents с указанием источника, из которого каждый загружен, MCP tools и сообщения беседы. Запустите её в первую очередь, чтобы подтвердить, присутствуют ли ваши CLAUDE.md, правила или описания skills вообще.

Для деталей по конкретной категории используйте специализированную команду:

Команда Показывает
/memory Какие файлы CLAUDE.md и rules загрузились, плюс записи auto-memory
/skills Доступные skills из проекта, пользователя и источников плагинов
/hooks Активные конфигурации hooks
/mcp Подключённые MCP серверы и их статус
/permissions Разрешённые и запрещённые правила, которые в настоящее время действуют
/doctor Диагностика конфигурации: здоровье установки, неверные файлы параметров, неиспользуемые расширения, дублирующиеся имена subagent в одной папке и проверенное содержимое CLAUDE.md, которое Claude может вывести из кодовой базы, с предложенными исправлениями
/debug [issue] Включает логирование отладки для сессии и предлагает Claude диагностировать, используя вывод журнала и пути параметров
/status Активные источники параметров, включая то, действуют ли управляемые параметры

Если файл памяти отсутствует в /memory, проверьте его расположение в соответствии с как загружаются файлы CLAUDE.md. Файлы CLAUDE.md в подпапках загружаются по требованию, когда Claude читает файл в этой папке с помощью инструмента Read, а не при запуске сессии.

Если /memory подтверждает, что файл загрузился, но Claude всё ещё не следует конкретной инструкции, проблема, вероятно, в том, как написана инструкция, а не в том, загрузилась ли она. CLAUDE.md хорошо работает для типов рекомендаций, которые вы дали бы новому коллеге, таких как соглашения проекта, команды сборки и где находятся файлы.

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

Проверьте разрешённые параметры

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

Запустите /doctor, чтобы проверить вашу конфигурацию и установку. Он сообщает о том, что находит, включая неверные файлы параметров, дублирующиеся установки, неиспользуемые расширения и проверенное содержимое CLAUDE.md, которое Claude может вывести из кодовой базы, затем предлагает исправления, которые применяет только после вашего подтверждения. Проверка обрезки CLAUDE.md требует Claude Code v2.1.206 или позже. До версии 2.1.205 /doctor открывал экран диагностики только для чтения, и нажатие f отправляло отчёт Claude для исправления.

Из терминала claude doctor выводит диагностику установки и параметров только для чтения без запуска сеанса.

Запустите /status, чтобы увидеть, какие источники параметров активны, включая то, действуют ли управляемые параметры. Чтобы понять, какая область выигрывает для данного ключа, см. Как взаимодействуют области.

Проверьте MCP серверы

Запустите /mcp, чтобы увидеть каждый настроенный сервер, его статус подключения и одобрили ли вы его для текущего проекта. Сервер может быть определён правильно, но всё ещё не предоставлять tools по нескольким распространённым причинам:

  • Серверы с областью проекта в .mcp.json требуют одноразового одобрения. Если prompt был отклонён, сервер остаётся отключённым, пока вы не одобрите его из /mcp.
  • Сервер, который не запускается, отображается как failed в /mcp. Относительные пути к файлам в command или args — частая причина, так как они разрешаются относительно каталога, из которого вы запустили Claude Code, а не расположения .mcp.json.
  • Сервер, который показывает как connected, но перечисляет нулевые tools, успешно запустился, но не возвращает список tools. Выберите Reconnect из /mcp. Если количество остаётся нулевым, запустите claude --debug mcp, чтобы увидеть вывод stderr сервера.

Для расположений конфигурации и правил области см. MCP.

Проверьте hooks

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

Если hook появляется, но не срабатывает, обычно причина в matcher. Проверьте его на эти ошибки:

  • Поле matcher — это одна строка, которая использует | для соответствия нескольким именам tools, например "Edit|Write". Разделитель , эквивалентен, поэтому "Edit,Write" соответствует тем же tools. До v2.1.191 запятая переходила к оценке regex и matcher никогда не совпадал, поэтому используйте |, если вы ещё не на v2.1.191.
  • Неправильное имя tool создаёт matcher, который ничему не соответствует, поэтому hook молча не срабатывает.
  • Значение массива — это ошибка схемы: Claude Code показывает уведомление об ошибке параметров и отклоняет весь файл параметров пользователя, проекта или локальных параметров, claude doctor сообщает об ошибке валидации, и ни один hook из этого файла не появляется в /hooks. В управляемых параметрах удаляется только неправильная запись, и другие hooks из этого файла всё ещё применяются.

Правки в settings.json вступают в силу в работающей сессии после краткой задержки стабильности файла. Вам не нужно перезагружаться. Если /hooks всё ещё показывает старое определение через несколько секунд после сохранения, запустите /hooks снова, чтобы обновить представление.

Если /hooks показывает hook, но он всё ещё не срабатывает, следующий шаг — наблюдать оценку hook в реальном времени. Запустите сессию с claude --debug hooks и вызовите tool call. Журнал отладки записывает каждое событие, какие matchers были проверены, и код выхода и вывод hook. См. Debug hooks для формата журнала и hooks troubleshooting для распространённых паттернов сбоев.

Протестируйте с чистой конфигурацией

Начните с claude --safe-mode, который запускает сессию со всеми отключёнными настройками, включая CLAUDE.md, skills, plugins, hooks, MCP серверы и пользовательские команды и агенты. Аутентификация, выбор модели, встроенные инструменты и разрешения работают нормально. Если проблема исчезает в безопасном режиме, одна из этих поверхностей является причиной; используйте целевые проверки выше, чтобы найти, какая именно. Безопасный режим по-прежнему применяет управляемые hooks и политику параметров от вашей организации. Управляемые plugins, skills, CLAUDE.md и MCP серверы отключены.

Если проблема сохраняется в безопасном режиме или ваши параметры сами по себе вызывают подозрения, сравните с сессией, которая ничего не загружает из вашей обычной установки. Укажите CLAUDE_CONFIG_DIR на пустой каталог, чтобы обойти всё под ~/.claude, и запустите из каталога, который не имеет папки .claude, файла .mcp.json или CLAUDE.md, чтобы конфигурация проекта также была пропущена.

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Чистая сессия не имеет пользовательских или проектных параметров, hooks, MCP серверов, plugins или памяти.

  • Управляемые параметры всё ещё применяются, если ваша организация их развёртывает, так как они находятся в системном пути вне ~/.claude
  • На Linux и Windows вам будет предложено войти снова, потому что учётные данные хранятся в каталоге конфигурации
  • На macOS учётные данные находятся в Keychain и переносятся в чистую сессию

Если проблема исчезает здесь, причина находится где-то в ваших реальных файлах ~/.claude или проекта .claude. Переинтродуцируйте их по одному, скопировав файлы во временный каталог или запустив из вашего проекта, чтобы найти, какой из них. Если это сохраняется в чистой сессии, причина находится вне вашей пользовательской и проектной конфигурации. Запустите /status, чтобы проверить, действуют ли управляемые параметры, ищите переменные окружения, которые влияют на Claude Code, затем см. Troubleshooting.

Проверьте распространённые причины

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

Симптом Причина Исправление
Hook никогда не срабатывает matcher — это JSON массив вместо строки Используйте одну строку с | для соответствия нескольким tools, например "Edit|Write". См. matcher patterns.
Hook никогда не срабатывает matcher использует , как разделитель в версии до v2.1.191 Claude Code v2.1.191 или позже рассматривает , как разделитель списка, как |. Более ранние версии оценивают запятую как буквальный символ, поэтому "Edit,Write" ничему не соответствует. Используйте | вместо этого или обновите Claude Code.
Hook никогда не срабатывает значение matcher в нижнем регистре, например "bash" Соответствие чувствительно к регистру. Имена tools написаны с заглавной буквы: Bash, Edit, Write, Read.
Hook никогда не срабатывает Hooks находятся в отдельном файле вместо settings.json Нет отдельного файла hooks для конфигурации проекта или пользователя. Определите hooks под ключом "hooks" в settings.json. Только plugins загружают отдельный hooks/hooks.json. См. hook configuration.
Permissions, hooks или env, установленные глобально, игнорируются Конфигурация была добавлена в ~/.claude.json ~/.claude.json содержит состояние приложения и переключатели UI. permissions, hooks и env принадлежат ~/.claude/settings.json. Это два разных файла.
Значение settings.json кажется игнорируемым Тот же ключ установлен в settings.local.json settings.local.json переопределяет settings.json, и оба переопределяют ~/.claude/settings.json. См. settings precedence.
Skill не появляется в /skills Файл skill находится в .claude/skills/name.md вместо папки Используйте папку с SKILL.md внутри: .claude/skills/name/SKILL.md.
Skill появляется в /skills, но Claude никогда его не вызывает Skill имеет disable-model-invocation: true в своём frontmatter или его описание не совпадает с тем, как вы формулируете запрос Проверьте значок в /skills: метка "user-only" означает, что Claude не будет его запускать самостоятельно. См. skill invocation.
Инструкции в подпапке CLAUDE.md кажутся игнорируемыми Файлы подпапок загружаются по требованию, а не при запуске сессии Они загружаются, когда Claude читает файл в этой папке с помощью инструмента Read, а не при запуске и не при записи или создании файлов там. См. как загружаются файлы CLAUDE.md.
Subagent игнорирует инструкции CLAUDE.md Встроенные агенты Explore и Plan пропускают CLAUDE.md. Пользовательские subagents загружают его так же, как основной диалог Для Explore или Plan переформулируйте инструкцию в своём делегирующем prompt. Для пользовательского subagent поместите критические инструкции в тело файла агента, которое становится системным prompt агента. См. что загружается при запуске.
Логика очистки никогда не запускается в конце сессии Нет настроенного SessionEnd hook Добавьте SessionEnd hook в settings.json. См. hook events list.
MCP серверы в .mcp.json никогда не загружаются Файл находится под .claude/ или использует формат конфигурации Claude Desktop Конфигурация MCP проекта находится в корне репозитория как .mcp.json, а не внутри .claude/. См. MCP configuration.
MCP серверы добавлены под mcpServers в settings.json, но никогда не появляются settings.json не читает ключ mcpServers Определите серверы проекта в .mcp.json в корне репозитория или запустите claude mcp add --scope user для серверов с областью пользователя. См. MCP configuration.
Добавлен MCP сервер проекта, но не появляется Prompt одноразового одобрения был отклонён Серверы с областью проекта требуют одобрения. Запустите /mcp, чтобы увидеть статус и одобрить.
MCP сервер не запускается из некоторых каталогов command или args использует относительный путь к файлу Используйте абсолютные пути для локальных скриптов. Исполняемые файлы в вашем PATH как npx или uvx работают как есть.
MCP сервер запускается без ожидаемых переменных окружения Переменные находятся в settings.json env, которые не распространяются на дочерние процессы MCP Установите env для каждого сервера внутри .mcp.json.
Правило отрицания Bash(rm *) не блокирует /bin/rm или find -delete Правила префикса совпадают с буквальной строкой команды, а не с базовым исполняемым файлом Добавьте явные паттерны для каждого варианта или используйте PreToolUse hook или sandbox для жёсткой гарантии.

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