Image description

Agent Teams в Claude Code: полная структура настройки

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

1. Включение фичи (env переменная)

# /etc/environment (системный уровень, для всех сессий)
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Без этой переменной TeamCreate и SendMessage недоступны.

Проверить: printenv | grep AGENT_TEAMS.

2. Файлы агентов: `~/.claude/agents/.md`

Каждый агент — отдельный .md файл с YAML frontmatter. Frontmatter определяет имя, модель, цвет и доступные инструменты.

Структура файла:

---
name: researcher          # ← subagent_type при вызове Agent tool
model: claude-sonnet-4-6  # ← ИГНОРИРУЕТСЯ в Agent Teams (баг Claude Code)
color: cyan               # ← цвет в UI: cyan/green/yellow/red/blue/magenta
allowedTools:
  - Read
  - Grep
  - Glob
  - Bash
# MCP инструменты — перечислять явно, иначе агент зависнет на permission request
  - mcp__tidewave__project_eval
disallowedTools:
  - Edit
  - Write
---

# [Имя] Agent

[Описание роли и инструкции...]

Критично: model: в frontmatter не работает для Team агентов. Все агенты запускаются на модели текущей сессии (Opus). Это известный баг Claude Code.

3. Наши 4 агента

Файл	Цвет	Роль	Write?	MCP
`researcher.md`	cyan	Исследование кодовой базы	❌	Tidewave + OpenMemory
`implementer.md`	green	Написание кода	✅	Tidewave + OpenMemory
`reviewer.md`	yellow	Spec + Quality review (два этапа в одном)	❌	Tidewave + OpenMemory
`elixir-debugger.md`	magenta	Диагностика в live app	❌	Tidewave + OpenMemory

4. Инструкции в `CLAUDE.local.md`

Минимальный набор, который нужно добавить:

## Agent Teams (MANDATORY)

`CLAUDE_CODE_EXPERIMENTAL_AGENTS=1` включён. Агенты общаются через `SendMessage`.

**ПЕРЕД ЛЮБОЙ РАБОТОЙ:**
1. Прочитай `memory/agent-teams.md` (паттерны оркестрации)
2. Используй `TeamCreate` для создания команды
3. Запускай агентов через `Agent` с параметрами `team_name` + `name`

**НИКОГДА:**
- Не использовать plain `Agent` без `team_name` — создаёт анонимных субагентов
- Не изобретать имена агентов — только 4 предопределённых из `~/.claude/agents/`
- Не использовать `subagent_type: "general-purpose"`

**4 агента:**
- `researcher` (cyan) — исследование кода, read-only
- `implementer` (green) — реализация, full access
- `reviewer` (yellow) — проверка spec + качества, read-only
- `elixir-debugger` (magenta) — live диагностика, read-only

**Порядок review:** reviewer ВСЕГДА после implementer.

**Permission requests:** агенты шлют запросы ТЕБЕ (team lead). Одобряй в UI — иначе агент зависнет.

5. Как использовать (паттерн вызова)

# 1. Создать команду
TeamCreate(team_name: "feature-auth", description: "Implement auth feature")

# 2. Запустить researcher
Agent(
  team_name: "feature-auth",
  name: "researcher",
  subagent_type: "researcher",
  prompt: "Research auth patterns in codebase.
           Teammates: implementer (will implement), reviewer (will review).
           When done: SendMessage to team-lead with findings."
)

# 3. После research — запустить implementer
Agent(
  team_name: "feature-auth",
  name: "implementer",
  subagent_type: "implementer",
  prompt: "Implement X based on [findings].
           When done: SendMessage to `reviewer` with report."
)

# 4. reviewer слушает SendMessage от implementer, делает review
Agent(
  team_name: "feature-auth",
  name: "reviewer",
  subagent_type: "reviewer",
  prompt: "Wait for implementer's report. Review spec + quality.
           If FAIL: SendMessage to `implementer` with issues.
           If PASS: SendMessage to team-lead with verdict."
)

6. Ключевые ограничения (известные баги)

Проблема	Поведение	Обходной путь
`model:` в frontmatter	Игнорируется — все агенты на Opus	Вручную `/model sonnet` в TMUX
Permission request от агента	Агент зависает, оркестратор не может одобрить программно	Одобрять вручную в UI (кнопка `y`)
MCP не наследуется	Каждый агент видит только инструменты из `allowedTools`	Заранее добавить все MCP инструменты в `allowedTools`

7. Чеклист для нового контейнера

[ ] CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 в /etc/environment
[ ] ~/.claude/agents/ — 4 файла агентов скопированы
[ ] CLAUDE.local.md — раздел “Agent Teams” добавлен
[ ] memory/agent-teams.md — файл с паттернами оркестрации
[ ] MCP инструменты в allowedTools каждого агента соответствуют доступным MCP серверам проекта