Координируйте команды сеансов Claude Code

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

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

Перед тем как настраивать команду, проверьте, подойдет ли вам более легкий вариант. Subagents работают в одном сеансе, а с помощью cross-session messaging Claude может передавать результаты между сеансами, которые вы запускаете самостоятельно.

Когда использовать команды агентов

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

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

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

Сравнение с subagents

Как команды агентов, так и subagents позволяют вам распараллелить работу, но они работают по-разному. Для отдельных сеансов, которые передают сообщения друг другу без команды, см. обмен сообщениями между сеансами.

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

Включение команд агентов

Команды агентов отключены по умолчанию. Включите их, установив переменную окружения CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS на 1, либо в переменной окружения вашей оболочки, либо через settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

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

Порождение товарищей по команде также требует интерактивного сеанса. В неинтерактивном режиме с флагом -p, включая сеансы Agent SDK, Claude не порождает товарищей по команде, и подагент, названный Claude, работает как обычный подагент даже с включенными командами агентов.

Запуск вашей первой команды агентов

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

Этот пример хорошо работает, потому что три роли независимы и могут исследовать проблему без ожидания друг друга:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

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

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

Терминал лидера перечисляет товарищей по команде на панели агентов ниже поля ввода запроса. На панели:

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

Начиная с версии 2.1.199, строка неактивного товарища по команде остается на панели, пока работает любой товарищ по команде или подагент, поэтому вы можете выбрать его для просмотра его стенограммы или отправить ему дополнительную работу. Когда каждый агент на панели неактивен, неактивные строки скрываются через 30 секунд и снова появляются при следующем ходе товарища по команде; товарищ по команде продолжает работать и остается доступным, пока скрыт. В версиях 2.1.181–2.1.198 неактивная строка скрывалась через 30 секунд после завершения собственного хода, даже если другие товарищи по команде все еще работали; неактивные строки не скрываются в версиях до 2.1.181.

Когда более трех товарищей по команде неактивны одновременно, строки, выходящие за пределы первых трех, сворачиваются в одну строку, которая подсчитывает свернутых товарищей по команде, например 2 idle agents когда пять неактивны. Выберите его и нажмите Enter для развертывания свернутых строк, или нажмите Esc для их свертывания снова. Работающие товарищи по команде, неудачные товарищи по команде и товарищ по команде, который вы просматриваете, всегда сохраняют свои собственные строки.

Если вы хотите, чтобы каждый товарищ по команде находился в отдельной разделенной панели, см. Выбор режима отображения.

Управление вашей командой агентов

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

Выбор режима отображения

Команды агентов поддерживают два режима отображения:

• In-process: все товарищи по команде работают внутри вашего основного терминала. Используйте клавиши со стрелками вверх и вниз в панели агента для выбора товарища по команде, затем нажмите Enter для просмотра и введите сообщение для отправки ему напрямую. Работает в любом терминале, дополнительная настройка не требуется.
• Split panes: каждый товарищ по команде получает свою панель. Вы можете видеть вывод всех одновременно и щелкнуть в панель для прямого взаимодействия. Требует tmux или iTerm2.

По умолчанию используется "in-process". Установите "auto" для включения разделенных панелей, когда вы уже работаете внутри сеанса tmux, или когда ваш терминал — это iTerm2 с установленным CLI it2, в противном случае используется in-process. Параметр "tmux" включает режим разделенных панелей и автоматически определяет, использовать ли tmux или iTerm2 на основе вашего терминала.

Установите "iterm2" для явного использования встроенных разделенных панелей iTerm2. Этот режим требует it2 CLI и показывает ошибку с командой установки, если it2 отсутствует. Подсказка настройки, которая предлагает установить it2 или переключиться на tmux, появляется при "auto" или "tmux", когда ваш терминал — это iTerm2 и tmux доступен как резервный вариант.

Чтобы переопределить значение по умолчанию, установите teammateMode в ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

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

claude --teammate-mode auto

Флаг --teammate-mode является экспериментальным и не отображается в claude --help.

Режим разделенных панелей требует либо tmux, либо iTerm2 с it2 CLI. Для установки вручную:

• tmux: установите через менеджер пакетов вашей системы. См. tmux wiki для инструкций, специфичных для платформы.
• iTerm2: установите it2 CLI, затем включите Python API в iTerm2 → Settings → General → Magic → Enable Python API.

Укажите товарищей по команде и модели

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

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Claude Code выбирает модель каждого товарища по команде из первого из следующих применимых вариантов:

