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

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

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

Сравнение с subagents

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

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

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

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.

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

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

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

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

{
  "teammateMode": "auto"
}

• Вне tmux и iTerm2: если tmux установлен, задайте для teammateMode значение "tmux". Панели открываются в отдельной сессии tmux. Чтобы наблюдать за ними, скопируйте команду из строки View teammates в промпте Claude Code и выполните эту команду во втором терминале.
• Панели не открываются в вашем окне iTerm2: задайте для teammateMode значение "iterm2", чтобы использовать собственные панели iTerm2. В этом случае товарищи по команде запускаются, только когда вы запускаете Claude Code в iTerm2 с настроенным it2.

claude --teammate-mode auto

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

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

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

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

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

Spawn an architect teammate to refactor the authentication module.

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

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

• /compact, /clear и /rewind действуют на диалог лидера, поэтому Claude Code просит вас подтвердить перед запуском любой из них из этого представления.
• /model и /fast устанавливают модель и быстрый режим лидера, а не товарища по команде, поэтому они не запускаются из этого представления. Уведомление объясняет причину.

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

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

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

Ask the researcher teammate to shut down

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

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

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

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

Архитектура

• Конфигурация команды: ~/.claude/teams/{team-name}/config.json. Claude Code удаляет директорию конфигурации команды при завершении сессии.
• Список задач: ~/.claude/tasks/{team-name}/. Эта директория остается на диске после завершения сессии. Чтобы изменить, как долго Claude Code ее хранит, задайте cleanupPeriodDays.

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

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

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

Разрешения

• --disallowedTools и --tools: участник команды начинает с правилами запрета и списком инструментов лидера, заданными в командной строке. Требуется Claude Code v2.1.309 или новее.
• --allowedTools: Claude Code не передает этот флаг участнику команды в разделенной панели, поэтому действие, разрешенное только этим флагом, там не подтверждено заранее. Чтобы подтвердить такие действия заранее, поместите правила в permissions.allow в --settings при запуске лидера. Например, выполните в оболочке claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}'. Правила применяются к лидеру и к каждому участнику команды в разделенной панели в рамках этой сессии.

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

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

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

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

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

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

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

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.

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

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.

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

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

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."

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

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

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

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

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

Wait for your teammates to complete their tasks before proceeding

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

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

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

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

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

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

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

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

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

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

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

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

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

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 также не удается, либо с ошибкой, либо путем молчаливого запуска на переднем плане. Субагенты, запущенные из основного диалога, следуют фоновому значению по умолчанию.
• Лидер фиксирован: основной сеанс является лидером на протяжении всей его жизни. Вы не можете повысить товарища по команде до лидера или передать лидерство.
• Нельзя задать режим разрешений для отдельного участника команды при создании: участники команды начинают с режима разрешений, описанного в разделе Разрешения.
• Разделенные панели требуют tmux или iTerm2: режим in-process по умолчанию работает в любом терминале.

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

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