Субагенты Claude Code

Субагент — отдельный исполнитель, а не ещё одно сообщение

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

Ближайшая аналогия — задача, отданная коллеге запиской. Он не сидел на обсуждении и не знает, о чём вы спорили полчаса назад, поэтому записка обязана быть самодостаточной. Зато он час копается в чужих файлах, а приносит полстраницы выводов, и разбирать его черновики вам не нужно.

Выгод четыре, и они разного рода. Основной диалог остаётся коротким. Права исполнителя настраиваются отдельно — ревьюеру не нужно право записи. Специализация записана в файл один раз, а не пересказывается руками в каждой сессии. Независимые куски запускаются параллельно: читаете первый результат, пока считается второй.

Что именно экономит изоляция контекста

Контекстное окно — весь текст, который модель видит на одном шаге: системные инструкции, история переписки, содержимое открытых файлов, вывод команд, результаты поиска. Размер зависит от модели и тарифа, у актуальных моделей Claude это сотни тысяч токенов, а сколько осталось прямо сейчас — показывает команда `/context` в сессии. Токен — обрывок текста, в среднем около четырёх латинских символов, так что кириллица и длинные пути вроде `src/features/billing/subscription-expiry.ts` съедают окно быстрее, чем кажется на глаз.

Когда место кончается, Claude Code сжимает историю: старые сообщения заменяются пересказом. Пересказ беднее оригинала, и первыми пропадают мелочи — точное имя поля, номер строки, версия пакета. Внешне ассистент бодр, а по факту начинает уверенно ошибаться в деталях. Быстрее всего окно выжигают рекурсивный grep по большому репозиторию, вывод сборки и тестов, дампы JSON и логи.

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

Из чего сделан субагент

Субагент — это файл Markdown с YAML-заголовком, и мест для него два. `.claude/agents/` внутри проекта — такие уезжают в git и работают у всей команды. `~/.claude/agents/` — личные, доступны в любом проекте. При совпадении имён побеждает проектный, и это удобно: командный вариант можно временно подменить своим.

Заголовок отделён сверху и снизу строками из трёх дефисов. Полей всего четыре, и по-настоящему обязательны только первые два. Остальные меняют не смысл субагента, а его цену и радиус поражения.

Всё, что идёт после закрывающих дефисов, — системный промпт субагента. Сюда пишут роль, порядок действий, границы («не трогай файлы вне `src`», «не предлагай рефакторинг, о котором не просили») и требуемый формат ответа. И держите в голове главное ограничение: на входе у субагента только собственный промпт и та формулировка задачи, которую передал основной агент. Вашего разговора он не видел.

• `name` — идентификатор латиницей через дефис, по нему субагента вызывают явно
• `description` — условие срабатывания, а не реклама: по этому тексту основной агент решает, звать ли субагента сам. Например: «Ревью свежего дифа. Вызывать после каждой правки кода»
• `tools` — доступные инструменты через запятую; поле можно опустить, тогда субагент наследует всё, включая подключённые MCP-серверы
• `model` — конкретная модель под задачу или `inherit`, чтобы взять ту же, что в основной сессии

Собираем первого субагента

Короткий путь — команда `/agents` прямо в сессии. Она покажет уже существующих субагентов и их область, а в режиме создания спросит по шагам: проектный или личный, имя, описание, набор инструментов, модель — и в конце откроет промпт на правку. Мастер нужен ровно один раз, чтобы не промахнуться с каталогом; дальше файл быстрее править в редакторе.

Минимальный поисковик живёт в `.claude/agents/repo-scout.md`. В заголовке — `name: repo-scout`, `description: Ищет по кодовой базе, где реализована конкретная логика. Вызывать перед правкой незнакомого модуля.` и `tools: Read, Grep, Glob`. Обратите внимание на то, чего в списке нет: `Bash`. Это не экономия строк — через bash можно и писать в файлы, поэтому режим «только чтение» получается отсутствием bash, а не вежливой просьбой в промпте.

