Один Клод не справляется. Собери рой

01В чём фокус

Ты уже работаешь с Claude Code и упёрся в одну и ту же стену. Задача большая, Клод в ней тонет: пока он разбирается с четвёртым файлом, из головы вылетает первый. Ты начинаешь дробить работу руками, объяснять заново, копировать куски из одного окна в другое.

Дробить правильно, объяснять заново нет.

В Claude Code есть три способа размножить исполнителя: субагент внутри твоей сессии, отдельная сессия со своим именем и команда агентов под управлением одного. Они не взаимозаменяемы, и половина разочарований оттуда: человек берёт субагента там, где нужна вторая сессия, и удивляется, что тот не помнит разговора.

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

Всё, что здесь написано про поля и поведение, сверено с официальной документацией. Не с обзорами релизов: они пересказывают, а пересказ стареет быстрее исходника.

02Что нужно до старта

Claude Code свежей версии. Разные куски описанного появились в разных выпусках, и это важно проверить до того, как ругаться на неработающее:

claude --version

Переписка между сессиями требует версии 2.1.224 или новее на macOS и Linux, включая Linux внутри WSL 2, а на нативной Windows 2.1.234 или новее. Упоминание сессии через собаку добавили в 2.1.232, уведомление о том, что соседняя сессия освободилась, в 2.1.236.

Тариф. Субагенты и переписка сессий работают на обычной подписке. Ограничение другого рода: переписка между сессиями недоступна на Amazon Bedrock, Claude Platform на AWS, Google Cloud и Microsoft Foundry. Если ты ходишь в модель через них, этот раздел гайда не про тебя, а субагенты работают везде.

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

Теперь честно про цену.

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

Больше агентов не значит лучше. Там, где задача линейная и шаги зависят друг от друга, рой проигрывает одному исполнителю: он тратит токены на согласование того, что и так шло бы по порядку.

03Ядро

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

Субагент стартует с чистой головы. Он получает свой системный промпт, сообщение с задачей, файлы правил проекта, снимок состояния репозитория и список своих соседей по сессии. И всё.

Он не видит историю твоей переписки, не знает, какие файлы ты читал, какие навыки вызывал, и не наследует твой стиль ответов.

Это не недоработка, а смысл конструкции. Чистая голова означает, что агент не потащит за собой сорок тысяч токенов вашего разговора и не собьётся на то, что обсуждалось полчаса назад. Ты платишь тем, что задачу надо описать целиком.

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

Отдельная сессия это вообще другой процесс, со своей историей и своими правами. Сессии не читают друг друга, но умеют обмениваться сообщениями: одна пишет другой короткий текст, и всё.

субагент         чистая голова, своя задача, свои права
форк             вся история родителя, его модель, его кэш
своя сессия      свой процесс, своя история, обмен сообщениями

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

043б. Что именно видит субагент

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

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

Если в поле skills перечислены навыки, их содержимое подгружается заранее и тоже оказывается в контексте.

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

Отсюда простое следствие, которое экономит вечера. Всё, что агент должен знать, живёт либо в задаче, либо в правилах проекта, либо в его собственном файле. Третьего места нет. Ссылка на «то, что мы обсуждали» для него пустой звук.

Форк устроен наоборот: полная история беседы, системный промпт и инструменты родителя, его модель и его кэш промпта. Кэш это не мелочь: переиспользованный кэш заметно дешевле набитого заново.

05Субагент это файл

Субагент не настраивается в интерфейсе. Это markdown-файл с шапкой, и он лежит в одном из двух мест:

.claude/agents/    только для этого проекта, кладётся в репозиторий
~/.claude/agents/  личный, доступен во всех проектах

Проектный побеждает личный при совпадении имён. Выше обоих стоят настройки организации, ниже обоих агенты из плагинов.

Сам файл выглядит так:

---
name: code-reviewer
description: Проверяет изменённый код на ошибки и следование стилю проекта
tools: Read, Grep, Glob, Bash
model: sonnet
---

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

Обязательных полей два. name это уникальный идентификатор строчными буквами через дефис. description это то, по чему Клод решает, отдавать ли этому агенту задачу, поэтому пишется как условие включения, а не как похвала.

