Claude CodeГайд

Agent Teams в Claude Code: как запустить команду AI-агентов

Заново прогнал три команды агентов в Claude Code 2.1.319: ревью тремя агентами в панелях tmux, тесты и правки с зависимостями, общий список задач и его цена.

Agent Teams в Claude Code: как запустить команду AI-агентов

6 ноября в трёх панелях tmux три агента Claude Code независимо нашли в моём демо-проекте одни и те же две дыры. Agent Teams в Claude Code — это режим, в котором одна сессия становится лидером и запускает команду AI-агентов. У каждого агента своё контекстное окно, агенты пишут друг другу напрямую и разбирают задачи из общего списка. Включается режим переменной CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, а команду просят обычным текстом.

Первую версию этой инструкции я написал в феврале 2026 года, через день после выхода фичи в Claude Code 2.1.32. С тех пор поменялось почти всё, кроме переменной: отдельный шаг создания команды убрали, режим отображения по умолчанию другой, навигация и план-режим работают иначе, а на моделях Claude 5 общий список задач нужно включать отдельно. Поэтому 6 ноября я заново прогнал три команды агентов в Claude Code 2.1.319 на маленьком демо-проекте. Все кадры терминала ниже сняты с этих прогонов.

В статье разберём:

  • чем команда агентов отличается от субагентов и когда она окупается;
  • как включить Agent Teams и что ещё нужно на моделях Claude 5;
  • как запустить первую команду и какой промпт ей дать;
  • какой режим отображения выбрать: одно окно или панели tmux;
  • как управлять агентами и общим списком задач;
  • где Claude Code хранит команду и сколько она тратит токенов;
  • какие ошибки ломают работу команды.

Что такое Agent Teams в Claude Code и чем команда отличается от субагентов

Команда агентов (agent team) — это несколько отдельных сессий Claude Code, которые работают над одной задачей одновременно. Главная сессия называется лидером: она запускает агентов-тиммейтов, раздаёт работу и собирает результат. Тиммейты работают независимо и переписываются напрямую, минуя лидера, а ты можешь написать любому из них.

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

Схема: слева главный агент и три субагента, которые возвращают ему результаты; справа лидер, общий список задач и три тиммейта, связанные друг с другом
Субагенты отчитываются главной сессии, тиммейты общаются друг с другом напрямую. Изображение: документация Anthropic
Субагенты Agent Teams
Контекст Свой, результат возвращается вызвавшему Свой, полностью независимый
Общение Ответ главной сессии Агенты пишут друг другу напрямую
Координация Всё ведёт главная сессия Сообщения и общий список задач
Расход токенов Ниже: наверх уходит только итог Выше: каждый агент это отдельный Claude

Команда окупается, когда работу можно разрезать на независимые куски. Ревью с разных сторон, отладка с несколькими гипотезами, новый модуль, который пилят по частям, изменения сразу во фронте, бэке и тестах. Если задача последовательная или касается одного файла, обычная сессия справится дешевле. В моих прогонах лучше всего сработало ревью: три агента независимо нашли одни и те же две дыры. В прогоне с правками кода лидеру уже пришлось ловить нестыковку между агентами. Для сотен однотипных задач лучше подходят dynamic workflows в Claude Code, а несколько своих сессий без координации удобнее держать в Agent View.

Dynamic workflows в Claude Code: сотни агентов разом
Когда задач сотни и они однотипные, скрипт-воркфлоу справится лучше команды из трёх агентов.

Как включить Agent Teams в Claude Code

Фича по-прежнему экспериментальная и по умолчанию выключена. Включается она переменной окружения в блоке env файла настроек. Подробно про сам файл я писал в гайде по settings.json:

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

Можно и просто экспортировать переменную в шелле перед запуском claude. Команды работают только в интерактивной сессии: в режиме claude -p и в Agent SDK тиммейты не запускаются, даже если переменная задана.

На моделях Claude 5 нужен ещё один шаг. Общий список задач держится на инструментах TaskCreate, TaskList и TaskUpdate, а их Claude Code по умолчанию даёт только Opus 4.7, Sonnet 4.6, Haiku 4.5 и более старым моделям. Так написано в справочнике инструментов. На Sonnet 5.5, Opus 5.5 и Fable список задач появится, только если добавить CLAUDE_CODE_ENABLE_TODO_TOOLS=1 (полный список переменных собран в справочнике по переменным окружения):

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"
  }
}

Я проверил это на втором прогоне. Без второй переменной лидер на Sonnet 5.5 честно сказал, что инструментов для общего списка у него нет, и выстроил зависимость «сначала тесты, потом исправление» порядком запуска агентов.

Ответ лидера Claude Code: команды для общего списка задач нет, поэтому сначала запущен агент tests, а fixer будет запущен после него
Без CLAUDE_CODE_ENABLE_TODO_TOOLS лидер на Sonnet 5.5 держит порядок задач сам, общего списка нет. Скриншот: терминал / matveev.tech

