Agent Teams в Claude Code: когда одного агента недостаточно

Что: Agent Teams — экспериментальная функция в Claude Code для координации нескольких экземпляров Claude, работающих как команда.

В чём отличие от subagents: Subagents только отчитываются главному агенту. Agent Teams общаются между собой напрямую, ведут дебаты и координируют работу через общий task list.

Когда использовать:

• Параллельный code review (security, performance, tests одновременно)

• Отладка с конкурирующими гипотезами (5 агентов тестируют разные теории)

• Разработка новых модулей (каждый владеет своей частью)

Ограничения: Экспериментальная функция, выключена по умолчанию. Нет возобновления сессий, один тим на сессию, split panes требуют tmux.

Документация: https://code.claude.com/docs/en/agent-teams

Контекст: почему это важно

Признаюсь: я управляю командой из 44 AI-агентов. Это не метафора — у нас в проде реально работает оркестратор с 44 специализированными агентами (bug-hunter, security-scanner, deployment-engineer и так далее).

Основная проблема: один агент упирается в контекстное окно. Даже с 200k токенов при анализе большого проекта контекст заканчивается быстро. Приходится либо сжимать историю (теряем детали), либо запускать subagents (но они только отчитываются обратно, не общаются между собой).

Anthropic решила эту проблему радикально: дать агентам возможность работать как настоящая команда.

Что такое Agent Teams

Agent Teams — это координация нескольких экземпляров Claude Code, работающих вместе. Один агент становится team lead (координатор), остальные — teammates (члены команды).

Архитектура

┌────────────────────────────────────────────────────┐
│                   Team Lead                         │
│  (главный агент, координирует работу)               │
└───────────┬────────────────────────────────────────┘
            │
            │ spawn teammates
            │
    ┌───────┼────────┬─────────┬─────────┐
    │       │        │         │         │
┌───▼───┐ ┌─▼─────┐ ┌─▼─────┐ ┌─▼─────┐ │
│Security│ │Perf   │ │Tests  │ │UX     │ │
│Reviewer│ │Checker│ │Validator│ │Research│ │
└───┬───┘ └─┬─────┘ └─┬─────┘ └─┬─────┘ │
    │       │        │         │         │
    └───────┼────────┴─────────┴─────────┘
            │
            │ mailbox (межагентная связь)
            │
    ┌───────▼────────────────────────────┐
    │       Shared Task List              │
    │  ┌──────────────────────────────┐  │
    │  │ 1. [ ] Review auth module    │  │
    │  │ 2. [x] Check performance     │  │
    │  │ 3. [ ] Validate tests        │  │
    │  └──────────────────────────────┘  │
    └─────────────────────────────────────┘

Компоненты:

Чем это отличается от subagents

Я использую и subagents, и agent teams в проде. Вот сравнение:

Когда что использовать:

// Subagent — для быстрой фокусной работы
if (task === "найти все использования функции X") {
  useSubagent(); // результат вернётся главному агенту
}

// Agent Teams — для сложной коллаборации
if (task === "провести code review с разных углов") {
  useAgentTeams(); // агенты обсуждают находки между собой
}

Use cases: когда это реально полезно

1. Параллельный code review

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

Пример запроса:

Создай команду агентов для ревью PR #142. Запусти трех ревьюеров:
- Один фокусируется на безопасности (SQL injection, XSS, auth)
- Один проверяет производительность (N+1 queries, memory leaks)
- Один валидирует покрытие тестами (unit, integration, edge cases)
Пусть каждый проверит и сообщит о находках.

Что происходит:

1. Team lead создаёт трёх teammates

2. Каждый читает PR и анализирует со своего угла

3. Они общаются между собой: “Я нашёл SQL injection в line 42” → “Я проверил, там нет теста на этот case”

4. Lead синтезирует финальный отчёт с приоритизацией

Результат: 3 независимых взгляда вместо одного последовательного прохода.

2. Отладка с конкурирующими гипотезами

Когда root cause неясен, один агент найдёт одно объяснение и остановится. Agent Teams борются с этим через явный антагонизм.

Реальный кейс:

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

Почему это работает:

• Агент 1 тестирует: “Может, WebSocket не держит соединение?”

• Агент 2 опровергает: “Проверил логи, WebSocket alive. Проблема в event loop.”

• Агент 3: “Нашёл! Unhandled promise rejection в message handler.”

• Агенты 4-5 пытаются воспроизвести и подтверждают гипотезу #3.

