admin/wiki

Files

Stream 143f9ad259 auto-sync: 2026-05-15 00:50:01

2026-05-15 00:50:01 +03:00

28 KiB

Raw Blame History

04. Роли агентов

Назначение: описать каждого агента — его зону ответственности, входы, выходы, инструменты MCP, выбор LLM, что он обязан делать и чего не имеет права делать.

Простым языком

Каждый агент — узкий специалист. Аналитик никогда не пишет код. Разработчик никогда не правит ТЗ. Ревьюер никогда не сам себе одобряет PR. Это сделано не из бюрократии, а потому что так получается дешевле и качественнее: каждый агент имеет минимальный, точный набор инструментов и контекста, и его легко проверить.

Аналогия: на типографии нет одного человека, который и верстает, и красит, и ОТК делает. Каждая операция — отдельный участок с собственным мастером и своим набором инструментов.

Семь агентов:

Analyst — читает запрос, пишет ТЗ.
Architect — решает «как впишется в систему», пишет ADR.
Designer — макеты UI/UX (если фича UI-овая).
Developer — пишет код и unit-тесты.
Reviewer — проверяет код.
Tester — запускает все тесты, включая UI.
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:

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-документах).

28 KiB Raw Blame History Unescape Escape

04. Роли агентов

Простым языком

Общая таблица ролей

1. Agent: Analyst

Зона ответственности

Вход

Выход

Инструменты (MCP)

Что обязан

Что запрещено

Эскалация

2. Agent: Architect

Зона ответственности

Вход

Выход

Инструменты (MCP)

Что обязан

Что запрещено

Эскалация

3. Agent: Designer

Зона ответственности

Вход

Выход

Инструменты (MCP)

Что обязан

Что запрещено

4. Agent: Developer

Зона ответственности

Вход

Выход

Инструменты (MCP)

Что обязан

Что запрещено

Эскалация

5. Agent: Reviewer

Зона ответственности

Вход

Выход

Инструменты (MCP)

Что обязан

Что запрещено

Эскалация

6. Agent: Tester

Зона ответственности

Вход

Выход

Инструменты (MCP)

Что обязан

Что запрещено

Эскалация

7. Agent: Deployer

Зона ответственности

Вход

Выход

Инструменты (MCP)

Что обязан

Что запрещено

Эскалация

Orchestrator (не агент в LLM-смысле)

Бюджет токенов и kill-switch

Защита от само-согласования

Сводка моделей и стоимости (порядок)

28 KiB

Raw Blame History