From 685b3f334d4d4af3556297e35743453f5fc660a6 Mon Sep 17 00:00:00 2001 From: Stream Date: Fri, 15 May 2026 01:10:03 +0300 Subject: [PATCH] auto-sync: 2026-05-15 01:10:01 --- tasks/multi-agent/BRD.md | 219 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 tasks/multi-agent/BRD.md diff --git a/tasks/multi-agent/BRD.md b/tasks/multi-agent/BRD.md new file mode 100644 index 0000000..10a5328 --- /dev/null +++ b/tasks/multi-agent/BRD.md @@ -0,0 +1,219 @@ +# 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, запускает агентов | +| Developer | Claude Code CLI | Пишет код, тесты, открывает PR | +| Reviewer | Claude Code CLI | Проверяет код на соответствие ТЗ/ADR | +| Tester | Claude Code CLI | Запускает тесты, оформляет отчёт | + +## 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 +- Агенты: Developer, Reviewer (через Claude Code CLI) +- Quality Gates: QG-0 → QG-5 (до деплоя) +- Пилотный проект: Enduro Trails + +### Вне скоупа (v1) +- Designer-агент (UI-дизайн пока ручной) +- Tester-агент (на пилоте — Developer пишет тесты сам) +- 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 │ + │ │ ├─ Запуск Developer ──►│ + │ │ │ ├─ Код + тесты + │ │ │ ├─ git commit + │ │ │ ├─ PR + │ │ │◄── webhook CI green │ + │ │ ├─ QG-4 check │ + │ │ ├─ Запуск Reviewer ───►│ + │ │ │ ├─ Review + │ │ │ ├─ approve/reject + │ │ │◄── webhook review │ + │ │ ├─ QG-5 check │ + │ │ ├─ Merge PR │ + │ │ ├─ Deploy test │ + │◄── Готово, проверь ─┤ │ │ + ├─── :approved: ─────► │ │ + │ │ ├─ Done │ +``` + +**Этапы пилота (5 из 8):** +1. **Постановка** — Слава в Plane (или через Стрим) +2. **Анализ** — Стрим пишет BRD/ТЗ/AC +3. **Разработка** — Claude Code CLI (код + тесты + PR) +4. **Code Review** — Claude Code CLI (другой запуск, другой prompt) +5. **Внедрение** — merge + deploy (CI или ручной) + +Пропущены на пилоте: Архитектура (Стрим решает inline), Дизайн (не нужен), Тестирование (Developer пишет тесты). + +## 6. Quality Gates (пилот) + +| QG | Между | Что проверяет | Как | +|----|-------|---------------|-----| +| QG-0 | Постановка → Анализ | title + description заполнены | Orchestrator (webhook) | +| QG-1 | Анализ → Разработка | ТЗ есть + :approved: от Славы | Orchestrator (файл + Plane API) | +| QG-4 | Разработка → Review | CI зелёный (lint + test + build) | Gitea Actions → webhook | +| QG-5 | Review → Merge | Review approve + 0 unresolved | Orchestrator (Gitea API) | +| 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. План запуска (3 недели) + +**Неделя 1: Инфраструктура** +- [ ] Node.js на mva154 +- [ ] Claude Code CLI установлен и авторизован +- [ ] Git repo Enduro Trails в Gitea (структура по канону) +- [ ] Gitea Actions runner работает +- [ ] Базовый CI (lint + build) + +**Неделя 2: Orchestrator + интеграции** +- [ ] Orchestrator (FastAPI) написан и задеплоен +- [ ] Webhooks: Plane → Orchestrator, Gitea → Orchestrator +- [ ] Plane: лейблы, шаблоны подзадач +- [ ] Тест: ручной прогон одной задачи через конвейер + +**Неделя 3: Пилот** +- [ ] Первая реальная фича через полный конвейер +- [ ] Метрики: lead time, cost, intervention rate +- [ ] Ретроспектива, корректировка + +## 11. Definition of Done (BRD) + +- [ ] Слава подтвердил scope и метрики +- [ ] Архитектура согласована +- [ ] План запуска реалистичен +- [ ] Риски приемлемы