Тело файла становится системным промптом агента. Запреты пишутся прямо там: «прод-код не трогай» работает лучше, чем надежда на здравый смысл.

06Поля, которые решают

Необязательных полей больше десятка, и три из них меняют поведение сильнее остальных.

tools это список инструментов, которые агенту доступны. Ревьюеру хватает чтения и поиска, и это не про экономию, а про безопасность: агент, у которого нет права писать, ничего не испортит, как бы его ни попросили.

Есть парное поле disallowedTools: оно вычитает инструменты из наследуемого набора, а не задаёт список с нуля.

model принимает sonnet, opus, haiku, fable, полный идентификатор модели или inherit. По умолчанию наследуется родительская. Механическую работу дешевле отдать модели попроще, а рассуждение по многим файлам оставить сильной.

permissionMode задаёт, как агент спрашивает разрешения: default, acceptEdits, auto, dontAsk, bypassPermissions или plan.

Остальные пригодятся позже: maxTurns ограничивает число шагов, skills подгружает навыки в контекст заранее, memory выбирает область памяти, effort задаёт уровень усилий от low до max, isolation со значением worktree запускает агента в отдельной копии репозитория, background держит его в фоне, color красит его в списке.

Заводить файл руками не обязательно. Скажи словами:

> Создай личного субагента в ~/.claude/agents/ для проверки кода. > Только чтение, модель Sonnet, пусть смотрит изменённые файлы.

075б. Одна задача, разложенная тремя способами

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

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

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

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

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

Места с решениями остаются тебе и одному форку, который в курсе всего разговора.

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

Ролей четыре: разведчик, исполнитель, решающий, проверяющий. Это не догма, но заметно лучше, чем «дайте мне пять агентов».

08Фон и передний план

Субагент работает либо в фоне, либо на переднем плане, и разница существеннее, чем кажется.

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

На переднем плане сессия ждёт его до конца, зато инструменты полные, и разрешения он спрашивает сам у себя.

Поле background: true держит агента в фоне даже тогда, когда Клод хочет вывести его на передний план.

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

09Свой результат за двадцать минут

Пять шагов. На выходе у тебя работающий ревьюер, который проверяет чужую работу, пока ты занят своей.

Шаг первый. Заведи агента.

Попроси Клода создать файл по образцу из четвёртого раздела. Проверь глазами, что в tools попало только чтение и поиск.

Шаг второй. Убедись, что он виден.

/agents

Список покажет доступных агентов и откуда каждый взялся. Если твоего нет, дело почти всегда в месте файла или в имени с заглавными буквами.

Шаг третий. Позови его явно.

Напиши в сессии собаку и первые буквы имени, выбери агента из подсказки и опиши задачу. Явный вызов надёжнее, чем надежда, что Клод сам догадается по описанию.

Шаг четвёртый. Работай дальше.

Агент ушёл в фон, ты продолжаешь. Когда он закончит, результат придёт в основную сессию.

Шаг пятый, который все пропускают. Прочитай не вывод, а работу.

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

10Что ты увидишь

Было. Большая задача идёт одним потоком. Ты объясняешь контекст, Клод работает, ты ждёшь. К середине его контекст забит подробностями первой трети, и качество проседает. Ты начинаешь новую сессию и объясняешь всё заново.

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

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

118б. Когда нужна команда агентов

Есть четвёртый способ, про который стоит знать, чтобы не изобретать его руками: команда агентов. Это набор сессий, которые запускает и координирует одна главная, с собственным протоколом обмена между участниками.

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

Брать команду стоит, когда работа делится на устойчивые роли и живёт часами. Для двух окон, которым надо изредка сообщать друг другу новости, это перебор.

12Сессии разговаривают между собой

Отдельная сессия это отдельный процесс, но не изолированный остров.

Посмотреть, кого видно:

/list-agents

Первая строка это имя твоей текущей сессии, то самое, по которому к ней обращаются другие. Ниже субагенты, товарищи по команде, соседние сессии на этой машине, а при подключённом удалённом управлении ещё и сессии на других машинах и в вебе.

