Когда субагенты помогают, а когда мешают
В Claude Code есть инструмент Agent, который позволяет запускать независимых субагентов прямо из диалога. У каждого субагента свой контекст — он выполняет задачу и возвращает результат основному агенту.
Звучит мощно, но на практике в большинстве случаев субагенты не нужны. В этой статье разберёмся: когда разделение на субагентов действительно помогает, а когда только мешает.
Напрямую вызвать Agent tool из CLAUDE.md или slash-команды нельзя — Claude Code сам решает, использовать его или нет. Но вы можете влиять на это решение через промпты.
Механика работы:
Ключевые свойства:
- Изолированный контекст: субагент не видит историю основного диалога — только промпт, с которым его запустили
- Сжатие результата: сколько бы файлов субагент ни прочитал и команд ни выполнил, обратно приходит только краткая выжимка
- Параллельный запуск: несколько субагентов могут работать одновременно
Самый типичный случай. Вы просите Claude Code разобраться в проблеме, и нужно проверить несколько направлений сразу.
Допустим, вы спрашиваете: «Как в проекте реализована аутентификация?»
Без субагентов Claude Code будет действовать последовательно: читать auth controller → middleware → routes → model → config… Шаг за шагом — медленно.
С субагентами:
Одновременно запускаются 3 субагента:
- Агент 1: изучает логику аутентификации в controller и middleware
- Агент 2: смотрит модели пользователей и сессий
- Агент 3: проверяет конфигурационные файлы и переменные окружения
Три направления работают параллельно, результаты сводятся вместе. В CLAUDE.md это можно обозначить так:
## Исследовательские задачи
При анализе проблем, затрагивающих несколько модулей, запускай
несколько субагентов параллельно для исследования разных направлений,
затем своди результаты.
Контекстное окно Claude Code ограничено. Если подзадача требует прочитать кучу файлов, но в итоге нужен только вывод — субагент оградит основной контекст от «информационного мусора».
Характерные примеры:
Общий признак таких задач — много входных данных, мало выходных. Субагент переваривает объём внутри себя и возвращает только суть.
Иногда вы не уверены, что изменения не сломают что-нибудь. Субагент с параметром isolation: "worktree" работает в отдельном git worktree. Даже если что-то пойдёт не так — ваша рабочая директория не пострадает.
## Рискованный рефакторинг
Для масштабного рефакторинга используй субагентов с изоляцией через worktree.
Применяй изменения только после проверки результата.
Подходящие ситуации:
- Пробный рефакторинг: не ясно, сработает ли подход — пусть субагент попробует
- Сравнение вариантов: реализовать задачу двумя способами параллельно и сравнить
- Генерация кода: создать шаблонный код, проверить и только потом влить
«Переименуй эту функцию из camelCase в snake_case» — тут проще сделать напрямую. Накладные расходы на запуск субагента (формирование контекста, ожидание ответа, разбор результата) превысят время самой работы.
Правило: если задача решается одним Grep + одним Edit — не создавай субагента.
«Прочитай конфиг → измени код на основе конфига → обнови тесты под изменения»
В такой цепочке каждый шаг зависит от предыдущего. Если разнести по субагентам, придётся гонять промежуточные результаты через промпты — неудобно и легко потерять информацию. Лучше делать последовательно.
Субагент возвращает текстовое резюме, а не структурированные данные. Если нужна точная правка (например, вставить конкретный код на строке 47), надёжнее поручить это основному агенту.
Субагенты хороши для «исследовать и дать заключение», а не для «внести точное изменение».
Если диалог только начался и контекстное окно почти пустое, нет смысла «экономить контекст» через субагентов. Задумываться об этом стоит, когда разговор затянулся и основной агент начинает сжимать историю.
Реальный пример: изучить все контроллеры Rails-проекта, использующие before_action, и проанализировать паттерны аутентификации и авторизации.
Без субагента:
Claude Code последовательно читает файлы контроллеров — каждый занимает место в основном контексте. При 20 контроллерах одно только содержимое файлов может съесть огромное количество токенов. К моменту формирования выводов ранние детали уже могут быть потеряны при сжатии.
С субагентом:
Запуск субагента: «Прочитай все контроллеры в app/controllers/,
найди все before_action-колбэки, проанализируй паттерны
аутентификации и авторизации, дай классифицированную сводку.»
Субагент читает все файлы в своём контексте и возвращает чистую сводку. Основной контекст практически не расходуется — получив выводы, можно двигаться дальше.
Заставить Claude Code использовать или не использовать субагентов нельзя, но через CLAUDE.md можно задать предпочтения:
## Предпочтения по использованию агентов
### Задачи, подходящие для субагентов
- Кросс-модульное исследование (одновременный поиск в 3+ директориях)
- Масштабный поиск и анализ кода
- Экспериментальный рефакторинг (с изоляцией через worktree)
### Задачи, не требующие субагентов
- Правки в одном файле
- Последовательные операции с зависимостями между шагами
- Исправление багов, когда точно известно, где менять
«Процесс» этой задачи значительно объёмнее «результата»?
Если да — используй субагента: пусть он переварит процесс и вернёт только результат.
Если нет — делай напрямую, без лишних прослоек.
Субагенты — это не «чем больше, тем лучше». Это инструмент управления контекстом, а не фреймворк для параллельного программирования. Правильное применение помогает Claude Code сохранять ясность мышления в больших проектах. Неправильное — просто тратит время на запуск.