25 KiB
25 KiB
BRD — Мультиагентная разработка ПО
type: brd version: 1 status: draft created_at: 2026-05-15 authors:
- "agent:stream"
- "human:slava" related: proposal: ../proposal_v1/README.md
1. Цель и метрика успеха
Цель: Построить систему, в которой Слава формулирует бизнес-требования, а агенты автоматически выполняют анализ, разработку, ревью, тестирование и деплой — с машинно-проверяемыми Quality Gates между этапами.
Метрики успеха (пилот — проект Enduro Trails):
- Lead time от постановки до деплоя в test ≤ 4 часа (для типовой фичи)
- Человеческое участие ≤ 3 действия на задачу (постановка + approve ТЗ + approve деплоя)
- Стоимость LLM ≤ $15/задача
- 0 деплоев сломанного кода (QG не пропускает)
2. Стейкхолдеры
| Роль | Кто | Интерес |
|---|---|---|
| Заказчик / Owner | Слава | Формулирует задачи, ставит approve, наблюдает в Plane |
| Analyst | Стрим (OpenClaw) | Пишет BRD/ТЗ, задаёт вопросы, координирует |
| Orchestrator | Скрипт (FastAPI) | Слушает webhooks, проверяет QG, запускает агентов |
| Architect | Claude Code CLI | ADR, C4-диаграммы, требования к инфре/данным |
| Developer | Claude Code CLI | Пишет код, тесты, открывает PR |
| Reviewer | Claude Code CLI | Проверяет код на соответствие ТЗ/ADR |
| Tester | Claude Code CLI | Запускает e2e/регресс, оформляет отчёт |
3. Scope
В скоупе (пилот)
- Orchestrator: webhook-обработка Plane + Gitea, QG-проверки, запуск агентов
- Claude Code CLI на mva154: установка, авторизация, headless mode
- Gitea: репо Enduro Trails, branch protection, CI (Gitea Actions)
- Plane: шаблоны Work Item, webhooks, лейблы, custom fields
- Агенты: Architect, Developer, Reviewer, Tester (через Claude Code CLI)
- Quality Gates: QG-0 → QG-7 (полный конвейер)
- Пилотный проект: Enduro Trails
Вне скоупа (v1)
- Designer-агент (UI-дизайн пока ручной)
- Deployer-агент (деплой ручной или через простой CI)
- Ephemeral preview-окружения
- Visual regression / a11y тесты
- Масштабирование на другие проекты
- Plane MCP-сервер (на старте — прямые API-вызовы из Orchestrator)
4. Архитектура (высокий уровень)
┌─────────────┐ webhook ┌──────────────┐ CLI ┌─────────────────┐
│ Plane │ ───────────────► │ Orchestrator │ ───────────► │ Claude Code CLI │
│ (витрина) │ ◄─────────────── │ (FastAPI) │ │ (на mva154) │
└─────────────┘ API updates └──────┬───────┘ └────────┬────────┘
│ │
│ git push/PR │ git commit
▼ ▼
┌──────────────┐ ┌─────────────────┐
│ Gitea │ ◄────────────│ Git repo │
│ (CI/forge) │ │ (source of truth)│
└──────────────┘ └─────────────────┘
│
│ webhook (CI result)
▼
┌──────────────┐
│ Orchestrator │ (проверяет QG, двигает дальше)
└──────────────┘
Стрим (OpenClaw):
- Получает задачу от Славы в чате
- Пишет BRD/ТЗ, коммитит в ветку
- Ставит статус в Plane → триггерит Orchestrator
Orchestrator (скрипт):
- Слушает webhooks от Plane и Gitea
- Проверяет QG (наличие файлов, lint, CI status, reactions)
- Запускает Claude Code CLI в headless mode с конкретной задачей
- Обновляет статусы в Plane
Claude Code CLI:
- Запускается на mva154 в директории git-репо
- Получает задачу: "Прочитай docs/work-items/XXX/02-trz.md, реализуй, закоммить"
- Работает нативно (без cloaking, без прокси)
- Коммитит результат в ветку
Gitea:
- Хранит код (source of truth)
- CI (Gitea Actions): lint, test, build
- Webhooks → Orchestrator
- Branch protection на main
Plane:
- Витрина для Славы
- Work Items с подзадачами (этапы конвейера)
- Reactions как approve-механизм
- Webhooks → Orchestrator
5. Производственный процесс
Слава Стрим Orchestrator Claude Code CLI
│ │ │ │
├─ Задача в Plane ──►│ │ │
│ ├─ BRD/ТЗ ──────────►│ │
│◄── Вопросы ────────┤ │ │
├─── Ответы ────────►│ │ │
│ ├─ ТЗ ready ─────────►│ │
│◄── Прошу approve ──┤ │ │
├─── :approved: ─────► │ │
│ │ ├─ QG-1 check │
│ │ ├─ Запуск Architect ──►│
│ │ │ ├─ ADR + требования
│ │ │ ├─ git commit
│ │ │◄── push event │
│ │ ├─ QG-2 check │
│ │ ├─ Запуск Developer ──►│
│ │ │ ├─ Код + тесты
│ │ │ ├─ git commit + PR
│ │ │◄── webhook CI green │
│ │ ├─ QG-4 check │
│ │ ├─ Запуск Reviewer ───►│
│ │ │ ├─ Review
│ │ │ ├─ approve/reject
│ │ │◄── webhook review │
│ │ ├─ QG-5 check │
│ │ ├─ Запуск Tester ─────►│
│ │ │ ├─ e2e + отчёт
│ │ │◄── test report │
│ │ ├─ QG-6 check │
│ │ ├─ Merge PR │
│ │ ├─ Deploy test │
│◄── Готово, проверь ─┤ │ │
├─── :approved: ─────► │ │
│ │ ├─ Done │
Этапы (7 из 8):
- Постановка — Слава в Plane (или через Стрим)
- Анализ — Стрим пишет BRD/ТЗ/AC
- Архитектура — Claude Code CLI (ADR, C4, требования к инфре/данным)
- Разработка — Claude Code CLI (код + unit-тесты + PR)
- Code Review — Claude Code CLI (другой запуск, проверка соответствия ТЗ/ADR)
- Тестирование — Claude Code CLI (e2e, регресс, отчёт)
- Внедрение — merge + deploy (CI или ручной)
Пропущен на пилоте: Дизайн (UI-макеты пока ручные).
5.1. Структура репозитория (канон)
enduro-trails/
├── CLAUDE.md # Паспорт проекта для агентов
├── README.md
├── CHANGELOG.md
├── Makefile # make dev / test / lint / build
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitea/workflows/ # CI (Gitea Actions)
│ └── ci.yml
├── .openclaw/agents/ # system prompts агентов
│ ├── architect.md
│ ├── developer.md
│ ├── reviewer.md
│ └── tester.md
├── docs/
│ ├── architecture/
│ │ ├── README.md
│ │ ├── c4-context.mmd
│ │ ├── c4-component.mmd
│ │ └── adr/
│ └── work-items/
│ └── <plane-id>/
│ ├── 00-business-request.md
│ ├── 01-brd.md
│ ├── 02-trz.md
│ ├── 03-acceptance-criteria.md
│ ├── 04-test-plan.yaml
│ ├── 06-adr/
│ ├── 12-review.md
│ └── 13-test-report.md
├── src/
├── tests/
│ ├── unit/
│ ├── integration/
│ └── e2e/
├── scripts/
│ ├── lint-spec.sh
│ ├── lint-adr.sh
│ └── req-coverage.py
└── migrations/
Все артефакты имеют YAML frontmatter (type, plane_id, status, version). Линтеры проверяют наличие и валидность.
5.2. CLAUDE.md (паспорт проекта)
Файл в корне репо — первое что читает каждый агент при запуске. Содержит:
- Стек технологий
- Команды (make dev/test/lint/build)
- Структура проекта
- Конвенции (commits, branches, naming)
- Правила для агентов (что можно, что нельзя)
5.3. Формат запуска агентов
Orchestrator запускает Claude Code CLI:
cd /home/slin/repos/enduro-trails && \
claude -p "Прочитай CLAUDE.md. Прочитай docs/work-items/<plane-id>/02-trz.md и все артефакты предыдущих этапов. Реализуй задачу согласно своей роли. Закоммить результат." \
--allowedTools read,write,edit,bash \
--systemPrompt "$(cat .openclaw/agents/developer.md)"
Параметры:
--systemPrompt— роль агента (из.openclaw/agents/<role>.md)--allowedTools— ограниченный набор инструментов- Рабочая директория — корень репо (агент видит весь проект)
- Бюджет: ограничен через Max подписку (5-часовое окно)
5.4. Обратная волна (back-to)
Когда агент возвращает задачу на предыдущий этап:
Reviewer → Developer:
- Reviewer ставит
request-changesв PR (через Gitea API) - Orchestrator получает webhook → лейбл
back-to:dev - Orchestrator запускает Developer повторно (читает комментарии review)
- Лимит: ≤3 итерации. После 3-й →
escalation:human-needed, уведомление Славе
Tester → Developer:
- Tester находит баг → создаёт issue в Plane, пишет в test-report
- Orchestrator: лейбл
back-to:dev, PR возвращается в stage:dev - Developer фиксит → снова QG-4 → QG-5 → QG-6
Architect → Analyst (Стрим):
- Architect находит противоречие в ТЗ → коммитит комментарий, лейбл
back-to:analysis - Orchestrator уведомляет Стрим → Стрим правит ТЗ → новый :approved: от Славы
5.5. Эскалация
Оркестратор эскалирует к Славе когда:
- Агент 3 раза вернулся на предыдущий этап
- Claude Code CLI вернул ошибку (rate limit, timeout, crash)
- QG красный после 3 попыток
- Найдена security-уязвимость уровня critical
Формат: уведомление в Plane (комментарий + лейбл escalation:*) + сообщение Славе через Стрим.
5.6. Идемпотентность и очередь
Идемпотентность: webhooks могут дублироваться. Orchestrator проверяет:
- Не запущен ли уже агент на эту задачу (lock по plane_id + stage)
- Не обработано ли уже это событие (event_id в журнале)
Очередь: задачи выполняются последовательно (один Claude Code CLI одновременно). Orchestrator ведёт FIFO-очередь. Приоритет: urgent > high > medium > low.
5.7. Service account в Git
- User:
claude-botв Gitea - Email:
claude-bot@mva154.local - PAT-токен для push в feature-ветки
- Не имеет права push в main (только через PR merge)
- Все коммиты агентов — от этого аккаунта (отличимы от человеческих)
5.8. Plane → Orchestrator: события
| Событие Plane | Реакция Orchestrator |
|---|---|
work_item.created (Feature) |
QG-0 → создать ветку + подзадачи + папку docs/ |
:approved: от Славы на подзадаче «Анализ» |
QG-1 → запустить Architect |
| Подзадача «Архитектура» → done | QG-2 → запустить Developer |
| CI green на PR | QG-4 → запустить Reviewer |
| Review approved | QG-5 → запустить Tester |
| Test report: verdict=pass | QG-6 → merge PR, deploy |
:approved: от Славы после деплоя |
QG-7 → закрыть Work Item |
5.9. Tester — scope на пилоте
На пилоте Tester запускает:
- Unit-тесты (повторно, в чистой среде)
- Integration-тесты
- E2e-тесты (Playwright) по Acceptance Criteria из
04-test-plan.yaml - Формирует
13-test-report.md
Не на пилоте (v2): visual regression, a11y (axe-core), performance, security scan.
6. Quality Gates
| QG | Между | Что проверяет | Как |
|---|---|---|---|
| QG-0 | Постановка → Анализ | title + description заполнены | Orchestrator (webhook) |
| QG-1 | Анализ → Архитектура | ТЗ/BRD/AC есть + :approved: от Славы | Orchestrator (файл + Plane API) |
| QG-2 | Архитектура → Разработка | ADR есть, req-coverage, диаграммы рендерятся | Orchestrator (lint-adr.sh) |
| QG-4 | Разработка → Review | CI зелёный (lint + test + build) | Gitea Actions → webhook |
| QG-5 | Review → Тестирование | Review approve + 0 unresolved | Orchestrator (Gitea API) |
| QG-6 | Тестирование → Внедрение | Все тесты зелёные, test-report создан | Orchestrator |
| QG-7 | Merge → Done | Deploy smoke OK + :approved: | Orchestrator |
7. Инфраструктура (что нужно поднять)
| Компонент | Статус | Действие |
|---|---|---|
| Plane | ✅ Работает | Настроить webhooks, лейблы, custom fields |
| Gitea | ✅ Работает | Создать репо Enduro Trails, настроить Actions, branch protection |
| Node.js на mva154 | ❌ Нет | Установить (для Claude Code CLI) |
| Claude Code CLI | ❌ Нет | npm install -g, авторизовать через Max |
| Orchestrator | ❌ Нет | Написать (FastAPI, ~500 строк), задеплоить в Docker |
| Gitea Actions runner | ❓ Проверить | Нужен для CI |
| Git repo Enduro Trails | ❌ Нет | git init, структура по канону, push в Gitea |
8. Бюджет и ограничения
LLM:
- Claude Max подписка ($100/мес) — для Claude Code CLI
- Vibecode — для Стрим (уже работает)
- Целевой бюджет: ≤ $15/задача
Инфра:
- Всё на mva154 (уже оплачен)
- Нет дополнительных серверов
Ограничения:
- Claude Code CLI: 5-часовое скользящее окно rate limit
- Один исполнитель одновременно (нет параллельных Claude Code сессий на одном аккаунте)
- Gitea Actions — нужно проверить, настроен ли runner
9. Риски
| Риск | Влияние | Вероятность | Митигация |
|---|---|---|---|
| Claude Code CLI rate limit | Задачи встают в очередь | Средняя | Очередь в Orchestrator, приоритизация |
| Claude Code CLI не справляется с задачей | Код не проходит QG | Средняя | Retry (≤3), потом эскалация к Славе |
| Orchestrator падает | Конвейер стоит | Низкая | Docker restart policy, healthcheck |
| Gitea Actions не работает | Нет CI | Средняя | Проверить на старте, альтернатива — скрипт |
10. Roadmap (фазы)
Каждая фаза самодостаточна — можно остановиться на любой и уже получать пользу.
Фаза 0: Инфраструктура (фундамент)
Цель: всё готово для ручного запуска агентов.
- Node.js на mva154
- Claude Code CLI установлен + авторизован через Max
- Git repo Enduro Trails в Gitea (структура по канону)
- Service account
claude-botв Gitea (PAT, без push в main) - CLAUDE.md в корне репо
- Базовый CI (Gitea Actions: lint + build)
- Branch protection на main (только через PR)
Критерий выхода: claude -p "Прочитай CLAUDE.md и выведи стек проекта" — работает.
Фаза 1: Ручной конвейер (валидация подхода)
Цель: убедиться что агенты справляются с задачами. Всё руками, без автоматизации.
- Стрим пишет ТЗ → коммитит в ветку
- Слава ставит :approved: в Plane
- Стрим вручную запускает Architect (ssh →
claude -p "..." --systemPrompt ...) - Стрим вручную запускает Developer
- CI проходит (lint + test + build)
- Стрим вручную запускает Reviewer
- Стрим вручную запускает Tester
- PR мержится, деплой
Критерий выхода: одна фича прошла полный цикл (Analyst → Architect → Developer → Reviewer → Tester → merge). Код рабочий, тесты зелёные.
Фаза 2: Orchestrator MVP
Цель: автоматизировать запуск агентов после CI/review событий.
- FastAPI скрипт в Docker (~500 строк)
- Слушает webhooks от Gitea (push, PR opened, CI result, review submitted)
- Автоматически запускает Reviewer после CI green
- Автоматически запускает Tester после review approve
- FIFO-очередь (один агент одновременно)
- Lock по plane_id + stage (идемпотентность)
- Журнал запусков (SQLite: when, agent, task, status, duration)
Критерий выхода: после push в ветку — Reviewer и Tester запускаются автоматически без участия Стрим.
Фаза 3: Plane интеграция
Цель: Plane как единая витрина, approve через reactions.
- Webhooks Plane → Orchestrator
- Автоматическое создание подзадач (7 шт) при новом Feature
- Автоматическое создание ветки
feature/<id>-<slug> - Reactions (:approved:) триггерят QG-переходы
- Лейблы
stage:*обновляются автоматически - Custom fields (qg_status, repo_branch, repo_pr) заполняются
- Эскалация → уведомление Славе через Стрим
Критерий выхода: Слава создаёт Feature в Plane → ставит :approved: на ТЗ → дальше всё автоматически до "Готово, проверь".
Фаза 4: Полный конвейер
Цель: автономная работа с обратной связью и самовосстановлением.
- QG-0 → QG-7 полностью автоматические
- Back-to: Reviewer → Dev (≤3 итерации), Tester → Dev, Architect → Analyst
- Architect запускается автоматически после QG-1
- Retry при ошибках CLI (rate limit, timeout) с exponential backoff
- Метрики: lead time, cost per task, intervention rate
- Дашборд в Plane (текущая работа, health, backlog)
- Graceful degradation (если CLI недоступен — задача в очередь, не теряется)
Критерий выхода: 5 фич подряд проходят конвейер без человеческого вмешательства (кроме постановки и финального approve).
Фаза 5: Оптимизация (v2)
Цель: масштабирование и расширение возможностей.
- Designer-агент (Figma MCP или генерация макетов)
- Deployer-агент (автоматический deploy в prod с canary)
- Visual regression (Playwright screenshots + diff)
- a11y тесты (axe-core)
- Performance / security scan
- Параллельные задачи (второй аккаунт Max или API)
- Масштабирование на другие проекты (fr24-noisemap, snowbike-rag)
- Plane MCP-сервер (вместо прямых API-вызовов)
Критерий выхода: система обслуживает 3+ проекта одновременно.
Оценка сроков:
| Фаза | Длительность | Зависимости |
|---|---|---|
| 0 | 2-3 дня | Node.js, Claude CLI auth |
| 1 | 3-5 дней | Фаза 0 |
| 2 | 1 неделя | Фаза 1 (валидация что агенты работают) |
| 3 | 1 неделя | Фаза 2 + Plane API |
| 4 | 1-2 недели | Фаза 3 |
| 5 | ongoing | Фаза 4 |
11. Definition of Done (BRD)
- Слава подтвердил scope и метрики
- Архитектура согласована
- Roadmap (фазы) реалистичен
- Риски приемлемы