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

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

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

Представьте: вы просите 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. ...

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

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

Управление поведением подагентов через 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 отображает статус выполнения подагентов в основной сессии. Вы можете видеть, каких подагентов он запустил, что делает каждый из них и завершён ли он.