Пять уровней внутри Claude Code: память, навыки, хуки, сабагенты и плагины
Claude Code рассматривается как среда выполнения агентов: память CLAUDE.md, навыки по запросу, детерминистичные хуки, изолированные сабагенты и плагины, которые объединяют всё это для команды.
Источники: **Claude Code’s 5-Layer Agent Development Kit: The Architecture Most Engineers Are Missing**
Многие инженеры считают Claude Code очень мощным помощником для программирования: открывается терминал, задаётся задача, он читает файлы и выполняет команды, после чего можно наблюдать за ходом работы. Это описание верно, но неполно. В документации Anthropic он представлен как агентный инструмент для программирования, работающий в терминале, понимающий структуру кодовой базы, выполняющий рутинные задачи и взаимодействующий с внешними системами через такие механизмы, как MCP. Если внимательно прочитать, становится ясно, что это скорее структурированная среда выполнения агентов с несколькими отдельными интерфейсами управления, чем просто модель, обёрнутая в оболочку командной строки.
К таким компонентам относятся файл CLAUDE.md, сохраняющий информацию в памяти, повторно используемые навыки, детерминистичные хуки, подагенты, которым поручаются задачи, плагины, доступные для установки, а также ссылки MCP на внешние системы. Поэтому акцент смещается. Вопрос о том, что может генерировать Claude Code, менее важен, чем вопрос о том, как можно формировать его поведение, ограничивать его функции, специализировать и делиться им внутри команды.
Стек из пяти слоев
Базовая модель может писать код, объяснять содержимое файлов и отвечать на вопросы. Однако сама по себе она не решает ряда проблем: сохранение информации о проекте между сессиями, повторное использование специализированных знаний, введение ограничений на уровне инфраструктуры, контроль за тем, что может быть делегировано, а также обеспечение единообразного поведения в команде. Эти проблемы выходят за рамки простого запроса, и дизайн Claude Code всё больше учитывает это. В документации они описаны как отдельные механизмы: постоянные файлы инструкций, расширяемые навыки, пользовательские субагенты, хуки, диапазоны настроек, плагины и возможность подключения через MCP. Вместе они не представляют собой простой набор функций — это слои, которые делают поведение агента более надежным, переиспользуемым и управляемым:
- CLAUDE.md — это слой памяти и правил.
- Навыки — это слой знаний, обеспечивающий необходимую экспертизу по запросу.
Шаблоны MCP и agent-team оборачивают всю структуру в качестве систем, связывающих её с внешним миром.
Эта классификация объясняет проблему, характерную для неудачных проектов с агентами: слабым местом редко бывала сама модель. Не хватало определенного слоя. Одна команда полностью зависит от подсказок и не имеет постоянной памяти проекта. Другая имеет подробные инструкции, но не располагает детерминистичными механизмами контроля за использованием рискованных инструментов. Третья перегружает одного универсального агента, в то время как работу следовало бы разделить между специалистами. Большинство сбоев агентов связаны с архитектурой, а не с проблемами подсказок. Каждый слой рассматривается ниже, начиная с основного.
Почему архитектурный подход лучше списка функций
Если рассматривать Claude Code как список функций, возникает вопрос о том, что он может делать. Однако если рассматривать его с точки зрения архитектуры, появляется более точный вопрос: какие слои он предоставляет для контроля над тем, как формируется, ограничивается, делегируется и обменивается поведение агента? Как только вопрос меняется, становится проще понимать структуру системы, а также диагностировать проблемы при её использовании.
Из документации следуют два вывода. Во-первых, ни один из этих механизмов не находится внутри самой модели. Они расположены вокруг неё — в файлах, обработчиках событий, контекстах конфигурации и форматах упаковки. Во-вторых, каждый из них решает определённую проблему: память помогает избежать забывчивости, навыки — улучшить общее поведение, хуки — бороться с ненадёжностью, подагенты — слишком большим объёмом контекста, а плагины — необходимостью вручную повторять хорошо настроенные настройки.
Первый уровень: CLAUDE.md в качестве памяти
Основой является CLAUDE.md. В документации его описывают как место для постоянных инструкций относительно того, как работать над проектом, в то время как отдельная функция автоматической памяти хранит заметки, которые Claude записывает для себя после многократных корректировок и установки предпочтений.
Такое разделение важно. CLAUDE.md не предназначен для временных промптов. Команды сохраняют здесь долгосрочный контекст: стандарты кодирования, принятые ранее архитектурные решения, популярные библиотеки, чек-листы для ревью и ограничения рабочего процесса — всё, что должно быть видно до первого сообщения в сессии.
Интересной технической частью является способ загрузки. Речь не идет о чтении одного файла только из текущей директории. Claude просматривает иерархию директорий, начиная с рабочей директории, и загружает все файлы CLAUDE.md и CLAUDE.local.md, которые он находит. Эти файлы объединяются в единый контекст, а не заменяют друг друга, причем инструкции, расположенные ближе к директории запуска, читаются позже.
Это делает его системой памяти с определенным диапазоном применения, а не отдельным файлом конфигурации. Файл верхнего уровня может содержать правила, действующие во всем репозитории, такие как правила номенклатуры, ожидания от тестов или архитектурные границы, в то время как файл более низкого уровня может ограничивать поведение конкретной подсистемы. Представьте себе монорепозиторий: корневой файл указывает, как называются тесты и где проходят границы сервисов, в то время как файл внутри каталога payments добавляет более строгие правила, действующие только там. Тот, кто запускает сессию в этом каталоге, получает оба набора правил, причем более специфические инструкции считаются в последнюю очередь.
Импорты обеспечивают возможность комбинирования элементов. Синтаксис @path/to/import позволяет командам разделять крупные наборы инструкций на меньшие, повторно используемые модули, так что один файл Markdown не превращается в хаос из ненужных элементов. Система Launch раскрывает импортированные файлы в контексте, причем сам импорт может содержать другие импорты, до пяти уровней глубины. На практике CLAUDE.md ведет себя скорее как система для комбинирования элементов проекта, чем как статическая шаблонная форма запроса.
Автоматическая память выполняет иную функцию. Обе загружаются в начале каждого разговора, но CLAUDE.md содержит то, что люди вводят намеренно, тогда как автоматическая память хранит собственные записи Claude в локальном каталоге, индексируемые через MEMORY.md. При запуске сессии загружаются только первые 200 строк или 25 КБ этого индекса. В отличие от этого файлы CLAUDE.md загружаются полностью, независимо от их длины, хотя компания Anthropic отмечает, что короткие файлы обрабатываются эффективнее. Одна из систем является контролируемой и декларативной; другая — адаптивной и эмергентной.
Лучшей моделью мышления, чем «контекст вставляется один раз, чтобы Claude запомнил стиль», является рабочий устав агента. Anthropic даже указывает местоположения во всей организации для централизованно управляемых файлов CLAUDE.md на основных операционных системах десктопов, что свидетельствует о том, что этот уровень предназначен для устойчивой операционной политики, а не только для личных предпочтений. Это избавляет команды от необходимости повторять одни и те же ограничения на каждой сессии и обеспечивает агенту стабильную основу перед началом работы над конкретными задачами.
Практическим следствием правил загрузки является то, что CLAUDE.md требует тщательного управления. Поскольку каждый обнаруженный файл загружается полностью, это приводит к увеличению объема данных в каждой сессии, поэтому рекомендации Anthropic относительно использования более коротких файлов служат основанием для их регулярной оптимизации. Процедуры, которые стали слишком объемными, первыми попадают в список для удаления, что напрямую ведет к следующему уровню.
Второй уровень: навыки как знания по запросу
Если CLAUDE.md представляет собой постоянную память и правила работы, то навыки обеспечивают модульные знания, которые доступны по мере необходимости. Согласно документации, новые способности Claude приобретаются путем записи инструкций в файл SKILL.md. Команда с слешом используется для явного вызова навыка, либо Claude может самостоятельно его использовать, когда считает, что задача этого требует.
Ключевым аспектом архитектуры является синхронизация времени. Совокупность навыков не представляет собой постоянную память проекта. Она включается в контекст только по мере необходимости, что позволяет использовать повторно применимые процедуры, чек-листы и руководства по конкретной области без увеличения объема каждой сессии.
Многие инженеры рассматривают настройку как один длинный запрос: они помещают всё в постоянный контекст, надеясь, что модель сама определит, что важно. Навыки представляют собой более структурированный вариант. Anthropic рекомендует создавать навыки тогда, когда одни и те же инструкции вставляются многократно или когда отдельный раздел в CLAUDE.md превращается из факта в процедуру. В CLAUDE.md должны храниться постоянные правила проекта, а в навыках — повторно применимые операционные знания. Это позволяет сохранять легкий вес постоянно загружаемого контекста и превращать сложные рабочие процессы в модули, которые Claude может использовать по мере необходимости.
Навыки — это не просто переименованные пользовательские команды. Старые файлы .claude/commands/.md и новые определения .claude/skills//SKILL.md ведут себя схожим образом при вызове, но навыки предоставляют дополнительный уровень контроля. Они позволяют использовать директорию с вспомогательными файлами, определять, кто может их активировать — пользователь, Claude или оба, поддерживают динамическую подстановку контекста и могут даже выполняться внутри подагента. Именно поэтому подходит термин «уровень знаний»: навык — это единица, с помощью которой экспертиза, процедуры и контекст задачи становятся составными элементами во время выполнения программы.
Можно рассматривать навык как запечатанный пакет знаний для выполнения определенной работы. В его описании указывается цель, а механизм сопоставления на этапе выполнения определяет, соответствует ли он текущему запросу; инструкции внутри загружаются только тогда, когда они могут помочь. В документации отмечается, что такие группировки навыков, как /debug, /loop и /simplify, основаны на промптах, а не на фиксированной логике, что является важным показателем их конструкции. Благодаря этому поведение становится модульным, поскольку не требуется встраивать всё в основной продукт, что является гораздо более масштабируемым подходом, чем использование одного огромного базового промпта для обработки всех рабочих процессов.
Рассмотрим команду, у которой есть стандартный метод для отладки ненадежных тестов, проверки миграций SQL или составления записей об выпуске. Понятие «перманентная память» слишком общее для таких задач, а единоразовые запросы к модели языка слишком повторяющиеся. Команда один раз формирует необходимую процедуру, хранит рекомендательные материалы рядом с ней, а Claude загружает их только тогда, когда это требуется задачей. Длинные рекомендательные тексты внутри навыка почти не стоят ничего до момента их использования, поэтому такой подход более чистый и дешевле в реализации.
Таким образом, навыки стимулируют привычку замечать повторения. Каждый раз, когда одно и то же объяснение вводится в третий раз или абзац в файле CLAUDE.md начинает выглядеть как нумерованная процедура, скорее всего, речь идет о навыке, который можно извлечь. Эта процедура занимает несколько минут, но окупается каждый раз, когда возникает аналогичная задача.
В совокупности CLAUDE.md обеспечивает агенту стабильные основные правила, а функции Skills дают ему целенаправленные, повторно используемые навыки без увеличения размера основного окна контекста. Следующий уровень делает такое поведение более безопасным.
Третий уровень: хуки в качестве ограничений
Хуки превращают поведение агента в нечто, что можно контролировать. Официальная документация описывает их как автоматизацию, основанную на событиях: команда выполняется до или после определенного действия в Claude Code по сигналу самого события. Хуки описывают типичные способы применения: автоматическое форматирование кода после изменений, отказ в редактировании защищенных файлов, восстановление контекста после сжатия разговора, аудит изменений конфигурации, обновление состояния среды при изменении файлов и предварительное одобрение определенных запросов на разрешения.
Это отличная работа от простого формулирования запросов. Запрос может предложить определённое поведение; хук же может детерминированно перехватить его или изменить. По этой причине хуки лучше рассматривать как слой защиты, а не просто удобство для автоматизации.
Конкретный пример — руководство по расчёту затрат: хук PreToolUse перехватывает команды Bash, распознаёт тестовые запуски и переписывает их так, чтобы результат, получаемый Claude, содержал только информацию о сбоях, а не весь поток данных. Механически хук получает JSON-пакет с описанием ожидающегося вызова, анализирует команду и возвращает JSON с изменёнными данными для ввода в инструмент. Во всём этом нет ничего такого, что позволяло бы ИИ принимать лучшие решения. Это инфраструктура, которая определяет, что модель может видеть или делать на данном этапе рабочего процесса.
Следует обратить внимание на разницу с правилами на уровне запроса. Мягкие ограничения часто бывают слишком слабыми для промышленного использования. Предположим, что генерируемый код всегда должен быть переформатирован, чувствительные файлы никогда не должны меняться или же вызовы разрушительных инструментов требуют более строгой проверки. Опора исключительно на письменные инструкции щекотлива, тогда как хуки перемещают контроль за пределы дискреционных возможностей модели и обеспечивают соблюдение правил рабочего процесса на уровне событий.
Хуки также находятся рядом с управлением контекстом, а не внутри него. В документации по устранению ошибок проблема «хуки не срабатывают» выделяется как отдельная проблема конфигурации, и рекомендуется использовать /doctor для диагностики проблем с хуками, серверами MCP и использованием контекста. Оба этих факта показывают, что хуки относятся к среде выполнения: это поведение, определяемое конфигурацией, которое необходимо правильно интегрировать в режим работы сессии, а не текст, который читает Claude.
Существует также аспект затрат. Руководство по затратам Anthropic рекомендует переносить обработку в хуки и навыки, поскольку хуки могут предварительно обработать большие объемы данных ещё до того, как модель их увидит. В качестве примера приводится фильтрация огромного журнала тестов, при которой сохраняются только сбои, что позволяет сократить объем данных, состоящий из десятков тысяч токенов, до значительно меньшего размера. Таким образом, хуки способствуют не только безопасности, но и эффективности: они сокращают потери токенов, сохраняют более чистый контекст и освобождают модель от задачи предсказуемой фильтрации, которую детерминистическая логика оболочки выполняет дешевле и надежнее.
Полезно представить себе ситуацию до и после внедрения хуков. До них команда пишет в инструкциях «всегда запускайте форматтер» и надеется на это. После внедрения хуков форматтер запускается при каждой правке, независимо от того, помнит ли об этом модель, а защищенные файлы просто невозможно изменить. Агент по-прежнему свободно решает, что создавать; хуки определяют, что допускается в процессе этих решений.
Большинство команд сначала недооценивают этот уровень. Память помогает агенту запоминать, а навыки — специализироваться, но хуки превращают повторяющиеся операционные требования в правила. Они находятся именно там, где происходит взаимодействие рассуждений, основанных на модели, и поведения, навязанного системой, что и является причиной многих сбоев в производственной среде. Без них качество слишком сильно зависит от формулировок запросов.
Четвертый уровень: сабагенты для делегирования
Если хуки отвечают за управление, то сабагенты — за делегирование задач. В документации их описывают как специализированных ИИ-ассистентов, которые выполняют определенные типы задач в своем собственном окне контекста и возвращают только результат.
Логика проста. Один из самых быстрых способов испортить сессию — позволить вспомогательным задачам загрязнять основной диалог логами, результатами поиска или исследовательскими рассуждениями, которые никогда не будут использованы снова. Вместо того чтобы заставлять одного универсального агента обрабатывать всё в одном потоке, основной агент передает вспомогательную задачу специализированному работнику, который выполняет её независимо и предоставляет краткое резюме. Преимущества включают:
- Исследования и реализация не вмешиваются в основной диалог, что позволяет сохранить контекст.
- Ограниченный доступ к инструментам обеспечивает соблюдение ограничений.
- Конфигурации можно повторно использовать в разных проектах.
- Целенаправленные запросы специализируют поведение агентов.
Называть подагента именованным промптом — значит недооценивать его. На самом деле это автономная единица работы, содержащая описание, системный промпт, выбранную модель, набор разрешенных инструментов, настройки памяти и временные ограничения.
Встроенные примеры иллюстрируют их назначение. Explore оптимизирован для чтения только и анализа кодовой базы, Plan предназначен для планирования рабочих процессов, а универсальный агент выполняет сложные многоэтапные задачи, сочетающие рассуждения и действия. В документации указано, что встроенные подагенты наследуют права родительского диалога плюс дополнительные ограничения на использование инструментов, поэтому делегирование задач ограничено по замыслу разработчиков.
Ещё одно ограничение: сабагенты не могут рекурсировать. Anthropic утверждает, что сабагент не может создавать других сабагентов, и именно это позволяет Claude избегать бесконечного вложения, при этом собирая необходимый контекст. Без чётких границ делегирование может привести к возникновению неконтролируемых структур агентов, которые требуют значительных ресурсов, сложны в мониторинге и трудны для анализа. Модель остаётся простой: основной агент передаёт задачу вниз, сабагент выполняет её изолированно, а результат возвращается обратно.
С практической точки зрения, подагенты могут настраиваться в различных контекстах. Их можно создавать интерактивно с помощью команды /agents, хранить для каждого пользователя в папке ~/.claude/agents/, хранить для каждого проекта в папке .claude/agents/, передавать по командной строке для одной сессии или включать в плагины. Каждый из них представляет собой файл формата Markdown с YAML-метаданными, однако определяемое им поведение очень разнообразно: выбор модели, доступ к инструментам, работа с памятью, хуки и навыки — всё это может быть настроено для конкретного подагента. Это профили выполнения, а не метки ролей.
Именно поэтому сабагенты относятся к числу самых важных компонентов. CLAUDE.md закрепляет основного агента за правилами проекта, модули навыков обеспечивают специализированные знания, а хуки обеспечивают соблюдение правил во время выполнения задач, но сабагенты предотвращают превращение всего этого в один перегруженный диалог с слишком большим количеством обязанностей. Изоляция — это тихая выгода: сабагент может читать десятки файлов, выполнять поиски и исследовать тупики, при этом ничто из этих действий не попадает в основной поток, который получает только итог. Они устанавливают четкие границы для вспомогательных задач, позволяют командам специализироваться в своих рабочих процессах и сохраняют основной контекст более чистым и долговечным. После внедрения принципа делегирования остается только организационная проблема: как упаковать всё это для команды.
Выбор места для каждого правила
Поскольку доступно пять уровней, выбор места размещения становится дизайнерским решением. Полезным тестом является вопрос о том, как должно вести себя правило. Если его значение всегда должно быть известно, поместите его в CLAUDE.md. Если это процедура, нужная лишь иногда, сделайте её навыком. Если её необходимо применять в любом случае, независимо от решения модели, это хук. Если задача шумная, самодостаточна или подходит для более дешевой модели, передайте её субагенту. Если вся структура должна быть передана другому месту, упакуйте её в плагин. Правила, размещенные на неправильном уровне, склонны давать сбои по типичным причинам: правило, оставленное в простом тексте, игнорируется, длинная процедура, сохраненная в памяти, занимает всё остальное пространство, а умная настройка, оставленная на одном ноутбуке, так и не доходит до команды.
Пятый уровень: плагины для распространения
Предположим, у команды уже есть файл с памятью, навыки, инструменты и подагенты. Проблема больше не связана с локальным поведением — речь идет о распространении. Как такая конфигурация может перемещаться между репозиториями, компьютерами и членами команды без необходимости ее повторного создания вручную каждый раз?
Anthropic предоставляет несколько механизмов для упаковки и повторного использования поведения в разных контекстах: подагенты на уровне пользователя и проекта, общие навыки, настройки плагинов, развертывание CLAUDE.md во всей организации, а также плагины, обеспечивающие интеллект кода или другие функции. Claude Code предназначен не только для индивидуальной настройки; он все чаще используется командами для стандартизации и распространения способов действия агента.
Самым ясным официальным сигналом служит модель плагинов и настроек. В документации по настройкам описаны специальные разделы для конфигурации плагинов, списки разрешенных элементов и права доступа, такие как codeIntelligence.*, а также локальные настройки проекта и унаследованные настройки пользователя. Там также указано, что аргументы командной строки, такие как флаги append-system-prompt и allowed-tools, не передаются в плагины, что подтверждает, что плагины представляют собой самостоятельные единицы распространения со своей собственной поверхностью поведения, а не пассивные расширения родительской сессии. Следовательно, плагины предназначены скорее для упаковки поведения агента, чтобы его можно было устанавливать, повторно использовать и контролировать в масштабах, чем для добавления инструментов.
Та же схема встречается и в других местах. Подагенты поддерживают установку на уровне пользователя, проекта, только для текущей сессии и в соответствии с настройками плагинов. Навыки реализованы по модульной схеме, что позволяет повторно использовать знания вне постоянно загружаемого слоя памяти. Архитектура не ограничивается лишь возможностью агента выполнять ту или иную задачу; она всё чаще фокусируется на том, как такие возможности можно упаковать и обменяться ими, что является отличительной чертой платформы, а не помощника для одного пользователя.
Управление также является его частью. Один общий пакет может содержать проверенных подагентов, строго ограниченные права на использование инструментов, стандартные механизмы взаимодействия или рабочие процессы, характерные для конкретной организации, поэтому команды распространяют правила, а не просто удобства. Пути в корпоративной среде для централизованно управляемых файлов CLAUDE.md показывают, что стандартизация планировалась с самого начала. Тот же многоуровневый дизайн, который ускоряет работу одного инженера, может стать моделью работы всей команды, в которой память, экспертиза, контроль и делегирование распределяются, а не создаются заново.
Что происходит, когда отсутствует уровень
Если рассматривать всю структуру в целом, она представляет собой практический чек-лист для диагностики ненадежной настройки агента. Симптомы обычно указывают на отсутствие определенного уровня.
- Агент постоянно задаёт одни и те же вопросы или игнорирует стиль дома. У него отсутствует память. Постоянно используемые правила должны находиться в файле CLAUDE.md, быть организованными по каталогам и разделёнными на импорты, чтобы файл не становился слишком большим.
- Каждая сессия начинается с длинного перенесённого текста процедуры. Знания ограничены промптами. Переместите повторяющиеся части в разделы с навыками, чтобы они загружались только тогда, когда это необходимо для выполнения задачи.
- Рискованные действия зависят от того, помнит ли модель о необходимости осторожности. Ограничения являются лишь рекомендациями. Хуки обеспечивают форматирование, защиту файлов и переписывание команд независимо от решения модели.
- Основной диалог заполняется логами и тупиками. Отсутствует делегирование задач. Подагенты с ограниченным набором инструментов берут на себя шумную вспомогательную работу и возвращают краткое резюме.
Общий момент заключается в том, что ни одно из этих решений не представляет собой просто лучшей формулировки запроса. Это структурные изменения, и именно поэтому они эффективны при реальной нагрузке. Рассматривая Claude Code как инструмент для разработки агентов, который случайно поставляется внутри терминала, такие изменения становятся более заметными, их легче обсуждать с командой, а также постепенно внедрять, слой за слоем.