auto-sync: 2026-05-15 01:10:01

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 и метрики
+- [ ] Архитектура согласована
+- [ ] План запуска реалистичен
+- [ ] Риски приемлемы