Режим совместной работы подагентов

Понимание и использование подагентов Claude Code — параллельное исследование, фоновые задачи, изолированное выполнение

Нужен API-ключ? Зарегистрироваться →·Эндпоинты и Base URL →

Режим совместной работы подагентов¶

Представьте: вы просите Claude помочь вам отрефакторить большой модуль, но перед рефакторингом ему нужно сначала разобраться в трёх вещах — какие существуют API-интерфейсы, как выглядит схема базы данных и каково покрытие тестами. В обычном режиме Claude может проверять их только последовательно, одну за другой. Но что, если он сможет одновременно отправить три «клона» для раздельного исследования?

В этом и заключается прелесть подагентов.

Что такое подагент¶

Концепция инструмента Agent¶

Подагент (Subagent) — это особый инструмент в Claude Code, который позволяет основной сессии создавать независимые экземпляры Claude для выполнения конкретных задач. Можно представить это так: «Claude нанял себе помощника».

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

Различия между подагентом и основной сессией¶

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

Преимущества независимого контекстного окна¶

Почему независимый контекст так важен? Приведём практический пример:

Допустим, вам нужно, чтобы Claude проанализировал проект из 200 файлов. Если читать файлы один за другим в основной сессии, а в каждом файле в среднем 200 строк, то одно только содержимое файлов займёт 40000 строк контекста. Добавьте к этому процесс анализа Claude — и контекст очень быстро заполнится.

С подагентом всё иначе. Подагент читает и анализирует эти файлы в собственном контексте, а в итоге передаёт обратно лишь аналитический отчёт на несколько сотен строк. Контекст основной сессии почти не увеличивается, и у вас остаётся достаточно места для продолжения дальнейшей работы.

Встроенные типы подагентов¶

На самом деле подагенты Claude Code — это не фиксированные «типы», а гибко создаваемые основной сессией сущности в зависимости от характера задачи. Тем не менее на практике подагенты обычно выполняют следующие роли:

Explore (поиск и исследование кода)¶

Это самое распространённое применение подагентов. Когда Claude нужно разобраться в каком-либо аспекте проекта, он запускает подагента Explore:

Возможности:

• Чтение файлов (Read)
• Поиск по коду (Grep, Glob)
• Просмотр структуры каталогов
• Анализ зависимостей кода

Ограничения:

• Обычно предоставляются только инструменты только для чтения
• Не может изменять файлы
• Не может выполнять команды

Типичные сценарии:

Проанализировать публичные интерфейсы всех сервисов в каталоге src/services/
Найти все файлы, которые ссылаются на UserService
Разобраться в логике работы промежуточного слоя аутентификации

Plan (проектирование архитектуры и планирование)¶

Подагент для составления планов или проектных решений:

Возможности:

• Все возможности Explore
• Поиск в интернете (документация, лучшие практики)
• Создание подробных проектных документов

Типичные сценарии:

Спроектировать архитектурное решение для слоя кэширования
Оценить целесообразность миграции с REST на GraphQL
Разработать стратегию шардирования базы данных

Универсальная задача (General-Purpose)¶

Подагент для выполнения конкретных задач, обладающий полным доступом к инструментам:

Возможности:

• Чтение и запись файлов
• Выполнение команд
• Запуск тестов
• Установка зависимостей

Типичные сценарии:

Запустить полный набор тестов в фоновом режиме
Сгенерировать документацию API
Выполнить форматирование кода

Сценарии использования подагентов¶

Сценарий 1: поиск и понимание кода¶

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

Я только что принял этот проект, помоги мне всесторонне понять его архитектуру:
1. С помощью подагента проанализируй структуру каталогов и ключевые модули бэкенда
2. С помощью подагента проанализируй дерево компонентов и управление состоянием на фронтенде
3. С помощью подагента проанализируй схему базы данных и связи между сущностями
Затем сведи воедино информацию по всем трём направлениям и дай мне обзор архитектуры проекта.

Claude может запустить три подагента, выполняющих эти задачи параллельно, а затем свести воедино их отчёты.

Сценарий 2: параллельное исследование нескольких вариантов¶

Когда нужно сравнить несколько технических решений, параллельные возможности подагентов очень полезны:

Мне нужно выбрать очередь сообщений для проекта. Пожалуйста, исследуй по отдельности следующие варианты:
1. Redis Streams — проверь, поддерживает ли это наша текущая конфигурация Redis
2. RabbitMQ — оцени затраты на введение новой зависимости
3. Прямое использование LISTEN/NOTIFY в PostgreSQL
Для каждого варианта проанализируй плюсы, минусы и совместимость с нашим проектом.

Сценарий 3: запуск длительных задач в фоне¶

Некоторые задачи занимают много времени (например, запуск тестов, генерация документации), их можно выполнять в фоновом режиме в подагенте:

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

