Автор: Редакция Зерокодера. В продакшене держим флот из read-only аналитиков и write-агентов Claude Code с весны 2026. Обновлено: июль 2026.
Субагенты в Claude Code — это отдельные ИИ-помощники со своим окном контекста, системным промптом и набором инструментов. Каждый задаётся Markdown-файлом с YAML-шапкой в папке .claude/agents/ (проектный) или ~/.claude/agents/ (личный). Обязательных полей два: name и description. По описанию Claude сам решает, когда делегировать задачу субагенту, и получает назад только итог, а не весь мусор из его работы. Файл подхватывается на лету — рестарт нужен, только если папки agents/ не было на старте сессии.
Главное в двух минутах:
- Субагент = Markdown-файл
имя.mdс YAML-шапкой в.claude/agents/; тело файла становится системным промптом. - Обязательны два поля:
name(латиница + дефисы) иdescription(по нему идёт автоделегирование). - Проектный субагент лежит в
.claude/agents/репозитория, личный — в~/.claude/agents/; при совпадении имён проектный старше. - Субагент стартует с чистого контекста: он не видит вашу переписку и прочитанные файлы — только задачу, которую сформулировал Claude.
- Три встроенных субагента уже есть из коробки: Explore, Plan и general-purpose.
Что такое субагент в Claude Code и зачем он нужен
По официальной документации Anthropic, субагент нужен, когда побочная задача засорила бы основной разговор поисковой выдачей, логами или содержимым файлов, к которым вы больше не вернётесь. Субагент делает эту работу в своём окне контекста и возвращает только резюме. Второй сценарий — когда один и тот же «работник» нужен раз за разом: его фиксируют в файле.
Что это даёт на практике:
- Экономия контекста. Ресёрч по десяткам файлов остаётся внутри субагента, в основной разговор приходит выжимка.
- Ограничение прав. Read-only ревьюер физически не может ничего сломать — у него нет
EditиWrite. - Параллельность. Несколько субагентов работают одновременно, и три независимых проверки занимают время самой долгой, а не их суммы.
- Экономия на модели. Рутину можно направить на дешёвую и быструю Haiku, а тяжёлый разбор — на Opus.
Наш прод-опыт. В Зерокодере субагенты разведены на два класса. Read-only аналитики (поиск по кодовой базе и данным, разбор воронки, ревью текста) не имеют инструментов записи вообще — их нельзя случайно попросить «поправить заодно». Write-агенты, которые реально меняют файлы или дёргают внешние API, вынесены отдельно и вызываются осознанно. Такая развязка — не про красоту архитектуры, а про то, чтобы ночной автоматический прогон не переписал прод.
Субагент экономит не только токены, но и внимание: вы отдаёте задачу и получаете ответ, а не простыню промежуточного вывода.
Встроенные субагенты: Explore, Plan и general-purpose
Ещё до первого своего файла у вас есть три штатных субагента — Claude вызывает их сам, когда уместно:
| Субагент | Инструменты | Когда Claude его берёт |
|---|---|---|
| Explore | Только чтение (Write и Edit запрещены) | Быстрый поиск и разбор кодовой базы без правок |
| Plan | Только чтение | Сбор контекста в режиме планирования (plan mode) |
| general-purpose | Все инструменты | Многошаговые задачи, где нужны и разведка, и правки |
Explore и Plan специально пропускают ваши CLAUDE.md и git-статус — так разведка остаётся быстрой и дешёвой (документация Claude Code, раздел built-in subagents). Это же объясняет, почему они одноразовые: их нельзя возобновить, id они не возвращают.
Три штатных субагента закрывают большинство сценариев — свой файл заводят, когда нужен повторяемый специалист с фиксированным промптом.
Как создать своего субагента: пошагово
Субагент — это один Markdown-файл, никакого реестра или сборки. Соберём read-only ревьюера, который проверяет свежие изменения и не может ничего в них поменять.
Шаг 1. Создайте папку и файл. Личный субагент (виден во всех проектах):
mkdir -p ~/.claude/agents
На Windows это C:\Users\<имя>\.claude\agents. Для проектного субагента — папка .claude/agents/ внутри репозитория (её коммитят в git, и субагент появляется у всей команды).
Шаг 2. Запишите файл reviewer.md целиком. Шапка между ---, ниже — системный промпт:
---
name: reviewer
description: Ревьюер кода. Использовать сразу после написания или правки кода — найти баги, дыры в безопасности и нарушения стиля. Ничего не меняет.
tools: Read, Grep, Glob
model: haiku
---
Ты — старший ревьюер. Когда тебя вызвали, разбери свежие изменения и верни
конкретную, применимую обратную связь по трём осям: корректность, безопасность,
читаемость.
Для каждой проблемы: назови файл и строку, покажи проблемный фрагмент,
предложи исправленный вариант. Не редактируй файлы — только отчёт.
Здесь tools: Read, Grep, Glob — это allowlist: ревьюер физически лишён записи. model: haiku сажает его на быструю дешёвую модель, потому что ревью по чек-листу не требует тяжёлой.
Шаг 3. Проверьте, что субагент виден. Рестарт не нужен: Claude Code следит за папками субагентов и подхватывает новый файл за несколько секунд — если сама папка agents/ существовала на старте сессии. Первый файл в только что созданной папке — единственный случай, когда сессию надо перезапустить.
Шаг 4. Вызовите его. Автоматически: «проверь мои последние изменения» — Claude сопоставит запрос с description и делегирует. Явно, с гарантией: @-упоминание из тайпахеда или прямой приказ «используй субагента reviewer».
Имя команды и идентификатор берутся из поля name, а не из имени файла — их можно не синхронизировать, но путаницы меньше, когда они совпадают.
Поля frontmatter, которых нет в других гайдах
Четвёрки name / description / tools / model хватает для рабочего субагента. Управляемость даёт остальной frontmatter — в русских разборах он почти не встречается, хотя весь есть в документации:
| Поле | Что делает |
|---|---|
name, description |
Единственные обязательные. name — латиница и дефисы; по description Claude решает, когда делегировать |
tools |
Allowlist инструментов. Пропущено — наследует все от основного разговора |
disallowedTools |
Denylist поверх наследования. Удобно, когда проще «всё, кроме Write, Edit». При обоих полях сначала применяется denylist |
model |
sonnet / opus / haiku / fable / полный ID / inherit. По умолчанию inherit |
permissionMode |
Режим прав субагента: default, acceptEdits, auto, dontAsk, bypassPermissions, plan |
skills |
Скиллы, чьё ПОЛНОЕ содержимое подгружается в контекст субагента на старте (не только описание) |
memory |
Постоянная память субагента между сессиями: user, project или local |
isolation: worktree |
Субагент работает во временном git-worktree — изолированная копия репозитория; если изменений не внёс, worktree удаляется автоматически |
background |
true — всегда выполнять фоном, не блокируя основной разговор |
effort |
Уровень усилий на время работы субагента (low … max), перекрывает сессионный |
hooks, mcpServers |
Хуки жизненного цикла и MCP-серверы, доступные только этому субагенту |
Практический вывод: опасным субагентам (что-то пишут, деплоят, дёргают внешние API) сразу давайте isolation: worktree или узкий tools, а не полагайтесь на то, что «Claude аккуратный». Ограничение на уровне файла надёжнее промпта.
Где лежат субагенты и какой приоритет у папок
Одноимённые субагенты из разных мест конфликтуют, и Claude Code берёт файл из более приоритетного. Полная лестница — пять уровней, а не «проект против юзера», как обычно пишут:
| Уровень | Расположение | Приоритет |
|---|---|---|
| Managed settings (организация) | каталог managed-настроек | 1 — высший |
CLI-флаг --agents (JSON на запуск) |
только текущая сессия | 2 |
| Проектный | .claude/agents/ репозитория |
3 |
| Личный | ~/.claude/agents/ |
4 |
| Плагинный | папка agents/ плагина |
5 — низший |
Отсюда рабочее правило: личный субагент в ~/.claude/agents/ — ваш дефолт на все проекты, а одноимённый проектный в репозитории его перекроет, когда команде нужна своя версия. Это штатный способ переопределить поведение под конкретный код.
Приоритет папок — это механизм переопределения, а не источник багов: положили проектную версию рядом — она победила личную.
Субагент, skill, MCP или слэш-команда: что выбрать
Четыре механизма расширения Claude Code решают разные задачи, и их постоянно путают:
| Механизм | Что это | Когда брать |
|---|---|---|
| Субагент | Отдельный контекст со своим промптом и инструментами; возвращает только результат | Изолированная многошаговая задача: ресёрч, ревью, разбор логов — чтобы не жечь основной контекст |
| Skill | Инструкции и файлы, подгружаются по требованию в текущий контекст | Повторяемая процедура, стиль, шаблон, чек-лист — без изоляции |
| MCP-сервер | Внешний процесс с инструментами: API, база, браузер | Доступ к внешним системам, которых у Claude нет из коробки |
| Слэш-команда | Объединена со скиллами: .claude/commands/x.md даёт /x |
Быстрый ручной вызов заготовленного промпта |
Разница между субагентом и скиллом — ось изоляции. Skill выполняется в вашем же разговоре и видит его контекст; субагент стартует с чистого листа и возвращает выжимку. Механизмы комбинируются: субагенту можно через поле skills подгрузить нужные навыки, а через mcpServers — дать доступ к MCP-серверу, которого нет в основном разговоре.
Правило на практике: нужна процедура в текущем контексте — skill; нужна изоляция и свои права — субагент; нужен доступ наружу — MCP.
Субагента можно возобновить, а не запускать заново
Частая ошибка — плодить новых субагентов на каждый уточняющий вопрос. Завершённый субагент сохраняет полную историю работы, и Claude может продолжить его инструментом SendMessage по id или имени: уточнение уйдёт в тот же контекст, где уже прочитаны нужные файлы. Новый запуск — всегда чистый лист и повторная трата токенов. Исключение — Explore и Plan: они одноразовые и id не возвращают.
Agent SDK: субагенты в коде, а не в файлах
Если вы строите собственное приложение поверх Claude, субагенты не обязательно держать в .claude/agents/. В Claude Agent SDK (TypeScript и Python) они задаются программно — через параметр agents в опциях вызова query(). Каждый субагент — объект AgentDefinition с обязательными description и prompt и опциональными tools, model и прочими:
agents: {
"code-reviewer": {
description: "Ревьюер кода. Для проверок качества и безопасности.",
prompt: "Ты — старший ревьюер. Ищи уязвимости и проблемы производительности.",
tools: ["Read", "Grep", "Glob"],
model: "sonnet"
}
}
Два нюанса, на которых спотыкаются. Первый: чтобы вызовы субагентов авто-одобрялись без запроса прав, инструмент Agent нужно включить в allowedTools — иначе Claude либо спросит, либо в строгом режиме откажет. Второй: программные агенты имеют приоритет над файловыми с тем же именем, так что agents в коде перекрывает .claude/agents/.
Файлы .claude/agents и SDK — это два входа в один и тот же механизм; выбор зависит от того, работаете вы в CLI или пишете своё приложение.
Типичные ошибки при работе с субагентами
- Субагент не срабатывает автоматически. В большинстве случаев —
descriptionбез слов, которыми вы реально формулируете задачу. Перепишите описание под живые фразы, добавьте «использовать проактивно». В SDK проверьте, чтоAgentвallowedTools. - Ждут, что субагент «помнит» разговор. Он стартует с чистого контекста и не видит ни переписку, ни прочитанные файлы. Всё нужное (пути, ошибки, решения) кладите прямо в формулировку задачи.
- Дробят цельную задачу. Если шаги плотно завязаны и постоянно нужен обмен контекстом — это работа для основного разговора; изоляция тут мешает.
- «Правлю файл — ничего не меняется». Первый файл в новой папке
agents/watcher не видит: перезапустите сессию. Проверьте валидность YAML и уникальность имени. - Опасному субагенту дали все инструменты. Права ограничивают на уровне файла (
tools,disallowedTools,isolation: worktree), а не на доверии к модели.
Чек-лист перед сдачей субагента: файл в правильной папке → name латиницей → description с реальными формулировками задач → tools сужены под роль → для правок/деплоя стоит isolation: worktree или узкий allowlist → проверены автоделегирование и явный вызов.
Собрать личную ИИ-команду из субагентов и скиллов можно без единой строки кода; на курсе Зерокодера по вайб-кодингу такой связке посвящён отдельный модуль.
Частые вопросы
Нужно ли уметь программировать, чтобы создать субагента?
Нет. Минимальный субагент — текстовый файл имя.md с YAML-шапкой из двух полей (name, description) и инструкциями на русском в папке ~/.claude/agents/. Код нужен только если вы задаёте субагентов через Agent SDK внутри своего приложения.
Чем субагент отличается от skill?
Осью изоляции. Skill подгружается в ваш текущий разговор и видит его контекст; субагент стартует с чистого контекста в отдельном окне и возвращает только результат. Их можно совмещать: субагенту подгружают скиллы через поле skills.
Нужно ли перезапускать Claude Code после правки файла субагента?
Обычно нет: изменения в .claude/agents/ и ~/.claude/agents/ подхватываются за несколько секунд. Рестарт нужен для первого файла в только что созданной папке agents/ либо при флаге --disable-slash-commands.
Как Claude решает, какого субагента вызвать?
По полю description: сопоставляет задачу с описаниями и делегирует подходящему. Конкретного вызывают по имени или через @-тайпахед; фраза «использовать проактивно» в описании подталкивает к автовызову.
Может ли субагент запускать других субагентов?
Да, с версии 2.1.172. Жёсткий лимит глубины — пять уровней: субагент на пятом уже не получает инструмент Agent.
Чем fork отличается от обычного субагента?
Fork наследует весь разговор целиком — промпт, инструменты, модель и историю. Именованный субагент стартует с чистого листа из своего файла. Fork удобен, когда предыстория слишком велика для пересказа в задаче.