wiki/tasks/multi-agent/proposal_v1/04_agents_roles.md

# 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/<id>/00-business-request.md`
- `CLAUDE.md` проекта
- `docs/architecture/README.md`
- `docs/work-items/` — список других активных задач (через `find` + frontmatter status)

### Выход
- `docs/work-items/<id>/01-brd.md`
- `docs/work-items/<id>/02-trz.md`
- `docs/work-items/<id>/03-acceptance-criteria.md`
- `docs/work-items/<id>/04-test-plan.yaml`
- (опционально) `docs/work-items/<id>/05-customer-journey.md`

### Инструменты (MCP)
- **Plane MCP** — читать Work Item, добавлять комментарии, менять статус подзадачи.
- **Filesystem** — Read/Write/Edit в `docs/work-items/<id>/`.
- **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/<id>/06-adr/adr-NNNN-*.md` (один или несколько)
- обновлённые `docs/architecture/c4-*.mmd` (если применимо)
- `docs/work-items/<id>/07-infra-requirements.md`
- `docs/work-items/<id>/08-data-requirements.md`
- `docs/work-items/<id>/09-ui-requirements.md` (если `ui_affected: true`)
- `docs/work-items/<id>/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/<id>/11-design/wireframes.md`
- `docs/work-items/<id>/11-design/mockups.md` + `assets/`
- `docs/work-items/<id>/11-design/states.md`
- `docs/work-items/<id>/11-design/a11y.md`
- (опц.) `docs/work-items/<id>/11-design/prototype/index.html`

### Инструменты (MCP)
- **Plane MCP** — статус, комментарии.
- **Filesystem** — Read везде, Write в `docs/work-items/<id>/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/<id>-*`.
- Открытый 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/<id>/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/<id>/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/<id>/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/<id>/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/<id>/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/<id>/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 <id>`
  - PR labeled `stage:test` → `claude --agent tester <id>`
  - 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-документах).