Субагент Claude Code
В Claude Code вы можете создаватьспециализированных ИИ-субагентовдля выполнения определённых типов задач, обеспечивая лучшую изоляцию контекста, более строгий контроль ограничений и более высокую эффективность выполнения.
Субагенты работают внезависимых контекстных окнах. Каждый субагент может иметь собственный системный промпт, заданную модель, явные разрешения на доступ к инструментам, независимые режимы разрешений и постоянную память между сессиями. Когда Claude определяет, что ваш запрос соответствует описанию субагента, он автоматически делегирует задачу этому субагенту, который выполняет её независимо и возвращает результат.
Субагенты получают только собственный системный промпт и базовую информацию об окружении (например, рабочую директорию),и не наследуют полный системный промпт Claude Code,что обеспечивает чистое и контролируемое поведение.
Зачем использовать субагентов
Основная ценность субагентов заключается визоляции + специализации,что в основном отражается в следующих аспектах:
Сохранять контекст основного диалога: Передавайте «тяжёлые задачи», такие как исследование и анализ логов, субагентам, чтобы основной диалог получал только итоговые сводки и не переполнялся большим объёмом промежуточного вывода. Исследования показывают, что запуск трёх субагентов параллельно для анализа проекта на 50,000 строк занимает около 45 секунд, тогда как последовательное выполнение — 3 минуты.
Обеспечивать соблюдение ограничений: Ограничивайте возможности субагентов с помощью белых или чёрных списков инструментов, например, анализ только для чтения или запрет опасных команд.
Поведенческая специализация: Создавайте специализированный ИИ для конкретных областей (ревью кода, отладка, анализ данных), чётко указывая границы возможностей агента в системном промпте, чтобы избежать ненужных вызовов.
Контролировать затраты: Поручайте простые задачи Haiku, а сложный анализ — Sonnet, и используйте переменные окружения, чтобыCLAUDE_CODE_SUBAGENT_MODELединообразно задать модель, используемую всеми субагентами.
Повторное использование между проектами: Субагенты уровня пользователя настраиваются один раз и доступны во всех проектах.
Субагент vs мультиагент
Эти два понятия легко перепутать; разница заключается в гранулярности задач и области выполнения:
| Пункт сравнения | Субагент | Мультиагент |
|---|---|---|
| Область выполнения | Запускается в рамках одной сессии Claude Code и возвращает результаты после обработки подзадач | Несколько сессий Claude Code выполняются параллельно или последовательно, обычно управляются оркестратором. |
| Контекст | Независимое окно контекста, изолированное от основного диалога. | Каждая сессия имеет полностью независимый контекст. |
| Вложенность | Субагенты не могут создавать других субагентов (используйте Skills, когда требуется вложенность). | Может координировать многоуровневые задачи через оркестратор. |
| Сценарии использования | Сфокусированные подзадачи, изоляция больших объёмов вывода, специализированный анализ. | Полнофункциональный конвейер разработки (проектирование → реализация → тестирование → выпуск). |
Встроенные субагенты
Claude Code поставляется с несколькими встроенными субагентами, которые обычно используются автоматически и не требуют ручной настройки.
1. Explore (агент исследования)
Используется для поиска и анализа кодовой базы в режиме только чтения. По умолчанию модель — Haiku (быстрая, с низкой задержкой), и включены только инструменты только для чтения (нельзя Edit/Write). Когда Claude нужно просмотреть код без его изменения, он автоматически использует агента Explore. Поддерживаются разные уровни глубины исследования:quick、medium、very thorough。
2. Plan (агент планирования)
Собирает информацию о кодовой базе в режиме планирования, чтобы помочь Claude понять структуру проекта и сформировать контекст для последующего проектирования решения. Включены только инструменты только для чтения, что позволяет безопасно собирать информацию для планирования без создания вложенных агентов.
3. General-purpose (универсальный агент)
Используется для сложных многошаговых задач. Включены все инструменты, и он наследует модель из основного диалога. Подходит для комплексных сценариев «просмотр + изменение + рассуждение» и задач, требующих многошагового изменения кода.
4. Другие внутренние агенты
| Имя агента | Описание |
|---|---|
| Bash | Запуск команд Shell в независимом контексте |
| statusline-setup | Настройка отображения строки состояния терминала |
| Руководство по Claude Code | Отвечайте на вопросы, связанные с использованием Claude Code |
Создайте своего первого субагента
1. Откройте интерфейс управления субагентами
Выполните следующую команду в Claude Code, чтобы открыть полный интерфейс управления субагентами:
/agents
Этот интерфейс предоставляет все возможности управления субагентами: просмотр всех доступных агентов (встроенные / пользовательские / проектные / плагины), создание новых агентов, редактирование существующих агентов и определение того, какая версия фактически применяется при конфликте имён.
2. Выберите создание субагента пользовательского уровня
В интерфейсе выберитеСоздать нового агента:

затем выберитеПроект (.claude/agents/)Файл агента будет сохранён в каталог .claude/agents/ в текущем каталоге. Если вы выберете~/.claude/agents/каталог, это будет действовать для всех проектов:

Используйте рекомендацию Claude:

3. Опишите обязанности агента
Вы можете напрямую сказать Claude на естественном языке, что должен делать этот агент, и Claude автоматически сгенерирует системный промпт и начальную конфигурацию. Например:
A code improvement agent that scans project files, makes suggestions for readability, performance, and best practices, and provides improvement examples.

После генерации нажмитеeклавишу, чтобы вручную отредактировать всё содержимое конфигурации.
4. Настройте разрешения инструментов и модель
- Только проверка кода → отметьте только инструменты, доступные только для чтения (Read / Grep / Glob)
- Нужно изменить код → оставьте инструменты Edit / Write
- Для модели рекомендуется выбратьSonnet, который обеспечивает сбалансированное сочетание аналитических возможностей и скорости выполнения.
Просто выберите Continue и нажмите Enter:

Для следующих параметров просто нажмите Enter, чтобы принять значения по умолчанию.
5. Выберите область памяти (необязательно)
- ВыберитеUser: в
~/.claude/agent-memory/создать постоянную память и накапливать опыт во всех проектах - ВыберитеNone: не сохранять результаты обучения, начинать с нуля при каждой задаче.

6. Используйте агента, которого вы только что создали
使用 code-improver 子代理为此项目提出改进建议