Как запустить команду агентов в Claude Code: промпт и первый прогон

После включения просто опиши задачу и состав команды. Отдельного шага «создать команду» больше нет: с версии 2.1.178 у каждой сессии одна неявная команда, а инструменты TeamCreate и TeamDelete удалены, это видно в changelog Claude Code. Лидер запускает тиммейта, когда вызывает агента с именем.

Для первого прогона я написал маленький CLI todo-scan на Python: он ищет TODO и FIXME в файлах и печатает JSON. В код специально положил две дыры: eval с именем файла и git blame через shell=True. Промпт был такой:

«Создай команду агентов для ревью модуля [папка с кодом]. Три тиммейта на Sonnet с именами security, perf и tests: security ищет уязвимости, perf смотрит на производительность, tests проверяет покрытие тестами. Код не меняйте. Пусть каждый пришлёт находки с оценкой серьёзности, а ты сведи их в общий отчёт.»

Имена в промпте я задаю намеренно: по ним потом удобно писать агентам и просить лидера кого-то остановить. Модель тоже лучше назвать сразу. Claude Code берёт её в таком порядке: модель из промпта, затем поле model из определения агента, затем CLAUDE_CODE_SUBAGENT_MODEL и в конце модель лидера. Настройку teammateDefaultModel убрали в версии 2.1.234, теперь она игнорируется. Как модель и уровень effort передаются агентам, я разбирал в статье про модель и effort level в Claude Code.

Окно tmux: слева сводный отчёт лидера, справа три панели агентов security, perf и tests с их находками
Лидер слева сводит отчёты, справа панели трёх тиммейтов. Все трое нашли eval и shell=True. Скриншот: терминал / matveev.tech

Команда отработала за две минуты. Все три агента независимо нашли обе дыры: eval в scanner.py:29 и shell=True в scanner.py:36. Лидер свёл их находки в общий отчёт на 22 пункта, отсортировал по серьёзности и у каждого пункта указал, кто из агентов его нашёл. Агент tests отдельно заметил, что обе критичные проблемы лежат в коде без тестов, и предложил сначала написать тесты. Один ревьюер такого перекрёстного подтверждения не даёт.

Как выбрать режим отображения: одно окно или панели tmux

Режимов два. В режиме in-process все агенты живут внутри основного терминала, а под полем ввода появляется панель со списком тиммейтов. Работает в любом терминале. В режиме split panes каждый агент получает свою панель tmux или iTerm2, и видно сразу всех.

Раздел документации Claude Code про режимы отображения: in-process и split panes, значение по умолчанию in-process
Сейчас по умолчанию стоит in-process, панели включаются отдельно. Скриншот: документация Anthropic

В феврале по умолчанию стоял auto, теперь по документации это in-process. Режим задаётся ключом teammateMode в ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

Значений четыре. in-process держит всех в одном окне. auto включает панели, если ты уже внутри tmux или в iTerm2 с утилитой it2, иначе работает как in-process. tmux включает панели всегда и сам выбирает между tmux и iTerm2. iterm2 использует родные панели iTerm2: для него нужен CLI it2 и включённый Python API в iTerm2 → Settings → General → Magic → Enable Python API. На одну сессию режим можно поменять флагом claude --teammate-mode in-process: он экспериментальный и в claude --help не показывается.

Панели не работают во встроенном терминале VS Code, в Windows Terminal и в Ghostty. Если сидишь в Ghostty, оставляй in-process или запускай Claude Code внутри tmux.

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

Вся координация идёт через лидера обычным текстом, но с любым агентом можно поговорить напрямую. В режиме in-process стрелками вверх и вниз выбираешь агента в панели, Enter открывает его сессию, и дальше ты пишешь уже ему. В поле ввода в этот момент стоит подсказка Message @имя….

Сессия агента tests в режиме in-process: отчёт о девяти тестах безопасности и поле ввода Message @tests
Открыта сессия агента tests: видно его отчёт, а сообщение из поля ввода уйдёт ему, а не лидеру. Скриншот: терминал / matveev.tech

Остальные клавиши в панели такие:

  • Escape прерывает текущий ход агента, которого ты смотришь;
  • x останавливает выбранного агента;
  • Ctrl+X Ctrl+K останавливает всех агентов разом;
  • Ctrl+T показывает и прячет список задач.

В феврале агентов переключали через Shift+Up/Down, это уже не работает. Режима делегирования на Shift+Tab в документации тоже больше нет. Теперь Shift+Tab в сессии агента переключает его режим разрешений, а лидеру, который начал писать код сам, достаточно сказать «дождись, пока агенты закончат».

