## Режим совместной работы подагентов Представьте: вы просите Claude помочь вам отрефакторить большой модуль, но перед рефакторингом ему нужно сначала разобраться в трёх вещах — какие существуют API-интерфейсы, как выглядит схема базы данных и каково покрытие тестами. В обычном режиме Claude может проверять их только последовательно, одну за другой. Но что, если он сможет одновременно отправить три «клона» для раздельного исследования? В этом и заключается прелесть подагентов. ## Что такое подагент ### Концепция инструмента Agent Подагент (Subagent) — это особый инструмент в Claude Code, который позволяет основной сессии создавать независимые экземпляры Claude для выполнения конкретных задач. Можно представить это так: «Claude нанял себе помощника». Claude в основной сессии выступает в роли руководителя проекта, координирующего всю работу. Когда возникает подзадача, требующая углублённого исследования, он может запустить подагента, чтобы тот занялся ею отдельно, а сам продолжает заниматься другими делами. ### Различия между подагентом и основной сессией | Характеристика | Основная сессия | Подагент | |------|--------|--------| | Контекст | Содержит полную историю диалога | **Независимое контекстное окно**, содержит только описание задачи | | Жизненный цикл | Длится до закрытия Claude Code | Автоматически завершается после выполнения задачи | | Доступ к инструментам | Все авторизованные инструменты | Может быть ограничен определённым набором инструментов | | Способ выполнения | Интерактивный диалог с вами | Автономное выполнение с возвратом результата | | Потребление контекста | Все операции потребляют один и тот же контекст | **Не потребляет контекст основной сессии** | | Результат | Отображается напрямую | Возвращается в основную сессию в виде сводки | Самое важное различие — это **независимое контекстное окно**. У подагента есть собственное контекстное пространство, и процесс его исследования не раздувает контекст основной сессии. В основную сессию передаётся только итоговый результат — это похоже на то, как вы отправляете человека в командировку для исследования: вернувшись, он передаёт вам лишь отчёт, а не пересказывает весь процесс исследования целиком. ### Преимущества независимого контекстного окна Почему независимый контекст так важен? Приведём практический пример: Допустим, вам нужно, чтобы 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 в том, когда и как использовать подагентов: ```markdown ## Правила использования подагентов ### Когда использовать подагентов - Для задач анализа более 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 вы можете запускать собственную логику, когда подагент выполняет определённые операции. Например, автоматически отправлять уведомление, когда подагент завершает тесты: ```json { "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 отображает статус выполнения подагентов в основной сессии. Вы можете видеть, каких подагентов он запустил, что делает каждый из них и завершён ли он.