Отправить сообщение просто: скажи словами, что нужно передать.

Скажи сессии, которая занимается платежами, что миграция схемы прошла

Или назови адресата явно через собаку, как субагента. Клод сам напишет текст сообщения, тебе не нужно диктовать формулировку.

Отдельно полезная вещь: попросить уведомление, когда соседняя сессия освободится.

Скажи мне, когда сессия с миграцией закончит то, чем занята

Уведомление одноразовое, никто никого не опрашивает по кругу, и если ответа нет двенадцать часов, подписка снимается сама.

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

Это ровно то, что делает переписку сессий безопасной: канал передаёт знание, а не полномочия.

139б. Что сообщением передать нельзя

Стоит понимать границу, потому что она объясняет, зачем канал вообще такой узкий.

Сообщение это текст, и только текст. Не история беседы, не файлы, не контекст. Если нужно перенести разговор целиком, сессия не пересылается, а возобновляется.

Сообщение не наделяет полномочиями. Оно не отвечает за тебя на запрос разрешения, не меняет настройки и не правит файл правил проекта, даже если прямо просит об этом. Команда вроде сжатия контекста приходит обычным текстом и не выполняется.

И работает это в обе стороны. Клод в одной сессии не станет просить соседнюю сделать то, что запрещено ему самому: обойти собственный запрет чужими руками не получится, такая просьба вернётся к тебе.

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

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

14Чтобы не споткнуться

Агент не понял задачу, потому что не был при разговоре.

Самая частая беда новичка. Ты полчаса обсуждал с Клодом устройство модуля, потом поручил субагенту его починить, а тот сделал не то. Он не видел обсуждения. Ему достались только твоя формулировка задачи и правила проекта.

Лечится двумя способами: либо описывать задачу целиком, как новому человеку, либо брать форк, который наследует всю переписку.

Фоновый агент не смог спросить.

Ты дал задачу с развилкой, агент в фоне, спросить он не может. Вместо вопроса получаешь решение, принятое за тебя. Развилки проговаривай в задаче: «если входных данных нет, остановись и сообщи, ничего не выдумывай».

Настройки авторежима затёрли встроенные правила.

Эта грабля дороже двух предыдущих. В авторежиме есть четыре списка правил, и если задать любой из них своими значениями, встроенные правила этого списка пропадают целиком. Вместе с ними уходят запреты на принудительную отправку в репозиторий, на скачивание скрипта прямо в оболочку и на выкладку в прод.

Чтобы добавить своё и сохранить встроенное, в массив кладётся строка "$defaults", и на её место подставляются умолчания:

{
  "autoMode": {
    "soft_deny": [
      "$defaults",
      "Никогда не запускай миграции базы вне миграционной утилиты"
    ]
  }
}

Проверить, что получилось на самом деле:

claude auto-mode config

Команда печатает правила, которые классификатор реально применяет, с уже подставленными умолчаниями. Смотреть её стоит каждый раз после правки настроек.

Сообщение ушло, но не дошло.

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

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

Если сообщение не дошло, порядок проверки такой: сначала версия, потом наличие адресата в списке, потом настройка приёма у получателя.

15Если полезешь глубже

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

Ограничение шагов. maxTurns останавливает агента после заданного числа ходов. Страховка от бесконечного круга, когда агент чинит своё же исправление.

Предзагрузка навыков. Поле skills кладёт нужные инструкции в контекст агента сразу, вместо того чтобы он их искал.

Уровень усилий. effort от low до max. Механической работе хватает низкого, разбору с рассуждением нужен высокий. Экономия здесь заметнее, чем на выборе модели.

Все команды оболочки через классификатор. В авторежиме узкие разрешающие правила вроде запуска тестов остаются в силе и срабатывают до классификатора. Значит, разрушительный аргумент может проскочить внутри разрешённой команды. Ключ autoMode.classifyAllShell со значением true отправляет на проверку вообще всё. Медленнее, но без щелей.

