Перейти к основному содержанию
Команды агентов являются экспериментальными и отключены по умолчанию. Включите их, добавив CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS в ваш settings.json или переменную окружения. Команды агентов имеют известные ограничения в отношении возобновления сеанса, координации задач и поведения при завершении.
Команды агентов позволяют координировать несколько экземпляров Claude Code, работающих вместе. Один сеанс выступает в роли лидера команды, координируя работу, назначая задачи и синтезируя результаты. Товарищи по команде работают независимо, каждый в своем контекстном окне, и общаются друг с другом напрямую. В отличие от subagents, которые работают в одном сеансе и могут только докладывать основному агенту, вы также можете взаимодействовать с отдельными товарищами по команде напрямую, не проходя через лидера.
Команды агентов требуют Claude Code версии 2.1.32 или позже. Проверьте вашу версию с помощью claude --version.
На этой странице рассматривается:

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

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

​
Сравнение с subagents

Как команды агентов, так и subagents позволяют вам распараллелить работу, но они работают по-разному. Выбирайте в зависимости от того, нужны ли вашим работникам общаться друг с другом:
Диаграмма, сравнивающая архитектуры subagent и agent team. Subagents порождаются основным агентом, выполняют работу и докладывают результаты. Команды агентов координируют работу через общий список задач, товарищи по команде общаются друг с другом напрямую.
SubagentsКоманды агентов
КонтекстСобственное контекстное окно; результаты возвращаются вызывающемуСобственное контекстное окно; полностью независимы
КоммуникацияДокладывают результаты только основному агентуТоварищи по команде обмениваются сообщениями напрямую
КоординацияОсновной агент управляет всей работойОбщий список задач с самокоординацией
Лучше всего дляСосредоточенные задачи, где имеет значение только результатСложная работа, требующая обсуждения и сотрудничества
Стоимость токеновНиже: результаты суммируются обратно в основной контекстВыше: каждый товарищ по команде — отдельный экземпляр Claude
Используйте subagents, когда вам нужны быстрые, сосредоточенные работники, которые докладывают обратно. Используйте команды агентов, когда товарищи по команде должны делиться выводами, оспаривать друг друга и координировать самостоятельно.

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

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

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

После включения команд агентов скажите Claude создать команду агентов и опишите задачу и структуру команды, которую вы хотите, на естественном языке. Claude создает команду, порождает товарищей по команде и координирует работу на основе вашего запроса. Этот пример хорошо работает, потому что три роли независимы и могут исследовать проблему без ожидания друг друга: 
I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.
После этого Claude создает команду с общим списком задач, порождает товарищей по команде для каждой перспективы, заставляет их исследовать проблему, синтезирует выводы и пытается очистить команду по завершении. Терминал лидера перечисляет всех товарищей по команде и то, над чем они работают. Используйте Shift+Down для циклического переключения между товарищами по команде и отправки им сообщений напрямую. После последнего товарища по команде Shift+Down возвращается к лидеру. Если вы хотите, чтобы каждый товарищ по команде находился в отдельной разделенной панели, см. Выбор режима отображения.

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

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

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

Команды агентов поддерживают два режима отображения:
  • In-process: все товарищи по команде работают внутри вашего основного терминала. Используйте Shift+Down для циклического переключения между товарищами по команде и введите сообщение для отправки им напрямую. Работает в любом терминале, дополнительная настройка не требуется.
  • Split panes: каждый товарищ по команде получает свою панель. Вы можете видеть вывод всех одновременно и щелкнуть в панель для прямого взаимодействия. Требует tmux или iTerm2.
