Setup Agent Team

---
name: setup-agent-team
description: Assemble an AI agent team in the current project - pick the roles, copy the templates into .claude/agents/, adapt them to the project stack and verify the result. Use when asked to set up an agent team, add a role to an existing team, or deploy the agents-best-teams methodology in a project.
---

# Сборка команды агентов под проект

Твоя задача — довести проект от «шаблонов в репозитории методологии» до «рабочих ролей в `.claude/agents/`, адаптированных под этот стек».

Шаблоны лежат в `${CLAUDE_PLUGIN_ROOT}/templates/`. Если методология установлена копированием, а не плагином, — в `templates/` репозитория.

---

## Шаг 1. Пойми проект

Прежде чем что-то предлагать, прочитай проект и определи:

- язык и фреймворк бэкенда, фронтенда;
- ORM и базу данных;
- как запускаются тесты;
- порты dev-серверов;
- есть ли мультиязычность, есть ли E2E-тесты.

Источники: `package.json`, `pyproject.toml`, `go.mod`, `composer.json`, `docker-compose.yml`, `Makefile`, README проекта.

### Если проект новый и читать нечего

В пустом проекте стек не из чего вывести — его нужно **решить и записать**, а не угадать. Спроси у пользователя недостающее и зафиксируй ответы в README, прежде чем идти дальше:

- язык и рантайм бэкенда, фронтенда;
- база данных и способ работы с ней;
- чем запускаются тесты;
- нужны ли локали и E2E;
- порты.

Не подставляй значения по умолчанию молча. Состав команды выводится из стека: решив за пользователя, что тут React и PostgreSQL, ты поставишь роли, которые проекту не нужны, и не поставишь те, что нужны.

### Заодно определи язык

Методология написана по-русски, но человеку она может быть нужна на другом языке. От этого зависят две вещи: на каком языке говорят защитные хуки и на каком будут написаны роли.

Определи язык по тому, как пользователь пишет тебе. Не угадывай молча — назови, что выбрал, и дай поправить одной фразой.

Запиши выбор в `.claude/.abt-lang` одним словом (`ru` или `en`) — этот файл читают хуки:

```bash
mkdir -p .claude && printf 'ru\n' > .claude/.abt-lang
```

Без файла хуки говорят по-английски: это умолчание, а не поломка. Переменная окружения `ABT_LANG` перекрывает файл, если она задана.

**Проверка шага:** ты можешь назвать стек проекта конкретно, а не «веб-приложение», в проекте есть файл, где этот стек записан, и создан `.claude/.abt-lang`.

---

## Шаг 2. Предложи состав команды

Не ставь все роли по умолчанию — это тот самый оверхед, против которого методология и написана.

Минимальный работающий состав: **один dev-агент под основной стек, `qa-tester`, `code-reviewer`**. Остальное добавляется, когда появляется нужда.

Соотнеси роли со стеком:

| Роль | Ставить, если |
|---|---|
| `dev-backend`, `dev-frontend` | есть соответствующая часть проекта |
| `dev-database` | есть миграции и нетривиальная схема |
| `qa-tester` | есть тесты или их надо завести |
| `code-reviewer` | всегда |
| `security-reviewer` | есть аутентификация, приём внешних данных или работа с деньгами |
| `investigator` | проект больше двух зон — баги начнут попадать между ними |
| `design-reviewer` | есть пользовательский интерфейс |
| `scope-challenger` | задачи приходят крупными и формулируются решением, а не проблемой |
| `pm-orchestrator` | ролей больше трёх |
| `browser-tester` | есть UI и настроен Playwright MCP |
| `devops` | есть релизный процесс |
| `docs-writer` | документация поддерживается всерьёз |
| `i18n-keeper` | есть локали |
| `local-sysops` | несколько локальных сервисов и портов |
| `finops-engineer` | есть облако, платные API или заметный счёт за инфраструктуру |
| `unit-economics-analyst` | продукт зарабатывает: есть тарифы, лимиты, платные планы |
| `investment-analyst` | есть внешняя отчётность — инвесторам или совету |
| `vendor-auditor` | много зависимостей и подписок, или продукт распространяется наружу |

Четыре последние роли — финансовые, и по умолчанию они не нужны. Ставь их, когда деньги в проекте кто-то реально считает: роль, чьи расчёты никто не читает, — это оверхед в чистом виде.

Покажи предложенный состав пользователю и дождись подтверждения. Состав команды — его решение, не твоё.

**Проверка шага:** пользователь подтвердил список ролей.

---

## Шаг 3. Скопируй и адаптируй

Скопируй выбранные шаблоны в `.claude/agents/` проекта. Затем открой каждый и адаптируй.