1. Модель, которую ваша подсказка порождения называет для этого товарища по команде.
2. Для товарища по команде, порожденного из определения подагента, определение model, где inherit выбирает модель лидера.
3. CLAUDE_CODE_SUBAGENT_MODEL, когда оно установлено на что-либо иное, чем inherit.
4. Текущая модель лидера.

Если вы установите CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, первые два источника не применяются. Claude Code выбирает модель каждого товарища по команде из CLAUDE_CODE_SUBAGENT_MODEL, когда оно установлено на что-либо иное, чем inherit, и из текущей модели лидера в противном случае. Требует Claude Code v2.1.257 или позже.

До версии v2.1.251 CLAUDE_CODE_SUBAGENT_MODEL был первым в этом порядке.

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

• Псевдоним семейства, такой как opus: На Anthropic API и Claude Platform на AWS, Claude Code запускает товарища по команде на самой новой версии этого семейства, которое разрешает список разрешений. На поставщиках с ID моделей, специфичными для поставщика, где подстановка не работает, заблокированный псевдоним откатывается как любое другое заблокированное значение согласно следующему пункту
• Любое другое заблокированное значение, включая псевдоним семейства на поставщиках, где подстановка не работает, или тот, у которого семейство не имеет разрешенной версии: Claude Code запускает товарища по команде на модели лидера вместо этого. Если вы установили CLAUDE_CODE_SUBAGENT_MODEL, Claude Code сначала пробует эту модель согласно этим же правилам

Товарищи по команде наследуют уровень усилий лидера. В режиме split-pane это применяется с версии v2.1.186; более ранние версии не передавали уровень усилий сеанса лидера товарищам по команде в режиме split-pane.

Требуйте планирования товарищей по команде перед реализацией

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

Spawn an architect teammate to refactor the authentication module.

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

Разговаривайте с товарищами по команде напрямую

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

• Режим in-process: используйте клавиши со стрелками вверх и вниз в панели агента для выбора товарища по команде, затем нажмите Enter для просмотра его сеанса и введите сообщение для отправки ему. Нажмите x на выбранном товарище по команде для его остановки. Нажмите Ctrl+T для переключения списка задач.
• Режим split-pane: щелкните в панель товарища по команде для прямого взаимодействия с его сеансом. Каждый товарищ по команде имеет полный вид своего собственного терминала.

Пока вы просматриваете товарища по команде в режиме in-process, простой текст и skills идут этому товарищу по команде, но встроенные команды все еще работают в сеансе лидера.

Модель товарища по команде и режим быстрого выполнения фиксируются при его порождении, поэтому /model и /fast изменяют только параметры лидера. Начиная с версии v2.1.199, ввод любой из этих команд при просмотре товарища по команде показывает уведомление о том, что изменение применяется к лидеру; более ранние версии применяли его к лидеру без указания. /effort все еще применяется к последующим ходам просматриваемого товарища по команде, потому что товарищи по команде следуют уровню усилий лидера.

Назначение и взятие задач

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

Агенты без инструментов Task координируют через сообщения вместо общего списка задач.

Лидер может явно назначать задачи или товарищи по команде могут самостоятельно брать их:

• Лидер назначает: скажите лидеру, какую задачу дать какому товарищу по команде
• Самостоятельное взятие: после завершения задачи товарищ по команде самостоятельно берет следующую неназначенную, разблокированную задачу

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

Завершение работы товарищей по команде

Чтобы корректно завершить сеанс товарища по команде, обратитесь к нему по имени. Например, с товарищем по команде по имени researcher:

Ask the researcher teammate to shut down

Лидер отправляет запрос на завершение. Товарищ по команде может одобрить, выходя корректно, или отклонить с объяснением.

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

Обеспечение качества с помощью hooks

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

• TeammateIdle: запускается, когда товарищ по команде собирается перейти в режим ожидания. Выйдите с кодом 2, чтобы отправить обратную связь и продолжить работу товарища по команде.
• TaskCreated: запускается, когда задача создается. Выйдите с кодом 2, чтобы предотвратить создание и отправить обратную связь.
• TaskCompleted: запускается, когда задача отмечается как завершенная. Выйдите с кодом 2, чтобы предотвратить завершение и отправить обратную связь.

Как работают команды агентов

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

Как Claude запускает команды агентов

Чтобы запустить команду, попросите Claude товарищей по команде. Claude запускает товарища по команде, когда он вызывает инструмент Agent с name при включенных командах агентов, если только вызов не является fork или не передает isolation при самом вызове. Claude Code не просит вас подтвердить запуск.