Claude запустит фонового подагента для выполнения тестов, а вы можете продолжать диалог с основной сессией, не дожидаясь их завершения.

Сценарий 4: изоляция операций с высоким риском¶

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

Пожалуйста, с помощью подагента попробуй выполнить следующие операции:
1. Переключиться на временную ветку
2. Попытаться обновить React до версии 19.x
3. Запустить сборку и посмотреть, сколько будет ошибок совместимости
4. Прислать мне список ошибок
Не выполняй операции в основной ветке.

Практическое руководство по подагентам¶

Пример 1: понимание незнакомой кодовой базы с помощью подагента¶

Допустим, в свой первый день вы принимаете средний по размеру проект на Python (около 50 исходных файлов) и вам нужно быстро разобраться в его структуре.

Ваш промпт:

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

1. Структура проекта и точки входа — просканируй структуру каталогов, найди точку входа main, определения маршрутов, файлы конфигурации
2. Модели данных — проанализируй все файлы моделей, построй связи между сущностями
3. Бизнес-логика — проанализируй каталог services, разберись в ключевых бизнес-процессах
4. Внешние зависимости — проанализируй requirements.txt и фактические импорты, найди ключевые зависимости

В завершение сведи воедино всю информацию и дай мне обзор проекта не более чем на 500 слов.

Процесс выполнения у Claude:

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

Запускаю 4 подагента для параллельного анализа...

[Подагент 1] Анализ структуры проекта...

  - Просканировано 52 файла Python
  - Найдена точка входа: main.py → FastAPI app
  - Определения маршрутов в каталоге routers/ (8 модулей маршрутизации)
  - Конфигурация: config.py + .env

[Подагент 2] Анализ моделей данных...

  - Найдено 12 моделей SQLAlchemy
  - Ключевые сущности: User, Organization, Project, Task, Comment
  - Ключевые связи: User ← many-to-many → Organization, Project → has-many → Task

[Подагент 3] Анализ бизнес-логики...

  - 9 файлов сервисов
  - Ключевые процессы: управление пользователями, управление проектами, назначение задач, система уведомлений
  - Обработка асинхронных задач с использованием Celery

[Подагент 4] Анализ внешних зависимостей...

  - 32 прямые зависимости
  - Ключевые зависимости: FastAPI, SQLAlchemy, Celery, Redis, Alembic
  - Обнаружено 2 неиспользуемые зависимости (requests, beautifulsoup4)

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

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

Вы обдумываете, как реализовать функцию уведомлений в реальном времени, и хотите сравнить несколько вариантов:

Мне нужно добавить в проект функцию уведомлений в реальном времени. Помоги мне параллельно оценить следующие три варианта:

Вариант A: WebSocket (с использованием встроенной поддержки WebSocket в FastAPI)
Вариант B: Server-Sent Events (SSE)
Вариант C: опрос (Polling)

Для каждого варианта проанализируй:
1. Совместимость с нашей текущей архитектурой (проверь существующий код)
2. Сложность реализации (примерно сколько файлов придётся изменить)
3. Производительность и масштабируемость
4. Совместимость с клиентами

Затем дай мне сравнительную таблицу и свою рекомендацию.

Результат сравнения у Claude может быть таким:

Три подагента завершили анализ. Сводное сравнение приведено ниже:

| Критерий оценки | WebSocket | SSE | Опрос |
|----------|-----------|-----|------|
| Совместимость с архитектурой | Нужно добавить маршрут WebSocket | Можно переиспользовать существующие HTTP-маршруты | Полностью совместимо |
| Сложность реализации | Высокая (около 8 файлов) | Средняя (около 4 файлов) | Низкая (около 2 файлов) |
| Работа в реальном времени | Лучшая (полный дуплекс) | Хорошая (push со стороны сервера) | Средняя (зависит от интервала опроса) |
| Масштабируемость | Нужна балансировка нагрузки для WebSocket | Можно использовать CDN | Самая простая |
| Интеграция с Celery | Нужен дополнительный мост сообщений | Можно напрямую потреблять события Celery | Достаточно опрашивать базу данных |

**Рекомендация**: учитывая, что вы уже используете Celery + Redis, SSE — оптимальный выбор.
Он может напрямую подписываться на канал Redis для получения событий Celery, имеет умеренную сложность реализации,
и при этом не требует дополнительной инфраструктуры.

Пример 3: запуск тестов фоновым подагентом¶

Вы вносите изменения в код и одновременно хотите знать результаты тестов:

Пожалуйста, запусти pytest в фоновом режиме, прогони весь набор тестов. Я продолжу править код, а когда прогон завершится — сообщи мне.

Claude запустит фонового подагента для выполнения тестов. Вы можете продолжать диалог с Claude и править код. Когда тесты завершатся, вы получите уведомление с результатами:

