Расширение Claude Code: CLAUDE.md, hooks, subagents, MCP

За пять глав мы установили Claude Code, научились давать указания, выбираться из тупиков и проектировать разрешения. Эта глава — про то, как переделать сам инструмент. Расширениями нельзя пользоваться, просто запомнив названия. Полезна другая вещь: таблица соответствия «какое из них решает мою текущую боль».

Карта выбора: всё решают четыре вопроса

Расширений шесть, но думать надо всего о четырёх вещах. Хватит ли просьбы / нужно ли гарантированное срабатывание / нужно ли отделить контекст / нужно ли подключиться наружу. Спросив себя об этом по порядку, вы почти всегда получите единственный ответ.

Хватит ли просьбы

Если изредка пропустить не смертельно, хватит слов. → CLAUDE.md (общие предпосылки) / Skills (порядок действий для конкретной работы)

Нужно ли гарантированное срабатывание

Если даже один пропуск недопустим, проверяйте условие программно. → hooks. Они запускаются, когда включённые настройки соответствуют событию и условиям.

Нужно ли отделить контекст

Если не хотите забивать основную линию огромным выводом, пусть работа идёт снаружи, а вы получите только вывод. → subagents

Нужно ли подключиться наружу

Если нужны сведения, которых ИИ знать неоткуда (текущие значения в базе, содержимое трекера задач). → MCP

Пятый вопрос — «буду ли я раздавать это другим». Если да, то plugins. Легче всего спутать Q1 и Q2: CLAUDE.md, Skills и hooks. Выглядят они одинаково, а различаются тем, когда их читают и кто их исполняет.

CLAUDE.md: отделяйте загрузку от соблюдения

CLAUDE.md передаёт контекст проекта в каждой сессии, если находится в загружаемом месте. Для общих инструкций всех проектов используйте ~/.claude/CLAUDE.md. Это текстовые инструкции, а не настройки, принудительно определяющие разрешения на операции.

Если агент говорит, что прочитал файл, но не следует ему, рассмотрите три вопроса по отдельности.

Загрузился ли файл? Посмотрите, есть ли CLAUDE.md и правила в разделе Memory files команды /context. На состав файлов влияют место запуска и настройки исключений. Напрямую загруженный AGENTS.md не отображается в этом списке, поэтому отсутствие записи ещё не доказывает, что файл не прочитан
Вернулся ли файл после сжатия? После /compact корневой CLAUDE.md заново читается с диска и вставляется в контекст. CLAUDE.md из подкаталогов и правила для отдельных путей возвращаются при чтении подходящих файлов. Решения, оставшиеся только в разговоре, обрабатываются иначе
Повлияли ли инструкции на действие? Даже если файл загружен, отдельно проверьте неясные правила и противоречия. Не считайте, что самая новая инструкция всегда побеждает. Укажите область действия и условия исключений

Официальный ориентир — менее 200 строк на файл CLAUDE.md. Это не предел загрузки и не граница, гарантирующая соблюдение. Оставляйте правила, нужные каждый раз, а подробности выносите отдельно с условиями их чтения. Импорт всего через @path не уменьшает стартовый контекст. Для редких процедур используйте Skills, а для указаний к определённым файлам — правила, привязанные к путям.

Это описано в официальной документации по памяти. Примеры того, как отличать эти случаи, и различия инструментов разобраны в статье как выяснить, почему ИИ-агент игнорирует правила.

«Я прочитал» не доказывает соблюдения. Проверяйте отображение загрузки отдельно от diff и результатов тестов. Условия, которые можно проверить программно, переносите в hooks или CI, как описано далее, и указывайте оставшиеся непроверенные области.

hooks: проверки при выполнении условий

Текстовое указание вроде «не переписывай .env» не гарантирует определённую долю соблюдения. Если нужно проверить условие и заблокировать операцию до выполнения, рассмотрите настройки разрешений и hooks.

В этом разделе речь о хуках типа command, запускающих команды оболочки. Когда включённые настройки соответствуют событию и условиям, их запускает сам Claude Code. Модели не нужно вспоминать о запуске. Но если хук отключён настройками или операция идёт в обход охваченных путей, он не сработает. Обзор приведён в статье Что такое hooks в Claude Code. Ниже девять характерных событий, а не полный перечень.

