В марте 2025-го, через пару недель после того, как термин «вайбкодинг» вообще появился. У Claude Code тогда было несколько миллионов скачиваний — сейчас больше пятнадцати, и растёт.
Причина была простая и совсем не про код. По работе в AlpinaGPT у меня много коммуникаций: почта, мессенджеры, созвоны, чаты. К весне 2025-го я понял, что в этом потоке невозможно держать всё в голове — что-то обещал на встрече, что-то всплыло в третьем чате, что-то нужно было отправить в почту, и часть обязательств просто терялась.
Я задумал собрать бота, который тянет информацию из всех источников в одно место. Цифровой мозг 24/7: не просто хранит, а видит связи — обещал на встрече отправить документ и через два дня не отправил, бот подсвечивает заранее; видит пересечения между людьми; сводит разговоры на одну тему из разных каналов. Та самая идея, которую я потом реализовал в архитектуре OpenClaw — единое хранилище в векторной базе и универсальный агент над ним. Только OpenClaw тогда ещё не было.
Шишек набил много. Тогда не было ни skills, ни routing.md, ни rules — только большой раздутый CLAUDE.md и эксперименты. Я читал десятки статей, гонял конфигурацию по кругу, выкидывал нерабочее, оставлял прижившееся. За год с лишним накопились и конфиг, и понимание, чего от такого подхода реально стоит ждать.
Claude Code из коробки умеет немного. Полезным он становится, когда вы наполнили ~/.claude/ своей конфигурацией: правилами, навыками, агентами, командами, MCP-серверами и хуками. Без этого даже мощная модель работает как обычный чат с инструментами, которые каждый раз приходится угадывать.
Разберу, как устроены rules, skills, agents, commands, MCP, plugins и hooks, как всё связывается через routing.md и как масштабировать конфиг без раздутого системного промпта. В конце — чек-лист первой настройки и список антипаттернов.
На пустом ~/.claude/ Claude Code знает только Read/Write/Edit/Bash и пару базовых tool'ов. На моём конфиге та же сессия начинается с того, что модель уже знает: где хранятся ключи, как обращаться к серверам, какой стиль кода я использую, какие инструменты под какие задачи. Разница не в скорости печатания — в количестве шагов, которые я не делаю, потому что они зашиты в правила и скиллы.
При первом запуске Claude Code создаёт каталог ~/.claude/ (на Windows — C:\Users\<вы>\.claude\). По умолчанию там пусто. Базовая структура, к которой стоит прийти:
~/.claude/
├── CLAUDE.md # навигация, авто-загружается каждую сессию
├── rules/ # правила поведения, авто-загружаются
├── skills/ # библиотека навыков on-demand
├── agents/ # специализированные субагенты
├── commands/ # slash-команды (/deploy, /translate, ...)
├── hooks/ # скрипты на события (PreToolUse, Stop, ...)
├── settings.json # plugins, MCP, permissions, hooks-маппинг
├── mcp.json # MCP-серверы по требованию
└── .credentials.master.env # API-ключи, никогда в gitСемь типов компонентов, каждый делает свою работу:
/имя, явные slash-команды.Связывает их один принцип — библиотека on-demand, а не bloat в системном промпте.
Это первый файл, который модель видит каждую сессию. Описывать в нём всё подряд нерационально: каждая правка ломает кеш промпта и обходится дороже на каждом запросе. Рабочий формат — короткий, 200–300 строк. Задача — дать карту, а не передать знание: режим работы, таблица правил из rules/, ссылки на конфиги, краткие списки инструментов, плагинов и MCP. Никаких подробных инструкций «как писать код» — это уезжает в rules/ или skills/, чтобы обновлять по отдельности и не ломать кеш всего промпта.
Помимо корневого, имеет смысл класть проектный CLAUDE.md в корень каждого репозитория — Claude Code подгружает его сверху при переходе в директорию. Удобно для проектных вещей: «у нас pnpm, не npm», «фронт на Next.js 15, не на 14», «деплой через vertex ssh».
Распространённая ошибка — пихать всё ценное прямо в CLAUDE.md. У меня в ~/.claude/skills/ сейчас несколько сотен папок: генерация изображений, посты в Telegram, рендер презентаций, парсинг RuTube, десятки сценариев. Грузись их содержимое в системный промпт — оно бы не уместилось до первого сообщения.
Поэтому в промпт грузится только карта местности: CLAUDE.md (~300 строк) и ~/.claude/rules/ — 20–25 файлов с правилами, в сумме ~30–50 тысяч токенов кешируемого префикса. Внутри rules/ — главный файл routing.md, таблица из 300+ строк формата «триггер → инструмент»:
| Категория | Триггеры | Инструмент |
| Изображения | "картинку", "нарисуй", "image" | Skill image-generation |
| Перевод | "переведи", "translate" | Command translate |
| Транскрипция | "транскрибируй", "распознай речь" | Skill deepgram |
| YouTube upload | "выложи в ютуб", "опубликуй" | Skill youtube-publisher |
| Деплой | "задеплой", "deploy" | Command deploy |Пишу «сделай саммари вебинара» — модель смотрит в routing.md, видит триггер, находит нужный скилл (например, meeting-analyzer) и подгружает только его файлы. До этого скилл лежит на диске и контекст не тратит. Вывод простой: размер библиотеки и размер контекста — независимые величины.
Когда добавлять в rules/, а когда в skills/: rules — то, что должно работать ВСЕГДА (безопасность, стиль общения, какие модели использовать), каждый байт тратит токены на каждом запросе. skills — то, что нужно ИНОГДА, грузится по триггеру. Правило большого пальца: если задача реже раза в день — это скилл, не правило.
Главная тревога: «большая конфигурация раздует контекст и съест экономику кеша». На практике — нет. В system prompt попадают только: CLAUDE.md (≈8K токенов), все rules/*.md (≈20–30K), список скиллов как короткие descriptions (≈5K, не тела), описания плагинов и MCP (≈10K). Итого около 40–50K токенов на старте. Тела скиллов (основной объём, ещё ≈300K) грузятся только когда роутинг сработал.
С prompt caching (включён по умолчанию) системный промпт кешируется после первого сообщения и стоит ~$0.15 за сессию вместо $1.50 без кеша — экономия в 10 раз. Cold start — 1–2 секунды на первое сообщение. Контекст «съедают» не правила и скиллы, а долгие диалоги с большими файлами. Держите сессию короткой, периодически делайте /compact — и конфиг даже на 200+ скиллов не выйдет за половину окна.
Файлы из ~/.claude/rules/ подгружаются в системный промпт каждую сессию. Самый дорогой слой по токенам и самый ценный по влиянию. Минимальный набор: routing.md (триггер → скилл/агент/команда), personality.md (стиль общения), security.md (где ключи, что нельзя в коде), delegation.md (когда делегировать субагенту), quality-gates.md (что проверять после изменений — build, type-check, lint), dont-do.md (запреты с объяснениями).
Что держать в голове: за размер платишь на каждом запросе (мои 20+ файлов дают ~30–50K токенов — нормально, кешируется); любое изменение rules ломает кеш, поэтому я не правлю правила в активной сессии; не пишите в rules то, что нужно только в одном проекте — для этого проектный CLAUDE.md. Самый важный файл — routing.md: без routing-таблицы модель не найдёт ваши скиллы по описанию.
Скилл — это директория ~/.claude/skills/<name>/ с обязательным SKILL.md. Внутри что угодно: доп. .md, скрипты, шаблоны, эталонные данные. Файл — markdown с YAML-frontmatter, главное в нём поле description: модель ищет скилл по нему. Хорошее описание — три части: что делает скилл (одно предложение), когда вызывать («Use when…»), ключевые слова для триггеров. Плохое: «Helper for images» — никаких триггеров, модель не найдёт.
Делайте скилл, если: задача повторяется хотя бы раз в неделю; в решении есть нетривиальная логика (структура промпта, последовательность шагов, обращение к API); эту логику не описать коротко в routing.md. Не делайте, если: задача — один вызов Bash или API (это команда, в commands/); нужно только напомнить про правило (это rules/); логика привязана к одному проекту (это проектный CLAUDE.md).
manus-slides — full-pipeline скилл генерации презентаций. На вход тема одной фразой, на выход готовый PPTX с обложкой, разделами и иллюстрациями. Внутри 24 стиля через Nano Banana 2 (Gemini Image): vinyl, whiteboard, grove, fresco, sketch, neon, onyx и другие. Сам почти всегда беру whiteboard — иллюстрации в стиле маркерной доски в переговорке, хорошо ложатся на бизнес-контент.
Скилл — не текстовая шпаргалка, а полноценный пакет из инструкции, рабочих скриптов и ассетов:
~/.claude/skills/manus-slides/
├── SKILL.md # инструкция (≈13K)
├── scripts/
│ ├── whiteboard_generator.py # пайплайн whiteboard → PNG → PPTX
│ ├── slide_manager.py # init/add/export проекта
│ ├── slide_templates.py # 13 HTML-шаблонов
│ └── slide_export.py # рендер через Playwright → PPTX/PDF
├── assets/ # шрифты, иконки, базовые изображения
└── references/ # эталонные примеры стилейАгент следует SKILL.md как инструкции, а тяжёлую работу — генерацию изображений, сборку PPTX, рендер — делают скрипты. В Claude Code это выглядит так: пишу «сделай презентацию для investor pitch на тему "AI-агрегатор для корпоративного обучения", стиль whiteboard, 12 слайдов» — routing ловит триггер «презентация», подключает manus-slides, тот формирует outline через Claude, под каждый слайд генерирует промпт, параллельно гоняет их через gemini-3.1-flash-image-preview, собирает в PPTX. Время от запроса до готовой презентации — 5–8 минут. Рукой та же работа — целый день.
В терминале момент срабатывания routing виден явно:
[routing] match: «презентация» → skills/manus-slides/SKILL.md (confidence 0.94)
[load] manus-slides/SKILL.md (4.2K tokens)
[load] manus-slides/scripts/whiteboard_generator.py (registered as tool)
✓ Outline generated: 12 slides
✓ Generating images (parallel, 12 requests via gemini-3.1-flash-image-preview)
✓ Building PPTX
✓ Saved to ./output/presentation.pptx (3.8 MB, 12 slides)
Done in 6m 14s.Скилл из ~200 строк превращает «целый день руками» в «пять минут одной командой». Таких у меня в ~/.claude/skills/ больше двух сотен. Большинство писал сам по мере появления повторяющихся задач: прогнал рутину второй раз — задумался, на третий оформил в скилл.
Чаще всего из служебных гоняю работу с Telegram. tg-post отвечает за публикацию в канал, а tg_client.py (тоже через скилл) — за чтение, поиск, парсинг и автоматизации. Одной командой: «найди в канале @aiproductreview все посты за последний месяц, где упоминается AlpinaGPT или конкуренты, выгрузи в CSV». Routing подгружает скилл, агент через tg_client.py авторизуется в моём аккаунте (Telethon, сессия локально), сканирует канал, фильтрует, складывает в CSV.
Под капотом единый CLI с 50+ командами: read-channel, parse-comments, parse-commenters, read-chat, parse-members, channel-stats, search, search-media, search-date, mentions, global-search, contacts, download, export-chat, send / send-file, react, create-poll, create-group / create-channel. Важно: скилл получает credentials из ~/.claude/.credentials.master.env, не из диалога — модель не видит TELEGRAM_API_ID и токены в чистом виде, она просто вызывает скрипты. Это второй типичный паттерн скилла после manus-slides: обёртка вокруг внешней системы.
В какой-то момент я заметил, что часто прошу Claude Code «сделай мне скилл для X». Решение — skill-creator, SKILL.md, который создаёт другие SKILL.md. Он уточняет имя, триггеры и шаги, создаёт каталог с правильным frontmatter, при необходимости кладёт рядом скрипт, добавляет строку в routing.md и показывает diff. Дальше я говорю «сделай скилл для парсинга PDF-выписок банка» — и через минуту скилл работает. Это и есть точка самовоспроизводства конфигурации.
Агент — специализированный субагент с отдельным контекстом. Вызываете через инструмент Task, передаёте промпт, он работает изолированно и возвращает результат. Зачем: контекстная изоляция (большой research не тащит за собой всю историю основного агента); параллелизм (несколько агентов на независимые задачи); специализация (свой системный промпт, свой набор инструментов, своя модель).
Файл агента — тот же markdown с frontmatter. Ключевые поля: model: opus | sonnet | haiku (для exploration хватает Haiku, для код-ревью лучше Opus); tools: Read, Glob, Grep — белый список (для security-агентов всегда read-only, никогда Write/Edit); description — по нему модель понимает, когда вызывать агента.
Когда нужен агент, а не скилл: если нужна изоляция контекста, другой системный промпт или ограниченный набор tools — агент. Если это просто переиспользуемый промпт-рецепт — скилл. Сомневаетесь — начинайте со скилла, переедете в агента позже.
Уровни делегирования я держу простым decision tree: Level 0 — делать самому (опечатка, переименование переменной); Level 1 — один агент (API endpoint в 2–5 файлах); Level 2 — оркестратор + 2–3 worker-агента (фича во фронт + бэк + тесты); Level 3 — полный workflow с QA (новый микросервис, миграция данных).
Не рассчитывайте, что claude поймёт вас с полуслова. «Исправь баг по результатам твоего research» — плохой промпт. Хороший: «исправь null-pointer в src/auth/validate.ts:42, поле user undefined при истёкшей сессии — добавь null-check, верни 401».
Сначала синтезируйте сами, потом дайте агенту конкретную спецификацию с файлами и строками. Работает лучше, чем разводить пять агентов в надежде, что они между собой договорятся.
Параллельные агенты полезны на независимых задачах, не трогающих одни файлы (один изучает структуру API, второй собирает endpoint-ы, третий ищет интеграционные тесты). Но результаты parallel-агентов нужно интегрировать руками — после parallel-фазы я делаю отдельный запрос: «вот три результата, дай план реализации с учётом всех трёх». Антипаттерн — параллелить зависимые задачи: если B нуждается в результате A, гоните последовательно. Для изолированных экспериментов удобны git worktrees: git worktree add ../experiment experiment/new-router даёт второй каталог с веткой, не понравился результат — git worktree remove выкидывает целый каталог.
Команда — файл ~/.claude/commands/<name>.md, вызывается явно через /<name>. Отличие от скилла: скилл ищется автоматически по описанию, команда вызывается явно по имени. Аргументы передаются через $ARGUMENTS — подставится то, что вы написали после /deploy.
Команда удобнее скилла, когда: действие осознанное и не должно срабатывать «случайно» (деплой, удаление, миграции); нужно передавать параметры из командной строки; хочется быстрый запуск без описания контекста. Полезный базовый набор: /deploy <env>, /translate <text>, /transcribe <file>, /commit, /code-review. Команда-обёртка над скиллом — нормально: мой /translate под капотом дёргает скилл deepl-pro. Имена лучше без префиксов проектов: /deploy production, а не /deploy-prod-vertex-with-checks.
MCP (Model Context Protocol) — открытый стандарт, описывающий, как модель общается с внешними сервисами. У сервера есть набор tools — модель их видит, вызывает с параметрами, получает ответ. Два вида: Local MCP (запускаются на машине через npx или Docker, описаны в settings.json или mcp.json) и Cloud MCP (серверы Anthropic / партнёров, доступны при подписке). Базовый полезный набор: filesystem, github (через плагин), context7, gmail, google-calendar.
Момент по производительности: каждый активный MCP добавляет описания своих tools в системный промпт каждой сессии. Держите 19 серверов включёнными — в промпте несколько килобайт описаний tools, которые вы используете раз в месяц. Поэтому большинство серверов я держу в mcp.json со статусом «есть, но выключен» и включаю по требованию. Если задача — один вызов API через requests раз в неделю, кладите в скилл с куском Python, не поднимайте отдельный MCP.
Типовые грабли: cold start (npx тянет пакеты при первом запуске — решение npm install -g для ежедневных); конфликты по портам (несколько http/sse-серверов на одинаковых портах); истёкшие OAuth-токены (Gmail, Calendar периодически просят переавторизоваться, 401 → переподключить); раздутые описания tools (между сервером с 5 точечными tools и сервером с 50 «на всё» — берите первый). Перед тем как поднять свой MCP — посмотрите, нет ли готового: Postgres, Redis, Slack, Notion, Linear, Sentry, Figma, Stripe уже написаны. Свой стоит писать только под уникальные внутренние системы.
Плагин — бандл сразу из нескольких вещей: skills, commands, agents, иногда хуки и MCP. Управляются в settings.json в секции enabledPlugins. Брать из официального маркетплейса claude-plugins-official, маркетплейсов вроде dev-browser-marketplace, открытых репозиториев на GitHub.
Принципы выбора: доверяйте источнику (плагин может содержать любой код — гляньте автора, активность репозитория, issues); не дублируйте функциональность; помните, что каждый плагин раздувает контекст (описания всех его команд и скиллов попадают в промпт); снимайте по одному (поставил, поработал неделю, честно ответил «пользовался?» — нет, удаляй). Реально окупаются: context7 (свежая документация), commit-commands (/commit, /commit-push-pr), code-review (внешний AI-ревью на PR), pyright-lsp / typescript-lsp (type-checking), playwright (браузерная автоматизация). Антипаттерн — «поставлю всё подряд»: раздутый контекст в лучшем случае, конфликт команд или недоверенный код в худшем.
Hooks — скрипты на конкретные события, описываются в settings.json. События: PreToolUse, PostToolUse, SessionStart, SessionEnd, Stop, UserPromptSubmit, SubagentStart, SubagentStop, CwdChanged, FileChanged. Самое полезное применение — блокировки на необратимые операции. У меня три PreToolUse-хука, которые просто возвращают exit-code 1 и стопят выполнение:
{
"hooks": {
"PreToolUse": [
{ "matcher": "Bash(rm -rf)", "hooks": [{"type": "command", "command": "exit 1"}] },
{ "matcher": "Bash(DROP DATABASE)", "hooks": [{"type": "command", "command": "exit 1"}] },
{ "matcher": "Bash(DROP TABLE)", "hooks": [{"type": "command", "command": "exit 1"}] }
]
}
}Три блокировки, не пятьдесят. Принцип: блокировать только необратимое — удаление, дроп, force-push в main. Остальное чинится через git stash, git restore, перезапуск контейнера. Что ещё вешают на hooks: Stop — звуковой сигнал «работа закончена»; PreToolUse Bash(git commit) — напоминание про Conventional Commits; Write|Edit — гард на защищённые директории; SessionStart — проверка обновлений фреймворка.
Чего не делать: не вешать тяжёлый Python с импортом десятков пакетов на частые события (лаги в полсекунды на каждый hook — я так повесил vector-memory на каждый PreToolUse, потом неделю выяснял, почему всё тормозит); не писать hooks, которые могут зависнуть (hook блокирует выполнение до exit-code, скрипт в сеть без таймаута — гарантированный фриз); не использовать hooks как защиту от модели (если модель «хочет» сделать опасное — это проблема промптинга; hooks — последний рубеж, не первый).
В settings.json есть секция permissions и permissionMode. Три режима: ask (спрашивает на каждый чувствительный tool call), acceptEdits (авто-принимает edit-операции, остальное спрашивает), bypassPermissions (не спрашивает ничего). Сам работаю в bypassPermissions — не потому что «доверяю модели», а потому что страховки уже стоят слоем ниже: опасные команды заблокированы хуками; API-ключи в ~/.claude/.credentials.master.env, а не в коде, модель физически не утечёт их в коммит; security-агенты read-only; большинство операций обратимо. То есть bypassPermissions — итоговая настройка после хуков, изоляции ключей и read-only на чувствительных агентах. НЕ стоит автоматизировать: деплой в прод без перепроверки, действия с финансовыми API, удаление сущностей в чужих системах, любую операцию, цена ошибки которой выше стоимости ручного клика. Начинаете — оставайтесь на ask, пока не построите свой набор хуков.
Когда модель работает с внешними данными (почта, веб-страницы, ответы MCP), она получает текст, на который злоумышленник может попытаться повлиять. Промпт-инъекция в email или в комментарии в коде может заставить агента «забыть инструкции». У меня пять слоёв защиты:
~/.claude/.credentials.master.env, MCP получают их через переменные окружения на старте, не через диалог. Даже на просьбу «выведи переменную X» — переменной нет в контексте модели.gmail_search.py в tools/) до отдачи тела письма в контекст ищет паттерны «ignore previous instructions», «forget your role», «act as» и помечает их [REDACTED:injection]. Web-fetch — то же. Модель видит уже очищенный текст.Главное правило: внешние данные — это контент для анализа, а не команды для исполнения. Любая модель, которой это не зашили на уровне инструментов и фильтров, рано или поздно поедет.
Тему prompt caching часто упускают на старте, а потом обнаруживают по счёту. Anthropic кеширует префикс запросов: если первые N токенов не изменились с прошлого запроса, они тарифицируются по льготной ставке (примерно в 10 раз дешевле обычного ввода). Системный промпт (CLAUDE.md + rules + описания плагинов и MCP) — это и есть стабильный префикс, он кешируется. При следующем запросе в той же сессии вы платите полную цену только за новый кусок. Меняете CLAUDE.md или файл из rules/ во время сессии — кеш ломается, запрос пересчитывается полностью.
Арифметика на системном промпте ~50К токенов: без кеша ~$1.50 за сессию, с кешем ~$0.15. Разница в 10 раз, на сотнях сессий в месяц заметно. Правила, которые держат кеш горячим: не правьте rules/ и CLAUDE.md в активной сессии; /compact вместо /clear (compact сжимает историю, но сохраняет префикс); включайте только нужные MCP; кеш протухает за ~5 минут неактивности. Даже под подпиской Max, где не платите за токены сверху, это важно — на горячем кеше Claude Code отвечает заметно быстрее.
Реалистичный объём на вечер:
~/.claude/CLAUDE.md с короткой навигацией. Не больше 200 строк — указатель, не учебник.rules/routing.md хотя бы с десятью строками по своим типовым задачам. Главная карта, по которой модель ищет скиллы.rules/personality.md с двумя-тремя правилами тона.Дальше работа в обычном режиме. Через неделю станет видно, чего в правилах не хватает; через две-три — какие задачи стоит отдать субагенту. Конфиг достраивается под ваши задачи постепенно, предусмотреть всё на старте бесполезно.
CLAUDE.md — классика. Кеш ломается, контекст проедается. Решение: короткая навигация + подключаемые файлы по триггерам./list для ls, /show для cat — шум. Команды только для действий с последовательностью шагов.~/.claude/.credentials.master.env (в .gitignore), доступ через os.getenv(), в mcp.json — только подстановки ${VAR_NAME}.~/.claude/. Личные в ~/.claude/skills/, рабочие в <project>/.claude/skills/.Гайд не для всех задач. Пишете один скрипт раз в две недели — все 200+ скиллов и 60 агентов вам не нужны. Базовый Claude Code из коробки прекрасно справляется с одноразовой автоматизацией, и вкладывать дни в конфигурацию ради 30 минут работы в неделю — overengineering. Конфиг такого размера окупается, когда вы работаете в Claude Code каждый день хотя бы по часу; есть повторяющиеся задачи (контент, парсинг, ресерч, агенты); хотите предсказуемого поведения между проектами и сессиями; готовы потратить пару выходных на первый набор скиллов и пару часов в неделю на доработку. Если ничего из этого не про вас — остановитесь после первых трёх скиллов и одного routing-файла.
Конфиг растёт под задачи, не наоборот. Не нужно сразу собирать «как у меня» или у кого угодно. Пройдите чек-лист, поработайте неделю, посмотрите, чего не хватает, добавьте. Если выбирать одну вещь, к которой стоит прийти быстрее остальных, — это связка routing.md + skills on-demand: позволяет растить библиотеку без раздутого контекста и не мешает кешу промпта.
Готовые конфиги для вдохновения можно подсмотреть в публичных репозиториях с тегами claude-code, anthropic-skills, awesome-claude. Копировать целиком смысла нет — у каждого свой набор задач. Полезно копировать паттерны: как устроен routing.md, как описаны frontmatter-ы скиллов, какие хуки выбраны. В моём ~/.claude/ лежит ещё несколько вещей, которые сюда не поместились: SOUL-файлы для агентов с устойчивой личностью, AI Gateway как карусель ключей, паттерн agent-firewall для входящего email, мета-скилл skill-creator. Это уже ближе к OpenClaw — отдельной обвязке поверх Claude Code, в которой агент перестаёт быть инструментом для сессии и становится постоянным исполнителем фоновых задач.
Это адаптированное изложение для архива публикаций Жемала Хамидуна. Полная версия статьи со всеми деталями — на Хабре: читать оригинал →