Результат: Теория, которая выживает после атак с 5 сторон, скорее всего правильная.

3. Разработка новых модулей

Когда модули независимы, каждый teammate владеет своей частью.

Пример:

Создай команду для добавления системы уведомлений:
- Teammate 1: Email provider (Resend API)
- Teammate 2: SMS provider (Twilio API)
- Teammate 3: Push notifications (Firebase)
- Teammate 4: Notification queue (BullMQ)

Каждый владеет своей папкой в src/notifications/

Критично: Разделите файлы так, чтобы агенты не редактировали один и тот же файл. Иначе будут конфликты.

4. Исследование с разных углов

Когда проектируете новую фичу, разные перспективы помогают.

Пример:

Я проектирую CLI-инструмент для трекинга TODO-комментариев в кодбазе.
Создай команду из 3 агентов:
- Один — на UX (какие команды удобны?)
- Один — на архитектуру (парсинг, индексация, кэширование)
- Один — devil's advocate (почему это плохая идея?)

Результат: После дебатов вы получите сбалансированное решение, а не первую пришедшую в голову идею.

Как это работает: технические детали

Включение Agent Teams

По умолчанию функция выключена. Включите через settings.json:

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

Или через environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

Два режима отображения

1. In-process mode (по умолчанию):

Все агенты в одном терминале. Используйте Shift+Up/Down для переключения между ними.

┌─────────────────────────────────────┐
│  Team Lead (активен)                │
│  > Waiting for teammates...         │
├─────────────────────────────────────┤
│  [Shift+Down]                       │
│  ↓ Security Reviewer                │
│  ↓ Performance Checker              │
│  ↓ Test Validator                   │
└─────────────────────────────────────┘

2. Split panes mode (требуется tmux или iTerm2):

Каждый агент в своей панели. Видите всех одновременно.

┌──────────────┬──────────────┬──────────────┐
│ Team Lead    │ Security     │ Performance  │
│              │ Reviewer     │ Checker      │
│              │              │              │
├──────────────┴──────────────┴──────────────┤
│ Test Validator                             │
│                                            │
└────────────────────────────────────────────┘

Для split panes нужен либо tmux, либо iTerm2 с it2 CLI.

Мой выбор: In-process для быстрых задач, split panes для долгих исследований.

Task list и координация

Задачи хранятся в ~/.claude/tasks/{team-name}/. Агенты могут:

1. Claim задачу (перевести в in_progress)

2. Отчитаться о завершении (completed)

3. Заблокировать задачу зависимостями (blockedBy)

Пример:

{
  "id": "task-1",
  "subject": "Review authentication module",
  "status": "in_progress",
  "owner": "security-reviewer",
  "blockedBy": []
}

Когда teammate завершает задачу, другие задачи с blockedBy: ["task-1"] автоматически разблокируются.

Mailbox: как агенты общаются

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

// Отправить одному агенту
message("security-reviewer", "Проверь line 42 на SQL injection");

// Broadcast всем
broadcast("Я нашёл критическую уязвимость. Приостановите работу.");

Важно: Broadcast дорогой — каждый агент получает копию. Используйте только для критичных сообщений.

Best practices: как правильно использовать

1. Давайте агентам достаточно контекста

Teammates не видят историю lead. Они загружают только:

• CLAUDE.md

• MCP серверы

• Skills

• Spawn prompt от lead

Плохо:

Spawn teammate для ревью аутентификации.

Хорошо:

Spawn teammate с промптом: "Провести security review модуля аутентификации
в src/auth/. Фокус на token handling, session management, input validation.
Приложение использует JWT токены в httpOnly cookies. Сообщи о проблемах
с severity ratings (Critical, High, Medium, Low)."

2. Размеряйте задачи правильно

Совет: 5-6 задач на teammate. Если агенты простаивают, попросите lead разбить работу мельче.

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

Два агента редактируют один файл → перезаписи и потеря изменений.

Плохо:

├── src/
│   ├── auth.ts  ← Security Reviewer редактирует
│   ├── auth.ts  ← Performance Checker редактирует

Хорошо:

├── src/
│   ├── auth/
│   │   ├── security.ts  ← Security Reviewer
│   │   ├── performance.ts  ← Performance Checker
│   │   └── tests.ts  ← Test Validator

4. Начинайте с исследований

Если первый раз используете agent teams, начните с задач без кода:

• Review PR

• Исследование библиотеки

• Отладка без изменений

Так вы поймёте механику без риска конфликтов.