SessionStart        при запуске или возобновлении
UserPromptSubmit    сразу после отправки              [может блокировать]
PreToolUse          прямо перед инструментом = привратник [может блокировать]
PostToolUse         после успеха инструмента = форматирование (не отменяет уже выполненное действие)
Notification        ожидание ввода или разрешения
Stop                конец ответа                      [может блокировать]
SubagentStop        субагент завершился               [может блокировать]
SessionEnd          сессия завершается
PreCompact          перед сжатием                     [может блокировать]

Возможность блокировки зависит от события. Остановить инструмент до выполнения и не дать ответу завершиться, чтобы продолжить работу, — разные действия. Запрещать опасные операции в PreToolUse и автоматически форматировать в PostToolUse — две обычные отправные точки. Настройка размещается под ключом "hooks" в settings.json. Место файла определяет область действия (~/.claude/ — пользователь, .claude/ — общая, settings.local.json — личная).

Теперь превратим просьбу из начала раздела — «не переписывай .env» — в механизм. Это пример «запретить редактирование защищённых файлов» из официального руководства, суженный до .env. Понадобятся две вещи: настройка и скрипт.

① .claude/settings.json — перед вызовом Edit или Write запускает скрипт.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh"
          }
        ]
      }
    ]
  }
}

② .claude/hooks/protect-env.sh — останавливает редактирование, если имя файла начинается с .env (включая .env.local и т. п.). В macOS и Linux дайте файлу право на выполнение: chmod +x .claude/hooks/protect-env.sh.

#!/bin/bash
# .claude/hooks/protect-env.sh
command -v jq >/dev/null || { echo "jq не найден, поэтому редактирование остановлено" >&2; exit 2; }