> **Не можешь прочитать шаблоны — остановись.** Каталог `templates/` лежит вне проекта, и доступ к нему может быть не выдан. Тогда единственный правильный ход — сказать об этом и назвать, что нужно: доступ на чтение к репозиторию методологии.
>
> **Роли по памяти не пишутся.** Написанное по памяти выглядит канонической ролью, ею не являясь, и разойдётся с оригиналом в тех местах, которые никто не станет перепроверять, — ровно то, ради чего вся конструкция с одной канонической копией и затевалась.
>
> Отдельно: запись в `.claude/` Claude Code подтверждает отдельно от обычных правок. Нет разрешения — не считай это провалом: покажи готовые файлы и команду, которой пользователь положит их сам.

**Если язык из шага 1 не русский — переведи роль при копировании.** В шапке переведённой роли поставь строку вида `<!-- переведено с templates/dev-backend.md; канон там -->`: если формулировка вызовет сомнение, будет куда посмотреть.

Что переводится, а что нет:

| Переводить | Оставить как есть |
|---|---|
| Текст роли целиком | `name`, `tools`, `model`, `permissionMode`, `maxTurns`, `effort`, `memory`, `color` |
| `description` во frontmatter | Пути, команды, имена файлов и полей |

`description` — проза, а не машинное поле: по нему роль находят и маршрутизируют. Русское описание в английской роли работает хуже, чем переведённое.

Перевод делается здесь, а не в репозитории, намеренно. В репозитории лежит одна каноническая копия, второй копии не существует — значит, ей нечему расходиться с оригиналом. Цена этого решения: перевод может исказить формулировку инварианта, поэтому раздел «Неприкосновенные инварианты» после перевода перечитай отдельно и сверь с кодом.

**Заменять нужно установочные плейсхолдеры:**

| Плейсхолдер | Чем заменить |
|---|---|
| `<your-project>` | название проекта |
| `<backend-framework>`, `<frontend-framework>` | реальные фреймворки |
| `<порт>`, `<ваш-бэк-порт>`, `<ваш-фронт-порт>` | реальные порты |
| `<пути бэкенда>`, `<пути фронтенда>`, `<пути тестов>` и прочие `<пути ...>` | реальные каталоги проекта. Это колонка «владеет файлами» в маршрутизации оркестратора, то есть сама граница зон: незаполненная, она обнуляет изоляцию, но выглядит настроенной |
| `<каталог-e2e>` | где в проекте лежат браузерные тесты: `e2e/` в корне или `tests/e2e/`. Это же значение определяет зону записи роли в хуке: если каталог называется не `e2e`, добавь его в `.claude/agents-best-teams.json` ключом `browser_tester_write_segments` |
| `<ваш>`, `<ваша>`, `<ваши>` | выбор из списка рядом |
| `<reasoning-LLM>`, `<мощный reasoning-LLM>`, `<мощный LLM>`, `<быстрый LLM>` | значение поля `model` |
| `<your-agent-dir>` | каталог агентов платформы |

В строках вида `Python 3.10+ / Node.js / Go / <ваш>` нужно **оставить один вариант** и удалить остальные вместе с плейсхолдером, а не дописывать значение рядом.

**Не трогать то, что заполняется по ходу работы.** В шаблонах есть разметка отчётов и рецептов — `<что сделать>`, `<step>`, `<вердикт>`, `<описание>`, `<PORT>` в командах вида `lsof -ti :<PORT>`. Это не плейсхолдеры установки, а места, которые агент заполняет во время задачи. Замена их сломает шаблон.

Различай по правилу: если значение одинаково для всех задач проекта — заменяй; если меняется от задачи к задаче — оставь.

**Есть плейсхолдеры без угловых скобок, и они опаснее.** Раздел «Неприкосновенные инварианты» в dev-ролях — это текст «Опиши здесь инварианты своего проекта. Примеры типичных:» и список примеров из типового стека: Alembic, централизованные guards, версионный префикс. Ни один grep по скобкам их не поймает.

Оставить этот раздел как есть — худший исход из трёх возможных. Пустой раздел просто бесполезен, а этот **активно врёт**: роль в проекте без ORM читает требование гонять схему через миграции и будет его выполнять.

Что делать:

1. **Выясни настоящие инварианты** — из кода, а не из головы: формат тела запроса и общий префикс у существующих эндпоинтов, единый формат ошибки, способ менять схему БД, где лежит проверка прав. Это то, что уже соблюдается в проекте; ты записываешь наблюдение, а не вводишь правило.
2. **Удали примеры, которых в проекте нет.** Нет миграций — нет подраздела про миграции.
3. **Если инвариант неочевиден из кода — спроси**, не угадывай. Инвариант, придуманный при установке, роль будет защищать наравне с настоящими.

**Файл настроек защиты — если проект не укладывается в умолчания.** Хук знает роли методологии и обычные раскладки тестов. Если E2E лежат не в `e2e/`, юнит-тесты называются иначе (`integration/`, `*.it.ts`) или ты добавил свою роль с полем `memory`, запиши это в `.claude/agents-best-teams.json`. Ключи и пример — `${CLAUDE_PLUGIN_ROOT}/hooks/README.md`, раздел «Файл настроек проекта». Запись в этот файл Claude Code покажет окном подтверждения, и это ожидаемо: файл расширяет зоны, решать должен человек. Для своей роли с памятью запись обязательна — без неё поле `memory` выдаст роли Write и Edit в обход её списка инструментов.

