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

Твоя задача — довести проект от «шаблонов в репозитории методологии» до «рабочих ролей в .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) — этот файл читают хуки:

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

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

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

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

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

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

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

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

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

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

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

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

Не можешь прочитать шаблоны — остановись. Каталог templates/ лежит вне проекта, и доступ к нему может быть не выдан. Тогда единственный правильный ход — сказать об этом и назвать, что нужно: доступ на чтение к репозиторию методологии.

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

Отдельно: запись в .claude/ Claude Code подтверждает отдельно от обычных правок. Нет разрешения — не считай это провалом: покажи готовые файлы и команду, которой пользователь положит их сам.

Дальше — по файлу ${CLAUDE_PLUGIN_ROOT}/skills/setup-agent-team/references/adapt-roles.md. Прочитай его перед адаптацией и пройди по каждой роли. Не прочитал — не адаптируй по памяти, по той же причине, что и с шаблонами. В нём:

• перевод, если язык из шага 1 не русский: текст и description переводятся, поля frontmatter, пути и команды — нет;
• плейсхолдеры установки и чем их заменить: <your-project>, фреймворки, порты, <пути ...> — это граница зон, <каталог-e2e>, модели. Разметку, которую агент заполняет во время задачи, — <что сделать>, <PORT>, — не трогать;
• «Неприкосновенные инварианты» — плейсхолдер без скобок, опаснее всех: примеры из чужого стека активно врут. Инварианты выясняются из кода, лишние примеры удаляются, неочевидное — спросить;
• файл настроек защиты .claude/agents-best-teams.json для нестандартных раскладок и своих ролей с памятью;
• команды проверки шага — они обязательны.

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

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

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

Проверка шага — командами из ${CLAUDE_PLUGIN_ROOT}/skills/setup-agent-team/references/link-roles.md плюс глазами: командой ловятся роли вне маршрутизации и каталоги без хозяина, пересечения зон — только глазами по таблице. Первая находит роли, которых нет в маршрутизации, и строки маршрутизации без роли; вторая — каталоги с кодом без хозяина. Обе предполагают установленного pm-orchestrator: на минимальном составе из трёх ролей шаг 4 не нужен.

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

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

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

• Защитные хуки. Если методология поставлена плагином — уже работают. Если копированием — нужно скопировать hooks/*.py целиком и подключить конфигурацию, а на macOS и Linux заменить в ней python на python3. Именно все файлы: конфигурация ссылается на девять скриптов, а messages.py нужен каждому из них.
• Шлюз ревью можно включить пустым файлом .claude/.review-gate: тогда коммит кода без одобрения code-reviewer откроет окно подтверждения. По умолчанию он выключен — предложи, но не включай без согласия: окно появляется на каждом коммите без ревью. Как одобрение попадает в шлюз — шаблон code-reviewer, раздел «Одобрение для шлюза коммитов».
• Stop-хук verify.py не даёт закончить работу с падающими тестами. Подключён всегда, но молчит, пока для проекта нет команды тестов в файле пользователя ~/.claude/agents-best-teams/verify.json. Напоминаний о нём в сессиях нет — включают его здесь, при настройке, когда пользователь рядом. Если в проекте есть тесты, спроси одним вопросом, включить ли проверку, и предложи команду тестов — ту, которой проект запускает тесты (README, package.json, pyproject.toml). Быструю: она идёт на каждом завершении ответа. Согласился — допиши в файл запись {"<путь к проекту>": "<команда>"}, сохранив чужие записи; Claude Code покажет окно подтверждения, это ожидаемо. В режиме bypassPermissions хук запись отклонит — тогда дай пользователю путь к файлу и готовую строку, сам не обходи. Тестов нет или пользователь отказался — не включай и больше не предлагай.
• agents.config — нужен для триангулированного ревью внешними моделями. Для Tier 1 не требуется; для Tier 2 требуется в подклассе security, RBAC, API-контракт и миграции — там второе независимое мнение обязательно, см. principles/05-triangulated-review.md.
• Персональная память ролей появится сама при первой работе агентов.

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