Как правильно оркестровать субагентов в Claude Code: руководство по распределению ролей

Как правильно оркестровать субагентов в Claude Code: руководство по распределению ролей

Консольный инструмент разработки Claude Code от Anthropic предлагает мощную концепцию разделения контекста — субагентов (Subagents). По мере работы над проектом контекст основного диалога неизбежно раздувается из-за поисковых логов, списков файлов и результатов тестов. Это не только замедляет ответы, но и экспоненциально увеличивает расходы на токены. Использование субагентов позволяет делегировать локальные задачи изолированным виртуальным сотрудникам, каждый из которых работает в собственном контексте с индивидуальным системным промптом, ограничением прав и выделенной моделью.

Ролевая модель и оптимизация контекста

Субагент в Claude Code — это не просто отдельная личность (persona), а изолированная сессия, запускаемая из главного окна терминала. Взаимодействие строится по принципу прогрессивного раскрытия (progressive disclosure): субагенту передается только та часть контекста, которая необходима для выполнения конкретной задачи.

Основные преимущества использования субагентов:

• Чистый контекст: Главный поток не захламляется выводом промежуточных команд. Основная сессия получает от субагента лишь финальный структурированный отчет.
• Экономия бюджета на токены: Для простых задач (сканирование логов, поиск файлов по шаблону) можно назначить быструю и дешевую модель, оставив мощную Claude Sonnet или Fable-5 для управления проектом.
• Безопасность (Least Privilege): Субагентам можно жестко ограничить список разрешенных инструментов. Например, агенту-исследователю (researcher) можно запретить редактирование файлов и выполнение команд терминала.

Модели и оптимизация расходов

Важной деталью настройки является выбор модели для субагента:

• Claude Haiku: Рекомендуется для быстрых рутинных операций, таких как поиск файлов по директориям, проверка синтаксиса или простое сканирование логов сборки. Это позволяет экономить до 90% стоимости по сравнению с использованием Sonnet.
• Claude Sonnet: Оптимальна для проведения качественного код-ревью, поиска логических ошибок и составления планов миграции. Она обладает отличным балансом цены и качества рассуждений.
• Claude Fable / Opus: Флагманский уровень вычислений. Должен использоваться только для критически сложных задач — например, проектирования общей архитектуры или поиска уязвимостей безопасности в распределенных системах.

Официальная процедура: создание субагента в интерфейсе и вручную

Развернуть собственного субагента в Claude Code можно двумя официальными способами.

Способ 1: Создание через интерактивное меню /agents

1. Введите в консоли Claude Code команду /agents.
2. Перейдите во вкладку «Library» и выберите «Create new agent».
3. Укажите область видимости (Scope): Personal для сохранения в глобальном каталоге пользователя (~/.claude/agents/) или Project для текущего репозитория (.claude/agents/). Проектные агенты удобно коммитить в Git для совместной работы в команде.
4. Опишите роль своими словами или сгенерируйте промпт с помощью Claude.
5. Задайте ограничения на инструменты (например, оставьте только read-only инструменты).
6. Выберите рабочую модель, цвет индикатора в консоли и режим памяти.
7. Сохраните изменения и вызовите субагента текстовой командой.

Способ 2: Создание вручную через конфигурационные файлы Вы можете напрямую создать Markdown-файл в папке .claude/agents/ (или глобальной папке пользователя). Файл должен содержать блок метаданных в формате YAML (frontmatter) и инструкции в теле документа.

Пример структуры конфигурационного файла субагента:

---
name: code-reviewer
description: Применяйте для проверки качества и стиля кода после изменений в файлах
model: claude-3-5-sonnet
tools: [read_file, grep_search]
disallowedTools: [write_file, run_command]
memory: project
color: blue
---
Вы являетесь экспертом по качеству кода. Проверьте переданные файлы на соответствие стилю программирования и наличие уязвимостей. Выдайте краткий отчет.

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

Поддерживаемые конфигурационные параметры

YAML-метаданные поддерживают детальную настройку прав и поведения агента:

• name: Краткое имя субагента для вызова.
• description: Подробное описание триггеров запуска. Чем точнее описано условие применения, тем корректнее главный агент будет перенаправлять задачи.
• tools / disallowedTools: Списки разрешенных и запрещенных системных утилит.
• permissionMode: Настройка режима подтверждения операций (автоматическое подтверждение или запрос у пользователя). В фоновом режиме (background: true) любые запросы прав автоотклоняются, поэтому фоновые агенты должны быть строго read-only.
• memory: Настройка базы знаний (none, project, user). Опция project сохраняет контекст внутри репозитория, а user — между сессиями конкретного пользователя.
• maxTurns: Ограничение числа мыслительных шагов для предотвращения зацикливания модели.

Разница между Skills и Subagents

Разработчикам важно не путать навыки (Skills) и субагентов (Subagents):

• Skill (Навык): Это конкретный инструмент или чек-лист, расширяющий возможности текущего агента (например, предоставление доступа к выполнению команд терминала).
• Subagent (Субагент): Это выделенный сотрудник с собственной сессией и изолированным контекстом, который самостоятельно решает задачу и отчитывается о результатах. Навык дает способность действовать, субагент же осуществляет автономный мыслительный цикл.

Процедура тестирования и валидации субагента

После создания нового субагента необходимо убедиться в его корректной работе:

1. Запустите команду /agents и проверьте, появился ли ваш агент в списке доступных.
2. Попробуйте вызвать его в чате: «Запусти субагента code-reviewer для проверки файла utils.py».
3. Убедитесь, что индикатор в консоли окрасился в выбранный вами цвет и отображает имя агента.
4. Проведите тест на безопасность: отправьте запрос, требующий изменения файлов, и убедитесь, что субагент отклонил операцию из-за отсутствия прав (disallowedTools).
5. Проверите, что в основное окно чата вернулся краткий структурированный вывод без промежуточного мусора.