Пока ты смотришь сессию агента, встроенные команды всё равно идут лидеру. Перед /compact, /clear и /rewind Claude Code спросит подтверждение, потому что они сотрут разговор лидера, а не агента. /model и /fast из этого вида не запускаются: модель агента фиксируется при запуске.

Чтобы корректно закрыть агента, попроси лидера: «попроси researcher завершить работу». Агент может согласиться или отказаться с объяснением. Если выйти через /exit, пока агенты ещё числятся в работе, Claude Code предложит остановить их, увести в фон или остаться.

Как работает общий список задач и зависимости между агентами

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

Третий прогон я запустил уже с CLAUDE_CODE_ENABLE_TODO_TOOLS=1 и таким промптом:

«Создай команду из трёх агентов на Sonnet и заведи задачи в общем списке. 1) tests пишет [файл тестов]: [что проверить]. 2) fixer правит [файл с кодом] под эти тесты, задача зависит от первой. 3) docs пишет README.md с примерами запуска, без зависимостей. Каждый правит только свои файлы.»
Лидер Claude Code завёл три задачи: tests и docs запущены, fixer заблокирован задачей номер один; ниже раскрыт список задач по Ctrl+T
Задача fixer ждёт тестов, а tests и docs идут параллельно. Внизу список задач, раскрытый по Ctrl+T. Скриншот: терминал / matveev.tech

Лидер сам расставил зависимость и не запускал fixer, пока tests не закрыл свою задачу. Мне такой вариант нравится больше, чем ручной порядок из второго прогона: зависимость видна в списке, и её не нужно держать в голове. Список задач по Ctrl+T показывает, кто что делает: галочка у готового, квадрат у ждущего, закрашенный квадрат у того, что сейчас в работе.

Для рискованных изменений агенту можно велеть сначала составить план. Порядок тут тоже поменялся: переведи лидера в plan mode через Shift+Tab, и агенты, которых он запустит, начнут в plan mode. Готовый план Claude Code одобряет сам, без ревью лидера. Если хочешь, чтобы план проверил лидер, переключи агента в plan mode вручную уже после запуска.

Правила качества удобнее вынести в хуки. Хук TeammateIdle срабатывает, когда агент собирается остановиться, TaskCreated и TaskCompleted срабатывают при создании и закрытии задачи. Код выхода 2 возвращает агенту обратную связь и не даёт закрыть задачу, например пока тесты красные. Как писать такие хуки, я разбирал в статье про хуки Claude Code.

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

Где Claude Code хранит команду агентов

Команда живёт в двух папках. Конфиг лежит в ~/.claude/teams/{имя-команды}/config.json, общий список задач в ~/.claude/tasks/{имя-команды}/. Имя команды Claude Code собирает сам: session- и первые восемь символов ID сессии. В той же папке команды лежат почтовые ящики, по JSON-файлу на агента: туда пишутся сообщения, пока получатель их не прочитает.

Дерево папки session-abcacf4a: config.json и папка inboxes с ящиками docs, fixer, team-lead и tests; ниже вывод jq со списком участников команды
Папка команды третьего прогона: конфиг и по ящику на агента. В конфиге видно, что все тиммейты на Sonnet. Скриншот: терминал / matveev.tech

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

{
  "agentId": "security@session-ea038854",
  "name": "security",
  "agentType": "general-purpose",
  "model": "sonnet",
  "prompt": "Ты ревьюер по безопасности. … КОД НЕ МЕНЯЙ и не коммить — только читай…",
  "planModeRequired": false,
  "backendType": "tmux"
}

Руками этот файл не правят: Claude Code перезаписывает его при каждом изменении команды. Когда сессия заканчивается, папку команды он удаляет сам, а список задач остаётся на диске на срок из cleanupPeriodDays. Файл вроде .claude/teams/teams.json в проекте ничего не настраивает, Claude прочитает его как обычный файл.

Постоянные роли задаются через определения субагентов. Если в .claude/agents/ лежит, скажем, security-reviewer, попроси: «запусти тиммейта типа security-reviewer для аудита модуля авторизации». К тиммейту применятся tools, model и текст определения, а вот skills не применятся: агент грузит скиллы из проекта и настроек пользователя. CLAUDE.md, MCP-серверы и скиллы проекта каждый тиммейт получает так же, как обычная сессия, поэтому общие правила стоит держать в CLAUDE.md. Историю разговора лидера тиммейт не получает, только промпт запуска.

Сколько токенов тратит команда агентов в Claude Code

Каждый тиммейт это отдельный экземпляр Claude со своим контекстом, поэтому расход растёт примерно пропорционально размеру команды. В документации о стоимости Anthropic оценивает команду в plan mode примерно в 7 раз дороже обычной сессии.