**Проверка шага:**

```bash
grep -rEn '<your-[a-z-]+>|<ваш[а-и]?>|<ваш-[а-яa-z-]+>|<backend-framework>|<frontend-framework>|<порт>|<reasoning-LLM[^>]*>|<быстрый[^>]*>|<мощный[^>]*>|<каталог-e2e>|<пути [^>]*>|<[^>]*reasoning[^>]*>|<[^>]*LLM[^>]*>' .claude/agents/
grep -rn 'Опиши здесь\|Примеры типичных\|Укажи здесь' .claude/agents/
```

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

---

## Шаг 4. Сведи роли друг с другом

Шаблоны написаны как самостоятельные, но команда работает только если роли согласованы:

1. В `pm-orchestrator` приведи таблицу маршрутизации к тем ролям, которые реально поставлены. Ссылки на отсутствующие роли — источник тупиков, а отсутствие поставленной роли означает, что её не позовут никогда.
2. Заполни в этой таблице колонку «владеет файлами» реальными путями проекта. Это и есть граница зон: пока у части проекта нет ровно одного хозяина, роли будут наступать друг на друга, сколько бы ни было написано в их промптах.
3. Проверь, что зоны не пересекаются и не оставляют дыр: каждый каталог с кодом упомянут ровно один раз.
4. Проговори, что **владение файлом не делится по содержимому**. Проза внутри чужого файла — `description` в `package.json`, комментарии в коде, тексты в конфигурации — остаётся зоной владельца файла. Иначе у файла появляется второй хозяин, и правило про «ровно один раз» превращается в «кроме прозы». Найденное несоответствие передаётся владельцу, а не правится на месте.
5. Сверь набор инструментов каждой роли с матрицей разрешений — скилл `permission-checklist`.

**Проверка шага** — глазами этот шаг не проверяется, поэтому командой (bash). Она предполагает установленного `pm-orchestrator`: на минимальном составе из трёх ролей его нет, и весь шаг 4 к такой команде не относится — маршрутизировать некому. Запустишь всё равно — `grep` пожалуется на отсутствующий файл, а `comm` перечислит все роли, и это будет выглядеть как «их не позовут никогда»:

```bash
comm -3 \
  <(ls .claude/agents/*.md | xargs -n1 basename | sed 's/\.md$//' | grep -v '^pm-orchestrator$' | sort) \
  <(grep -o '^| `[a-z0-9-]*`' .claude/agents/pm-orchestrator.md | tr -d '|` ' | sort)
```

Должно вернуть пусто. Слева окажутся роли, которых нет в маршрутизации, — их не позовут никогда; справа — те, что есть в таблице, но не поставлены: тупик при попытке делегировать.

**Этот шаг забывают чаще всех остальных**, и особенно когда роль добавляют к уже собранной команде: скопировать файл в `.claude/agents/` быстро и выглядит законченным действием. Роль после этого существует, отвечает на прямой вызов и при этом невидима для оркестратора — то есть в обычной работе не участвует вовсе.

---

## Шаг 5. Расскажи, что осталось

Сообщи пользователю, что сделано, и назови оставшиеся шаги, не выполняя их без спроса:

- **Защитные хуки.** Если методология поставлена плагином — уже работают. Если копированием — нужно скопировать `hooks/*.py` целиком и подключить конфигурацию. Именно все файлы: конфигурация ссылается на шесть хуков, а `messages.py` нужен каждому из них.
- **Шлюз ревью включился сам**, потому что в команде есть `code-reviewer`: коммит кода без его одобрения откроет окно подтверждения. Предупреди об этом, чтобы первое окно не стало сюрпризом. Как одобрение попадает в шлюз — шаблон `code-reviewer`, раздел «Одобрение для шлюза коммитов».
- **Stop-хук `verify.py`** не даёт закончить работу с падающими тестами. Подключён всегда, а включается записью с командой тестов в файле пользователя `~/.claude/agents-best-teams/verify.json`, ключ — путь к проекту (`hooks/README.md`, раздел «Stop-хук»). Тесты уже есть — предложи включить сейчас. Тестов ещё нет — скажи, что хук понадобится, когда они появятся: напоминание об этом придёт само в начале сессии.
- **`agents.config`** — нужен для триангулированного ревью внешними моделями. Для Tier 1 не требуется; для Tier 2 требуется в подклассе security, RBAC, API-контракт и миграции — там второе независимое мнение обязательно, см. `principles/05-triangulated-review.md`.
- **Персональная память ролей** появится сама при первой работе агентов.

Финальный отчёт — короткий: какие роли поставлены, что адаптировано, что осталось за пользователем.