13 KiB
13 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, запускает агентов |
| 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):
- Постановка — Слава в Plane (или через Стрим)
- Анализ — Стрим пишет BRD/ТЗ/AC
- Разработка — Claude Code CLI (код + тесты + PR)
- Code Review — Claude Code CLI (другой запуск, другой prompt)
- Внедрение — 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 и метрики
- Архитектура согласована
- План запуска реалистичен
- Риски приемлемы