FILE_PATH=$(jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"   # приводим Windows-разделитель \ к /

if [[ "${FILE_PATH##*/}" == .env* ]]; then
  echo "Blocked: $FILE_PATH — это .env, редактировать не буду" >&2
  exit 2
fi
exit 0

Структура: имя события → массив условий сопоставления и команд. Поле matcher задаёт имена инструментов: "Edit|Write" соответствует Edit или Write (без него подходят все инструменты). Хук получает JSON на стандартном вводе, и для Edit и Write в tool_input.file_path лежит абсолютный путь к редактируемому файлу. В Windows разделитель в этом пути — \, поэтому скрипт сначала приводит его к / и только потом сравнивает. Если остановить операцию кодом завершения 2, текст из стандартного потока ошибок передаётся Claude как причина отказа, и Claude, прочитав его, ищет другой способ. Код 1 считается неблокирующей ошибкой, и операция продолжается, поэтому для остановки используйте 2. Код 0 означает отсутствие возражений, и дальше идёт обычная проверка разрешений.

Скрипт использует bash и jq (пример из официального руководства тоже рассчитан на jq). В Windows хуки выполняются в Git Bash, а если Git Bash не установлен — в PowerShell, поэтому для этого примера нужен Git Bash. Чтобы при отсутствии jq правки не проходили бесконтрольно, скрипт останавливает операцию первым же действием.

Хуки могут ужесточить ограничения, но не могут их ослабить. Даже вернув разрешение, они лишь пропускают запрос, а запрещающие правила всегда в приоритете. Отказ на PreToolUse действует даже в режиме, который пропускает все согласования, поэтому его можно держать как дно под тем, что вы ослабили в главе 5.

Проверяется это так же, как в официальном руководстве. Попросите Claude «добавить в .env строку комментария»: редактирование остановится до выполнения, и Claude получит сообщение Blocked:. Заодно убедитесь, что остальные файлы, кроме .env, редактируются как прежде. Если ошибиться в пути к скрипту, появится лишь уведомление Failed with non-blocking status code, а ворота останутся открытыми — не пропустите это уведомление. Учтите, что этот пример останавливает только два инструмента, Edit и Write; изменения через команды Bash или PowerShell идут другим путём. Расширяйте охват под то, что нужно остановить. Форматы вывода и различия событий описаны в официальном руководстве по Hooks.

Сразу учитывайте цену: хуки типа command автоматически выполняют команды оболочки с правами вашего пользователя и могут изменить или удалить любой файл, доступный вашей учётной записи. Официальная документация требует прочитать и протестировать каждую команду, прежде чем добавлять её. Настраивайте только доверенные команды и проверяйте входные данные. Изменения, внесённые прямо в файлы настроек, обычно применяются автоматически. Смотрите регистрацию через /hooks. Если изменение не применилось, сначала проверьте JSON и расположение файла, а уже затем перезапускайте сессию.

subagents: отдать работу, отделив контекст

Полный вывод тестов и огромные логи заполняют контекст массой текста, которую вы собирались лишь просмотреть, вытесняя важные предпосылки. Субагенты выполняют такую работу в отдельном контексте и возвращают сводку с выводами. Обычно у них собственные контекст, инструкции и разрешения на инструменты, поэтому родитель должен явно передать необходимые сведения. Исключение — выполнение с ответвлением разговора, наследующее историю родителя; это отличается от context: fork у навыка. Поскольку отчёт является сводкой, просите включить нужные подтверждения и открытые вопросы.

Разделять выгодно: широкие изыскания / проверки с большим объёмом вывода / самодостаточные задачи, от которых нужен только вывод
Разделять в убыток: последовательная обработка / частые круги туда-обратно / параллельная работа над одним файлом / правка в один-два хода

Это штатная возможность, так что она доступна без настройки. Чтобы добавить своё определение, положите .claude/agents/<имя>.md (общие — в ~/.claude/agents/) и опишите в YAML-заголовке name, description, tools, model. Управление — через /agents, вызов — через @agent-<имя>. Для начала хватит штатных: для разведки, для планирования и универсального.

Ключ к вызову — description. Главный агент читает его, решая, делегировать ли задачу, поэтому расплывчатое описание снижает вероятность автоматического выбора. Конкретно указывайте назначение и условия применения. Та же ловушка есть у Skills.

Легко спутать с этим Agent Teams — механизм, где несколько независимых сессий взаимодействуют через общий список задач. Экспериментальная возможность с явным включением, по умолчанию выключена (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Работают отдельные экземпляры, поэтому расход токенов велик, и вкладывать их друг в друга нельзя. Разницу разбирает статья Чем subagents отличаются от Agent Teams. При сомнениях берите одну сессию или subagents.

Skills: превратить порядок действий в актив

Для шаблонного «каждый раз в таком порядке» Skills хороши тем, что открываются только тогда, когда нужны. По сути это папка, построенная вокруг файла SKILL.md. В начале — name и description, ниже порядок действий в Markdown, а рядом можно положить reference/ и scripts/. Достаточно положить это в .claude/skills/ (проект) или ~/.claude/skills/ (общие), и это будет распознано.

Основной принцип — постепенное раскрытие. Обычно в контекст попадает список названий и описаний навыков, а содержимое загружается при автоматическом выборе или явном вызове /skill-name. Дополнительные материалы читаются по необходимости. Список описаний тоже расходует контекст; если навыков много, описания могут сокращаться или пропускаться ради соблюдения бюджета. Пишите конкретный description и отдельно проверяйте вызов навыка и ожидаемый результат процедуры. Как его создать, описано в статье Что такое Claude Agent Skills.

Одной строкой: CLAUDE.md — регулярно загружаемые предпосылки; Skills — процедуры, открываемые автоматически или явным вызовом; хуки типа command — обработка по настроенным событиям и условиям.

MCP: дотянуться до внешних систем

MCP (Model Context Protocol) — стандарт для доступа к внешним данным и операциям, например текущим значениям в базе данных или тикетам в трекере задач. Ниже — два распространённых способа подключения. Ищите причину проблемы, сопоставляя способ подключения с подробностями ошибки.

Локальный (stdio) — сервер запускается как дочерний процесс на вашем компьютере. Подсказки — путь исполняемого файла, необходимые переменные окружения и вывод ошибок сервера
Удалённый (HTTP) — подключение к серверу по URL. Подсказки — URL, сеть, ошибки на стороне сервера и учётные данные

Начните со статуса и подробностей в /mcp. failed возможен и у локальных, и у удалённых серверов. Если Issue: в claude mcp get <name> содержит HTTP-код или текст ошибки, прочитайте и их. needs authentication — отправная точка для проверки аутентификации, pending approval — для пересмотра одобрения проектного сервера. Если фиксированный заголовок Authorization отклонён с 401/403 при подключении, статус будет failed, хотя причина в аутентификации. Исправления собраны в статье Ошибки подключения MCP в Claude Code: причины и решения.

Разместите общий файл конфигурации .mcp.json в корне проекта. Раздел env каждого сервера используйте для переменных, передаваемых stdio-серверу; для HTTP-аутентификации используйте OAuth или headers в зависимости от сервиса. Не записывайте реальные ключи прямо в общие файлы; вместо этого ссылайтесь на переменные окружения, например ${API_KEY}. Некоторые имена переменных, включая учётные данные самого Claude Code, в удалённых URL и заголовках заменяются пустыми строками; подробности — в официальных правилах подстановки.

По умолчанию определения инструментов загружаются по запросу. В обычной конфигурации с включённым поиском инструментов в контекст сначала попадают только их названия и описания серверов. Определения загружаются заранее, например при отключённом поиске, в неподдерживаемых средах или для серверов с настройкой alwaysLoad. Вывод тоже занимает контекст, поэтому проверяйте фактический расход через /context и отключайте неиспользуемые серверы.

plugins: собрать комплект и раздать его

Плагины позволяют объединить навыки, определения субагентов, хуки и конфигурацию MCP для распространения. Если у отдельного плагина есть манифест, поместите его в .claude-plugin/plugin.json. Стандартная структура располагает skills/, agents/, hooks/hooks.json и .mcp.json в корне самого плагина. Не размещайте их внутри .claude-plugin/. Плагин, использующий только стандартную структуру, может обходиться без манифеста.

/plugin marketplace add owner/repo   ← зарегистрировать каталог
/plugin install name@marketplace     ← установить оттуда конкретный плагин
/plugin list                         ← список плагинов, установленных через маркетплейсы

Это основные шаги установки через маркетплейс. Одна лишь регистрация каталога не устанавливает плагины. /plugin list показывает плагины, установленные этим способом, а не все плагины из других источников, например каталогов навыков или синхронизации. Области действия: user (все ваши проекты), project (общая конфигурация), local (только вы в данном проекте). Даже при project каждый участник должен установить плагины из внешних источников. Область managed управляется централизованно и ограничивает изменение конфигурации пользователями. Создание своих плагинов описано в статье Плагины и маркетплейс Claude Code: использование, создание и публикация.

Плагины могут выполнять произвольный код с вашими правами, предупреждает официальная документация. Публикации сообщества проходят автоматическую проверку и проверку безопасности Anthropic, но это не гарантирует ожидаемого поведения. Проверяйте издателя, включённый код и MCP-серверы. Проектирование разрешений из главы 5 применяется и к чужому коду.

С чего начинать: разговор о порядке

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

Объясняете одно и то же каждый раз → CLAUDE.md. Если это касается только одной работы, то Skills
Записали, а не соблюдается → проверьте загрузку, область действия и конфликты инструкций. Программно проверяемые условия переносите в hooks
Контекст быстро забивается → тяжёлые изыскания в subagents, ненужные MCP отключить
ИИ не дотягивается до сведений → MCP. Подключайте по одному и переходите к следующему, увидев, что предыдущий заработал
Хотите раздать одинаковую настройку → plugins. Собирайте только то, чем сами уже пользуетесь
Ничего особенно не мешает → не ставьте ничего. Это и есть лучшее состояние

Последняя строка не шутка. Расширения увеличивают и число причин застрять: за «Claude Code ведёт себя странно» часто стоит слой, добавленный вами самими. Поэтому сначала локализация из главы 4.

Итоги

Критерий выбора — четыре вопроса: хватит ли просьбы (CLAUDE.md, Skills) / нужно ли гарантированное срабатывание (hooks) / нужно ли отделить контекст (subagents) / нужно ли подключиться наружу (MCP). Раздавать — plugins
CLAUDE.md хранит постоянные инструкции. Корневой файл возвращается после сжатия. Сокращение не гарантирует соблюдения; проверяйте загрузку и поведение отдельно
Хуки типа command запускает Claude Code при совпадении настроенных условий. Проверяйте пути выполнения и поведение блокировки; хук после операции не отменяет уже совершённое действие
subagents работают в отдельном контексте и возвращают только сводку. Для последовательной обработки и частых кругов туда-обратно не годятся
Skills используют постепенное раскрытие, загружая содержимое по необходимости. Для автоматического выбора нужны конкретные описания; даже после явного вызова проверяйте результат процедуры
MCP — стандарт внешнего доступа. Ищите причины проблем, сопоставляя статус в /mcp со способом подключения и подробностями ошибки
plugins — коробка для раздачи. Чужой код исполняется с вашими правами, поэтому проверяйте издателя
Порядок установки задаётся симптомом. По одному и только после того, как боль появилась

О том, как сравнивать сами инструменты и выбирать между ними, — глава 6 «Расширяем возможности» курса по ИИ-программированию.

Чем больше расширений, тем выше расход. Напоследок разберём эксплуатацию для долгой работы. Переходите к главе 7 «Стоимость и лимиты».

Как его расширять — CLAUDE.md, hooks, subagents и MCP