Модель по умолчанию. Переменная ANTHROPIC_MODEL перебивает настройку модели из любого файла. Переменная ANTHROPIC_DEFAULT_MODEL работает только тогда, когда модель не задана ни в одном файле настроек. Разница неочевидная, и на ней легко потерять полчаса.

16А если…

А если я не хочу, чтобы агенты трогали мой код?

Дай им только чтение в поле tools. Агент без права записи физически ничего не изменит, что бы ему ни написали.

А если задача маленькая?

Не дроби. Один исполнитель на линейной задаче быстрее и дешевле роя.

А если субагент завис?

Поставь maxTurns. И посмотри на описание задачи: зависают обычно там, где критерий готовности не задан и агент не понимает, когда остановиться.

А если сессии не видят друг друга?

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

А если агент запросил разрешение, а я не вижу запроса?

Значит, он на переднем плане и спрашивает сам у себя, а не у тебя. Фоновые агенты показывают запросы в основной сессии, передний план нет.

А если хочется, чтобы агент вообще ничего не спрашивал?

Есть поле permissionMode, и у него есть значения, снимающие вопросы. Прежде чем ставить самое смелое, сузь tools: агент без опасных инструментов безопаснее агента с широкими правами и отключёнными вопросами.

А если я работаю через облачного провайдера?

Субагенты работают, переписка сессий нет. Это ограничение платформы, а не настройка.

1712б. Чек-лист перед тем, как звать рой

Пять вопросов. Если на два из них ответ отрицательный, задачу быстрее сделать одному исполнителю.

Задача делится на куски, которые не зависят друг от друга. Если второй шаг нельзя начать, не увидев результат первого, параллелить нечего.

Каждый кусок описывается в одном абзаце. Не «разберись с авторизацией», а «проверь, что во всех обработчиках стоит проверка токена, список файлов такой».

Понятно, что считается готовым. Агент без критерия готовности либо останавливается рано, либо крутится до упора в число шагов.

Понятно, чего трогать нельзя. Запрет пишется в файл агента и в описание задачи, а не подразумевается.

Ты готов заплатить за параллельность. Пять агентов это пятикратный расход токенов. Иногда это очевидно выгодно, иногда нет, и решать до запуска.

Такой чек-лист выглядит формальностью ровно до первого раза, когда рой сделал не ту работу дважды подряд и об этом стало известно через полчаса.

18Зачем на самом деле

Соблазн считать это ускорением. Пять агентов вместо одного, значит в пять раз быстрее. Так не бывает: согласование съедает часть выигрыша, а токены растут честно в пять раз.

Настоящая ценность в другом. Рой заставляет разложить задачу до того, как начнёшь. Чтобы отдать кусок агенту, его приходится описать: что на входе, что считается готовым, чего трогать нельзя. Это ровно та работа, которую обычно пропускают и потом переделывают результат.

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

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

С этого места вайбкодинг перестаёт быть разговором с машиной и становится устройством мастерской.

19А дальше

Соседние гайды закрывают два других куска той же мастерской.

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

Не чат, а сотрудник про агентов с собственным облачным компьютером и про то, где проходит граница безопасности, когда ботов много. Полезно прочитать до того, как раздавать рою доступы.

20Источники

Субагенты: https://code.claude.com/docs/en/sub-agents Все поля фронтматтера, таблица приоритетов, точные списки того, что агент видит и чего не видит.

Агенты параллельно: https://code.claude.com/docs/en/agents Сравнение способов запустить несколько агентов и когда какой уместен.

Переписка между сессиями: https://code.claude.com/docs/en/cross-session-messaging Требования по версиям, границы прав входящего сообщения, настройки приёма.

Команды агентов: https://code.claude.com/docs/en/agent-teams Про случай, когда сессиями управляет одна главная, а не ты руками.

Настройка авторежима: https://code.claude.com/docs/en/auto-mode-config Четыре списка правил, строка со значениями по умолчанию и команды проверки.

Настройки: https://code.claude.com/docs/en/settings Уровни файлов настроек и что чем перебивается.

Переменные окружения: https://code.claude.com/docs/en/env-vars Полный перечень, включая выбор модели.