Три файла субагентов, которые окупаются
Файл субагента в Claude Code это Markdown-файл, который описывает помощника со своим свежим контекстом. Anthropic советует использовать меньше субагентов и оставляет их для нескольких случаев, давая тест. Мы написали файлы, которые она всё же оставляет, прогнали каждый на реальном репозитории и применили fold-тест ещё к одному агенту. Условия: Claude Code 2.1.294 с Opus 5.5, прогоны сделаны 2026-11-08 на небольшом TypeScript API для счетов и на репозитории Hono.
Загвоздка в том, что популярный совет звучит как «удалите своих субагентов», а статья Anthropic оставляет их для конкретных случаев и даёт тест. Мы прогнали этот тест на агенте, который есть в каждой подборке, на авторе тестов. Влитый в скилл, он прошёл все двенадцать прогонов. Выжили три файла: скаут только для чтения, ревьюер только для чтения, который пропустил зелёное изменение и всё равно отметил риск, о котором никто не спрашивал, и изолированный билдер, который собрал целую функцию в своей копии репозитория, пока основная сессия продолжала работать.
Что такое файл субагента и тест Anthropic
Субагент это помощник со своим свежим контекстом. В большом репозитории всё, что читает ваша сессия, остаётся в её контексте, то есть в рабочей памяти, и она заполняется. Субагент работает как коллега, который получает задачу, читает половину кодовой базы и присылает короткую записку.
Вы создаёте папку agents внутри папки .claude, и каждый субагент это Markdown-файл в ней. Вверху вы пишете имя и описание, когда его вызывать. Это единственные обязательные поля. Описание важнее, чем кажется: именно его читает Claude, решая, вызывать ли помощника вообще. Когда мы набрали команду agents, Claude Code сообщил, что мастер удалён, так что файл вы пишете сами или просите Claude. Формат описан в документации по sub-agents.
Прикладная AI-команда Anthropic написала статью о том, как возвращать субагентов в основной агентный цикл, и адресовала её своей платформе. Субагентов она оставляет для трёх случаев: контекст раздувается, нужна параллельная работа в свежих контекстах, которые потом выбрасываются, или агент не может выбрать нужные инструменты. Всё остальное обычно может быть скиллом, то есть теми же инструкциями, которые подгружаются в основную сессию, когда нужны. Тест такой: собрать небольшой eval, влить субагента в основной цикл и оставить субагента, только если версия без него справляется хуже.
Цена субагента в том, что он стартует вслепую. Он знает только то, что вы вложили в его промпт, и при каждой передаче задачи деталь может потеряться. Поэтому, прежде чем писать любой файл, назовите случай, на который он отвечает.
Fold-тест Anthropic на четвёртом агенте
Fold-тест это способ Anthropic решить, заслуживает ли субагент своего файла. Он запускается на eval, то есть на фиксированном наборе задач, которые вы каждый раз прогоняете одинаково, с критерием прохождения, выбранным заранее. Мы применили его к автору тестов, агенту, которого добавляет почти каждый, потому что он есть в любой подборке. Это субагент, который пишет тесты для модуля, никогда не трогает ваши исходники и гоняет набор тестов, пока он не позеленеет.
Метод: оставьте файл агента как есть, скопируйте те же инструкции в скилл и прогоните каждую задачу несколько раз с агентом. Затем уберите файл агента в сторону и прогоните те же задачи со скиллом. Если тест не в пользу файла, вы ничего не теряете, ведь переносятся только инструкции.
Мы запустили это на нашем небольшом API для счетов, по одному промпту на модуль, например «добавь тесты для роутера»: шесть задач по два прогона на каждый вариант. Критерий был зафиксирован заранее: набор тестов зелёный, ни один исходный файл не изменён, а новые тесты ловят подложенный баг. Подложенный баг это крошечное изменение в коде, которое старые тесты пропускали, так что хороший новый тест должен на нём падать.
| Вариант | Вызван | Прошёл | Средняя стоимость | Среднее время |
|---|---|---|---|---|
| Субагент | 12/12 | 11/12 | $0.410 | 72 с |
| Влит в скилл | 12/12 | 12/12 | $0.262 | 36 с |
Субагент промахнулся один раз. На роутере он запустил тестовую команду, которую настройки нашего проекта не разрешали, поэтому новые тесты никто не прогнал, и один из них остался красным. Влитая версия работала примерно вдвое быстрее, потому что основная сессия уже знала репозиторий и ей не нужно было с нуля инструктировать помощника. Влитый автор тестов отвечает раньше и стоит дешевле на каждом запросе, и вы ничего не теряете. Родственная статья Anthropic говорит, что системы со многими агентами обычно сжигают заметно больше токенов, чем один агент, и наши прогоны указывают в ту же сторону.
Автор тестов не проходит fold-тест, потому что в виде скилла он справляется не хуже и дешевле. Ограничение в том, что это небольшой eval, по двенадцать прогонов на сторону на одном репозитории, и промах отчасти вызван нашими разрешениями. Запустите его на своём репозитории и прочитайте каждый прогон, где результат перевернулся. Мы написали скилл, прогнали обе версии, и файл агента ушёл, потому что влитая версия ни разу не оказалась хуже.
Файл первый: скаут только для чтения
Скаут это субагент, который умеет только читать и искать и возвращает несколько строк с доказательством. Без него вопрос, для которого нужно прочитать много файлов, заставляет основную сессию читать их все и тащить каждую строку за собой.
Вы даёте ему инструменты чтения и поиска и ничего больше, так что он не может править файлы и запускать собственных помощников. Вы ставите его на Haiku, маленькую и дешёвую модель Anthropic, потому что для чтения и поиска лучшая модель не нужна. Ещё вы пишете контракт ответа, то есть форму, которую требуете: сначала ответ, потом файл и строка, которые его доказывают, потом то, чего он не нашёл. В описании вы говорите Claude применять его для вопросов, где нужно прочитать много файлов, по одному скауту на вопрос, параллельно.
Мы склонировали Hono, большой open source веб-фреймворк, и попросили аудит того, как все двадцать семь его встроенных middleware отклоняют запрос. Мы прогнали аудит напрямую без агентов, а затем со скаутами параллельно, где каждый брал свою долю папок. Оба способа дали один и тот же ответ, вплоть до тех же middleware и тех же кодов статуса. По два прогона каждого:
| Показатель | Напрямую, прогон 1 / прогон 2 | Скауты, прогон 1 / прогон 2 |
|---|---|---|
| Основной контекст в конце (токены) | 45,868 / 47,476 | 30,505 / 33,937 |
| Стоимость | $0.457 / $0.433 | $0.267 / $0.344 |
Со скаутами основная сессия закончила примерно на треть легче, потому что читала их короткие записки, а не каждый файл. Этот запас важен, если вы продолжаете работать в той же сессии: следующая задача начинается с меньшим количеством мусора и меньшим риском что-то забыть. Скауты работали на дешёвой модели, поэтому весь прогон стоил меньше. Это тот самый случай «оставить», который описывает Anthropic: большое чтение происходит там, откуда его можно выбросить, а ваша сессия сохраняет место для работы, которая идёт после.
Теперь ограничение. На мелких вопросах, где нужно несколько файлов, скауты почти ничего не сэкономили. Бенчмарк на dev.to показал то же на обычном поиске: параллельный запуск не нашёл ничего нового и стоил намного дороже. Кроме того, основная сессия передала ответ скаутов дальше, не открывая файлы сама, так что проверяйте строки-доказательства, прежде чем действовать. Отправляйте скаута, когда чтение большое и после него у сессии есть другая работа, и пропускайте его для быстрой справки.
Файл второй: ревьюер только для чтения
Ревьюер это субагент со свежим взглядом, который умеет только читать. Когда тесты зелёные, соблазнительно влить изменение, которого никто не читал, а сессия, написавшая изменение, хуже всех подходит для его оценки, ведь она уже верит в собственный план. Ревьюер видит спецификацию и diff, то есть список строк, которые изменение добавляет и удаляет.
Вы даёте ему только инструменты чтения и поиска. Вы не даёте edit и write, чтобы он не мог исправлять найденное, и не даёте инструмент agent, чтобы он не запускал помощников. Документация Anthropic говорит именно это: чтобы ревьюер оставался read-only, не включайте в его инструменты agent. Затем вы вписываете в файл форму ответа: вердикт, пройдено или нет, потом каждая находка с файлом, строкой и цитатой кода, потом то, что он не смог доказать. Ещё одно правило держит его честным: никаких замечаний по стилю и никаких находок без процитированной строки, так что к каждой находке прилагается строка, которую вы можете открыть и проверить сами.
Мы дали ему настоящее изменение, экспорт открытых счетов в таблицу, написанный нашим билдером, вместе со спецификацией и полным diff. Он вернулся через девятнадцать секунд с вердиктом «пройдено» и одной незначительной находкой про запись клиента, которой может не быть. В разделе о том, что он не смог доказать, он отметил две вещи, о которых никто не спрашивал. Имя клиента, начинающееся со знака равенства, может выполниться в таблице как формула, а строки сортировались как текст, что работает, только пока номера счетов одной длины. Вот ревьюер, который пропустил зелёное изменение и всё равно отметил риск, не тронув ни одного файла.
Мы проверили каждый пункт сами. Ничто не удаляет клиента, так что находка про отсутствующую запись случиться не может, а вот риск формулы и сортировку стоит исправить. Ограничение в том, что ревьюер знает только то, что может прочитать, поэтому остальное он помечает как недоказанное, а каждую находку вы проверяете, прежде чем действовать. Запускайте ревьюера после сборки и перед слиянием и читайте его список недоказанного так же внимательно, как вердикт.
Файл третий: изолированный билдер
Билдер это субагент, который пишет код в собственном worktree, то есть во второй копии вашего репозитория, на своей ветке, в своей папке. Он подходит для работы, которая стоит отдельно и не должна блокировать вашу сессию, пока строится.
Вы задаёте поле isolation со значением worktree, и Claude Code создаёт эту копию для него и убирает её, если ничего не изменилось. Ещё вы задаёте лимит ходов, чтобы билдер, ходящий по кругу, остановился и отдал то, что есть, с пометкой «частично». Без лимита застрявший билдер может продолжать тратить ходы на один и тот же падающий тест, пока вы ждёте впустую. В инструкциях вы говорите ему сообщить свою ветку, гонять тесты и проверку типов, пока оба не пройдут, и сделать коммит.
Мы попросили своего билдера сделать экспорт открытых счетов в таблицу с тестами, где имена клиентов могут содержать запятые и кавычки. Он ушёл в фон, и пока он работал, мы задали основной сессии другой вопрос: какие счета можно аннулировать и где живёт это правило. Основная сессия ответила точной строкой в коде, и билдер ей не мешал. Билдер вернулся примерно через полторы минуты с коммитом в своей ветке и четырнадцатью новыми тестами, все прошли. Наша основная ветка не менялась, пока мы не решили слить. Мы слили только после того, как ревьюер пропустил работу, и main просто переехала на коммит билдера, без merge-коммита. Работа билдера всегда видна как ветка, которую можно прочитать, протестировать и слить или выбросить.
Одна статья про параллельный запуск формулирует правило одной строкой: параллельно для чтения, по одному для записи. Ограничение в том, что worktree стартует от вашей ветки по умолчанию, а не оттуда, где вы находитесь, поэтому незакоммиченной работы там нет. Никогда не отправляйте его в код, который правит ваша основная сессия, и никогда не запускайте бригаду билдеров, пишущих одновременно. Дайте билдеру один самостоятельный кусок, продолжайте работать и сливайте после ревью.
Итог: три файла и один тест
Anthropic говорит использовать меньше субагентов, и она права, но три файла всё же заслуживают места, каждый по причине, которую можно назвать. Скаут держит большое чтение вне основной сессии. Ревьюер даёт свежий взгляд, который умеет только читать. Билдер пишет отдельный кусок в своей копии репозитория. Впишите эту причину в описание каждого файла, потому что именно его читает Claude, решая, вызывать ли помощника. Если причину не удаётся записать одним предложением, это обычно признак того, что агент должен быть скиллом.
Автор тестов справился не хуже в виде скилла, поэтому его файл ушёл, и ваш, скорее всего, тоже можно убрать. Пропускайте субагента для быстрого вопроса, для кода, который ваша сессия уже правит, и для любой персоны без контекстной причины существовать. В этих случаях помощник обходится вам в инструктаж, ожидание и передачу задачи и не даёт ничего, чего не смогла бы сделать ваша сессия. Agent teams, то есть сессии, которые пишут друг другу сообщения, это другое, и ничто здесь в них не нуждается.
Правило одно, и его написала Anthropic: прежде чем новый агент получит файл, влейте его в скилл, прогоните обе версии и оставьте файл, только если скилл справляется хуже.
AIDive