Здоровье конфигурации
В ~/.claude/scripts/ лежит полдюжины проверщиков, но звать их было некому —
и потому конфиг молча расходился с документацией. Этот навык — единая точка
входа: что запускать, в каком порядке и как читать вывод.
Порядок неслучаен: сначала то, что ломает работу прямо сейчас, потом то, что копится.
1. Связность ссылок — с канарейкой
python ~/.claude/scripts/refcheck.py --canary
Ищет ссылки на несуществующие файлы в навыках, правилах и командах.
Флаг --canary обязателен. Он подкладывает заведомо битую ссылку и
убеждается, что проверка её ловит. Без него «ноль ошибок» неотличимо от
«проверка сломалась и молчит» — а именно так отчёты и врут.
⚠️ Скрипт заводит временный навык-пробник skills/_refcheck-probe. Если прогон
оборвать, пробник останется в листинге. Убрать: rm -rf ~/.claude/skills/_refcheck-probe.
⏱ На большом конфиге (тысячи файлов) прогон идёт десятки минут и может
ничего не печатать до конца: при выводе в файл Python буферизует stdout,
поэтому пустой файл на двадцатой минуте означает «работает», а не «повис».
Пускать фоном и не ждать у экрана; признак живого прогона — пробник ещё лежит
в skills/.
Отдельно про «спорные» строки со знаком ?: это упоминания путей внутри прозы —
например, когда стандарт навыка ПОКАЗЫВАЕТ, как выглядит правильная ссылка на
справочник. Разбирать их не надо.
А вот жёсткое ✗ либо чинить, либо переформулировать текст так, чтобы путь
перестал читаться как ссылка. Постоянное ложное срабатывание обесценивает
«БИТЫХ: 0» ровно так же, как пропуск настоящего — проверено на себе: абзац выше
в первой редакции сам содержал путь-пример и сам же стал единственной «битой
ссылкой» следующего прогона.
2. Счётчики и структура
python ~/.claude/scripts/config_health.py
python ~/.claude/scripts/config_lint.py
Сколько навыков, агентов и команд встало по факту; пустые описания, битые каталоги, осиротевшие записи.
Числа отсюда — единственный законный источник. В документации их держать нельзя: они протухают молча и потом служат основанием считать существующее несуществующим (в этой конфигурации так было трижды).
3. Лимит памяти
python ~/.claude/scripts/memory_fit.py --check
python ~/.claude/scripts/memory_fit.py --limit 20 # ужать с запасом
MEMORY.md грузится в начало каждой сессии, и всё за пределом 200 строк ИЛИ
25 КБ отбрасывается без ошибки и предупреждения — вместе с указателями на
заметки.
Держать под 21 КБ: на 24 запаса уже нет, а индекс растёт каждый день. Автоматика умеет ужимать только пояснения и выносить старое в архив; когда она исчерпалась, режут хвосты записей вручную — индекс это указатели, а не пересказ.
4. Вес системного промпта
python ~/.claude/skills/config-health/scripts/prompt_weight.py # сводка + топ едоков
python ~/.claude/skills/config-health/scripts/prompt_weight.py --top 40
python ~/.claude/skills/config-health/scripts/prompt_weight.py --json > before.json # сравнить «до/после»
Скрипт лежит рядом с навыком (scripts/). Токены считает tiktoken — если пакета
нет (pip install tiktoken), берёт оценку по символам, с запасом в большую сторону.
Считает ровно то, что уходит в модель на КАЖДОМ запросе, и разбивает по
источникам: rules/ целиком · CLAUDE.md · MEMORY.md (с отсечкой по
фактическому лимиту — хвост за 200 строк / 25 КБ в промпт не попадает вовсе) ·
листинг навыков · навыки, команды и агенты включённых плагинов · свои
команды и агенты. Токены — tiktoken o200k_base.
Две вещи, которые он ловит и которых глазами не видно:
- листинг навыков — это только поля
description. ТелоSKILL.mdгрузится лишь при вызове. Поэтому длинный навык дёшев, а сотня коротких описаний — дорога: в большом конфиге листинг навыков может стоить столько же, сколько все правила вместе. skillOverridesна несуществующее имя молча не делает ничего. Так было с записьюfirecrawl: реальный навык зовётсяfirecrawl-cli, экономия выглядела сделанной и не была. Скрипт сверяет каждую запись с фактическими навыками (своими и плагинными) и называет висящие.
Что с этим делать:
- правило, нужное редко, →
config/rules-ref/, читать по требованию. Признак кандидата — файл описывает устройство (как работает хук, таблицы выбора, справочные данные), а не что делать; - навык из большого семейства, который зовут раз в квартал, →
name-only; но тогда обязательно перенеси различающие сценарии его запросов на видимый вход (строка в роутинге). Скрытое описание + отсутствие строки = навык перестал находиться вовсе, при этом остался вызываемым — то есть сломался тихо; - плагин, которым не пользуешься, →
false: уносит разом все свои навыки, команды, агентов и MCP-серверы.
5. Живость MCP
claude mcp list
Запускать из нового процесса — он читает конфиг с нуля, поэтому показывает правку без перезапуска сессии.
Три частые причины «✘ Failed to connect», и все три чинятся по-разному:
| Что видно | Причина | Чинить |
|---|---|---|
| то Connected, то Failed у одного сервера | не уложился в MCP_TIMEOUT |
поднять таймаут; замерить старт initialize |
| «Authorization header is badly formatted» / 403 | ${ПЕРЕМЕННАЯ} подставилась пустотой |
переменная должна быть в окружении процесса — .credentials.master.env движок не читает |
| «Missing environment variables» | переменной нет вовсе | завести или выключить плагин |
⚠️ mcpServers читается только из ~/.claude.json. Секция в
settings.json игнорируется молча — так семь серверов месяцами числились
настроенными и не поднимались ни разу.
Когда прогонять
- после обновления пака или установки плагинов;
- когда «навык не находится» или зовётся не тот;
- когда в сессии появились ошибки MCP;
- раз в пару недель просто так — дрейф накапливается незаметно.
Что этот навык НЕ делает
| Задача | Куда |
|---|---|
| Проверить ЧУЖОЙ скилл перед установкой | skill skill-manager (режим «Аудит») |
| Здоровье кода проекта (баги, зависимости) | skill health-inline (команды /health-bugs, /health-deps, /health-cleanup) |
| Обезличить своё перед публикацией | skill leak-scan |
| Уборка памяти, связывание заметок | skill dream |