Claude также сам называет обычных subagent, чтобы позже отправлять им сообщения. Эти вызовы следуют тому же правилу, поэтому команды могут формироваться даже если вы их не запрашивали. Если вы хотите subagent вместо этого, отключите команды агентов.

Архитектура

Команда агентов состоит из:

Почтовый ящик каждого агента — это JSON-файл в ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Claude Code проверяет каждую запись при чтении файла почтового ящика. Записи, которые не соответствуют формату сообщения, сообщаются как ошибки и удаляются из файла; действительные сообщения все еще доставляются. До версии 2.1.207 одна неправильно сформированная запись почтового ящика вызывала повторяющуюся ошибку каждую секунду и блокировала доставку для этого почтового ящика, пока вы не удалили файл вручную.

Claude Code сообщает о сообщении как отправленном только когда запись в файл почтового ящика получателя успешна, независимо от того, является ли сообщение простым текстом или структурированным протокольным сообщением, таким как одобрение плана или запрос на завершение. Когда запись не удается, например, потому что диск заполнен или директория почтового ящика не доступна для записи, отправляющий агент получает ошибку и ничего не отправляется. См. Failed to write to a teammate's inbox для сообщений об ошибках и шагов восстановления.

Claude Code автоматически управляет зависимостями задач: когда товарищ по команде завершает задачу, от которой зависят другие задачи, он разблокирует зависимые задачи без каких-либо действий с вашей стороны.

Команды и задачи хранятся локально под именем, производным от сеанса. Имя — это session- с последующими первыми восемью символами ID сеанса:

• Конфигурация команды: ~/.claude/teams/{team-name}/config.json
• Список задач: ~/.claude/tasks/{team-name}/

Claude Code генерирует оба этих файла автоматически при запуске сеанса и обновляет их по мере присоединения товарищей по команде, перехода в режим ожидания или ухода. Директория конфигурации команды удаляется при завершении сеанса. Директория списка задач сохраняется локально и никогда не загружается, поэтому возобновленные сеансы сохраняют свои задачи. Хранение управляется тем же cleanupPeriodDays, который вы уже контролируете для стенограмм сеансов, следуя правилам очистки хранилища.

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

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

Конфигурация команды содержит массив members с именем каждого товарища по команде и ID агента. Запись лидера всегда имеет тип агента team-lead. Запись товарища по команде имеет любой тип агента, который лидер назвал при его порождении, будь то встроенный тип или определение subagent, и опускает поле, когда лидер ничего не назвал. Товарищи по команде могут читать этот файл для обнаружения других членов команды.

Нет эквивалента конфигурации команды на уровне проекта. Файл вроде .claude/teams/teams.json в каталоге вашего проекта не распознается как конфигурация; Claude обрабатывает его как обычный файл.

Использование определений subagent для товарищей по команде

При порождении товарища по команде в любом режиме отображения вы можете ссылаться на тип subagent из проекта, пользователя или управляемой области subagent. Это позволяет вам определить роль один раз, такую как security-reviewer или test-runner, и переиспользовать ее как делегированный subagent и как товарища по команде в команде агентов.

Чтобы использовать определение subagent, упомяните его по имени при просьбе Claude порождать товарища по команде:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

Claude Code читает определение subagent, которое вы назвали, и применяет эти части к товарищу по команде. Где часть зависит от режима отображения товарища по команде, запись говорит об этом:

• tools: Claude Code ограничивает товарища по команде инструментами в списке tools определения. Для товарища по команде в процессе Claude Code добавляет SendMessage в этот список, и в сеансе, который имеет инструменты Task, он также добавляет TaskCreate, TaskGet, TaskList и TaskUpdate.
• model: Claude Code использует model определения в любом режиме отображения, когда ваш запрос на порождение не называет один. См. как Claude Code выбирает модель товарища по команде.
• Body: для товарища по команде в процессе Claude Code добавляет body определения к его системному запросу по умолчанию как дополнительные инструкции. Для товарища по команде в разделенной панели Claude Code использует body вместо его системного запроса по умолчанию.
• skills: Claude Code не применяет skills определения к товарищу по команде ни в одном режиме отображения. Товарищ по команде загружает skills из ваших параметров проекта и пользователя.
• mcpServers: для товарища по команде в разделенной панели Claude Code применяет mcpServers определения в соответствии с правилами для этого поля, которые охватывают сеанс, запущенный с --agent. Товарищ по команде в процессе игнорирует поле и загружает MCP servers из ваших параметров проекта и пользователя.

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