5. Мониторьте и корректируйте

Lead иногда начинает делать работу сам вместо делегирования teammates. Если заметили:

Подожди завершения teammates перед тем, как продолжить.

Delegate mode: когда lead только координирует

По умолчанию lead может сам браться за задачи. Delegate mode запрещает это — только координация.

Когда использовать:

• Большая команда (5+ teammates)

• Комплексная задача с много уровнями зависимостей

• Вы хотите, чтобы lead только управлял, не кодил

Как включить: После создания команды нажмите Shift+Tab для входа в delegate mode.

Ограничения и где НЕ работает

Agent Teams — это экспериментальная функция. Вот что пока не работает:

Когда НЕ использовать agent teams:

• Последовательные задачи с зависимостями

• Редактирование одного файла

• Простые задачи (overhead > польза)

Для таких случаев используйте один агент или subagents.

Shutdown и cleanup

Остановить teammate

Попроси security-reviewer teammate остановиться.

Lead отправит shutdown request. Teammate может принять или отклонить с объяснением.

Cleanup после работы

Почисти команду.

Lead удалит все ресурсы команды. Важно: Сначала остановите всех teammates, иначе cleanup провалится.

Критично: Cleanup всегда запускайте через lead, не через teammate. Иначе контекст может не разрешиться корректно.

Стоимость: сколько это ест токенов

Agent Teams использует значительно больше токенов, чем один агент. Каждый teammate = отдельный экземпляр Claude.

Пример:

• 1 агент с task = 50k токенов (~$0.15)

• 5 агентов в команде = 250k+ токенов (~$0.75)

Важно: Если работаете через Claude.ai с подпиской Claude Pro ($20/мес), лимиты значительно выше, чем через API. Для активного использования Agent Teams подписка реально окупается — можно запускать команды без постоянного контроля за API costs.

Когда оно того стоит:

• Параллельный code review (находят больше проблем)

• Отладка с гипотезами (быстрее к root cause)

• Новые модули (параллелизация разработки)

Когда не стоит:

• Рутинные задачи

• Последовательная работа

• Один файл

См. agent team token costs для подробностей.

Практические советы из моего опыта

1. Pre-approve частые операции

Teammates наследуют permission mode от lead. Если lead запущен с --dangerously-skip-permissions, все teammates тоже.

Совет: Настройте permission settings, чтобы уменьшить количество промптов.

2. Teammates останавливаются на ошибках

Teammate может застопориться после ошибки вместо recovery.

Решение:

• Проверьте вывод через Shift+Up/Down (in-process) или кликните на pane (split)

• Дайте инструкции напрямую или

• Spawn нового teammate для продолжения

3. Lead завершается раньше времени

Lead может решить, что работа закончена, хотя задачи ещё не выполнены.

Решение:

Продолжай работу. Подожди, пока teammates завершат все задачи.

4. Orphaned tmux sessions

Если tmux session остался после завершения команды:

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

Disclaimer: Expected Pushback

Я понимаю, что статья может вызвать критику:

“Это же ещё более дорого, чем обычный Claude!”
Да. Agent Teams жрут токены. Но для code review или отладки это окупается — находят больше проблем за меньшее время.

“Зачем мне это, если можно просто дольше работать с одним агентом?”
Контекстное окно конечно. При анализе большого проекта один агент упирается в 200k токенов. Agent Teams дают параллелизацию + независимые контексты.

“Это экспериментальная функция с кучей ограничений.”
Согласен. Нет resume для in-process, нет вложенных тимов, один тим на сессию. Но для параллельного code review или отладки с гипотезами это уже работает.

Моя позиция: Если у вас простые задачи — используйте один агент или subagents. Agent Teams — для случаев, когда нужна реальная коллаборация с обсуждениями.

Если знаете лучший способ организовать параллельную работу AI-агентов — напишите в комментариях. Я всегда открыт к улучшениям.

Контакты и обратная связь

Telegram

Канал: https://t.me/maslennikovigor
Прямой контакт: https://t.me/maslennikovig

GitHub (orchestrator kit — агенты, скиллы, команды)

Репозиторий: https://github.com/maslennikov-ig/claude-code-orchestrator-kit

Игорь Масленников
Пишу про AI-агентов, LLM-архитектуру и автоматизацию разработки.

Вопрос к читателям: Используете ли вы параллельную работу AI-агентов в своих проектах? Какие кейсы у вас работают, а где получается overhead? Буду рад услышать ваш опыт в комментариях.