Что такое агенты Claude Code и чем субагент отличается от основного?
Коротко: Агенты Claude Code - это субагенты, отдельные помощники внутри одной сессии, которым основной агент отдаёт побочную задачу. У каждого своё окно контекста, свой системный промпт, свои инструменты и разрешения. Работу субагент делает у себя и возвращает в разговор только итог. Ты говоришь с основным агентом, он раздаёт поручения.
Когда ищут «агенты claude code», почти всегда имеют в виду субагентов. Название программы при этом пишут кто как: латиницей, «клод код», «клауд код» - программа одна. Что значит слово «агент» в целом, разобрано в словаре. Чем агент в папке проекта отличается от подсказки в редакторе и чата в браузере, показано в статье ИИ для программирования.
Разница в памяти разговора. Основной агент помнит всё, что вы обсудили в сессии. Субагент стартует с чистого листа: вместо истории он получает поручение от основного агента. Сотни строк поиска и логи остаются у него, а тебе приходит короткая сводка.
Своя связка агентов появилась у меня весной 2026 года, вместе с первым продуктом: код писал агент, я ставил задачи. Версию 2.1.278 на macOS и справку claude agents я проверил сам 21 сентября 2026 года. Остальное сверено по документации Anthropic 5 ноября 2026 года: в журнале изменений на этот день последняя версия 2.1.318.
Своего агента собрать несложно: по сути это один текстовый файл, общий порядок разобран в статье как создать ИИ-агента. Но начинать проще с готовых. Пять агентов - юриста, финансиста, ресёрч, разведчика идей и ассистента-календарь - можно забрать бесплатно: пак агентов для Claude Code. Это пять файлов для папки .claude/agents/, в архиве есть инструкция с нуля.
Где вы сейчас
Коротко: Агенты Claude Code разбираются от простого к сложному: встроенные, свой агент, вызов, параллельная работа, стоимость. Если часть уже пройдена, прыгай к нужному разделу. Ниже четыре ситуации и куда идти в каждой.
- Программы пока нет. Сначала установка по шагам. Если ищешь вариант без оплаты, посмотри, где предел у бесплатных ИИ-агентов: у Claude Code бесплатного входа нет.
- Стоит, хочу понять, что такое агенты. Читай подряд со встроенных агентов.
- Набрал /agents и увидел одну строку вместо меню. Раздел про /agents, потом шаг 1.
- Свой агент есть, нужно несколько сразу. Разделы про параллельную работу и стоимость.
Когда нужен субагент?
Коротко: Агенты Claude Code нужны, когда побочная работа забьёт основной разговор мусором или когда задаче нужны свои права. Четыре случая: много вывода, независимые куски, урезанные права, цепочка шагов. Остальное проще делать в основном разговоре.
- Много вывода. Прогон тестов, чтение логов, разбор документации. Всё это остаётся у субагента, к тебе приходит сводка:
Используй субагента, чтобы запустить тесты и вернуть только упавшие с текстом ошибок. - Независимые куски. Авторизация, база и API изучаются одновременно, каждый кусок у своего агента, в конце Claude сводит итоги.
- Свои права. Агент только для чтения, без права что-то менять, или на дешёвой модели вроде Haiku.
- Цепочка шагов. Один агент находит проблемы, второй их чинит: итог первого Claude передаёт второму.
Когда субагент мешает, разобрано в конце, в разделе про стоимость.
Какие агенты Claude Code уже встроены?
Коротко: Три агента работают без всякой настройки: Explore ищет по файлам, Plan собирает сведения в режиме плана, general-purpose берёт сложные задачи с правками. Claude зовёт их сам, когда задача подходит. Служебные агенты запускаются под конкретные команды, звать их руками не нужно.
| Агент | Что делает | Правит файлы | Модель |
|---|---|---|---|
| Explore | быстрый поиск и разбор файлов проекта | нет, только чтение | как у основного разговора; если там Fable - Opus (при подписке, в консоли Anthropic и через шлюз) |
| Plan | собирает сведения, пока ты в режиме плана | нет, только чтение | как у основного разговора |
| general-purpose | многошаговые задачи: и поиск, и правки | да | как у основного разговора, если не задано иначе |
| claude | запасной, когда задача не подходит узким агентам | да | своей нет |
| statusline-setup | настройка строки состояния по команде /statusline | - | Sonnet |
| claude-code-guide | ответы на вопросы о самом Claude Code | - | Haiku |
Explore и Plan не читают CLAUDE.md и статус git, так поиск быстрее и дешевле. Они отрабатывают один раз и возобновить их нельзя: для продолжения работы нужен general-purpose или свой агент. Остальные агенты правила проекта получают - как их писать, разобрано в статье про CLAUDE.md.
В русских гайдах до сих пор пишут, что Explore работает на отдельной быстрой модели. С версии 2.1.198 он берёт модель основного разговора. Держать поиск на дешёвой модели можно своим агентом с именем Explore и полем model: haiku: он заменит встроенного.
Почему команда /agents больше не открывает меню?
Коротко: Мастер создания агентов убрали в версии 2.1.198, она вышла 1 июля 2026 года. Теперь команда /agents печатает напоминание: попроси Claude создать агента или отредактируй папку .claude/agents/ сам. Файлы агентов и их поля при этом не поменялись. Меню из старых инструкций искать бесполезно.
Строка из журнала изменений версии 2.1.198:
Removed the
/agentswizard; ask Claude to create or manage subagents, or edit.claude/agents/directly«Мастер /agents удалён: просите Claude создавать агентов и управлять ими или правьте .claude/agents/ напрямую.»
- Anthropic, журнал изменений Claude Code
В русских инструкциях из выдачи до сих пор встречается меню с пунктом «Create new agent» из версий до 2.1.197. Открывается меню - значит, Claude Code давно не обновлялся. Проверь версию:
claude --version
У меня 21 сентября команда ответила 2.1.278 (Claude Code).
Не путай две похожие команды. /agents набирается внутри сессии. claude agents запускается из терминала и открывает agent view, экран фоновых сессий; в справке он подписан «Manage background agents».
Шаг 1. Попросить Claude создать агента
Коротко: Самый короткий путь - описать агента словами прямо в сессии и сказать, куда его сохранить. Claude сам напишет файл с именем, описанием, списком инструментов, моделью и инструкцией. Тебе остаётся открыть файл и сверить, что в нём то, что ты просил.
Запрос из документации в переводе:
Создай личного субагента code-improver в ~/.claude/agents/. Пусть он
просматривает файлы и предлагает улучшения: читаемость, скорость,
лучшие практики. По каждой находке - объяснение, текущий код и
исправленный вариант. Сделай его только для чтения и поставь модель Sonnet.
Файл ляжет в ~/.claude/agents/code-improver.md, а агент будет работать во всех проектах на этой машине. Агент без всякого кода, только для одного проекта, описывается так же:
Создай в .claude/agents/ этого проекта субагента text-checker. Пусть он
вычитывает черновики статей: опечатки, повторы, слишком длинные
предложения. Править файлы ему нельзя, только читать и возвращать
список замечаний. Модель - haiku.
Потом открой файл и сверь шапку с просьбой. Если Claude не находит нового агента, перезапусти Claude Code: так бывает, когда папки ~/.claude/agents/ не было до старта сессии.
Шаг 2. Какие поля нужны в файле агента?
Коротко: Агент - обычный текстовый файл .md. Сверху шапка с настройками между двумя строками из трёх дефисов, ниже инструкция агенту простым текстом. Обязательных полей два: name и description. Остальное по желанию: инструменты, модель, режим разрешений, скиллы, память. Файл кладут в .claude/agents/ проекта или в ~/.claude/agents/.
Агент из шага 1, написанный руками:
---
name: text-checker
description: Вычитывает черновики статей и возвращает список замечаний. Звать после каждого нового черновика.
tools: Read, Grep, Glob
model: haiku
---
Ты редактор. Прочитай указанный файл и найди опечатки, повторы и
предложения длиннее 30 слов. Файлы не меняй. Верни список замечаний:
строка, что не так, как исправить.
Текст под шапкой становится системным промптом агента, а общий системный промпт Claude Code субагент не получает.
Где лежит файл и чей агент главнее при одинаковом имени:
| Где лежит | Для кого | Приоритет |
|---|---|---|
| настройки организации (managed settings) | вся компания | 1, самый высокий |
флаг --agents при запуске |
только текущая сессия | 2 |
.claude/agents/ в проекте |
этот проект, файл можно хранить в git | 3 |
~/.claude/agents/ |
все твои проекты на этой машине | 4 |
папка agents/ плагина |
там, где плагин включён | 5, самый низкий |
Поля шапки:
| Поле | Обязательно | Что задаёт |
|---|---|---|
name |
да | уникальное имя до 256 знаков, удобнее строчными буквами и дефисами; без двоеточия и не с дефиса |
description |
да | когда Claude должен отдавать задачу этому агенту |
tools |
нет | разрешённые инструменты; без поля агент получает все, что доступны субагентам |
disallowedTools |
нет | инструменты, которые надо убрать из набора |
model |
нет | sonnet, opus, haiku, fable, полный ID модели или inherit |
permissionMode |
нет | режим разрешений: default, acceptEdits, auto, dontAsk, bypassPermissions, plan; manual - то же, что default |
skills |
нет | скиллы, которые загрузятся в агента целиком при старте |
mcpServers |
нет | MCP-серверы только для этого агента |
memory |
нет | постоянная память между сессиями: user, project или local |
maxTurns, effort, isolation, background, color, hooks |
нет | предел ходов, уровень усилий, отдельная копия репозитория, работа в фоне, цвет, хуки |
omitClaudeMd |
нет | true - агент стартует без твоих CLAUDE.md; версия 2.1.271 и новее |
Как написать скилл для поля skills, разобрано в статье про скиллы Claude Code.
Перезапуск после правки не нужен: Claude Code подхватывает изменение за несколько секунд. А вот файл без name или description, с шапкой не с первой строки, с двоеточием или дефисом в начале имени или со сломанной разметкой YAML пропускается без сообщения в сессии. Причину чаще всего видно только в отладочном журнале при запуске claude --debug. Там же видно опечатку в названии поля: Claude Code молча игнорирует незнакомое поле, а в журнале пишет does not recognize or apply (версия 2.1.296 и новее). Проверить папку можно командой (версия 2.1.233 и новее):
claude plugin validate .claude/agents
Файл с читаемой шапкой, но без поля name команда не отмечает, его ищи глазами.
Шаг 3. Как позвать своего агента?
Коротко: Claude зовёт агента сам, когда задача совпадает с его описанием. Можно назвать агента в запросе, и Claude обычно отдаст задачу ему. С упоминанием через @ задачу берёт именно этот агент. А флаг
--agentзапускает от лица агента всю сессию. Ниже все четыре способа с примерами.
Сам, по описанию. Claude выбирает агента по тексту description. Чтобы агента звали чаще, документация советует дописать туда «use proactively».
По имени. Особого синтаксиса нет:
Используй субагента text-checker, чтобы вычитать черновик drafts/post.md
Через @. Набери @ и выбери агента из подсказок, как выбираешь файл:
@"text-checker (agent)" вычитай drafts/post.md
Упоминание решает только, какой агент возьмёт задачу, само поручение всё равно пишет основной Claude. Руками то же набирается как @agent-text-checker.
На всю сессию. Флаг --agent из справки claude --help отдаёт сессии системный промпт, инструменты и модель агента:
claude --agent text-checker
Работа агента видна в ленте строкой с его именем и кратким описанием задачи, например code-improver(Suggest code improvements).
Два готовых агента для копирования
Коротко: Проверяльщик текстов из шага 2 править файлы не умеет. Ниже два агента для кода: ревьюер, который только читает, и отладчик, которому нужно править. Разница в одной строке
tools. Скопируй файл в.claude/agents/и позови по имени.
Ревьюер по образцу из документации Anthropic, сокращённый и переведённый. Файлы ему менять нельзя: Edit и Write в списке нет.
---
name: code-reviewer
description: Проверяет свежие правки в коде: ошибки, безопасность, читаемость. Звать после каждой правки, файлы не меняет.
tools: Read, Grep, Glob, Bash
model: inherit
---
Ты старший ревьюер. Запусти git diff, посмотри изменённые файлы и сразу
начинай проверку. Ищи: непонятные имена, дубли кода, пропущенную
обработку ошибок, ключи и пароли в тексте, непроверенный ввод.
Ответ раздели на три списка: критично (чинить сейчас), предупреждения,
предложения. К каждому пункту добавь пример исправления.
Отладчик по тому же образцу. Ему нужен Edit, потому что он чинит:
---
name: debugger
description: Разбирает ошибки и упавшие тесты, находит причину и вносит минимальную правку. Звать, когда что-то сломалось.
tools: Read, Edit, Bash, Grep, Glob
---
Ты отладчик, твоя задача - найти причину, а не заглушить симптом.
Возьми текст ошибки и стек, найди шаги воспроизведения, определи место
сбоя, внеси минимальную правку и проверь, что ошибка ушла.
В ответе: причина простыми словами, чем она подтверждена, что именно
исправлено и как проверить.
Шапки обоих файлов claude plugin validate пропустила на версии 2.1.312. Как агенты справляются с твоим проектом, я не замерял: проверь на своём коде, начни с ревьюера, он ничего не меняет.
Я сам плачу за Claude картой для подписок «Плати по миру»: выпускается за пару минут, пополняется рублями через СБП. Оформить картуРеклама. ООО "Капибара". ИНН 9703231520. erid: CQH36pWzJqNS1hfhQNyQNjbmhaUSfywWpWF3LE48uoYyEF
Как раздать задачи нескольким агентам параллельно?
Коротко: Попроси сделать работу параллельно отдельными субагентами. Claude запустит нескольких агентов сразу, каждый пройдёт свой кусок, а в конце Claude сведёт итоги. Лучше всего это работает, когда куски задачи не зависят друг от друга. Субагенты работают в фоне, а кто чем занят, показывает команда /tasks.
Параллельно отдельными субагентами: проверь ссылки на странице
services.html, выпиши вопросы клиентов из faq.md и найди в папке
drafts статьи без заголовка. Каждому - короткий отчёт.
Если второму агенту нужен итог первого, проси цепочкой: «используй code-reviewer, чтобы найти проблемы, потом optimizer, чтобы их исправить».
Что полезно знать про параллельную работу:
- В интерактивной сессии субагенты по умолчанию уходят в фон. Когда фоновому агенту нужно разрешение, вопрос всплывает в основной сессии с его именем.
/tasksпоказывает фоновую работу сессии; закончивший агент остаётся в списке ещё около 30 секунд.- Одновременно по умолчанию работает до 20 субагентов, предел меняет переменная
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. - Субагент может запускать своих, до трёх уровней ниже основного разговора; число уровней меняет
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. - Фоновые агенты получают меньше встроенных инструментов, чем агенты на переднем плане. Если в
toolsу тебя что-то нестандартное, а агент без него не обходится, проверь его в деле. /subtaskзапускает форк - субагента, который получает весь текущий разговор. Если agent view выключен, та же команда называется/fork.- Скилл
/batchдробит большую правку на 5-30 частей, каждую в отдельной копии репозитория.
Итог каждого агента возвращается в основной разговор, поэтому проси короткие отчёты.
Агенты в ClaudeBase. Как сводить нескольких агентов в одну работу, разобрано в материале «Сценарии (Workflows): когда одного агента мало», в уроке 2.2 «Хуки, скиллы, субагенты и сценарии» и во втором уроке первого модуля «Какие бывают агенты и как агент работает на деле». Всё это открывается с доступом к базе.
Когда нужны команда агентов, agent view или workflow?
Коротко: Субагенты - самый лёгкий из пяти способов параллельной работы в Claude Code. Кроме них есть agent view для фоновых сессий, команды агентов, динамические workflows на десятки агентов и проекты в облаке. Часть из них пока в статусе эксперимента или беты. Новичку почти всегда хватает субагентов.
| Способ | Что это | Статус на 05.11.2026 |
|---|---|---|
| Субагенты | помощники внутри одной сессии, возвращают сводку | работает по умолчанию |
Agent view, claude agents |
один экран для фоновых сессий: кто работает, кто ждёт ответа | research preview |
| Команды агентов | ведущая сессия раздаёт задачи напарникам, те переписываются напрямую | экспериментальные, выключены по умолчанию |
| Динамические workflows | скрипт гоняет десятки агентов и сверяет их находки | все платные тарифы и доступ по API, на Pro включаются в /config |
| Проекты | параллельные облачные сессии из одного разговора на claude.ai/code | публичная бета на Pro, Max и Ultra |
План у субагентов держит Claude по ходу разговора, у workflow - скрипт, у команды - ведущая сессия. Команды включаются переменной в settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Документация советует начинать с трёх-пяти напарников: каждый расходует токены как отдельная сессия. Готовый workflow - встроенная команда /deep-research: поиск по нескольким направлениям со сверкой источников и отчётом со ссылками.
Сколько стоит субагент и когда он не нужен?
Коротко: Каждый субагент - отдельный разговор с моделью, и его токены идут в твой лимит подписки. По замерам Anthropic, агент расходует примерно в четыре раза больше токенов, чем чат, а система из нескольких агентов примерно в пятнадцать. Поэтому субагента зовут под объёмную обособленную работу, а короткую правку делают в основном разговоре.
Цифры четыре и пятнадцать - из инженерного блога Anthropic, статья How we built our multi-agent research system от 13 июня 2025 года.
Что ещё документация Claude Code говорит про расход:
- команда агентов, чьи напарники работают в режиме плана, тратит примерно в 7 раз больше токенов, чем обычная сессия;
- десять фоновых сессий в agent view расходуют квоту примерно в десять раз быстрее одной;
- для простых задач агенту советуют
model: haiku; чтобы все субагенты работали на одной модели, задайCLAUDE_CODE_SUBAGENT_MODELвместе сCLAUDE_CODE_SUBAGENT_MODEL_FORCE=1(версия 2.1.257 и новее); - на тарифах Pro, Max, Ultra, Team и Enterprise
/usageпоказывает долю расхода на субагентов.
Где смотреть остаток лимита - в статье про лимиты Claude Code.
Субагент не нужен для задач с частыми уточнениями, для этапов с общим контекстом и для быстрой точечной правки. Не нужен он и там, где важна скорость: субагент стартует с нуля и собирает контекст заново. Вопрос по открытому разговору проще задать через /btw - ответ учитывает весь контекст и не попадает в историю. Повторяемую инструкцию оформляют скиллом.
ИИ-агент на Claude: что это значит?
Коротко: Под «ИИ-агентом на Claude» понимают три вещи: сам Claude Code на твоём компьютере, субагентов внутри него, о которых эта статья, и свой агент в своём продукте на Agent SDK или Managed Agents. Непрограммисту подходят первые два варианта.
В статье Anthropic Building effective agents агентом названа система, где модель сама управляет ходом работы и выбором инструментов. Под это определение попадают все три. Первый - Claude Code, он читает файлы, запускает команды и правит проект на твоей машине. Второй - субагенты, их настраиваешь ты. Третий - Agent SDK, библиотека на Python и TypeScript для агента внутри своего сервиса или бота, и Managed Agents, где агента и песочницу запускает сама Anthropic. Оба варианта третьего требуют программирования.
Сколько агент делает без человека, разобрано на соседнем примере - агент Codex.
Частые ошибки: когда агенты Claude Code не запускаются или обрываются
Коротко: Четыре сообщения, которые Claude Code печатает при сбоях с субагентами, дословно по документации Anthropic (справочник ошибок и страница про субагентов), и что делать с каждым. Сообщение про предел одновременных субагентов в первую очередь получает сам Claude, а не ты. Все чинятся правкой файла агента или ожиданием.
Agent descriptions are over the 15.0k-token limit
Описания всех твоих агентов вместе длиннее 15 000 токенов. Агенты загружаются, но описания занимают контекст. Сократи поля description, подробности перенеси в текст под шапкой: он грузится, только когда агент работает.
Agent would be spawned with zero tools
Ни одна строка в tools не совпала с настоящим инструментом, например из-за опечатки Grpe вместо Grep. Исправь названия или удали поле tools: тогда агент получит все инструменты, доступные субагентам.
Concurrent subagent limit reached
Одновременно уже работают 20 субагентов. Дождись, пока часть закончит, или подними предел переменной CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
Agent terminated early due to an API error
Субагент остановился на ошибке API, например упёрся в лимит использования; причина идёт после двоеточия. Когда ошибка пройдёт, попроси Claude повторить задачу или продолжить работу этого агента.
Агента нет совсем - проверь шапку файла и перезапусти сессию, если папка agents появилась уже после её старта.
Агент работает - что дальше?
Коротко: Дальше агенту нужны правила, инструменты и готовые наработки. Правила он берёт из CLAUDE.md, сервисы подключаются по MCP, готовые агенты приходят в плагинах. Три ближайших шага - ниже.
- Напиши правила проекта: их получают и основной агент, и твои субагенты. Порядок - в статье про CLAUDE.md.
- Дай агенту доступ к сервисам через MCP в Claude Code или возьми готовых агентов из плагинов.
- Держи под рукой шпаргалку команд:
/tasks,/btw,/subtaskи остальное.
Если не хочешь разбираться с агентами в одиночку, в ClaudeBase есть уроки про то, как агент работает на деле, и про хуки, скиллы, субагенты и сценарии. Файлы вручную копировать не придётся: через MCP-подключение Claude Code сам заглядывает в базу и берёт нужный материал.