Агент работает в независимом контексте и по завершении возвращает сводку результатов в основной диалог.
Область действия субагентов
Субагент — это по сути файл Markdown с YAML frontmatter; его место хранения определяет его область действия и приоритет:
| Место хранения | Область действия | Приоритет |
|---|---|---|
CLI --agentsФлаг |
Только в текущем сеансе | Наивысшая |
.claude/agents/ |
Текущий проект | Высокая |
~/.claude/agents/ |
Все проекты (глобально) | Средняя |
| Агенты плагинов | Область действия плагина | Самый низкий |
Когда субагенты с одинаковым именем находятся в разных местах, версия с более высоким приоритетом переопределяет версию с более низким приоритетом. Вы можете использовать/agentsкоманду, чтобы проверить, какая версия действительно действует.
Рекомендации по выбору места хранения: агент проекта (.claude/agents/) можно коммитить вместе с кодом для совместного использования командой; пользовательские агенты (~/.claude/agents/) хранят личные привычки и инструменты общего назначения, эффективные в разных проектах; CLI-агенты (--agents) используются для временных тестов или скриптов автоматизации и не сохраняются на диск.
Структура файла конфигурации
Каждый файл конфигурации субагента состоит из двух частей: YAML-фронтматтер (метаданные и конфигурация) и тело Markdown (системный промпт).
Пример
name: code-reviewer # Обязательно: уникальный идентификатор, строчные буквы + дефисы
description: Проверяет код на качество, лучшие практики и проблемы безопасности.
Вызывать, когда пользователь просит проверить, провести аудит или оценить качество кода.
# Обязательно: определяет, когда Claude автоматически вызывает этого агента; рекомендуемый формат — "когда вызывать + что он может делать"
tools: Read, Grep, Glob # Белый список инструментов (можно использовать только эти инструменты)
model: sonnet # Указанная модель: haiku / sonnet / opus / inherit
permissionMode: default # Режим разрешений (см. раздел «Режимы разрешений» ниже)
memory: project # Область постоянной памяти (см. раздел «Память» ниже)
---
Вы старший рецензент кода.
Проанализируйте код и предоставьте практичные отзывы, упорядоченные по степени серьёзности: Критично / Существенно / Незначительно.
Обновляйте память вашего агента повторяющимися паттернами, соглашениями и известными проблемами, которые вы обнаружите.
Полное описание поля
| Поле | Обязательный | Описание |
|---|---|---|
name |
Обязательный | Уникальный идентификатор, также имя, используемое для явного вызова. Формат: строчные буквы + дефисы, напримерcode-reviewer |
description |
Обязательный | Самое важное поле; от него полностью зависит, будет ли и когда Claude автоматически вызывать этого агента, поэтому обязательно чётко опишите сценарии использования |
tools |
Optional | Список разрешённых инструментов; после установки можно использовать только перечисленные инструменты, а инструменты MCP также исключаются |
disallowedTools |
Optional | Список запрещённых инструментов; наследует все инструменты из основного диалога, но исключает перечисленные инструменты (инструменты MCP сохраняются) |
model |
Optional | Указанная модель; можно задать какhaiku、sonnet、opus, полный ID модели, илиinherit(по умолчанию, наследуется из основного диалога) |
permissionMode |
Optional | Управление поведением разрешений, см. раздел «Режимы разрешений» ниже |
memory |
Optional | Область постоянной памяти:user / project / local, см. раздел «Память» ниже |
background |
Optional | Если установлено значениеtrue, агент всегда выполняется в фоновом режиме (не блокирует основной диалог) |
isolation |
Optional | Если установлено значениеworktree, выполняется во временном git worktree, полностью изолированном от основного репозитория |
skills |
Optional | Список Skills, автоматически загружаемых при запуске этого агента |
hooks |
Optional | Хуки жизненного цикла:SubagentStart / SubagentStop / PreToolUse / PostToolUse |
Разница между tools и disallowedTools
| Способ настройки | Поведение | Типичный сценарий |
|---|---|---|
| Ни то, ни другое не задано | Наследует все инструменты из основного диалога, включая инструменты MCP | Агенты общего назначения, которым не нужны ограничения |
Задан только одинtools |
Может использовать только инструменты из белого списка; инструменты MCP исключены | Агенты анализа только для чтения, строго ограниченные сценарии |
Задан только одинdisallowedTools |
Наследует все инструменты, исключает инструменты из чёрного списка, инструменты MCP сохраняются | Сохраняет возможности MCP, но запрещает операции записи |
| Заданы оба | ПрименитьdisallowedToolsсначала, затем фильтровать из оставшихся инструментов поtools |
Детальный контроль доступа к инструментам |
Пример
---
name: safe-researcher
description: Агент-исследователь с доступом только для чтения. Используйте при анализе кода без внесения изменений.
tools: Read, Grep, Glob, Bash # Включены только эти четыре инструмента; Write и Edit отсутствуют в белом списке, и их нельзя использовать
---
Пример
---
name: no-writes
description: Анализирующий агент, который наследует все инструменты, кроме записи файлов.
disallowedTools: Write, Edit # Инструменты MCP сохраняются; исключаются только Write и Edit
---
Режимы разрешений
ЧерезpermissionModeполе управляет поведением разрешений, когда субагент выполняет операции:
| Mode | Поведение | Применимый сценарий |
|---|---|---|
default |
Обычный запрос разрешения, спрашивает пользователя перед каждой операцией | Общие сценарии, рекомендуемый вариант по умолчанию |
acceptEdits |
Автоматически принимать правки файлов, не нужно подтверждать каждый раз | Агенты, которые часто изменяют файлы, сокращая перерывы во взаимодействии |
dontAsk |
Автоматически отклонять несанкционированные операции, не прерывая поток выполнения | Строгие сценарии только для чтения, молча пропускать при ошибке операции |
bypassPermissions |
Пропустить все проверки разрешений и выполнять напрямую | Только для полностью доверенных контролируемых автоматизированных сред |
plan |
Режим планирования только для чтения, не выполняет никаких операций записи | Формулирование плана, анализ архитектуры |
bypassPermissionsПодходит только для полностью доверенных субагентов. Кроме того, субагенты будутнаследовать режим разрешений родительской сессии—если основная сессия включает обход, все субагенты также будут обходить. Используйте с чрезвычайной осторожностью.
Персистентная память (Memory)
Черезmemoryfields, субагенты могут накапливать знания между сессиями, такие как шаблоны кодовой базы, опыт отладки, архитектурные решения и т. д., без необходимости повторно исследовать каждый раз.
| Значения области видимости | Место хранения | Применимые сценарии |
|---|---|---|
user |
~/.claude/agent-memory/<name>/ |
Знания агента применяются ко всем проектам, например общие стандарты проверки кода |
project |
.claude/agent-memory/<name>/ |
Знания привязаны к проекту и могут совместно использоваться членами команды через git (рекомендуется по умолчанию) |
local |
.claude/agent-memory-local/<name>/ |
Знания привязаны к проекту, но не коммитятся в git; хранятся только как личный локальный опыт |
Пример
name: code-reviewer
description: Проверяет код на качество и соответствие лучшим практикам. Вызывайте при проверке изменений кода.
memory: user # Память уровня пользователя: накапливать опыт ревью между проектами
---
Вы — ревьюер кода.
Проверяя код, обновляйте память вашего агента, записывая паттерны, соглашения,
и повторяющиеся проблемы, которые вы обнаруживаете в этой кодовой базе
Управление использованием памяти в разговоре:
- Перед началом задачи:
Please consult your memory first before starting the review.(Позвольте агенту использовать имеющийся опыт) - После завершения задачи:
After the task is completed, save the patterns you discovered to memory.(Непрерывное накопление) - Вы также можете напрямую добавить в системный промпт инструкцию «проактивно поддерживать память», чтобы агент выполнял её автоматически без необходимости напоминать каждый раз.
Режим изоляции worktree
После настройкиisolation: worktreeсубагент запускается во временном git worktree, полностью изолированном от основного репозитория. Подходит для следующих сценариев:
- Исследовательские задачи, требующие обширных изменений файлов с неопределёнными результатами
- Запуск нескольких сравнений решений параллельно без взаимного влияния
- Операции, требующие чистой среды, например автоматизированное тестирование и CI-валидация
Пример
name: experimental-refactor
description: Пробует подходы к рефакторингу в изолированном worktree.
Используйте, когда исследуете рискованный рефакторинг, который не должен затрагивать основную ветку.
isolation: worktree # Запуск во временном worktree; изменения не влияют на основной репозиторий
инструменты: Read, Write, Edit, Bash
---
Вы — агент по рефакторингу, работающий в изолированной среде.
Смело вносите изменения — они не затронут основную ветку.
Опишите, что вы изменили, и был ли подход успешным.
Фоновое выполнение (Background)
Субагенты поддерживают как режим выполнения на переднем плане, так и фоновый режим, которые ведут себя по-разному:
| Режим выполнения | Поведение | Ограничения |
|---|---|---|
| Передний план | Блокирует основной диалог до завершения; запросы разрешений и уточняющие вопросы передаются пользователю в реальном времени | Без особых ограничений |
| Фон | Выполняется параллельно, не прерывая основной диалог; необходимые разрешения подтверждаются заранее перед запуском | Не может использовать MCP, не может выполнять интерактивное уточнение; задачи завершаются ошибкой из-за недостаточных разрешений, а не приостанавливаются и ожидают |
Claude автоматически определяет, использовать передний план или фоновый режим в зависимости от характеристик задачи. Вы также можете управлять этим вручную:
Ctrl + B: Переключить текущего выполняющегося субагента в фоновый режимCtrl + F(нажмите дважды для подтверждения): Завершить всех фоновых агентов- Задаётся в frontmatter
background: true: Этот агент всегда работает в фоновом режиме - Добавьте к сообщению префикс
&: Отправить задачу как фоновую задачу в веб-клиент claude.ai - Через
/tasksкоманда, проверяйте ход выполнения фоновой задачи в любое время
Чтобы полностью отключить функцию фоновых задач, задайте следующие переменные среды:
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
Чтобы единообразно задать модель, используемую всеми субагентами (например, использовать Opus для сложных рассуждений в основном диалоге и Sonnet в субагентах для экономии затрат):
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"
Хуки жизненного цикла (Hooks)
Субагенты поддерживают следующие события хуков, которые можно использовать в сценариях автоматизации, таких как логирование, проверка операций и уведомление о результатах:
| Событие хука | Момент срабатывания | Типичные случаи использования |
|---|---|---|
SubagentStart |
При запуске субагента | Записывать логи запуска, инициализировать среду |
SubagentStop |
При завершении задачи субагента | Записывать результаты, запускать последующие задачи, отправлять уведомления. Включаетagent_idиagent_transcript_pathполе |
PreToolUse |
Перед вызовом инструмента | Проверить правомерность операции; код выхода скрипта, равный 2, может заблокировать вызов инструмента |
PostToolUse |
После вызова инструмента | Форматировать вывод, генерировать журналы изменений |
Расширенное использование: динамическое управление поведением инструмента с помощьюPreToolUseхуков. Например, разрешить агенту базы данных выполнять только SQL-запросы для чтения, при этом любые операции записи перехватываются скриптом:
Пример
name: db-analyst
description: Агент анализа базы данных только для чтения. Используйте для запросов и формирования отчётов, никогда для записи.
tools: Bash
# Настройте хуки в .claude/settings.json:
# PreToolUse для Bash -> validate-readonly-query.sh
# Когда скрипт обнаруживает операцию, отличную от SELECT, он возвращает код выхода 2, блокируя выполнение команды
---
Вы аналитик базы данных. Выполняйте только SELECT-запросы.
Никогда не выполняйте INSERT, UPDATE, DELETE, DROP или любые DDL-инструкции.
Отключение конкретных субагентов
Если вы не хотите, чтобы Claude автоматически вызывал определённый встроенный субагент, вы можете.claude/settings.jsonдобавить его в список отключённых в:
Пример
"subagents": {
"deny": ["explore", "plan"] // Отключить встроенные агенты explore и plan
// После отключения Claude не будет вызывать их автоматически, но вы всё ещё можете вызывать их явно вручную
}
}
Как вызывать субагентов
1. Автоматическое делегирование
Claude будет автоматически определять на основеdescriptionполя, подходит ли задача для субагента, без необходимости указывать вручную в промпте:
Help me check the quality of recent code changes.
2. Явный вызов
Явно укажите в промпте, какого агента использовать:
让 code-reviewer 子代理检查最近的改动
Типичные шаблоны использования
1. Изоляция задач с высоким объёмом вывода
Помещайте задачи, которые генерируют большой объём промежуточного вывода (например, запуск тестов, сканирование логов), в субагентов, а основной диалог получает только краткие выводы:
Use a subagent to run all tests, returning only failed tests and root cause analysis.
2. Параллельное исследование
Запускайте несколько субагентов одновременно для обработки разных модулей, что значительно сокращает время анализа:
并行使用子代理分别分析认证模块、数据库模块和 API 模块,汇总后给出整体架构建议
3. Связывание конвейеров субагентов
Разбейте сложный рабочий процесс на несколько специализированных агентов, передавая результаты последовательно:
先用 code-reviewer 找出问题,再用 optimizer 子代理修复这些问题
Принцип проектирования для цепочечных рабочих процессов: каждый агент делает только одну вещь и определяет свой интерфейс через чёткий сигнал «ввод → обработка → вывод → сигнал передачи». Ниже приведён пример трёхэтапного конвейера из производственной практики:
- pm-spec: читает требования, генерирует рабочую спецификацию, ставит отметку после подтверждения
READY_FOR_ARCH - architect-review: проверяет проектные ограничения, создаёт запись об архитектурном решении (ADR), ставит отметку
READY_FOR_BUILD - implementer-tester: реализует код и тесты, обновляет документацию, ставит отметку
DONE
ЧерезSubagentStopхуки, слушающие файлы статуса, автоматически запускают следующего агента без ручного вмешательства.
4. Параллельное ревью кода
同时启动 style-checker、security-scanner、test-coverage 三个子代理并行审查, 将审查时间从数分钟压缩到数十秒
Когда следует использовать субагентов
Сценарии, подходящие для субагентов:
- Задачи самодостаточны, имеют чёткие входные данные и ожидаемый результат
- Результат объёмный и значительно займёт контекст основного диалога
- Требуются строгие ограничения (только для чтения, изолированное рабочее дерево и т. п.)
- Похожие задачи повторяются, их стоит оформить как агентов
- Включает несколько независимых подобластей, которые можно обрабатывать параллельно
Сценарии, подходящие для основного диалога:
- Требуются частые итеративные корректировки, высокая интерактивность
- Многоэтапные задачи имеют сильные зависимости, контекст должен оставаться непрерывным
- Быстрые небольшие изменения, когда накладные расходы на запуск агента не оправданы
- Практический опыт: при более чем 3–4 субагентах накладные расходы на управление могут фактически снизить общую эффективность
Субагенты не могут создавать других субагентов (чтобы предотвратить бесконечную вложенность). Если нужна вложенная логика, используйтеSkills。
Лучшие
Как писать описание
- Используйте описания, ориентированные на действия:
Invoke when the user requests reviewing / analyzing / checking code quality. - Укажите предусловия:
Use after the specification document is confirmed, producing architecture decision records. - Чётко описывайте границы агента и сценарии, в которых он не силён, чтобы предотвратить некорректный вызов
Проектирование разрешений инструментов (принцип наименьших привилегий)
- Агенты только для чтения (проверка, аудит):
Read, Grep, Glob - Исследовательские агенты (сбор информации):
Read, Grep, Glob, WebFetch, WebSearch - Агенты реализации (написание кода):
Read, Write, Edit, Bash, Glob, Grep
Единственная ответственность
- Каждый агент делает только одну вещь, с чёткими правилами ввода/вывода/передачи
- Не пытайтесь заставить один агент делать всё
Предложения по системному промпту
- Укажите личность агента в системном промпте:
Please remain critical, don't just say nice things. - Укажите слабые стороны и ограничения агента, чтобы избежать излишней самоуверенности
- Если память включена, добавьте инструкцию "активно поддерживать память" в системный промпт, чтобы агент выполнял её автоматически
Выбор между параллельным и последовательным выполнением
- Поддомены независимы друг от друга → предпочитайте параллельное выполнение, чтобы сэкономить время
- Следующий шаг зависит от предыдущего результата → необходимо использовать последовательное выполнение для обеспечения качества
- Избегайте параллелизма ради самого параллелизма: 10 параллельных агентов, выполняющих простые задачи, тратят токены и увеличивают затраты на координацию