Пользовательские субагенты в Claude Code — это специализированные ИИ-помощники, которые могут быть вызваны для выполнения определенных типов задач. Они обеспечивают более эффективное решение проблем, предоставляя задачно-ориентированные конфигурации с настраиваемыми системными промптами, инструментами и отдельным окном контекста.

Что такое субагенты?

Субагенты — это предварительно настроенные ИИ-личности, которым Claude Code может делегировать задачи. Каждый субагент:
  • Имеет определенную цель и область экспертизы
  • Использует собственное окно контекста, отдельное от основного разговора
  • Может быть настроен с определенными инструментами, которые ему разрешено использовать
  • Включает пользовательский системный промпт, который направляет его поведение
Когда Claude Code сталкивается с задачей, которая соответствует экспертизе субагента, он может делегировать эту задачу специализированному субагенту, который работает независимо и возвращает результаты.

Ключевые преимущества

Сохранение контекста

Каждый субагент работает в собственном контексте, предотвращая загрязнение основного разговора и сохраняя его сосредоточенность на высокоуровневых целях.

Специализированная экспертиза

Субагенты могут быть точно настроены с подробными инструкциями для конкретных областей, что приводит к более высоким показателям успеха в назначенных задачах.

Переиспользуемость

После создания субагенты могут использоваться в разных проектах и делиться с вашей командой для согласованных рабочих процессов.

Гибкие разрешения

Каждый субагент может иметь разные уровни доступа к инструментам, позволяя вам ограничить мощные инструменты определенными типами субагентов.

Быстрый старт

Чтобы создать своего первого субагента:
1

Откройте интерфейс субагентов

Выполните следующую команду:
/agents
2

Выберите 'Create New Agent'

Выберите, создать ли субагента уровня проекта или пользователя
3

Определите субагента

  • Рекомендуется: Сначала сгенерируйте с Claude, затем настройте, чтобы сделать его своим
  • Подробно опишите своего субагента и когда он должен использоваться
  • Выберите инструменты, к которым хотите предоставить доступ (или оставьте пустым для наследования всех инструментов)
  • Интерфейс показывает все доступные инструменты, упрощая выбор
  • Если вы генерируете с Claude, вы также можете редактировать системный промпт в своем собственном редакторе, нажав e
4

Сохраните и используйте

Ваш субагент теперь доступен! Claude будет использовать его автоматически при необходимости, или вы можете вызвать его явно:
> Используй субагента code-reviewer для проверки моих недавних изменений

Конфигурация субагентов

Расположение файлов

Субагенты хранятся как Markdown-файлы с YAML frontmatter в двух возможных местах:
ТипРасположениеОбласть действияПриоритет
Субагенты проекта.claude/agents/Доступны в текущем проектеНаивысший
Субагенты пользователя~/.claude/agents/Доступны во всех проектахНиже
Когда имена субагентов конфликтуют, субагенты уровня проекта имеют приоритет над субагентами уровня пользователя.

Агенты плагинов

Плагины могут предоставлять пользовательских субагентов, которые бесшовно интегрируются с Claude Code. Агенты плагинов работают идентично пользовательским агентам и появляются в интерфейсе /agents. Расположение агентов плагинов: Плагины включают агентов в своей директории agents/ (или пользовательских путях, указанных в манифесте плагина). Использование агентов плагинов:
  • Агенты плагинов появляются в /agents рядом с вашими пользовательскими агентами
  • Могут быть вызваны явно: “Используй агента code-reviewer из security-plugin”
  • Могут быть вызваны автоматически Claude при необходимости
  • Могут управляться (просматриваться, инспектироваться) через интерфейс /agents
См. справочник компонентов плагинов для подробностей о создании агентов плагинов.

Конфигурация на основе CLI