tmux имеет известные ограничения на некоторых операционных системах и традиционно работает лучше всего на macOS. Использование tmux -CC в iTerm2 — это рекомендуемая точка входа в tmux.
По умолчанию используется "auto", который использует разделенные панели, если вы уже работаете внутри сеанса tmux, и in-process в противном случае. Параметр "tmux" включает режим разделенных панелей и автоматически определяет, использовать ли tmux или iTerm2 на основе вашего терминала. Чтобы переопределить, установите teammateMode в вашем settings.json: 
{
  "teammateMode": "in-process"
}
Чтобы принудительно включить режим in-process для одного сеанса, передайте его как флаг: 
claude --teammate-mode in-process
Режим разделенных панелей требует либо tmux, либо iTerm2 с it2 CLI. Для установки вручную:
  • tmux: установите через менеджер пакетов вашей системы. См. tmux wiki для инструкций, специфичных для платформы.
  • iTerm2: установите it2 CLI, затем включите Python API в iTerm2 → Settings → General → Magic → Enable Python API.

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

Claude решает количество товарищей по команде для порождения на основе вашей задачи, или вы можете указать ровно то, что вы хотите: 
Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

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

Для сложных или рискованных задач вы можете потребовать, чтобы товарищи по команде планировали перед реализацией. Товарищ по команде работает в режиме только для чтения план-режима до тех пор, пока лидер не одобрит его подход: 
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.
Когда товарищ по команде заканчивает планирование, он отправляет запрос на одобрение плана лидеру. Лидер проверяет план и либо одобряет его, либо отклоняет с обратной связью. Если отклонено, товарищ по команде остается в режиме плана, пересматривает на основе обратной связи и повторно отправляет. После одобрения товарищ по команде выходит из режима плана и начинает реализацию. Лидер принимает решения об одобрении автономно. Чтобы повлиять на суждение лидера, дайте ему критерии в вашем запросе, такие как «одобрять только планы, которые включают покрытие тестами» или «отклонять планы, которые изменяют схему базы данных».

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

Каждый товарищ по команде — это полный, независимый сеанс Claude Code. Вы можете отправить сообщение любому товарищу по команде напрямую, чтобы дать дополнительные инструкции, задать дополнительные вопросы или переориентировать его подход.
  • Режим in-process: используйте Shift+Down для циклического переключения между товарищами по команде, затем введите сообщение для отправки им. Нажмите Enter для просмотра сеанса товарища по команде, затем Escape для прерывания его текущего хода. Нажмите Ctrl+T для переключения списка задач.
  • Режим split-pane: щелкните в панель товарища по команде для прямого взаимодействия с его сеансом. Каждый товарищ по команде имеет полный вид своего собственного терминала.

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

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

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

Чтобы корректно завершить сеанс товарища по команде: 
Ask the researcher teammate to shut down
Лидер отправляет запрос на завершение. Товарищ по команде может одобрить, выходя корректно, или отклонить с объяснением.

​
Очистка команды

Когда вы закончите, попросите лидера очистить команду: 
Clean up the team
Это удаляет общие ресурсы команды. Когда лидер запускает очистку, он проверяет наличие активных товарищей по команде и завершается с ошибкой, если какие-либо все еще работают, поэтому сначала завершите их.
Всегда используйте лидера для очистки. Товарищи по команде не должны запускать очистку, потому что их контекст команды может не разрешиться правильно, потенциально оставляя ресурсы в несогласованном состоянии.

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

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

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

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

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

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

​
Архитектура

Команда агентов состоит из:
КомпонентРоль
Лидер командыОсновной сеанс Claude Code, который создает команду, порождает товарищей по команде и координирует работу
Товарищи по командеОтдельные экземпляры Claude Code, которые каждый работают над назначенными задачами
Список задачОбщий список рабочих элементов, которые товарищи по команде берут и завершают
Почтовый ящикСистема обмена сообщениями для коммуникации между агентами
См. Выбор режима отображения для параметров конфигурации отображения. Сообщения товарищей по команде поступают лидеру автоматически. Система автоматически управляет зависимостями задач. Когда товарищ по команде завершает задачу, от которой зависят другие задачи, заблокированные задачи разблокируются без ручного вмешательства. Команды и задачи хранятся локально:
  • Конфигурация команды: ~/.claude/teams/{team-name}/config.json
  • Список задач: ~/.claude/tasks/{team-name}/