Для товарища по команде, которого он возвращает, Claude Code повторно применяет определение, которое пришло из директории .claude/agents/ проекта или директории --add-dir только если вы доверили папке, в которой находится файл агента. Доверие к родительской папке не считается. До тех пор товарищ по команде возвращается без инструментов или инструкций определения, сохраняя только инструменты, которые Claude Code добавляет к каждому товарищу по команде в процессе. См. определение агента товарища по команде не было восстановлено для текста уведомления.

Разрешения

Товарищи по команде начинают с режима разрешений лидера, за исключением режима dontAsk, который они не наследуют. Если лидер работает с --dangerously-skip-permissions, все товарищи по команде тоже. После порождения вы можете изменить отдельные режимы разрешений товарищей по команде, но вы не можете установить режимы разрешений для отдельных товарищей по команде во время порождения.

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

Сообщения между агентами

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

В автоматическом режиме классификатор применяет две проверки к сообщениям между агентами:

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

Контекст и коммуникация

Каждый товарищ по команде имеет свое собственное контекстное окно. При порождении товарищ по команде загружает тот же контекст проекта, что и обычный сеанс: CLAUDE.md, MCP servers и skills. Он также получает запрос на порождение от лидера. История разговора лидера не переносится.

Как товарищи по команде делятся информацией:

• Автоматическая доставка сообщений: когда товарищи по команде отправляют сообщения, они автоматически доставляются получателям. Лидеру не нужно опрашивать обновления.
• Уведомления о неактивности: когда товарищ по команде заканчивает и останавливается, он автоматически уведомляет лидера и включает свой окончательный ответ в уведомление. Товарищ по команде, чей ход заканчивается на ошибке API, уведомляет лидера о том, что он не удался, и включает текст ошибки.
• Общий список задач: агенты, которые имеют инструменты Task, могут видеть статус задачи и брать доступную работу.
• Обмен сообщениями товарищей по команде: отправить сообщение одному конкретному товарищу по команде по имени. Чтобы достичь всех, отправьте одно сообщение на получателя.

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

Использование токенов

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

Запросы товарища по команде в процессе выходят за пределы TTL bucket кэша основного разговора, поэтому его кэш держится пять минут по умолчанию, включая подписку Claude. Чтобы сохранить его на час, установите subagentPromptCacheTtl на 1h. API выставляет счета за записи кэша на 1 час по более высокой ставке.

Примеры вариантов использования

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

Запуск параллельной проверки кода

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

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

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

Исследование с конкурирующими гипотезами

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

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

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

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

Лучшие практики

Дайте товарищам по команде достаточно контекста

Товарищи по команде автоматически загружают контекст проекта, включая CLAUDE.md, MCP servers и skills, но они не наследуют историю разговора лидера. См. Контекст и коммуникация для деталей. Включите детали, специфичные для задачи, в запрос на порождение:

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

Выберите подходящий размер команды

Нет жесткого ограничения на количество товарищей по команде, но применяются практические ограничения:

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

Начните с 3-5 товарищей по команде для большинства рабочих процессов. Это уравновешивает параллельную работу с управляемой координацией. Если у вас есть 15 независимых задач, 3 товарища по команде — хорошая отправная точка.

Масштабируйте только когда работа действительно выигрывает от одновременной работы товарищей по команде. Три сосредоточенных товарища по команде часто превосходят пять рассеянных.

Размер задач надлежащим образом

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

Ждите, пока товарищи по команде закончат

Иногда лидер начинает реализовывать задачи сам вместо ожидания товарищей по команде. Если вы заметите это:

Wait for your teammates to complete their tasks before proceeding

Начните с исследования и проверки

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

Избегайте конфликтов файлов

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

Мониторинг и управление

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

Устранение неполадок

Товарищи по команде не появляются

Если товарищи по команде не появляются после того, как вы попросили Claude создать команду:

• В режиме in-process товарищи по команде появляются на панели агента ниже поля ввода подсказки. Используйте клавиши со стрелками вверх и вниз для выбора одного, затем нажмите Enter для его просмотра.
• Строка товарища по команде, которая исчезла после простоя, была скрыта, а не остановлена. Неактивные строки скрываются через 30 секунд после того, как вся панель переходит в режим ожидания, и снова появляются при следующем ходе товарища по команде. Когда более трех товарищей по команде неактивны, их избыточные строки сворачиваются в одну строку N idle agents, которую Enter разворачивает. Отправьте товарищу по команде сообщение по имени, чтобы вернуть скрытую строку.
• Проверьте, что задача, которую вы дали Claude, была достаточно сложной, чтобы оправдать команду. Claude решает, порождать ли товарищей по команде, на основе задачи.
• Если вы явно запросили разделенные панели, убедитесь, что tmux установлен и доступен в вашем PATH:

  which tmux
  