Блок Session в /usage: стоимость сессии 0,52 доллара, 2 минуты 46 секунд API, 135 строк кода, 1,2 млн токенов из кэша на claude-sonnet-5-5
Третий прогон с тремя агентами на Sonnet 5.5 стоил 0,52 доллара по ценам API, почти всё ушло на чтение кэша. Скриншот: Claude Code / matveev.tech

На моём демо-проекте третий прогон, лидер и три агента на Sonnet 5.5, по /usage стоил $0,52 по ценам API. Это 2 минуты 46 секунд работы API, 135 добавленных строк и 1,2 млн токенов, прочитанных из кэша. На подписке эти деньги не списываются, но лимит недели расходуется так же. На реальном проекте с большим CLAUDE.md и десятком MCP-серверов цифра будет кратно выше: каждый агент грузит всё это заново.

Вот что держит расход в рамках:

  • агенты на Sonnet, а Opus только у лидера, если нужна сильная сводка;
  • 3–5 агентов на задачу, по 5–6 задач на агента;
  • короткий промпт запуска, без пересказа того, что уже есть в CLAUDE.md;
  • останавливать агентов, которые закончили: они тратят токены, пока живы.

Есть и неочевидная деталь с кэшем. Запросы тиммейта в режиме in-process кэшируются на 5 минут, даже на подписке. Если агенты подолгу думают между ходами, поставь subagentPromptCacheTtl в 1h: на API запись в часовой кэш дороже, зато кэш не протухает между ходами. Другие способы сэкономить я собрал в статье о том, как экономить токены в Cursor и Claude Code.

Какие ошибки ломают работу команды агентов

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

Пустой список задач на моделях Claude 5. Лидер на Sonnet 5.5 или Opus 5.5 не видит инструментов задач и координирует агентов вручную. Признак: по Ctrl+T пусто, а лидер пишет, что зависимость выразит порядком запуска. Лечится переменной CLAUDE_CODE_ENABLE_TODO_TOOLS=1.

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

Старое значение режима в ~/.claude.json. Claude Code до сих пор читает teammateMode, который туда записали старые версии. У меня там остался auto, и первый прогон внутри tmux открылся панелями, хотя по документации по умолчанию стоит in-process. Проверить можно так: rg teammateMode ~/.claude.json.

Скрытая зависимость между агентами. В третьем прогоне docs писал README параллельно с fixer и описал старое поведение: «бинарный файл роняет сканер». Лидер заметил это только при сводке и отправил docs переделать. Если один агент описывает результат другого, поставь между их задачами зависимость. Если два агента правят один файл, они перезапишут друг друга, поэтому файлы делят заранее.

Сводка лидера: README устарел, потому что docs писал его до правки fixer, лидер попросил docs обновить раздел ограничений
Лидер поймал устаревший README: docs и fixer шли параллельно, хотя docs описывал результат fixer. Скриншот: терминал / matveev.tech

Лидер передаёт отчёт агента без проверки. Во втором прогоне лидер прямо написал, что тесты сам не запускал и передаёт отчёт fixer как есть. Тесты я прогнал руками, 10 из 10 прошли, но так бывает не всегда. Проси лидера в конце запустить проверку самому или повесь хук TaskCompleted.

Права наследуются от лидера. Новый тиммейт стартует в режиме разрешений лидера, включая bypassPermissions от --dangerously-skip-permissions. Задать агенту отдельный режим при запуске нельзя. Запросы разрешений агентов приходят в сессию лидера, поэтому частые операции лучше заранее разрешить в настройках, о них подробнее в статье про разрешения и песочницу в Claude Code.

Claude Code auto mode: AI сам решает, что безопасно
Как работает auto mode, который тиммейты наследуют от лидера, и что он пропускает без вопросов.

/resume не возвращает агентов. После возобновления сессии тиммейтов в режиме in-process уже нет, а лидер может пытаться им писать. Попроси его запустить новых. Остальные ограничения остались с февраля: одна команда на сессию, вложенных команд нет, лидера не поменять, статус задачи иногда отстаёт от реальной работы, а остановка агента ждёт конца его текущего шага.

С чего начать работу с Agent Teams

Начни с ревью, оно у меня сработало лучше всего. Добавь в блок env обе переменные, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS и CLAUDE_CODE_ENABLE_TODO_TOOLS, запусти Claude Code и дай промпт ревью из раздела про первый прогон, подставив свою папку с кодом. Агенты код не меняют, а по сводке лидера сразу видно, какие находки подтвердили двое или трое.

После прогона открой /usage и посмотри, во что обошлась команда. Если цена устраивает, переходи к задачам с правками кода и зависимостями в общем списке, как в третьем прогоне.

Больше гайдов по настройке и фичам в разделе о Claude Code.

Читайте также

CTO говорит

Разбираю релизы моделей и инструментов: что вышло и стоит ли переходить.

Читать в Telegram

Ещё в разделе Claude Code

Весь раздел