Фоновые тесты завершены. Результаты:

- Всего: 247 тестов
- Пройдено: 241
- Провалено: 4
- Пропущено: 2

Проваленные тесты:
1. test_order_service.py::test_calculate_total_with_discount
   AssertionError: 99.99 != 100.0
2. test_user_service.py::test_create_user_duplicate_email
   IntegrityError: тестовая база данных была очищена некорректно
3. ...

Нужно ли мне помочь проанализировать эти проваленные тесты?

Настройка подагентов¶

Собственные подагенты: модель и инструменты в файле¶

По состоянию на 2026-10-15, согласно документации Claude Code, собственный подагент — это Markdown-файл с YAML front matter. Положите его в .claude/agents/ (только для текущего проекта) или в ~/.claude/agents/ (для всех ваших проектов) либо просто попросите Claude написать его. Обязательны только name и description:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Частые поля: tools (разрешённые инструменты), model (используемая модель), effort (интенсивность рассуждения), maxTurns (максимум ходов) и isolation: worktree (запуск во временном git worktree).

В model можно указать алиасы sonnet / opus / haiku / fable, полный ID модели (например, claude-opus-5-5 или claude-sonnet-5) либо inherit, чтобы взять модель основного диалога. Claude Code выбирает модель подагента в таком порядке (более ранние пункты приоритетнее):

1. Параметр model, переданный при конкретном вызове
2. Поле model в определении подагента
3. Переменная окружения CLAUDE_CODE_SUBAGENT_MODEL
4. Текущая модель основного диалога

Чтобы узнать, на какой модели подагент работает на самом деле, выполните /tasks (нужен Claude Code v2.1.242 или новее). Назначить поисковым подагентам haiku, оставив основной диалог более сильной модели, — распространённый способ держать расход под контролем.

Управление поведением подагентов через CLAUDE.md¶

Помимо описанных выше файлов подагентов, вы можете с помощью CLAUDE.md направлять Claude в том, когда и как использовать подагентов:

## Правила использования подагентов

### Когда использовать подагентов

- Для задач анализа более 10 файлов следует использовать подагентов
- Когда нужно сравнить несколько вариантов, запускайте отдельного подагента для каждого варианта
- Запуск тестов следует выполнять в фоновом подагенте

### Шаблон описания задачи для подагента
При запуске подагента описание задачи должно содержать:
1. Чёткую цель (что делать)
2. Ограничения области (чего не делать)
3. Формат вывода (какой результат вернуть)

### Обработка результатов подагента
Результат подагента должен содержать:

- Сводку анализа (не более 200 слов)
- Список ключевых находок
- Пути к связанным файлам
- Потенциальные риски или проблемы

Понимание инструментов, доступных подагенту¶

То, какие инструменты может использовать подагент, зависит от того, какие права предоставила ему основная сессия. На практике:

• Задачи только для чтения: обычно предоставляются только инструменты поиска, такие как Read, Grep, Glob
• Задачи выполнения: предоставляются инструменты записи, такие как Bash, Write, Edit
• Сетевые задачи: предоставляются сетевые инструменты, такие как WebSearch, WebFetch

Вы можете обозначить набор инструментов с помощью естественного языка:

Пожалуйста, с помощью подагента проанализируй (только для чтения) связи всех моделей в каталоге src/models/.

Добавив подсказку «только для чтения», вы склоняете Claude к созданию подагента, обладающего лишь возможностями поиска и чтения.

Фоновое выполнение¶

Подагент может работать в фоновом режиме, не блокируя ваше взаимодействие с основной сессией. Когда вы говорите «в фоне...» или «асинхронно...», Claude использует параметр run_in_background:

Пожалуйста, в фоновом режиме сделай для меня две вещи:
1. Запусти полную проверку lint
2. Проверь, нет ли в зависимостях известных уязвимостей безопасности
Я продолжу править код, а когда закончишь — сообщи мне результаты.

После завершения работы фонового подагента система уведомит Claude, а Claude передаст результаты вам.

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

1. Давайте подагенту чёткое описание задачи¶

Контекст подагента совершенно новый — он не знает, о чём вы ранее говорили с основной сессией. Поэтому описание задачи должно быть самодостаточным:

Плохой подход:

С помощью подагента проверь ту проблему, о которой только что говорилось.

(Подагент не знает, что такое «та проблема, о которой только что говорилось»)

Хороший подход:

С помощью подагента проверь, корректно ли метод
process_refund() в src/services/payment_service.py обрабатывает конкурентные запросы на возврат средств.
Нужно обратить внимание на уровень изоляции транзакций базы данных и использование оптимистичной блокировки.

2. Эффективно используйте параллельных подагентов для повышения производительности¶

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

