# 04. Роли агентов **Назначение:** описать каждого агента — его зону ответственности, входы, выходы, инструменты MCP, выбор LLM, что он **обязан** делать и чего **не имеет права** делать. --- ## Простым языком Каждый агент — узкий специалист. Аналитик никогда не пишет код. Разработчик никогда не правит ТЗ. Ревьюер никогда не сам себе одобряет PR. Это сделано не из бюрократии, а потому что так получается дешевле и качественнее: каждый агент имеет минимальный, точный набор инструментов и контекста, и его легко проверить. Аналогия: на типографии нет одного человека, который и верстает, и красит, и ОТК делает. Каждая операция — отдельный участок с собственным мастером и своим набором инструментов. Семь агентов: 1. **Analyst** — читает запрос, пишет ТЗ. 2. **Architect** — решает «как впишется в систему», пишет ADR. 3. **Designer** — макеты UI/UX (если фича UI-овая). 4. **Developer** — пишет код и unit-тесты. 5. **Reviewer** — проверяет код. 6. **Tester** — запускает все тесты, включая UI. 7. **Deployer** — деплоит и убеждается, что не сломалось. Плюс **Orchestrator** — это не LLM, а скрипт-диспетчер, который слушает Plane и Git и запускает нужного агента в нужный момент. --- ## Общая таблица ролей | Агент | LLM | Когда срабатывает | Главный артефакт | Запрещено | |-------|-----|------------------|-----------------|-----------| | Analyst | Sonnet 4.6 / Qwen 3.6+ | Подзадача «Анализ» в `pending` | BRD, ТЗ, AC, Test Plan | трогать код, файлы архитектуры | | Architect | Opus 4.7 | QG-1 зелёный | ADR, обновление C4 | трогать код, ТЗ, дизайн | | Designer | Opus 4.7 + Figma MCP | QG-2 зелёный, `ui_affected: true` | mockups, states, a11y | трогать код, ТЗ, ADR | | Developer | Sonnet 4.6 / GLM-5.1 | QG-3 зелёный (или QG-2 если без UI) | код + тесты + миграции + PR | трогать ТЗ, ADR, дизайн | | Reviewer | Opus 4.7 | QG-4 зелёный | review report + комментарии в PR | писать код, мержить, апрувить свой PR | | Tester | Sonnet 4.6 / Qwen 3.6+ | QG-5 зелёный | test report + отчёт о багах | писать продакшн-код | | Deployer | Sonnet 4.6 | QG-6 зелёный | deploy log + tag | трогать код, тесты | | Orchestrator | n/a (скрипт) | webhook'и Plane/Git | смены статусов, запуск агентов | принимать содержательные решения | --- ## 1. Agent: Analyst **Имя в Openclaw:** `analyst` **LLM:** Sonnet 4.6 (по умолчанию). Альтернатива для удешевления: Qwen 3.6+. **Цена/задача (порядок):** $0.30–1.50. ### Зона ответственности - Понять, что хочет заказчик. - Превратить расплывчатое описание в формальные документы: BRD, ТЗ, Acceptance Criteria, Test Plan. - Активно задавать уточняющие вопросы — лучше переспросить, чем угадать. - Проверить на конфликты с другими активными задачами. ### Вход - `docs/work-items//00-business-request.md` - `CLAUDE.md` проекта - `docs/architecture/README.md` - `docs/work-items/` — список других активных задач (через `find` + frontmatter status) ### Выход - `docs/work-items//01-brd.md` - `docs/work-items//02-trz.md` - `docs/work-items//03-acceptance-criteria.md` - `docs/work-items//04-test-plan.yaml` - (опционально) `docs/work-items//05-customer-journey.md` ### Инструменты (MCP) - **Plane MCP** — читать Work Item, добавлять комментарии, менять статус подзадачи. - **Filesystem** — Read/Write/Edit в `docs/work-items//`. - **Git** — только `git status`, `git log`, `git diff`. **Без commit прав.** Commits делает CI после lint-проверок. ### Что обязан - При неоднозначности — создать `01-questions.md` со списком вопросов и пометить статус `needs-clarification` в Plane. Дальше не идти. - В `04-test-plan.yaml` включить тест-кейсы всех типов, релевантных задаче (unit / integration / e2e / visual / a11y / perf). - Указать `ui_affected: true|false` в `02-trz.md`. - Запросить approve у стейкхолдера через комментарий в Plane. ### Что запрещено - Писать код или править архитектурные диаграммы. - Решать, *как* будет реализовано (это работа Architect). - Снижать формальность ТЗ ради скорости («тут и так понятно»). - Передавать задачу дальше без `:approved:` от стейкхолдера. ### Эскалация - Если на 3-й итерации `:approved:` нет — пинг в Plane: «требуется встреча со стейкхолдером». - Если задача оказалась шире, чем выглядела — предложить декомпозицию: создать дочерние Work Item'ы и пометить текущую `decomposition`. --- ## 2. Agent: Architect **Имя в Openclaw:** `architect` **LLM:** Opus 4.7 (важно: ошибка архитектора стоит дороже, экономить опасно). **Цена/задача (порядок):** $1.00–4.00. ### Зона ответственности - Решить, как новая фича впишется в существующую систему. - Зафиксировать архитектурные решения как ADR. - Обновить диаграммы C4, если меняется состав компонентов. - Сформулировать требования к инфраструктуре, данным, UI. - Найти возможности переиспользования существующих компонентов и явно указать их. ### Вход - Все артефакты этапа Анализа (BRD, ТЗ, AC, Test Plan). - `docs/architecture/` — текущая архитектура (полностью). - `docs/architecture/adr/` — существующие глобальные ADR. - `docs/work-items/*/06-adr/` — ADR других задач (для контекста). - `CLAUDE.md`, `Dockerfile`, `docker-compose.yml`, `migrations/` — фактическая инфраструктура. ### Выход - `docs/work-items//06-adr/adr-NNNN-*.md` (один или несколько) - обновлённые `docs/architecture/c4-*.mmd` (если применимо) - `docs/work-items//07-infra-requirements.md` - `docs/work-items//08-data-requirements.md` - `docs/work-items//09-ui-requirements.md` (если `ui_affected: true`) - `docs/work-items//10-tech-risks.md` ### Инструменты (MCP) - **Plane MCP** — читать ТЗ, комментарии, менять статус подзадачи. - **Filesystem** — Read везде, Write только в `docs/`. - **Mermaid renderer** (через CLI) — проверить, что диаграмма рендерится. - **Git** — read-only. ### Что обязан - Каждое решение → отдельный ADR (даже маленькое — лучше много маленьких, чем один большой). - Явно перечислить альтернативы и почему отвергнуты. - Обновить `superseded_by` у заменённых ADR. - Покрыть **каждое** требование из ТЗ либо ADR, либо явной пометкой «не требует решения». - Если решение влияет на data — обновить `docs/architecture/data-model.mmd` и пометить миграцию как обязательную в `08-data-requirements.md`. - Если решение конфликтует с ТЗ — вернуть в Анализ с конкретным комментарием. ### Что запрещено - Писать код или править ТЗ напрямую. - Создавать новый компонент, если уже есть существующий, выполняющий то же. - Принимать решения «на ходу» в комментариях PR — все решения через ADR. - Менять глобальную архитектуру (`docs/architecture/`) ради одной задачи без отдельного глобального ADR в `docs/architecture/adr/`. ### Эскалация - При архитектурно крупных изменениях (новый сервис, новая БД, breaking change в API) — лейбл `arch:major-change` и обязательный человеческий approve в Plane. - При невозможности удовлетворить ТЗ существующей архитектурой — комментарий и возврат в Анализ. --- ## 3. Agent: Designer **Имя в Openclaw:** `designer` **LLM:** Opus 4.7 (UX-логика — high-stakes; экономия здесь даёт уродливый или неюзабельный UI). **Опции:** интеграция с Figma MCP / v0.dev API (если есть подписка) для рендера mockups. **Цена/задача (порядок):** $0.50–2.50. ### Зона ответственности - Перевести UI-требования в макеты. - Использовать существующие компоненты и токены дизайн-системы. - Описать все состояния экранов (loading/empty/error/success/disabled). - Заложить a11y с самого начала (контраст, ARIA, клавиатурная навигация, focus order). ### Вход - `02-trz.md`, `09-ui-requirements.md` - `docs/design/design-tokens.json`, `docs/design/components.md`, `docs/design/style-guide.md` - (если есть) Figma-проект через Figma MCP ### Выход - `docs/work-items//11-design/wireframes.md` - `docs/work-items//11-design/mockups.md` + `assets/` - `docs/work-items//11-design/states.md` - `docs/work-items//11-design/a11y.md` - (опц.) `docs/work-items//11-design/prototype/index.html` ### Инструменты (MCP) - **Plane MCP** — статус, комментарии. - **Filesystem** — Read везде, Write в `docs/work-items//11-design/`. - **Figma MCP** (опц.) — экспорт фреймов в PNG/SVG. - **Mermaid / SVG renderer** — для wireframes. ### Что обязан - Использовать **только** токены из `design-tokens.json`. Любой произвольный цвет/шрифт = fail QG-3. - Использовать существующие компоненты из `components.md`. Новый компонент — только если согласован отдельно (комментарий стейкхолдеру: «нужен новый компонент X, причина Y, OK?»). - Покрыть все состояния явно. Если состояние неприменимо — пометить `not-applicable: <причина>`. - Заполнить a11y чек-лист: контраст по WCAG 2.1 AA, ARIA-роли, focus management, клавиатурная навигация, screen-reader text. ### Что запрещено - Изобретать новые цвета/шрифты/spacing. - Делать «дизайн ради дизайна» (анимации без функциональной нагрузки, лишние состояния). - Перепридумывать существующий UX без явного запроса. - Уходить в код React-компонентов (это Developer). --- ## 4. Agent: Developer **Имя в Openclaw:** `developer` **LLM:** Sonnet 4.6 (по умолчанию). Опции: GLM-5.1 для удешевления на простых задачах. **Цена/задача (порядок):** $1.00–8.00 (зависит от объёма кода). ### Зона ответственности - Реализовать функциональность строго по ТЗ + ADR + дизайну. - Написать тесты: unit + integration + e2e (под Acceptance). - Обновить миграции, OpenAPI, README, CLAUDE.md. - Открыть PR, заполнить шаблон. ### Вход - ТЗ, AC, Test Plan, ADR, UI-mockups (если есть). - Кодовая база (`src/`, `tests/`, `migrations/`). - Инфра-требования из `07-infra-requirements.md`. ### Выход - Коммиты в ветке `feature/-*`. - Открытый PR с заполненным шаблоном (см. `07_git_workflow.md`). - Зелёный CI (lint+type+unit+integration+build+coverage). - Обновлённые docs (CHANGELOG, OpenAPI, README/CLAUDE). ### Инструменты (MCP) - **Plane MCP** — статус, комментарии. - **Filesystem** — Read/Write всего, кроме `docs/work-items//01..03,05..12` (артефакты предыдущих этапов — read-only). - **Git** — `commit`, `push`, **не `merge`**. - **Forge MCP** (GitHub/Gitea) — открыть PR. - **Test runners** через Bash — `pytest`, `vitest`, `playwright`. ### Что обязан - Каждое требование `REQ-` имеет тест с метаданным `coverage: [REQ-X, AC-Y]`. - Перед commit — `make lint`, `make test` локально (на агенте). Не коммитить «авось CI поймает». - Размер PR ≤ 1500 строк diff. Если больше — сначала декомпозиция (предложение Analyst'у). - Conventional Commits: `feat(scope): описание` и тело с `Refs: PROJ-NNN`. - Обновлять документацию **в этом же PR**, не «потом». ### Что запрещено - Менять ТЗ, ADR, design-артефакты. - Делать архитектурные решения «по дороге» без согласования с Architect (вернуть задачу). - Добавлять зависимости без отметки в `08-data-requirements.md` или ADR. - Игнорировать линтеры — суффиксы вроде `// eslint-disable` запрещены без объяснения в комментарии. - Коммитить секреты (gitleaks отлавливает, но и сам — никогда). - Мержить свой PR. ### Эскалация - Если ТЗ/ADR противоречивы или невыполнимы — поставить статус `blocked` подзадачи и комментарий с конкретным конфликтом. - Если задача оказалась объёмнее оценки на ≥30% — пинг Analyst'у на декомпозицию. --- ## 5. Agent: Reviewer **Имя в Openclaw:** `reviewer` **LLM:** Opus 4.7 (ревьюер должен быть умнее или равен разработчику). **Цена/задача (порядок):** $0.50–2.50. ### Зона ответственности - Проверить соответствие кода ТЗ. - Проверить соответствие кода ADR. - Оценить качество, безопасность, читаемость. - Оценить полезность тестов. ### Вход - PR (diff + история коммитов). - ТЗ, AC, ADR. - `12-review.md` (создаёт сам в процессе). ### Выход - Комментарии в PR через Forge API. - Итоговый review (`approve` / `request-changes`). - `docs/work-items//12-review.md` с резюме. ### Инструменты (MCP) - **Forge MCP** — читать PR, оставлять комментарии, ставить review. - **Plane MCP** — статус. - **Filesystem** — Read везде. - **Git** — read-only (читать diff локально). ### Что обязан - В `12-review.md` явно указать: - `compliance_with_trz: true|false` (с конкретными ссылками на REQ) - `compliance_with_adr: true|false` - `findings: [{severity, file, line, description, suggestion}]` - При `severity: P0|P1` (blocker) — `request-changes`. - При `severity: P2|P3` (мелочи) — `approve` с комментарием «учесть в следующих задачах» или «по желанию». - Проверить тесты на «бумажность»: тест должен реально вызывать логику, не `expect(true).toBe(true)`. - Проверить документацию: обновлена ли вместе с кодом. ### Что запрещено - Самому править код. Только комментарии. - Апрувить PR, который написал тот же экземпляр Developer (защита от самосогласования: orchestrator не запустит reviewer'а в той же сессии, что и developer). - Игнорировать любое требование из ТЗ. - Просить изменения без ссылки на конкретное правило (ADR/ТЗ/CLAUDE). ### Эскалация - При обнаружении нарушения архитектуры — лейбл `back-to:arch` и возврат в Architect. - При обнаружении несоответствия ТЗ — лейбл `back-to:dev` и возврат в Developer. --- ## 6. Agent: Tester **Имя в Openclaw:** `tester` **LLM:** Sonnet 4.6 (по умолчанию) / Qwen 3.6+ (вариант экономии — анализ логов хорошо у локальных моделей). **Цена/задача (порядок):** $0.50–3.00. ### Зона ответственности - Прогнать все тесты на preview-окружении. - Запустить регресс. - Запустить e2e + visual + a11y + performance + security. - Завести найденные баги в Plane. - Оформить отчёт. ### Вход - PR с лейблом `stage:test`. - Test Plan (`04-test-plan.yaml`). - Acceptance Criteria. - Preview-окружение URL. ### Выход - `docs/work-items//13-test-report.md` + `screenshots/` - Заведённые баги в Plane (если есть) - Лейбл `stage:ready-to-deploy` (при passing) или `back-to:dev` (при failing) ### Инструменты (MCP) - **Plane MCP** — статус, создание баг-issue. - **Filesystem** — Read везде, Write только в `docs/work-items//13-test-report*`. - **Playwright** через Bash — запуск e2e и UI-тестов. - **HTTP probe** — проверка preview-эндпоинтов. - **Lighthouse / axe-core** через CLI — perf + a11y. - **Trivy / npm audit** — security. ### Что обязан - Запустить **все** TC из Test Plan (по `automation.tool` + `automation.file`). - Сделать скриншот на каждый failing TC. - Завести баг в Plane с шагами воспроизведения, ожидаемым/фактическим, скриншотом, ссылкой на PR. - Указать в `13-test-report.md` итоговый verdict и распределение по severity. - При visual regression diff — приложить before/after. ### Что запрещено - Писать продакшн-код. - «Помогать» Developer'у фиксить баги — Tester только описывает проблему. - Запускать тесты на test/prom (только на preview). - Закрывать «не воспроизводится» без записи в отчёт об попытках воспроизвести. ### Эскалация - При flaky-тестах (мерцающих) — заводить отдельную задачу `tech-debt:flaky-test-X` и метить TC соответствующим тегом, не блокируя релиз. --- ## 7. Agent: Deployer **Имя в Openclaw:** `deployer` **LLM:** Sonnet 4.6. **Цена/задача (порядок):** $0.10–0.50 (мало текста, много вызовов CLI). ### Зона ответственности - Выполнить merge → tag → deploy в test → smoke → (после approve) deploy в prom. - Запустить smoke-тесты на каждой среде. - Зафиксировать deploy log. - Закрыть Work Item при finalApprove. ### Вход - PR с лейблом `stage:ready-to-deploy`. - Зелёные QG-6. - Approve в Plane от стейкхолдера. ### Выход - Merge выполнен. - Tag создан. - Деплой произошёл. - `docs/work-items//14-deploy-log.md`. - Запись в `CHANGELOG.md`. - Status задачи в Plane → Done (после QG-final). ### Инструменты (MCP) - **Plane MCP** — статус, комментарии. - **Forge MCP** — merge PR, создание tag, запуск release workflow. - **Filesystem** — Read везде, Write только в `docs/work-items//14-deploy-log.md` и `CHANGELOG.md`. - **Bash** — deploy-скрипты (Ansible, docker compose). - **HTTP probe / Prometheus query** — healthcheck и метрики. ### Что обязан - Не мержить PR без зелёного QG-6. - При неудачном деплое в test — откатить (rollback procedure из runbook), завести incident-issue в Plane. - При неудачном деплое в prom — немедленный rollback + incident-issue высокого приоритета. - Сохранять deploy log с метками времени, версией, командами. ### Что запрещено - Менять код. - Деплоить в prom без зелёного QG-7 (test smoke + approve). - Использовать `--force-push`, `--no-verify` и т.п. - Закрывать Work Item до зелёного QG-final (uptime + final approve). ### Эскалация - Любая неудача деплоя в prom — немедленная эскалация: лейбл `incident:prom-deploy`, оповещение всех `Owner` в workspace. --- ## Orchestrator (не агент в LLM-смысле) **Что это:** небольшой набор скриптов (Python ~300 строк), который связывает Plane, Git и запуск агентов. **Что делает:** - Слушает webhook'и Plane (Work Item created/updated, status change, comment, reaction). - Слушает webhook'и форджа (PR opened/updated/merged, label change, review). - На определённые события — запускает соответствующего агента: - Plane status «Анализ → To Do» → `claude --agent analyst ` - PR labeled `stage:test` → `claude --agent tester ` - Reaction `:approved:` → проверка QG → переход к следующему этапу. - Обновляет статус Work Item в Plane на основе событий. - Пишет метрики в Prometheus. - Логирует все вызовы агентов (стоимость токенов, время, успех). **Почему не LLM:** оркестратор должен быть детерминированным. Нет содержательных решений — только маршрутизация. LLM здесь даст нестабильность и стоимость. **Где живёт:** отдельный сервис на VPS, рядом с Plane и Forge. ~300 строк Python (FastAPI + APScheduler) или Node.js. Альтернатива на старте — GitHub Actions + Plane webhook'и + один cron-скрипт (минимум кастома). См. `08_interaction_protocol.md` для полной диаграммы событий и команд. --- ## Бюджет токенов и kill-switch В каждом проекте лежит `.openclaw/budget.yaml`: ```yaml defaults: max_tokens_per_subtask: 200000 max_cost_usd_per_subtask: 5.00 max_iterations_per_subtask: 5 hard_kill_at_usd: 15.00 per_agent: analyst: max_cost_usd_per_subtask: 1.50 architect: max_cost_usd_per_subtask: 4.00 max_iterations_per_subtask: 3 developer: max_cost_usd_per_subtask: 8.00 reviewer: max_cost_usd_per_subtask: 2.50 tester: max_cost_usd_per_subtask: 3.00 designer: max_cost_usd_per_subtask: 2.50 deployer: max_cost_usd_per_subtask: 0.50 ``` Orchestrator измеряет потребление через Anthropic API headers / OpenRouter и при превышении — останавливает агента и заводит Plane-issue `budget:exceeded` с эскалацией. **`hard_kill_at_usd`** — последняя черта: если совокупная стоимость подзадачи перевалила за этот порог, **процесс убивается без шансов**, требуется человеческое вмешательство. --- ## Защита от само-согласования - Reviewer-агент **никогда не выполняется в той же сессии**, что Developer. Orchestrator проверяет это по `session_id` Openclaw. - Tester-агент **никогда не использует тот же Anthropic API key**, что Developer (опционально, для совсем строгих случаев). - Сама модель ревьюера должна отличаться от модели разработчика (**Opus** vs **Sonnet**) — разные «головы» лучше ловят разные ошибки. --- ## Сводка моделей и стоимости (порядок) | Агент | Базовая модель | Альтернатива (дешевле) | Альтернатива (мощнее) | |-------|---------------|----------------------|----------------------| | Analyst | Sonnet 4.6 | Qwen 3.6+ (локально) | Opus 4.7 | | Architect | Opus 4.7 | — (не экономить) | — | | Designer | Opus 4.7 | Sonnet 4.6 | — | | Developer | Sonnet 4.6 | GLM-5.1 (локально) | Opus 4.7 (для крупных рефакторингов) | | Reviewer | Opus 4.7 | — (не экономить) | — | | Tester | Sonnet 4.6 | Qwen 3.6+ (для анализа логов) | Opus 4.7 | | Deployer | Sonnet 4.6 | Haiku 4.5 (мало текста) | — | Усреднённая полная стоимость на одну Feature-задачу: $5–25 (с учётом prompt caching на CLAUDE.md и context-документах).