Claude Code агенты: как субагенты экономят контекст

Что это решает

Claude Code агенты (их же называют субагентами) — отдельные исполнители, которых главная сессия запускает под конкретную подзадачу и получает от них короткий итог вместо всей черновой выдачи. Боль здесь простая: поиск по репозиторию, чтение логов и перебор файлов забивают контекст мусором, после чего агент теряет исходную задачу и начинает спорить сам с собой. Субагент перемалывает объём в своём окне и возвращает абзац. Вторая польза — права: разведчику выдают только чтение, и он физически не может ничего сломать в рабочем дереве.

Как устроено

Файл агента

Описание лежит в markdown-файле: .claude/agents/<имя>.md для проектных агентов, ~/.claude/agents/<имя>.md для личных.

---
name: explorer
description: Read-only разведчик по кодовой базе — найти файлы, проследить поток вызовов, ответить «где происходит X». Диспетчить перед правкой незнакомого модуля и когда нужен список всех вызовов символа.
model: sonnet
tools: Read, Glob, Grep, Bash
---

Ты ищешь и читаешь код, ничего не меняя. Файлы адресуются абсолютными путями,
git запускается как `git -C <корень> ...`.

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

Формат ответа: сначала список найденного строками вида `путь:строка — что там`,
потом три-пять строк вывода. Содержимое файлов целиком не пересказывать.

Поля шапки: name — имя для вызова, description — когда этого агента диспетчить, tools — белый список инструментов, model — какая модель отрабатывает (значение inherit берёт модель родительской сессии). Тело файла работает системным промптом исполнителя.

Что происходит при вызове

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

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

Как считать экономию

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

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

Белый список инструментов

tools: Read, Glob, Grep означает, что агент не запишет в файл, даже если решит, что надо. Правящему агенту добавляют Edit, Write, Bash. Минимальный набор экономит не только нервы: агент не тратит шаги на инструменты, которые ему не пригодятся, и не уходит чинить то, о чём его не просили.

Модель под задачу

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

Батч вместо фан-аута

На задаче «обработать много однотипных элементов» соблазн — запустить по агенту на элемент. Каждый агент оплачивает свой системный промпт, свою постановку и свой прогрев, и суммарный расход выходит кратно больше, чем у того же объёма работы, разложенного пачками: один агент берёт пачку элементов и возвращает по ним общий результат. Фан-аут по одному элементу оправдан только там, где элементы дорогие и независимые, а результат по каждому нужен отдельным текстом.

Как подключить

Создать каталог в репозитории:

mkdir -p .claude/agents

Написать агента под конкретную работу:

cat > .claude/agents/reviewer.md <<'EOF'
---
name: reviewer
description: Ревью диффа текущей ветки на предмет ошибок и лишних правок. Диспетчить перед созданием MR и при просьбах «посмотри мой дифф», «проверь ветку».
model: inherit
tools: Read, Glob, Grep, Bash
---

Читаешь дифф ветки относительно базовой и файлы вокруг него, ничего не меняя.

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

Формат ответа: список замечаний, каждое строкой `файл:строка — что не так — чем грозит`.
Порядок — от блокеров к мелочам. Если замечаний нет, ответить одной строкой «замечаний нет».
EOF

Урезать tools до минимума. Исследователю — чтение и поиск; правящему — плюс запись, и лучше в отдельном рабочем дереве.
Прописать формат возврата. Это самое важное поле тела: главная сессия получит только текст, и всё, что не попало в формат, пропадёт.
Проверить вызов явной просьбой: «используй агента reviewer на текущей ветке».
Закоммитить .claude/agents/ — тогда агент есть у всей команды.

Полезные сценарии

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

Ограничения

Субагент не видит диалог и не задаёт уточняющих вопросов. Недосказанная постановка даёт уверенно сделанную не ту работу.
Возврат — текст. Детали, не попавшие в формат ответа, теряются насовсем: переспросить у завершившегося агента нечего.
Отладка тяжелее обычной. Шаги не видны, виден результат; плохой ответ разбирают повторным запуском с более узкой постановкой.
Экономия не бесплатна: системный промпт и постановка оплачиваются на каждом запуске, поэтому мелкая задача через агента дороже той же задачи напрямую.
Несколько правящих агентов в одном рабочем дереве конфликтуют. Писать в файлы должен один, остальные — читать.
Субагент не заменяет план работ: цепочку из пяти зависимых шагов выстраивает главная сессия, агент берёт один шаг.
Метрику или вывод, пришедшие от агента, нельзя пересказывать дальше без выборочной сверки с первоисточником: агент отвечает уверенно и в случае ошибки тоже.

Как проверить результат

Прогнать одну задачу с агентом и без него, сравнить, что осталось в главном контексте (/context) и сколько шагов ушло на итог.
Проверить границы прав: попросить read-only агента что-нибудь изменить. Отказ должен приходить с уровня инструментов, а не из вежливости модели.
Прочитать возврат глазами и спросить: хватило бы этого текста человеку, который не видел исходников? Не хватило — править формат ответа в теле агента, а не постановку каждый раз.
Дать заведомо неполную постановку и посмотреть, что вернётся. Агент, который молча додумывает недостающее, требует более жёсткого промпта с явным «при нехватке данных вернуть вопрос, а не догадку».
Сверить выборочно две-три ссылки файл:строка из ответа с реальными файлами. Ошибка в координатах означает, что агент пересказывает по памяти, а не по прочитанному.

Правило одной строкой: субагент оправдан там, где на входе много текста, а на выходе короткий вывод, и всё нужное для работы уложено в постановку.