Пожалуйста, выполни параллельно следующие задачи:
1. [Подагент A] Проанализируй все точки вызова API в коде фронтенда
2. [Подагент B] Проанализируй конечные точки API бэкенда и определения параметров
3. [Подагент C] Проверь, соответствует ли документация API фактическим интерфейсам

После завершения всех трёх задач сведи воедино места, где API не соответствуют.

3. Не злоупотребляйте подагентами¶

Подагенты не всесильны. Следующие сценарии эффективнее обрабатывать прямо в основной сессии:

• Простой просмотр файлов: чтобы прочитать один-два файла, достаточно сослаться на них через @
• Простой поиск: для поиска по одному ключевому слову основная сессия справится быстрее
• Задачи, требующие непрерывного взаимодействия: подагент «одноразовый», он не подходит для задач, требующих многораундового диалога
• Последовательные задачи, зависящие от результата предыдущего шага: подагент здесь лишь увеличивает сложность

Эмпирическое правило: если задачу можно чётко описать одним-двумя предложениями и она не требует чтения большого числа файлов, делайте её прямо в основной сессии.

4. Понимайте механизм передачи результатов подагента¶

После выполнения задачи результат подагента передаётся обратно в основную сессию в виде сводки. Это означает:

• Исходный текст файлов, которые читал подагент, не передаётся обратно целиком (он слишком большой)
• Передаются только аналитические выводы и ключевая информация подагента
• Если вам нужно увидеть какой-то конкретный файл, обнаруженный подагентом, вам придётся самостоятельно прочитать его ещё раз в основной сессии

Подагент сообщил мне, что в payment_service.py на строке 127 есть проблема,
помоги мне посмотреть строки 120-140 этого файла.

5. Используйте подагентов для «пробных» операций¶

Не уверены, осуществим ли тот или иной вариант? Используйте подагента, чтобы прощупать почву, вместо того чтобы рисковать в основной ветке:

Пожалуйста, с помощью подагента проведи эксперимент:
1. Создай временный каталог /tmp/experiment
2. Скопируй в него src/models/user.py
3. Попробуй заменить декларативные модели SQLAlchemy на dataclasses
4. Посмотри, какие возникнут проблемы

Не трогай ни один файл проекта.

Продвинутый уровень: сочетание подагентов с другими функциями¶

Подагент + режим Plan¶

В режиме Plan тоже можно использовать подагентов. Это мощное сочетание — использовать подагентов для углублённого исследования на этапе планирования:

(в режиме Plan)
Пожалуйста, с помощью подагента исследуй для меня следующие вопросы, а затем на основе результатов исследования составь план миграции:
1. Список всех текущих конечных точек REST API и частота их вызовов
2. Какие конечные точки уже имеют эквивалентную реализацию на GraphQL
3. Степень зависимости клиентского кода от REST API

Подагент + инструменты MCP¶

Если вы настроили серверы MCP (например, инструмент запросов к базе данных), подагенты тоже могут их использовать:

Пожалуйста, с помощью подагента подключись к базе данных и проанализируй следующее:
1. Объём данных в каждой таблице
2. Топ-10 медленных запросов
3. Отсутствующие индексы
Используй инструмент MCP для базы данных, чтобы выполнить запросы.

Подагент + Hooks¶

С помощью Hooks вы можете запускать собственную логику, когда подагент выполняет определённые операции. Например, автоматически отправлять уведомление, когда подагент завершает тесты:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -X POST https://hooks.slack.com/... -d '{\"text\": \"$MESSAGE\"}'"
          }
        ]
      }
    ]
  }
}

Часто задаваемые вопросы¶

В: Может ли подагент видеть историю моего диалога с основной сессией?

О: Нет. Контекст подагента совершенно новый, он содержит только описание задачи, которое дал ему Claude. Именно поэтому описание задачи должно быть самодостаточным. Тем не менее подагент может читать CLAUDE.md, поэтому правила и соглашения уровня проекта действуют и для подагента.

В: Может ли подагент запускать «под-подагентов»?

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

В: Могут ли несколько подагентов общаться между собой?

О: Напрямую — нет. Если вам нужно, чтобы подагент B зависел от результата подагента A, остаётся только дождаться завершения A, после чего основная сессия передаст результат подагенту B.

В: Расходуют ли подагенты дополнительную квоту API?

О: Да. Подагенты используют независимое контекстное окно, и вход и выход каждого подагента расходуют токены. Однако поскольку контекст подагента обычно меньше (содержит только конкретную задачу), общий расход зачастую оказывается меньше, чем при выполнении того же самого в основной сессии.

В: Как узнать, что делает подагент?

О: Claude отображает статус выполнения подагентов в основной сессии. Вы можете видеть, каких подагентов он запустил, что делает каждый из них и завершён ли он.

Enterprise →