# Config Health

> Здоровье конфига Claude Code: битые ссылки, вес промпта, лимит памяти, живость MCP. Триггеры: «проверь конфиг», «вес промпта». НЕ чужой скилл→skill-manager; НЕ код→health-inline

- Skill: `jhamidun/config-health` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add jhamidun/config-health`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jhamidun/config-health/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: JHamidun (https://skillmd.com/u/jhamidun)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/jhamidun/config-health

---


# Здоровье конфигурации

В `~/.claude/scripts/` лежит полдюжины проверщиков, но **звать их было некому** —
и потому конфиг молча расходился с документацией. Этот навык — единая точка
входа: что запускать, в каком порядке и как читать вывод.

Порядок неслучаен: сначала то, что ломает работу прямо сейчас, потом то, что
копится.

---

## 1. Связность ссылок — с канарейкой

```bash
python ~/.claude/scripts/refcheck.py --canary
```

Ищет ссылки на несуществующие файлы в навыках, правилах и командах.

**Флаг `--canary` обязателен.** Он подкладывает заведомо битую ссылку и
убеждается, что проверка её ловит. Без него «ноль ошибок» неотличимо от
«проверка сломалась и молчит» — а именно так отчёты и врут.

⚠️ Скрипт заводит временный навык-пробник `skills/_refcheck-probe`. Если прогон
оборвать, пробник останется в листинге. Убрать: `rm -rf ~/.claude/skills/_refcheck-probe`.

⏱ **На большом конфиге (тысячи файлов) прогон идёт десятки минут** и может
**ничего не печатать до конца**: при выводе в файл Python буферизует stdout,
поэтому пустой файл на двадцатой минуте означает «работает», а не «повис».
Пускать фоном и не ждать у экрана; признак живого прогона — пробник ещё лежит
в `skills/`.

Отдельно про «спорные» строки со знаком `?`: это упоминания путей внутри прозы —
например, когда стандарт навыка ПОКАЗЫВАЕТ, как выглядит правильная ссылка на
справочник. Разбирать их не надо.

А вот жёсткое `✗` либо чинить, либо переформулировать текст так, чтобы путь
перестал читаться как ссылка. Постоянное ложное срабатывание обесценивает
«БИТЫХ: 0» ровно так же, как пропуск настоящего — проверено на себе: абзац выше
в первой редакции сам содержал путь-пример и сам же стал единственной «битой
ссылкой» следующего прогона.

## 2. Счётчики и структура

```bash
python ~/.claude/scripts/config_health.py
python ~/.claude/scripts/config_lint.py
```

Сколько навыков, агентов и команд встало по факту; пустые описания, битые
каталоги, осиротевшие записи.

**Числа отсюда — единственный законный источник.** В документации их держать
нельзя: они протухают молча и потом служат основанием считать существующее
несуществующим (в этой конфигурации так было трижды).

## 3. Лимит памяти

```bash
python ~/.claude/scripts/memory_fit.py --check
python ~/.claude/scripts/memory_fit.py --limit 20     # ужать с запасом
```

`MEMORY.md` грузится в начало каждой сессии, и всё за пределом **200 строк ИЛИ
25 КБ** отбрасывается без ошибки и предупреждения — вместе с указателями на
заметки.

Держать под 21 КБ: на 24 запаса уже нет, а индекс растёт каждый день.
Автоматика умеет ужимать только пояснения и выносить старое в архив; когда она
исчерпалась, режут хвосты записей вручную — индекс это указатели, а не пересказ.

## 4. Вес системного промпта

```bash
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

```bash
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` |