Вы также можете определить субагентов динамически, используя флаг CLI --agents, который принимает JSON-объект:
claude --agents '{
  "code-reviewer": {
    "description": "Эксперт по проверке кода. Используй проактивно после изменений кода.",
    "prompt": "Ты старший рецензент кода. Сосредоточься на качестве кода, безопасности и лучших практиках.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
Приоритет: Субагенты, определенные через CLI, имеют более низкий приоритет, чем субагенты уровня проекта, но более высокий приоритет, чем субагенты уровня пользователя. Случай использования: Этот подход полезен для:
  • Быстрого тестирования конфигураций субагентов
  • Субагентов, специфичных для сессии, которые не нужно сохранять
  • Скриптов автоматизации, которым нужны пользовательские субагенты
  • Обмена определениями субагентов в документации или скриптах
Для подробной информации о формате JSON и всех доступных опциях см. справочную документацию CLI.

Формат файла

Каждый субагент определяется в Markdown-файле с такой структурой:
---
name: your-sub-agent-name
description: Описание того, когда этот субагент должен быть вызван
tools: tool1, tool2, tool3  # Необязательно - наследует все инструменты, если опущено
model: sonnet  # Необязательно - укажите псевдоним модели или 'inherit'
---

Системный промпт вашего субагента идет здесь. Это может быть несколько абзацев
и должно четко определять роль субагента, возможности и подход
к решению проблем.

Включите конкретные инструкции, лучшие практики и любые ограничения,
которым должен следовать субагент.

Поля конфигурации

ПолеОбязательноОписание
nameДаУникальный идентификатор, использующий строчные буквы и дефисы
descriptionДаОписание цели субагента на естественном языке
toolsНетСписок конкретных инструментов через запятую. Если опущено, наследует все инструменты из основного потока
modelНетМодель для использования этим субагентом. Может быть псевдонимом модели (sonnet, opus, haiku) или 'inherit' для использования модели основного разговора. Если опущено, по умолчанию используется настроенная модель субагента

Выбор модели

Поле model позволяет контролировать, какую ИИ-модель использует субагент:
  • Псевдоним модели: Используйте один из доступных псевдонимов: sonnet, opus или haiku
  • 'inherit': Используйте ту же модель, что и основной разговор (полезно для согласованности)
  • Опущено: Если не указано, использует модель по умолчанию, настроенную для субагентов (sonnet)
Использование 'inherit' особенно полезно, когда вы хотите, чтобы ваши субагенты адаптировались к выбору модели основного разговора, обеспечивая согласованные возможности и стиль ответов на протяжении всей сессии.

Доступные инструменты

Субагентам может быть предоставлен доступ к любым внутренним инструментам Claude Code. См. документацию по инструментам для полного списка доступных инструментов.
Рекомендуется: Используйте команду /agents для изменения доступа к инструментам - она предоставляет интерактивный интерфейс, который перечисляет все доступные инструменты, включая любые подключенные инструменты MCP-сервера, упрощая выбор нужных.
У вас есть два варианта для настройки инструментов:
  • Опустить поле tools для наследования всех инструментов из основного потока (по умолчанию), включая инструменты MCP
  • Указать отдельные инструменты как список через запятую для более детального контроля (может редактироваться вручную или через /agents)
Инструменты MCP: Субагенты могут получать доступ к инструментам MCP из настроенных MCP-серверов. Когда поле tools опущено, субагенты наследуют все инструменты MCP, доступные основному потоку.

Управление субагентами

Использование команды /agents (Рекомендуется)

Команда /agents предоставляет комплексный интерфейс для управления субагентами:
/agents
Это открывает интерактивное меню, где вы можете:
  • Просматривать всех доступных субагентов (встроенных, пользовательских и проектных)
  • Создавать новых субагентов с управляемой настройкой
  • Редактировать существующих пользовательских субагентов, включая их доступ к инструментам
  • Удалять пользовательских субагентов
  • Видеть, какие субагенты активны при наличии дубликатов
  • Легко управлять разрешениями инструментов с полным списком доступных инструментов

Прямое управление файлами

Вы также можете управлять субагентами, работая напрямую с их файлами:
# Создать субагента проекта
mkdir -p .claude/agents
echo '---
name: test-runner
description: Используй проактивно для запуска тестов и исправления сбоев
---

Ты эксперт по автоматизации тестирования. Когда видишь изменения кода, проактивно запускай соответствующие тесты. Если тесты не проходят, анализируй сбои и исправляй их, сохраняя первоначальное намерение теста.' > .claude/agents/test-runner.md

# Создать субагента пользователя
mkdir -p ~/.claude/agents
# ... создать файл субагента

Эффективное использование субагентов

Автоматическое делегирование

Claude Code проактивно делегирует задачи на основе:
  • Описания задачи в вашем запросе
  • Поля description в конфигурациях субагентов
  • Текущего контекста и доступных инструментов
Чтобы поощрить более проактивное использование субагентов, включите фразы типа “используй ПРОАКТИВНО” или “ДОЛЖЕН БЫТЬ ИСПОЛЬЗОВАН” в поле description.

Явный вызов

Запросите конкретного субагента, упомянув его в своей команде:
> Используй субагента test-runner для исправления неудачных тестов
> Попроси субагента code-reviewer посмотреть на мои недавние изменения
> Попроси субагента debugger исследовать эту ошибку

Примеры субагентов

Рецензент кода

---
name: code-reviewer
description: Специалист-эксперт по проверке кода. Проактивно проверяет код на качество, безопасность и поддерживаемость. Используй немедленно после написания или изменения кода.
tools: Read, Grep, Glob, Bash
model: inherit
---

Ты старший рецензент кода, обеспечивающий высокие стандарты качества кода и безопасности.

При вызове:
1. Запусти git diff, чтобы увидеть недавние изменения
2. Сосредоточься на измененных файлах
3. Начни проверку немедленно

Чек-лист проверки:
- Код простой и читаемый
- Функции и переменные хорошо названы
- Нет дублированного кода
- Правильная обработка ошибок
- Нет открытых секретов или API-ключей
- Реализована валидация ввода
- Хорошее покрытие тестами
- Рассмотрены вопросы производительности

Предоставь обратную связь, организованную по приоритету:
- Критические проблемы (должны быть исправлены)
- Предупреждения (следует исправить)
- Предложения (стоит рассмотреть улучшение)

Включи конкретные примеры того, как исправить проблемы.

Отладчик

---
name: debugger
description: Специалист по отладке ошибок, сбоев тестов и неожиданного поведения. Используй проактивно при столкновении с любыми проблемами.
tools: Read, Edit, Bash, Grep, Glob
---

Ты эксперт-отладчик, специализирующийся на анализе первопричин.

При вызове:
1. Захвати сообщение об ошибке и трассировку стека
2. Определи шаги воспроизведения
3. Изолируй место сбоя
4. Реализуй минимальное исправление
5. Проверь, что решение работает

Процесс отладки:
- Анализируй сообщения об ошибках и логи
- Проверяй недавние изменения кода
- Формируй и тестируй гипотезы
- Добавляй стратегическое логирование отладки
- Инспектируй состояния переменных

Для каждой проблемы предоставь:
- Объяснение первопричины
- Доказательства, подтверждающие диагноз
- Конкретное исправление кода
- Подход к тестированию
- Рекомендации по предотвращению

Сосредоточься на исправлении основной проблемы, а не только симптомов.

Специалист по данным

---
name: data-scientist
description: Эксперт по анализу данных для SQL-запросов, операций BigQuery и инсайтов данных. Используй проактивно для задач анализа данных и запросов.
tools: Bash, Read, Write
model: sonnet
---

Ты специалист по данным, специализирующийся на SQL и анализе BigQuery.

При вызове:
1. Пойми требование к анализу данных
2. Напиши эффективные SQL-запросы
3. Используй инструменты командной строки BigQuery (bq) при необходимости
4. Анализируй и суммируй результаты
5. Представь находки четко

Ключевые практики:
- Пиши оптимизированные SQL-запросы с правильными фильтрами
- Используй соответствующие агрегации и соединения
- Включай комментарии, объясняющие сложную логику
- Форматируй результаты для читаемости
- Предоставляй рекомендации, основанные на данных

Для каждого анализа:
- Объясни подход к запросу
- Документируй любые предположения
- Выдели ключевые находки
- Предложи следующие шаги на основе данных

Всегда обеспечивай, чтобы запросы были эффективными и экономически выгодными.

Лучшие практики

  • Начинайте с агентов, сгенерированных Claude: Мы настоятельно рекомендуем генерировать вашего начального субагента с Claude, а затем итерировать над ним, чтобы сделать его лично вашим. Этот подход дает вам лучшие результаты - прочную основу, которую вы можете настроить под свои конкретные потребности.
  • Проектируйте сфокусированных субагентов: Создавайте субагентов с единственными, четкими обязанностями, а не пытайтесь заставить одного субагента делать все. Это улучшает производительность и делает субагентов более предсказуемыми.
  • Пишите подробные промпты: Включайте конкретные инструкции, примеры и ограничения в ваши системные промпты. Чем больше руководства вы предоставите, тем лучше будет работать субагент.
  • Ограничивайте доступ к инструментам: Предоставляйте только те инструменты, которые необходимы для цели субагента. Это улучшает безопасность и помогает субагенту сосредоточиться на релевантных действиях.
  • Контроль версий: Включайте субагентов проекта в контроль версий, чтобы ваша команда могла извлечь пользу и улучшить их совместно.

Продвинутое использование

Цепочка субагентов

Для сложных рабочих процессов вы можете связывать несколько субагентов:
> Сначала используй субагента code-analyzer для поиска проблем производительности, затем используй субагента optimizer для их исправления

Динамический выбор субагентов

Claude Code интеллектуально выбирает субагентов на основе контекста. Делайте ваши поля description конкретными и ориентированными на действия для лучших результатов.

Соображения производительности

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

Связанная документация

  • Плагины - Расширьте Claude Code пользовательскими агентами через плагины
  • Слэш-команды - Изучите другие встроенные команды
  • Настройки - Настройте поведение Claude Code
  • Хуки - Автоматизируйте рабочие процессы с обработчиками событий