Год с Claude Code: как собрать рабочую конфигурацию с первого запуска

Год с Claude Code: как собрать рабочую конфигурацию с первого запуска
Жемал Хамидун, Head of AI Alpina Digital, CPO AlpinaGPT,автор тг-канала «Готовим ИИшницу».

Зачем я начал вайбкодить
В марте 2025 года, через пару недель после того, как термин «вайбкодинг» вообще появился. У Claude Code тогда было несколько миллионов скачиваний — сейчас больше пятнадцати, и продолжает расти.
Причина была простая и совсем не про код. У меня по работе в АльпинаGPT много коммуникаций: почта, мессенджеры, созвоны, чаты. К весне 2025 я уже понимал, что в этом потоке невозможно держать всё в голове. Что-то обещал на одной встрече, что-то всплыло в третьем чате, что-то нужно было отправить в почту — и часть этих обязательств просто терялась.
И я подумал: попробую собрать себе бота, который будет тянуть информацию из всех источников в одно место. Этакий цифровой мозг, работающий 24/7. Чтобы он не просто хранил информацию, а видел связи: я обещал на встрече отправить документ — и если через два дня не отправил, бот заранее подсвечивает. Видит пересечения между людьми в моём окружении. Сводит разговоры с одинаковыми темами из разных каналов.
Идея была ровно та, которую потом я реализовал в архитектуре OpenClaw — единое хранилище в векторной базе и универсальный агент над ней. Только OpenClaw тогда ещё не существовало.
Так начался путь – и я набил много шишек. Тогда не было ни skills, ни routing.md, ни rules — только большой раздутый CLAUDE.md и эксперименты. Я читал десятки статей и постов от тех, кто уже что-то пробовал, гонял конфигурацию по кругу, выкидывал то, что не работает, оставлял то, что прижилось.
За этот год с лишним накопилась конфигурация и понимание, чего от такого подхода реально стоит ждать, а чего нет. В следующих статьях я расскажу, как устроен мой текущий конфиг и как я делал разных агентов — включая доработку OpenClaw под конкретные задачи.
О чём эта статья
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

Семь типов компонентов. Каждый делает свою работу:

Компонент	Когда грузится	Зачем
CLAUDE.md	Каждая сессия	Навигация и стиль работы
rules/*.md	Каждая сессия	Правила, которым модель должна следовать всегда
skills/*/SKILL.md	По триггеру	Отдельные специализированные «навыки»
agents/*.md	По вызову Task	Субагенты с изолированным контекстом
commands/*.md	По /имя	Явные slash-команды
hooks/*.js	На событие	Блокировки, нотификации, гарды
MCP-серверы	По описанию	Внешние интеграции (Gmail, GitHub, БД)

Связывает их один принцип — библиотека on-demand, а не bloat в системном промпте. Дальше разберём, как это устроено.
CLAUDE.mdкак точка входа
Пара слов про корневой CLAUDE.md. Это первый файл, который модель видит в каждой сессии. Подробно описывать в нём вообще всё — нерационально: каждая правка ломает кеш промпта и обходится дороже на каждом запросе.
Рабочий формат — короткий: 200–300 строк. Его задача — дать карту, а не передать знание. Структура примерно такая:

# CLAUDE BRAIN — НАВИГАЦИЯ   ## Режим работы - Работаем автономно, не спрашиваем разрешения на мелочи - Останавливаемся только когда нужна информация от человека   ## Правила (auto-load из ~/.claude/rules/) | Файл | Назначение | |------|------------| | routing.md | Маршрутная карта задача → инструмент | | security.md | API-ключи, чувствительные данные | | personality.md | Стиль общения и приоритеты |   ## Конфигурация (~/.claude/config/) | Что | Файл | |-----|------| | Реестр проектов | config/projects-registry.md | | Модели AI | config/models.md | | Сервер | config/server.md |   ## Инструменты | Что | Где | Кол-во | |-----|-----|--------| | Skills | skills/ | <столько-то> | | Agents | agents/ | <столько-то> | | Commands | commands/ | <столько-то> |

Дальше — короткие списки плагинов и MCP, и всё. Никаких подробных инструкций «как писать код», «как делать ревью», «как форматировать ответы». Это всё уезжает в rules/ или в skills/, чтобы можно было обновлять по отдельности и не ломать кеш всего промпта.
Помимо корневого ~/.claude/CLAUDE.md, имеет смысл класть проектный 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» / «транскрипт», находит нужный скилл (например, meeting-analyzer) и подгружает только его файлы. До этого скилл лежит на диске и контекст не тратит.
Из этого следует простой вывод: размер библиотеки и размер контекста — независимые величины. Библиотеку можно растить, сколько нужно, окно от этого не страдает.
Когда стоит добавлять что-то в rules/, а не в skills/:

• rules — то, что должно работать ВСЕГДА (правила безопасности, стиль общения, какие модели использовать). Каждый байт здесь тратит токены на каждом запросе и инвалидирует кеш при изменении.
  
• skills — то, что нужно ИНОГДА (рендеринг презентации, парсинг сайта, отправка в Telegram). Грузится по триггеру.

Правило большого пальца: если задача реже одного раза в день — это скилл, не правило.
Сколько это стоит в токенах на старте
Главная тревога: «такая большая конфигурация раздует контекст и съест всю экономику кеша». На практике — нет.
В каждой сессии в system prompt попадают только: CLAUDE.md (≈8K токенов), все rules/*.md (≈20–30K в сумме), список доступных скиллов как короткие descriptions (≈5K, не тела скиллов), описания плагинов и MCP-серверов (≈10K). Итого — около 40–50K токенов на старте сессии. Тела скиллов (а это основной объём, ещё ≈300K) загружаются только когда роутинг сработал на конкретный триггер.
С prompt caching (включён по умолчанию у Claude) этот системный промпт кешируется после первого сообщения и стоит ~$0.15 за сессию вместо $1.50 без кеша — экономия в 10 раз. Cold start — 1–2 секунды на первое сообщение, дальше уже tepid.
Контекст «съедают» не сами правила и скиллы, а долгие диалоги с большими файлами. Если вы держите сессию короткой и периодически делаете /compact — конфиг даже на 200+ скиллов не выйдет за половину окна.
Слой 1. Rules — правила поведения
Файлы из ~/.claude/rules/ подгружаются в системный промпт каждую сессию. Это самый дорогой слой по токенам и самый ценный по влиянию.
Минимальный набор, который стоит завести каждому:

Файл	Содержание
routing.md	Таблица «триггер → скилл/агент/команда»
personality.md	Стиль общения (язык, тон, на «ты» / «вы»)
security.md	Где лежат API-ключи, что нельзя в коде
delegation.md	Когда делегировать субагенту, когда делать самому
quality-gates.md	Что проверять после изменений (build, type-check, lint)
dont-do.md	Список запретов с объяснениями

Шаблон файла-правила — обычный markdown с заголовком и пояснением:

# Personality   ## Language - Communication: Russian - Code: English (always) - Comments in code: English - Commit messages: English (Conventional Commits)   ## Tone - Direct, technical, no fluff - Address user informally (on "ty") - Show results, don't ask permission for small things   ## Anti-patterns - Excessive praise ("Great question!") - Filler phrases ("Let me think about that...") - Marketing-speak and buzzwords

Что важно держать в голове при работе с правилами:

• За размер платишь на каждом запросе. У меня 20+ файлов rules дают примерно 30–50 тысяч токенов. Это нормально — кешируется и стоит в 10 раз дешевле обычного ввода. Но если набьёте сюда мегабайт — заметите по счёту и по скорости отклика.
  
• Любое изменение rules ломает кеш. Поэтому я не правлю правила во время активной сессии. Меняю — и начинаю новую.
  
• Не пишите в rules то, что нужно знать только в одном проекте. Для проектных вещей кладите CLAUDE.md в корень проекта — он подгружается автоматически, когда вы работаете в этой директории.

Самый важный файл — routing.md. Его лучше начать сразу с десяти-пятнадцати строк по своим типовым задачам, а потом дополнять по мере появления новых скиллов. Без routing-таблицы модель не найдёт ваши скиллы по описанию.
Слой 2. Skills — основная рабочая лошадка
Скилл — это директория в ~/.claude/skills// с обязательным файлом SKILL.md. Внутри может лежать что угодно: дополнительные .md, скрипты, шаблоны, эталонные данные.
Структура файла — markdown с YAML-frontmatter:

--- name: image-generation description: AI image generation prompt engineering for DALL-E 3,   Gemini Imagen, Stable Diffusion, Midjourney. Use when asked to   generate, create, or draw images. ---   # Image Generation Skill   ## When to Use - User asks to create/generate an image - User needs help writing image prompts - User mentions DALL-E, Midjourney, Stable Diffusion   ## Core Prompt Structure   ### 1. Subject [Main subject] + [Detailed description] + [Pose/Action]   ### 2. Style photographic / illustration / 3D render / oil painting   ### 3. Lighting golden hour / studio / dramatic / soft natural   ...

Главное в этой структуре — поле description во frontmatter. Модель ищет нужный скилл по нему. Чем точнее описание, тем выше шанс, что модель найдёт скилл сама, без подсказки в routing.md.
Хорошее description — три части:

• Что делает скилл (одно предложение).
  
• Когда вызывать («Use when…»).
  
• Ключевые слова для триггеров (DALL-E, Gemini, Stable Diffusion).

Плохое описание: «Helper for images». Никаких триггеров — модель никогда не найдёт.
Когда делать скилл, а когда не делать
Делайте скилл, если:

• Задача повторяется хотя бы раз в неделю
  
• В решении есть нетривиальная логика (структура промпта, последовательность шагов, обращение к API)
  
• Эту логику не получится коротко описать в routing.md

Не делайте скилл, если:

• Задача делается одной командой Bash или одним вызовом API — это командная работа, кладите в commands/
  
• Нужно только напомнить модели про какое-то правило — это правило, кладите в rules/
  
• Логика жёстко привязана к одному проекту — это CLAUDE.md в корне проекта

Первый скилл за 10 минут
Минимальный воркфлоу:

mkdir -p ~/.claude/skills/my-first-skill cat > ~/.claude/skills/my-first-skill/SKILL.md <<'EOF' --- name: my-first-skill description: Что-то полезное, что я делаю регулярно. Use when user asks to ... ---   # My First Skill   ## When to Use - Условие 1 - Условие 2   ## Steps 1. Сделать X 2. Проверить Y 3. Вернуть результат в формате Z EOF

Дальше добавьте триггер в rules/routing.md:

| Моя задача | "ключевое слово 1", "ключевое слово 2" | Skill my-first-skill |

Запускайте сессию заново — модель загрузит обновлённую карту.
Пример скилла из жизни — презентации в нужном стиле за 5 минут
Чтобы было понятно, как скилл реально окупается, покажу один из тех, что я сам гоняю каждую неделю.
manus-slides — full-pipeline скилл генерации презентаций. На вход — тема (одной фразой). На выход — готовый PPTX с обложкой, разделами и иллюстрациями. Внутри 24 стиля через Nano Banana 2 (Gemini Image): vinyl, whiteboard, grove, fresco, sketch, neon, onyx и другие. Лично я почти всегда беру whiteboard — это иллюстрации в стиле маркерной доски в переговорке. Хорошо ложится на бизнес-контент, не выглядит как стоковая презентация, не требует подбора шрифтов и цветов.
Важный момент: скилл — это не просто текстовая шпаргалка для модели. Это полноценный пакет из инструкции, рабочих скриптов и ассетов. Структура каталога manus-slides:

~/.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 (как пользоваться) + рабочие скрипты (что реально делает работу) + ассеты + референсы. Агент следует SKILL.md как инструкции по эксплуатации, но всю тяжёлую работу — генерацию изображений, сборку PPTX, рендер слайдов — делают скрипты. В терминальном выводе ниже видна строка [load] manus-slides/scripts/whiteboard_generator.py (registered as tool) — это тот самый момент, когда агент подцепляет executable.
В Claude Code это работает так:

> сделай презентацию для investor pitch на тему «AI-агрегатор для корпоративного обучения»,   стиль whiteboard, 12 слайдов

Routing.md ловит триггер «презентация», подключает manus-slides, тот:

• Через Claude формирует outline — 12 слайдов с заголовками и тезисами.
  
• Для каждого слайда генерирует промпт под whiteboard-стиль (заголовок + структура иллюстрации).
  
• Параллельно гоняет промпты через gemini-3.1-flash-image-preview, получает PNG для каждого слайда.
  
• Собирает всё в PPTX с обложкой и метаданными.

Время от запроса до готовой презентации — 5–8 минут. Рукой та же работа — целый день: думать структуру, искать иллюстрации, выравнивать вёрстку.
Минимальный фрагмент SKILL.md, чтобы понять структуру:

--- name: manus-slides description: Создание презентаций. Использовать когда пользователь просит «сделай презентацию», «оформи слайды», «pitch deck». Поддерживает 24 AI-стиля (whiteboard, vinyl, sketch и др.) через Gemini Image. Экспорт в PPTX/PDF. ---   # Manus Slides   Full-pipeline: тема → outline → слайды (PNG через Gemini) → PPTX.   ## Quick start 1. Спросить тему и стиль (whiteboard по умолчанию) 2. Сгенерировать outline (Claude) 3. Для каждого слайда — image-prompt в стиле whiteboard 4. Параллельный запуск Gemini image generation 5. Сборка в PPTX (python-pptx)

Это пример того, как скилл из 200 строк превращает «целый день руками» в «пять минут одной командой». И это не единственный — у меня в ~/.claude/skills/ сейчас лежит более двух сотен подобных. Большинство я писал сам по мере появления повторяющихся задач: одну рутину прогнал второй раз — задумался, на третий уже оформил в скилл.
Чтобы было понятнее, как routing срабатывает — вот как это выглядит в терминале:

> сделай презентацию для investor pitch на тему «AI-агрегатор для корпоративного   обучения», стиль whiteboard, 12 слайдов   [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)   I'll generate the presentation. Let me start with the outline.   ✓ Outline generated: 12 slides   1. Title — AI-агрегатор для корпоративного обучения   2. Problem — фрагментация обучения в корпорациях   3. Solution — единая платформа с AI-агентами   ...   ✓ Slide prompts ready ✓ Generating images (parallel, 12 requests via gemini-3.1-flash-image-preview)   [01/12] ████████████████████ done   [12/12] ████████████████████ done ✓ Building PPTX ✓ Saved to ./output/presentation.pptx (3.8 MB, 12 slides)   Done in 6m 14s.

Это и есть пайплайн: routing нашёл нужный skill, подгрузил его описание (≈4K токенов вместо 200K, если бы все скиллы лежали в system prompt), агент выполнил задачу и вернулся.
Ещё один пример — парсинг Telegram
Скилл, который я гоняю чаще всего из служебных, — это работа с Telegram. Мой tg-post skill отвечает за публикацию в канал, а tg_client.py (тоже подключён через скилл) — за чтение, поиск, парсинг и автоматизации.
Что я делаю одной командой в Claude Code:

> найди в канале @aiproductreview все посты за последний месяц,   где упоминается AlpinaGPT или конкуренты, выгрузи в CSV

Routing подгружает skill telegram → агент через 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

Структура та же, что у manus-slides — SKILL.md плюс набор Python-скриптов плюс session-файл (Telethon). Что важно: скилл получает credentials из ~/.claude/.credentials.master.env, не из диалога. Модель не видит TELEGRAM_API_ID и токены в чистом виде — она просто вызывает скрипты.
Это второй типичный паттерн скилла после manus-slides: обёртка вокруг внешней системы. Когда у меня появляется новая система, с которой я работаю руками регулярно, — я делаю под неё такую же скилл-обёртку. Получается готовый интерфейс «Claude Code → внешний сервис», который работает одной командой на естественном языке.
Как растёт конфигурация — мета-скилл, который пишет скиллы
В какой-то момент я заметил, что часто описываю Claude Code одну и ту же задачу: «сделай мне скилл для X». Решение — skill-creator. Это SKILL.md, который умеет создавать другие SKILL.md.
Минимальная заготовка:

--- name: skill-creator description: Создаёт новые скиллы по описанию задачи. Использовать когда пользователь просит «сделай мне скилл», «добавь скилл», «оформи это в скилл». Анализирует запрос, генерирует SKILL.md с правильным frontmatter, помещает в ~/.claude/skills// и подключает в routing.md. ---   # Skill Creator   ## Когда срабатывает - Пользователь просит создать новый скилл - Описывает повторяющуюся задачу, которая просится в виде скилла   ## Что делает 1. Уточняет: имя, триггеры, шаги выполнения 2. Создаёт ~/.claude/skills//SKILL.md с frontmatter (name, description, triggers) 3. Если нужен скрипт — кладёт рядом scripts/.py 4. Добавляет строку в ~/.claude/rules/routing.md с триггером и путём 5. Сообщает о создании, показывает diff   ## Шаблон выходного SKILL.md [минимальный шаблон 15–30 строк]

После этого я могу сказать Claude Code «сделай скилл для парсинга PDF-выписок банка» — он сам создаёт каталог, пишет SKILL.md, прописывает routing, и через минуту скилл работает. Это и есть точка самовоспроизводства конфигурации: дальше она растёт по запросу, без ручной возни с файлами.
Если хотите мой полный skill-creator — он в архиве (см. блок ниже про конфиг).
Слой 3. Agents — делегируем задачи
Агент — это специализированный субагент с отдельным контекстом. Вы вызываете его через инструмент Task, передаёте промпт, он работает изолированно и возвращает результат.
Зачем это нужно:

• Контекстная изоляция. Если основной агент уже наполнил окно контекстом, а вам нужно сделать большой research — отдайте subagent-у. Он не будет тащить за собой всю историю.
  
• Параллелизм. Можно запустить несколько агентов одновременно для независимых задач (поиск в разных частях кодовой базы, разные типы анализа).
  
• Специализация. У агента может быть свой системный промпт, свой набор инструментов, своя модель.

Структура файла агента — тот же markdown с frontmatter:

--- name: code-reviewer description: Reviews code for security, quality, and performance model: opus tools: Read, Glob, Grep ---   # Purpose   You are a Principal Code Reviewer. Your mission is to perform rigorous, actionable code reviews using a two-pass methodology to separate critical problems from informational notes.   ## Identity - Style: Direct, evidence-based, constructive - Principles: Security first, Zero Silent Failures, READ-ONLY   ## Process Pass 1: Surface only critical issues (security, correctness, P0 bugs) Pass 2: Informational notes (style, minor refactors)   ## Rules - Point to specific file paths and line numbers - Suggest concrete fixes, not generic advice - Never use Write, Edit, or Bash tools — read-only

Несколько ключевых полей:

• model: opus | sonnet | haiku — какую модель использовать. Для exploration хватает Haiku, для код-ревью лучше Opus.
  
• tools: Read, Glob, Grep — белый список инструментов. Для security-агентов всегда делайте read-only — никогда не давайте Write/Edit.
  
• description — по нему модель будет понимать, когда вызывать агента автоматически.

Когда нужен агент, а когда хватит скилла

Признак	Скилл	Агент
Нужна изоляция контекста	нет	да
Нужен другой системный промпт	нет	да
Нужно ограничить набор tools	нет	да
Просто переиспользуемый промпт-рецепт	да	нет

Если сомневаетесь — начинайте со скилла. Если позже окажется, что задача засирает основной контекст или нужен read-only режим — переезжайте в агента.
Уровни делегирования
Для себя я держу простой 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 — гоните последовательно. Параллельные на зависимостях ломаются непредсказуемо: B стартует, не дождавшись А, и работает по неполным данным.
Worktrees для изолированных экспериментов
Отдельная штука, которая очень удобна вместе с агентами, — git worktrees. Это возможность иметь несколько рабочих копий одного репозитория на разных ветках одновременно.
Сценарий: вы работаете на feature/login, и тут срочно нужно проверить идею в experiment/new-router. Без worktrees — стэшить, переключаться, восстанавливать. С worktrees — git worktree add ../experiment experiment/new-router, и у вас рядом второй каталог с этой веткой.
Агенту тоже можно дать команду работать в worktree. Если он что-то наломает или результат не понравится — выкидываем целый каталог одной командой git worktree remove. Никаких стэшей, никаких потерянных файлов.
Слой 4. Commands — slash-команды
Команда — это файл ~/.claude/commands/.md, который вызывается явно через /. От скилла отличается тем, что:

• Скилл ищется автоматически по описанию.
  
• Команда вызывается явно по имени.

Структура минимальная:

--- description: Universal deployment command for various environments argument-hint: [staging / production / local] ---   # Deploy: $ARGUMENTS   Deploy to $ARGUMENTS environment.   ## Process   ### Pre-Deploy Checks - Tests passing - Linting clean - Env variables configured - Database migrations ready   ### Deployment Steps 1. Build application 2. Run tests 3. Push to registry 4. Run migrations 5. Health check 6. Smoke tests

$ARGUMENTS — подставится то, что вы написали после /deploy.
Когда удобнее команда, чем скилл:

• Действие явно осознанное и не должно вызываться «случайно» (деплой, удаление, миграции)
  
• Нужно передавать параметры из командной строки
  
• Хочется быстрый запуск без описания контекста

Несколько команд, которые имеет смысл сделать любому:

Команда	Что делает
/deploy	Деплой с pre-deploy checks
/translate	Перевод через ваш любимый сервис
/transcribe	Транскрипция аудио
/commit	Создать commit с правильным форматом
/code-review	Запустить code-review агента на текущих изменениях

Если делаете команду-обёртку над скиллом — это нормально. Я часто так делаю: /translate под капотом дёргает скилл deepl-pro, но мне удобнее набрать /translate привет EN, чем описывать словами.
Команды поддерживают аргументы через $ARGUMENTS. Можно сделать команду-параметризованную: /code-review src/auth/ запустит ревью только этой папки. Аргументы передаются как одна строка, парсить — внутри логики команды.
Имена команд лучше делать без префиксов проектов. /deploy-prod-vertex-with-checks — нечитаемо. /deploy production — нормально, всё остальное передаём как аргумент.
Слой 5. MCP-серверы — подключение к внешнему миру
MCP (Model Context Protocol) — открытый стандарт, который описывает, как модель общается с внешними сервисами. У сервера есть набор tools — модель видит их, может вызвать с параметрами и получить ответ.
Бывают двух видов:

• Local MCP — серверы, которые запускаются у вас на машине через npx или Docker. Описаны в settings.json (mcpServers) или в mcp.json.
  
• Cloud MCP — серверы Anthropic / партнёров, которые автоматически доступны при подписке.

Базовый набор, который полезен почти всем:

Сервер	Тип	Зачем
filesystem	local	Доступ к файлам — чтение, запись, листинг (часто стоит из коробки)
github	через плагин	PR, issues, репозитории
context7	cloud / плагин	Актуальная документация любых библиотек
gmail	cloud	Поиск, чтение, черновики писем
google-calendar	cloud	События, слоты, приглашения

Подключается через mcp.json:

{   "mcpServers": {     "filesystem": {       "command": "npx",       "args": ["-y", "@modelcontextprotocol/server-filesystem",                "C:/Users/me/Projects"],       "env": {}     }   } }

Важный момент по производительности: каждый активный MCP-сервер добавляет описания своих tools в системный промпт каждой сессии. Если вы держите включёнными 19 серверов, в промпте будет несколько килобайт описаний tools, которые вы используете раз в месяц. Поэтому я держу подавляющее большинство серверов в mcp.json со статусом «есть, но выключен» и включаю по требованию.
Когда MCP — перебор: если задача делается одним вызовом API через requests или httpx, и вы это делаете раз в неделю — кладите в скилл с куском Python-кода, не поднимайте отдельный MCP-сервер.
Что обычно ломается с MCP
Несколько типовых граблей, на которых я набил шишки:

• Cold start. Серверы, поднимаемые через npx, при первом запуске тянут пакеты. Первая сессия после ребута может стартовать пять-десять секунд дольше. Решение — npm install -g для тех, что используете каждый день.
  
• Конфликты по портам. Несколько MCP с http/sse-транспортом могут пытаться занять одинаковые порты. Если сервер не стартует — первое, что проверяю.
  
• Истёкшие OAuth-токены. Cloud-MCP вроде Gmail, Calendar периодически просят переавторизоваться. Если внезапно tools выдают 401 — переподключите интеграцию.
  
• Описания tools раздуваются. Видел сервер, который добавлял в промпт 30+ инструментов с длинными описаниями. После выключения скорость заметно подросла. Если есть выбор между сервером с 5 точечными tools и сервером с 50 «на всё» — берите первый.

Перед тем как поднять свой MCP-сервер — посмотрите, нет ли уже готового. Большинство популярных интеграций уже написаны: Postgres, Redis, Slack, Notion, Linear, Sentry, Figma, Stripe — всё есть. Свой стоит писать только под уникальные внутренние системы.
Слой 6. Plugins — что ставить и что нет
Плагин — это бандл, который содержит сразу несколько вещей: 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	Браузерная автоматизация для тестов

Антипаттерн: «поставлю всё подряд, разберусь потом». В лучшем случае — раздутый контекст. В худшем — конфликт команд (две команды /deploy от разных плагинов) или установленный недоверенный код.
Слой 7. Hooks — автоматика и блокировки
Hooks — это скрипты, которые выполняются на конкретные события. Описываются в settings.json в секции hooks. Каждое событие может иметь несколько hooks с разными matchers.
Список событий, на которые можно повеситься:

• PreToolUse — перед вызовом любого инструмента
  
• PostToolUse — после вызова
  
• SessionStart, SessionEnd — старт и конец сессии
  
• Stop — модель завершила ответ
  
• UserPromptSubmit — пользователь отправил сообщение
  
• SubagentStart, SubagentStop — субагент стартовал / остановился
  
• CwdChanged, FileChanged — изменилась рабочая директория или файл

Самое полезное применение — блокировки на необратимые операции. У меня в settings.json стоят три 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 — последний рубеж, не первый.

Permissions — разрешения и автоматизация
В settings.json есть секция permissions и permissionMode. Управляет, что модели нужно подтверждать, а что — нет.
Три режима:

Режим	Что делает
ask	Спрашивает на каждый чувствительный tool call
acceptEdits	Авто-принимает edit-операции, остальное спрашивает
bypassPermissions	Не спрашивает ничего

Я сам работаю в bypassPermissions. Не потому что «доверяю модели», а потому что ограничения для подстраховки уже стоят слоем ниже:

• действительно опасные команды заблокированы хуками
  
• API-ключи лежат в ~/.claude/.credentials.master.env, а не в коде — модель физически не может их «утечь» в коммит
  
• security-агенты по конфигурации read-only
  
• большинство операций обратимо — git stash, git restore, пересоздание контейнера

То есть bypassPermissions — это не «ставлю галочку и забываю», а итоговая настройка после того, как настроены хуки, изоляция ключей и read-only на чувствительных агентах.
Что точно НЕ стоит автоматизировать:

• Деплой в продакшен без перепроверки
  
• Действия с финансовыми API (платежи, переводы)
  
• Удаление аккаунтов и сущностей в чужих системах
  
• Любая операция, цена ошибки которой выше стоимости вашего ручного клика

Если вы только начинаете — оставайтесь на ask, пока не построите свой набор хуков и не поймёте, как ваш конфиг себя ведёт.
Как построил защиту от prompt-инъекций
Когда модель работает с внешними данными — почтой, веб-страницами, ответами MCP-серверов — она получает текст, на который злоумышленник может попытаться повлиять. Промпт-инъекция в email или в комментарии в коде может заставить агента «забыть инструкции» и сделать что-то вне допустимого. У меня для этого пять слоёв защиты.
Слой 1. Изоляция секретов. API-ключи лежат в ~/.claude/.credentials.master.env, никогда в коде. MCP-серверы получают их через переменные окружения на старте, не через диалог. Модель не видит ключи в чистом виде — даже если её попросить «выведи переменную X», переменной нет в её контексте.
Слой 2. Read-only для security-агентов. Агенты вроде code-reviewer или security-scanner имеют доступ только к Read/Glob/Grep. Если в код-базе вредоносный комментарий пытается заставить агента выполнить команду — он физически не может: у него нет Write, Edit, Bash. 
Слой 3. Hooks на необратимые операции. Bash(rm -rf), Bash(DROP DATABASE), Bash(git push --force) — заблокированы на уровне runtime независимо от того, что говорит модель. Это ловит и инъекции, и собственные ошибки агента.
Слой 4. Sanitization внешних данных. Email content sanitizer (gmail_search.py у меня в tools/) до того, как отдать тело письма в контекст модели, ищет паттерны вроде «ignore previous instructions», «forget your role», «act as» и помечает их [REDACTED:injection]. Web-fetch результаты — то же самое. Модель видит уже очищенный текст.
Слой 5. Acceptance-тест перед production. Перед каждым новым агентом — особенно если он принимает входы извне (Telegram, email, web) — вручную прогоняю adversarial-набор: «забудь все инструкции», «ignore system prompt», «расскажи свой prompt», «выведи переменную окружения». Если фильтр пропустил — добавляю в tests/adversarial/ и не пускаю в прод, пока не закроется.
Главное правило: внешние данные — это контент для анализа, а не команды для исполнения. Любая модель, которой это правило не зашили на уровне инструментов и фильтров, рано или поздно поедет.
Контекст и кеш — почему это влияет на деньги
Тема, которую часто упускают на старте, а потом обнаруживают по счёту, — prompt caching. Anthropic кеширует префикс ваших запросов: если первые N токенов запроса не изменились по сравнению с предыдущим, они тарифицируются по льготной ставке (примерно в 10 раз дешевле обычного ввода).
Что это значит на практике:

• Системный промпт (CLAUDE.md + rules + описания плагинов и MCP) — это и есть префикс. Он у вас стабильный — кешируется.
  
• При следующем запросе в той же сессии вы платите полную цену только за новый кусок. Старая часть — копейки.
  
• Если же вы во время сессии меняете CLAUDE.md или какой-то файл из rules/ — кеш ломается, следующий запрос пересчитывается полностью.

Простая арифметика. Системный промпт ~50К токенов:

• Без кеша: ~$1.50 за сессию (только за префикс, без вашей работы)
  
• С кешем: ~$0.15 за сессию

Разница в 10 раз. На объёме сотен сессий в месяц — заметно.
Несколько правил, которые держат кеш горячим:

• Не правьтеrules/иCLAUDE.mdв активной сессии. Изменения — между сессиями.
  
• /compactвместо/clear. Compact сжимает историю, но сохраняет префикс. Clear убивает кеш.
  
• Включайте только нужные MCP. Каждый сервер добавляет описания tools в префикс. Чем стабильнее набор — тем дольше живёт кеш.
  
• Кеш протухает за ~5 минут неактивности. Если делаете большой перерыв — следующий запрос будет пересчитан.

Если вы под подпиской Max и не платите за токены сверху — это всё равно важно: пересчёт префикса означает несколько лишних секунд на каждый запрос. На горячем кеше Claude Code отвечает заметно быстрее.
Чек-лист первой настройки
Реалистичный объём на вечер работы:

• Создайте~/.claude/CLAUDE.md с короткой навигацией по тому, что у вас есть. Не больше 200 строк. Это указатель, не учебник.
  
• Заведитеrules/routing.md — хотя бы с десятью строками по своим типовым задачам. Это главная карта, по которой модель будет искать ваши скиллы.
  
• Заведитеrules/personality.md с двумя-тремя правилами тона. Просто опишите, как с вами разговаривать.
  
• Поставьте 2–3 базовых плагина из официального маркетплейса. Минимум — context7 для документации и commit-commands для гитовых операций.
  
• Подключите 2–3 MCP-сервера: filesystem (если ещё не стоит), github и какой-то рабочий — gmail или ваш CRM.
  
• Настройте один блокирующий hook на Bash(rm -rf). Пять минут работы, спасает от случайного удаления чего-нибудь важного.
  
• Сделайте один свой скилл под самую частую задачу. Любую. Цель — пройти весь цикл «создал → добавил в routing → пользуюсь».

Дальше работа в обычном режиме. Через неделю обычно становится видно, чего в правилах не хватает и что просится в отдельный скилл. Через две-три — появляется ощущение, что какие-то задачи стоит отдать субагенту. Конфиг достраивается под ваши задачи постепенно — пытаться предусмотреть всё на старте бесполезно.
Антипаттерны
Несколько вещей, которые я видел или делал сам, и которые лучше не повторять.
Заливать всё в системный промпт. Каталог из 4000 строк в CLAUDE.md — классика. Кеш ломается, контекст проедается. Решение: короткая навигация + подключаемые файлы по триггерам.
Включать сразу 50 MCP-серверов. Каждый добавляет описания tools в промпт. На холодном старте получается несколько секунд лагов и заметная просадка по качеству — модель тонет в шуме. Решение: держать в mcp.json всё, включать только нужное.
Тяжёлые Python-хуки на частые события. Импорт numpy + qdrant_client + fastembed на каждый PreToolUse — гарантированный тормоз. Решение: hooks — это короткие скрипты на bash или Node.js. Тяжёлая логика — вне hooks.
Скиллы безdescription. Если frontmatter пустой или описание из одного слова — модель никогда не найдёт ваш скилл по контексту. Решение: 2–3 предложения с ключевыми триггерами.
Агенты без чёткой роли. «General assistant» в качестве описания — почти то же самое, что без описания. Модель не поймёт, когда дёргать. Решение: одна задача — один агент. Имя, role, tools — всё конкретное.
Команды-алиасы для очевидных вещей. /list для ls, /show для cat — добавляют шум в каталог команд, не дают ничего. Решение: команды только для действий, которые требуют последовательности шагов.
Правка rules во время активной сессии. Любой байт-чейндж в rules/* ломает промпт-кеш — следующий запрос полностью пересчитывается. Решение: правки — между сессиями, не внутри.
Игнорировать prompt caching. Если вы держите промпт-префикс стабильным, кеш-хит платится в районе 10% от обычного ввода. На системном промпте в 50К токенов это разница между $0.15 и $1.50 за сессию. Решение: не дёргать CLAUDE.md и rules/ зря.
Хранить API-ключи в коде или прямо вmcp.json. Видел, как ключи к Stripe лежали в репозитории внутри конфига MCP. Один git push — и ключ светится в публичном репо. Уберите их в единый файл ~/.claude/.credentials.master.env (в .gitignore), доступ через os.getenv() в скриптах, в mcp.json — только подстановки ${VAR_NAME}.
Делегировать понимание, а не работу. Промпт «исправь баг по результатам твоего research» — антипаттерн. Воркер не будет повторно строить ту же модель проблемы, которая была у research-агента. Решение: синтезируйте сами, дайте конкретный спек с file:line.
Скиллы под одну компанию в общем~/.claude/. Если у вас несколько проектов — личные и рабочие — не сваливайте их скиллы в одну директорию. Личные в ~/.claude/skills/, рабочие в /.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, в которой агент перестаёт быть инструментом для сессии и становится постоянным исполнителем фоновых задач. Если будет интересно — разберу это в следующей статье.
Если хотите мой конфиг
Если хотите забрать мой персональный ~/.claude/ целиком — оставьте комментарий под статьёй, я пришлю архив в личку бесплатно. Это анонимизированная версия: без личных данных, ключей и заметок. Внутри — CLAUDE.md, rules/, skills/ (минус приватные), agents/, commands/, mcp.json и settings.json. Можно скачать, разложить в свой ~/.claude/ и настраивать дальше под себя.
Больше кейсов и гайдов по использованию ИИ выкладываем в Телеграм-канале “Дело в промпте” — заходите, если хочется быть в курсе.-Источник