# Claude Code Agent Teams: команда агентов от задачи до релиза

> AI Release · @ai_release1 · https://ai-release.org/guides/claude-code-agent-teams-komanda-agentov.html

## TL;DR
- Время выполнения: 60–90 минут на каркас из ролей и конвейера; первый сквозной прогон задачи — 1–2 часа.
- Уровень сложности: Advanced
- Понадобится: Claude Code с доступом к Agent Teams (доступность зависит от тарифа и версии — сверьтесь с документацией), git 2.x, репозиторий проекта, Python 3 с PyYAML для проверки конфига, текстовый редактор.

## Требования и подготовка
![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/claude-code-agent-teams-komanda-agentov-ru-1.jpg?v=1793342552)

- ОС: Linux, macOS или Windows с WSL/PowerShell — командная строка должна поддерживать `git` и запуск Claude Code.
- Claude Code установлен и запускается; Agent Teams включён в вашей конфигурации (точное имя параметра и способ включения сверьте с документацией — в источнике функция упоминается без флагов).
- Git-репозиторий с хотя бы одним коммитом: `git log --oneline -1` должен что-то вывести.
- Python 3 и PyYAML: `python -c "import yaml; print(yaml.__version__)"` — нужен для валидации конвейера.
- Права на создание веток и тегов в репозитории.
- Политика доступа агентов к файлам и секретам описана заранее: агенты читают репозиторий, поэтому перед запуском пройдите чек-лист из гайда [Безопасность ИИ-агентов: как защитить данные и избежать утечек](https://ai-release.org/guides/bezopasnost-ii-agentov-kak-zaschitit-dannye-i-izbezhat.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

Agent Teams — режим Claude Code, в котором над задачей работает несколько агентов с закреплёнными ролями. В источнике описана практика Сергея Ладыгина: 12 ролей, 44 релиза за полгода, 8 версий моделей без переписывания ролей.

## Шаг 1. Зафиксируйте контракт роли и создайте 12 файлов ролей
**Что сделать:** завести каталог `.agents/roles`, шаблон контракта и 12 файлов ролей. Контракт роли — это описание «что на входе, что на выходе, по какому критерию работу принимают».

**Зачем:** роль без контракта нельзя ни проверить, ни передать другому агенту. Именно контракт, не содержащий имени модели, позволяет менять модель, не переписывая роли.

**Пример:** шаблон роли с четырьмя обязательными блоками.

```bash
mkdir -p .agents/roles .agents/out
cat > .agents/_role-template.md <<'EOF'
# Роль: <название>
## Вход
- Задача: <ID задачи и ссылка>
- Контекст: <какие файлы и спеки читать>
## Выход
- Артефакт: <патч / design.md / review.md / release.md>
- Путь: .agents/out/<ID задачи>/
## Критерий приёмки
- [ ] <проверяемый критерий, например: тесты проходят>
- [ ] <проверяемый критерий, например: нет изменений вне разрешённых путей>
## Запрещено
- Менять файлы вне <разрешённый путь>
- Указывать в этом файле имя или версию модели
EOF
for i in $(seq -w 1 12); do cp .agents/_role-template.md ".agents/roles/$i.md"; done
```

**Как проверить:** считайте файлы и убедитесь, что шаблон лежит отдельно.

```bash
ls -1 .agents/roles | wc -l
```

Ожидаемый вывод: `12`. Если вывелось `13`, шаблон попал в каталог ролей — перенесите его в `.agents/`.

## Шаг 2. Соберите конвейер «задача → релиз» с гейтами
![Иллюстрация к разделу «Шаг 2. Соберите конвейер задача → релиз с гейтами»](https://ai-release.org/guides/img/claude-code-agent-teams-komanda-agentov-ru-2.jpg?v=1793342560)

**Что сделать:** описать этапы в `.agents/pipeline.yaml`. Гейт — обязательная проверка, без которой этап не передаётся дальше. Распределение 12 ролей по этапам:

| Этап | Ролей | Артефакт | Гейт |
|---|---|---|---|
| intake (постановка) | 2 | `task.md` | есть критерий приёмки и список затронутых файлов |
| design (проектирование) | 2 | `design.md` | решение описано, риски перечислены |
| build (реализация) | 4 | патч | сборка проходит, тесты зелёные |
| verify (проверка) | 2 | `review.md` | нет замечаний уровня blocker |
| release (релиз) | 2 | `release.md` | CHANGELOG обновлён, тег поставлен |

**Зачем:** таблица превращает «команду агентов» в конвейер с точками контроля: на каждом этапе видно, кто отдал артефакт и чем он подтверждён.

**Пример:** конфиг конвейера.

```yaml
# .agents/pipeline.yaml — шаблон. Способ подключения Agent Teams
# и имена полей сверьте с документацией Claude Code для вашей версии.
version: 1
roles_dir: .agents/roles
artifacts_dir: .agents/out
stages:
  - id: intake
    roles: ["01", "02"]
    output: "task.md"
    gate: "есть критерий приёмки и список затронутых файлов"
  - id: design
    roles: ["03", "04"]
    output: "design.md"
    gate: "решение описано, риски перечислены"
  - id: build
    roles: ["05", "06", "07", "08"]
    output: "patch"
    gate: "сборка проходит, тесты зелёные"
  - id: verify
    roles: ["09", "10"]
    output: "review.md"
    gate: "нет замечаний уровня blocker"
  - id: release
    roles: ["11", "12"]
    output: "release.md"
    gate: "CHANGELOG обновлён, тег поставлен"
```

**Как проверить:** валидируйте YAML и создайте ветку под задачу.

```bash
python -c "import yaml; yaml.safe_load(open('.agents/pipeline.yaml')); print('OK')"
git switch -c task/TASK-14
git branch --show-current
```

Ожидаемый вывод: `OK`, затем `task/TASK-14`. Отдельная ветка на задачу нужна, чтобы изменения одного прогона не смешивались с другими.

**Пример постановки для агента** (запустите Claude Code и передайте текст):

```text
Прочитай .agents/pipeline.yaml и .agents/roles/01.md, .agents/roles/02.md.
Выполни этап intake для задачи TASK-14: <описание задачи>.
Результат запиши в .agents/out/TASK-14/task.md.
Не меняй файлы вне .agents/out/TASK-14/.
```

Ограничение путей в промпте и в блоке «Запрещено» работает потому, что агент получает явную границу зоны правок, а вы проверяете её через `git status`.

## Шаг 3. Прогоните релиз и проверьте приёмку
![Иллюстрация к разделу «Шаг 3. Прогоните релиз и проверьте приёмку»](https://ai-release.org/guides/img/claude-code-agent-teams-komanda-agentov-ru-3.jpg?v=1793342569)

**Что сделать:** пройти этапы до `release`, поставить тег и проверить, что роли не привязаны к модели.

**Зачем:** тег фиксирует результат прогона, а проверка на упоминания модели подтверждает, что смена модели не потребует переписывания 12 файлов ролей.

**Как проверить:** выполните три команды.

```bash
git status --short
git tag -a v0.1.0 -m "первый сквозной прогон"
git tag --list 'v*' | wc -l
grep -rni 'model' .agents/roles || echo "OK: роли не зависят от модели"
```

Ожидаемый результат: `git status` показывает только файлы внутри `.agents/out/TASK-14/`, счётчик тегов выводит `1`, grep печатает `OK: роли не зависят от модели`.

Чек-лист приёмки релиза:

- [ ] артефакты всех пяти этапов лежат в `.agents/out/TASK-14/`
- [ ] в `review.md` нет замечаний уровня blocker
- [ ] `CHANGELOG` обновлён
- [ ] тег создан и запушен: `git push origin v0.1.0`
- [ ] роли не содержат имени модели

Ориентир по темпу из источника: 44 релиза за полгода — это примерно 1,7 релиза в неделю (44 / 26 недель). Если у вас больше одного релиза в неделю, конвейер и гейты настроены сопоставимо. Публикацию сборки в сторы вынесите отдельным шагом по гайду [Как автоматизировать публикацию приложений в App Store и Google Play с помощью ИИ-агентов](https://ai-release.org/guides/kak-avtomatizirovat-publikatsiyu-prilozheniy-v-app-stor.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## Возможные проблемы и решения

**Проблема. Claude Code не запускается из терминала**
- Ошибка: `claude: command not found`
- Причина: CLI установлен, но его каталог не в `PATH`, либо установка не завершилась.
- Решение: проверьте `echo $PATH` (Windows: `echo %PATH%`), найдите бинарник `where claude` / `which claude` и добавьте его каталог в `PATH`. Команду установки для вашей ОС сверьте с документацией.

**Проблема. Агент сделал коммит, но ветка не уходит в удалённый репозиторий**
- Ошибка: `fatal: The current branch task/TASK-14 has no upstream branch`
- Причина: ветка создана локально через `git switch -c`, upstream не задан.
- Решение: `git push -u origin task/TASK-14`. Флаг `-u` связывает локальную ветку с удалённой один раз, дальше достаточно `git push`.

**Проблема. Два агента правили один файл, слияние остановилось**
- Ошибка: `CONFLICT (content): Merge conflict in src/app.py`
- Причина: зоны правок ролей пересеклись — границы в блоке «Запрещено» заданы слишком широко.
- Решение: посмотрите конфликтующие файлы `git diff --name-only --diff-filter=U`, разведите роли по разным путям в файлах `.agents/roles/*.md`, затем разрешите конфликт (`git checkout --ours <файл>` или `git checkout --theirs <файл>`), выполните `git add <файл>` и `git merge --continue`.

## Резюме и следующие шаги
Каркас готов, когда в `.agents/roles` лежат 12 контрактов, `.agents/pipeline.yaml` проходит валидацию, а первый прогон закрыт тегом `v0.1.0`. Дальше добавляйте по одной задаче за прогон и расширяйте гейты по мере роста числа релизов.

## FAQ
**Что такое Agent Teams в Claude Code?**
Режим, в котором задачу ведёт несколько агентов с закреплёнными ролями; в источнике описана конфигурация из 12 ролей, доведённая до 44 релизов.

**Можно ли вести разработку без команды людей?**
В источнике разработчик полгода ведёт сервис один: код пишут агенты, человек ставит задачи и принимает результат.

**Сколько ролей нужно на старте?**
Ориентир из источника — 12 ролей. Начинайте с минимального набора: роль добавляется, когда у неё появляется отдельный артефакт и отдельная проверка.

**Как менять модель, не переписывая роли?**
Не указывать имя модели в файлах ролей и проверять это командой `grep -rni 'model' .agents/roles`. Какую модель выбрать под задачу, смотрите в [сравнении ИИ-ассистентов](https://ai-release.org/guides/sravnenie-ii-assistentov.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).