Конфигурация команды содержит массив members с именем каждого товарища по команде, ID агента и типом агента. Товарищи по команде могут читать этот файл для обнаружения других членов команды.

​
Разрешения

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

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

Каждый товарищ по команде имеет свое собственное контекстное окно. При порождении товарищ по команде загружает тот же контекст проекта, что и обычный сеанс: CLAUDE.md, MCP servers и skills. Он также получает запрос на порождение от лидера. История разговора лидера не переносится. Как товарищи по команде делятся информацией:
  • Автоматическая доставка сообщений: когда товарищи по команде отправляют сообщения, они автоматически доставляются получателям. Лидеру не нужно опрашивать обновления.
  • Уведомления о неактивности: когда товарищ по команде заканчивает и останавливается, он автоматически уведомляет лидера.
  • Общий список задач: все агенты могут видеть статус задачи и брать доступную работу.
Обмен сообщениями товарищей по команде:
  • message: отправить сообщение одному конкретному товарищу по команде
  • broadcast: отправить всем товарищам по команде одновременно. Используйте редко, так как затраты масштабируются с размером команды.

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

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

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

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

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

Один рецензент имеет тенденцию сосредотачиваться на одном типе проблемы за раз. Разделение критериев проверки на независимые области означает, что безопасность, производительность и покрытие тестами получают тщательное внимание одновременно. Запрос назначает каждому товарищу по команде отдельный объектив, чтобы они не перекрывались: 
Create an agent team to review PR #142. Spawn three reviewers:
- 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 товарищей по команде для большинства рабочих процессов. Это уравновешивает параллельную работу с управляемой координацией. Примеры в этом руководстве используют 3-5 товарищей по команде, потому что этот диапазон хорошо работает для различных типов задач. Наличие 5-6 задач на товарища по команде держит всех продуктивными без чрезмерного переключения контекста. Если у вас есть 15 независимых задач, 3 товарища по команде — хорошая отправная точка. Масштабируйте только когда работа действительно выигрывает от одновременной работы товарищей по команде. Три сосредоточенных товарища по команде часто превосходят пять рассеянных.

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

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

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

Иногда лидер начинает реализовывать задачи сам вместо ожидания товарищей по команде. Если вы заметите это: 
Wait for your teammates to complete their tasks before proceeding

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

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

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

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

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

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

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

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

Если товарищи по команде не появляются после того, как вы попросили Claude создать команду:
  • В режиме in-process товарищи по команде могут уже работать, но не видны. Нажмите Shift+Down для циклического переключения между активными товарищами по команде.
  • Проверьте, что задача, которую вы дали Claude, была достаточно сложной, чтобы оправдать команду. Claude решает, порождать ли товарищей по команде, на основе задачи.
  • Если вы явно запросили разделенные панели, убедитесь, что tmux установлен и доступен в вашем PATH: 
    which tmux
  • Для iTerm2 проверьте, что it2 CLI установлен и Python API включен в предпочтениях iTerm2.

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

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

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

Товарищи по команде могут остановиться после возникновения ошибок вместо восстановления. Проверьте их вывод, используя Shift+Down в режиме in-process или щелкнув панель в режиме split, затем либо:
  • Дайте им дополнительные инструкции напрямую
  • Порождите товарища по команде-замену для продолжения работы

​
Лидер завершает работу до завершения работы

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

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

Если сеанс tmux сохраняется после завершения команды, он может не быть полностью очищен. Перечислите сеансы и убейте созданный командой: 
tmux ls
tmux kill-session -t <session-name>

​
Ограничения

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

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

Изучите связанные подходы для параллельной работы и делегирования:
  • Легкое делегирование: subagents порождают вспомогательных агентов для исследования или проверки в вашем сеансе, лучше для задач, которые не нуждаются в координации между агентами
  • Ручные параллельные сеансы: Git worktrees позволяют вам запускать несколько сеансов Claude Code самостоятельно без автоматической координации команды
  • Сравнение подходов: см. сравнение subagent vs agent team для разбора рядом