Вызвать субагента можно двумя способами. Автоматически — основной агент сам подберёт подходящего по полю `description`. Явно — «используй субагента repo-scout: найди, где формируется итоговая цена заказа». Пока вы отлаживаете промпт, держите основным второй способ: он предсказуем и сразу показывает, что субагент вообще запустился. Задачу формулируйте целиком — пути от корня проекта, что считать результатом, чего делать не нужно.

Формат ответа: выжимка вместо сочинения

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

Если результат читает не человек, а код, просите JSON и описывайте схему буквально. Формулировка «Ответ — ровно один JSON-массив объектов с полями file, line, severity, problem. Никакого текста до и после. Если находок нет — верни `[]`» работает заметно лучше, чем «ответь в формате JSON». Отдельно опишите поведение при нехватке данных, иначе субагент допишет правдоподобное вместо пустого результата.

Про гарантии стоит сказать прямо. В обычном Claude Code формат — договорённость, а не контракт: модель почти всегда его держит, но может добавить вежливую фразу сверху. Жёсткая проверка по схеме появляется на уровне Claude Agent SDK, где итог возвращается через отдельный инструмент и его вызов обязателен. Практический вывод: схему держите плоской, полей делайте мало и на своей стороне всегда допускайте, что пришёл мусор.

Когда субагент помогает, а когда мешает

Хорошие случаи узнаются по соотношению вход/выход: много шума на входе, мало нужного на выходе. Поиск по незнакомому репозиторию, ревью дифа, инвентаризация зависимостей, разбор длинного лога, проверка сотни файлов по одному правилу. Сюда же задачи, где важны урезанные права, и те, что распадаются на независимые куски: три модуля можно проверить одновременно.

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

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

Три рабочих примера

Ревью. Субагент `code-reviewer` с `tools: Read, Grep, Glob, Bash` — bash здесь нужен ради `git diff`. В промпте: «Смотри только изменённые строки. Не предлагай рефакторинг несвязанного кода. Для каждой находки укажи файл, строку, что сломается и при каких входных данных. Стилевые придирки не пиши вовсе». Последние две фразы важнее остальных: без них ревьюер уходит в рассуждения о читаемости, и настоящие находки тонут.

Документация. Субагент `doc-writer` читает модуль целиком и пишет раздел README или комментарии к публичным функциям. Выигрыш тут именно в изоляции: пара тысяч строк исходников остаётся в его окне, а в ваш диалог возвращается «обновил docs/api.md, разделы такие-то, три функции без описания — вот они». Такому нужны права на запись, поэтому перечислите в промпте файлы, которые он трогать не должен, и проверяйте результат через `git diff`, а не на глаз.

Поиск. Субагент `repo-scout` с `Read, Grep, Glob` и задачей вроде «найди все места, где проверяется срок действия подписки». Он перебирает варианты названий, проходит по цепочке вызовов и возвращает десяток строк с координатами и одной фразой на каждую. Тот же вопрос без субагента вываливает в основной диалог сотни совпадений grep, половина из которых — комментарии и тесты.

Проверка и типичные грабли

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

Файлы субагентов держите в репозитории рядом с кодом и правьте их как код: провалился прогон — уточнили формулировку, закоммитили. Через месяц у команды набирается небольшой набор проверенных исполнителей под свои задачи. Это устойчивее, чем каждый раз заново объяснять ассистенту, чего вы от него хотите.

• Расплывчатое `description` — субагента либо не зовут никогда, либо зовут не к месту
• `Bash` у «читающего» субагента — ограничение прав становится декоративным
• Задача, сформулированная так, будто исполнитель читал ваш чат: «поправь то, о чём мы говорили»
• Строка «уточни у пользователя, если что-то неясно» — уточнять ему не у кого
• Универсальный субагент, который умеет всё сразу: работает хуже трёх узких

Практика

Проверьте себя

Частые вопросы

Похожие уроки