• Для iTerm2 проверьте, что it2 CLI установлен и Python API включен в предпочтениях iTerm2.

Claude порождает товарищей по команде вместо подагентов

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

Чтобы названные подагенты снова запускались как подагенты, отключите команды агентов, установив CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS на 0:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

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

Установка переменной на 0 в вашем пользовательском settings.json переопределяет экспорт оболочки. Другие источники параметров все еще могут включать команды агентов:

• Файлы параметров с более высоким приоритетом: параметры проекта, локальные параметры и полезная нагрузка --settings применяются после пользовательских параметров, поэтому запись env, которая устанавливает переменную на 1 в любом из них, побеждает. См. Приоритет параметров.
• Управляемые параметры: управляемые параметры применяются после всех остальных источников. Если ваша организация включает команды агентов там, попросите вашего администратора изменить управляемое значение.

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

Слишком много запросов разрешений

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

Агенты останавливаются рано

Товарищи по команде могут остановиться после возникновения ошибок вместо восстановления. Проверьте их вывод, выбрав товарища по команде на панели агента и нажав Enter в режиме in-process, или щелкнув панель в режиме split, затем либо:

• Дайте им дополнительные инструкции напрямую
• Порождите товарища по команде-замену для продолжения работы

Сообщение от лидера или другого товарища по команде пробуждает товарища по команде в режиме in-process, который ожидает повтора неудачного запроса API, поэтому он повторяет попытку немедленно вместо ожидания полной задержки повтора.

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

Осиротевшие сеансы tmux

Если сеанс tmux сохраняется после завершения сеанса Claude Code, он может не быть полностью очищен. Перечислите сеансы и убейте созданный командой:

tmux ls
tmux kill-session -t <session-name>

Ограничения

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

• Нет возобновления сеанса с товарищами по команде in-process: /resume и /rewind не восстанавливают товарищей по команде in-process. После возобновления сеанса лидер может попытаться отправить сообщение товарищам по команде, которые больше не существуют. Если это произойдет, скажите лидеру порождать новых товарищей по команде.
• Статус задачи может отставать: товарищи по команде иногда не отмечают задачи как завершенные, что блокирует зависимые задачи. Если задача кажется застрявшей, проверьте, действительно ли работа выполнена, и обновите статус задачи вручную или скажите лидеру подтолкнуть товарища по команде.
• Завершение может быть медленным: товарищи по команде завершают свой текущий запрос или вызов инструмента перед завершением, что может занять время.
• Одна команда на сеанс: сеанс имеет ровно одну команду, ограниченную этим сеансом. Вы не можете создавать дополнительные именованные команды или делиться командой между сеансами.
• Нет вложенных команд: товарищи по команде не могут порождать своих собственных товарищей по команде. Только лидер может управлять командой.
• Нет фоновых подагентов от товарищей по команде in-process: собственные подагенты товарища по команде in-process работают на переднем плане, потому что фоновая работа товарища по команде не может пережить процесс лидера. Claude Code возвращает ошибку, когда товарищ по команде порождает подагента, чье определение устанавливает background: true. Запрос товарища по команде run_in_background: true также не удается, либо с ошибкой, либо путем молчаливого запуска на переднем плане, как описано в как Claude Code выбирает передний план или фоновый режим. Подагенты, запущенные из основного разговора, следуют фоновому значению по умолчанию.
• Лидер фиксирован: основной сеанс является лидером на протяжении всей его жизни. Вы не можете повысить товарища по команде до лидера или передать лидерство.
• Разрешения установлены при порождении: товарищи по команде начинают с режима разрешений, описанного в разделе Разрешения. Вы можете изменить режим разрешений отдельного товарища по команде после порождения, но вы не можете установить режимы разрешений для отдельных товарищей по команде во время порождения.
• Разделенные панели требуют tmux или iTerm2: режим in-process по умолчанию работает в любом терминале. Режим разделенных панелей не поддерживается в интегрированном терминале VS Code, Windows Terminal или Ghostty.

Следующие шаги

Изучите связанные подходы для параллельной работы и делегирования:

• Легкое делегирование: subagents порождают вспомогательных агентов для исследования или проверки в вашем сеансе, лучше для задач, которые не нуждаются в координации между агентами
• Обмен сообщениями между вашими собственными сеансами: cross-session messaging позволяет Claude передавать результаты между сеансами, которые вы запускаете самостоятельно
• Ручные параллельные сеансы: Git worktrees позволяют вам запускать несколько сеансов Claude Code самостоятельно без автоматической координации команды