Как настроить кастомного сабагента в Claude Code: конфиг в .claude/agents и 5 уровней скоупа

Пошаговая инструкция по созданию Markdown-манифестов с ограничением инструментов, маршрутизацией на дешевые модели и лимитом описаний в 15 000 токенов.

В сложных задачах основной контекст диалога быстро забивается длинными логами, промежуточными результатами поиска и прочитанными файлами. Сабагенты в Claude Code решают эту проблему: каждый запускается в изолированном контекстном окне, выполняет поручение и возвращает в основной диалог только короткую выжимку.

Вместо устаревшего интерактивного визарда /agents разработчики Anthropic перешли на декларативные Markdown-файлы. Теперь конфигурация хранится в репозитории, версионируется через git и применяется на лету: встроенный наблюдатель отслеживает изменения на диске за несколько секунд без перезапуска сессии.

Документация Claude Code по архитектуре и настройке сабагентов. Источник: Anthropic

Сабагенты размещаются на пяти уровнях видимости. Если в нескольких местах объявлен агент с одинаковым именем, Claude Code выбирает манифест по строгой иерархии приоритетов:

Managed settings (приоритет 1, наивысший). Политики администраторов организации в централизованном каталоге настроек, переопределяющие любые локальные конфигурации.
Флаг CLI --agents (приоритет 2). JSON-объект или путь к файлу при запуске команды claude, действующий строго в рамках текущей сессии.
Каталог проекта .claude/agents/ (приоритет 3). Манифесты конкретного репозитория. Поиск выполняется вверх по дереву каталогов от текущей рабочей папки до корня проекта.
Пользовательский каталог ~/.claude/agents/ (приоритет 4). Персональные агенты разработчика, доступные во всех проектах на машине.
Каталоги плагинов agents/ (приоритет 5, низший). Агенты из установленных расширений с префиксом вида plugin:name.

Каждый сабагент описывается одним Markdown-файлом. В заголовке frontmatter задаются параметры исполнения, а тело файла становится системным промптом агента.

--- name: code-reviewer description: Reviews code for quality and security. Use proactively after code changes. tools: Read, Grep, Glob model: sonnet --- Ты ревьюер. Анализируй diff и файлы, выдавай конкретные замечания: путь к файлу, строка, описание дефекта. Ничего не исправляй самостоятельно.

Ключевые параметры заголовка:

name — идентификатор агента длиной до 256 символов без двоеточий.
description — описание назначения, по которому Claude принимает решение об автоматическом вызове агента.
tools и disallowedTools — белые и черные списки доступных инструментов.
model — целевая модель (sonnet, haiku, opus, fable или inherit).
effort — уровень рассуждений (low, medium, high, max).
permissionMode — режим подтверждений (default, acceptEdits, auto, dontAsk, bypassPermissions, plan).

Текстовая инструкция «ничего не меняй в коде» не дает гарантий безопасности: модель в ходе цепочки действий может самовольно отредактировать файл. Надежная изоляция настраивается через параметр tools. Если исключить из него Write и Edit, сабагент технически лишается возможности модифицировать проект.

Главная ловушка безопасности — инструмент Bash. Если сабагенту запрещены Write и Edit, но оставлен Bash, запись файлов возможна через команды терминала. Для строгого аудита оставляют только Read, Grep, Glob.

Фоновые сабагенты, запущенные по умолчанию, автоматически фильтруются движком: из них принудительно удаляются интерактивные инструменты AskUserQuestion, EnterPlanMode, ScheduleWakeup и WaitForMcpServers.

Поле description каждого зарегистрированного сабагента загружается в контекст основного агента на каждом шаге. Если суммарный объем описаний всех пользовательских сабагентов превышает 15 000 токенов, Claude Code выводит предупреждение при запуске. Длинные регламенты и критерии проверок переносят в тело системного промпта, который загружается только в момент непосредственного запуска агента.

Второй способ оптимизации расходов — маршрутизация на модель Haiku. Рутинные задачи вроде сбора статистики, синтаксических проверок или первичного поиска файлов не требуют мощности Opus.

В поставку Claude Code входят готовые встроенные сабагенты. Агенты Explore и Plan оптимизированы для быстрых поисковых операций и по умолчанию стартуют без инструкций CLAUDE.md и без снимка git status, что снижает расход токенов. Пользовательский файл с именем Explore.md переопределяет стандартного поискового агента:

--- name: Explore description: Fast codebase exploration agent running on Haiku tools: Read, Grep, Glob model: haiku --- Ты исследователь кодовой базы. Ищи файлы, зависимости и структуры кода.

Автоматически. Основной агент сам передает задачу сабагенту, если запрос пользователя совпадает с описанием в поле description.
Явно текстом. Прямое указание в диалоге, например: Use the code-reviewer subagent on src/auth.py.
Через упоминание. Указание имени через символ собаки в чате: @agent-code-reviewer.
Выделенная сессия в терминале. Запуск всей сессии Claude Code под управлением конкретного агента командой claude --agent code-reviewer.