373 lines
20 KiB
Markdown
373 lines
20 KiB
Markdown
# 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):**
|
||
1. **Постановка** — Слава в Plane (или через Стрим)
|
||
2. **Анализ** — Стрим пишет BRD/ТЗ/AC
|
||
3. **Архитектура** — Claude Code CLI (ADR, C4, требования к инфре/данным)
|
||
4. **Разработка** — Claude Code CLI (код + unit-тесты + PR)
|
||
5. **Code Review** — Claude Code CLI (другой запуск, проверка соответствия ТЗ/ADR)
|
||
6. **Тестирование** — Claude Code CLI (e2e, регресс, отчёт)
|
||
7. **Внедрение** — 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:
|
||
|
||
```bash
|
||
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:**
|
||
1. Reviewer ставит `request-changes` в PR (через Gitea API)
|
||
2. Orchestrator получает webhook → лейбл `back-to:dev`
|
||
3. Orchestrator запускает Developer повторно (читает комментарии review)
|
||
4. Лимит: ≤3 итерации. После 3-й → `escalation:human-needed`, уведомление Славе
|
||
|
||
**Tester → Developer:**
|
||
1. Tester находит баг → создаёт issue в Plane, пишет в test-report
|
||
2. Orchestrator: лейбл `back-to:dev`, PR возвращается в stage:dev
|
||
3. Developer фиксит → снова QG-4 → QG-5 → QG-6
|
||
|
||
**Architect → Analyst (Стрим):**
|
||
1. Architect находит противоречие в ТЗ → коммитит комментарий, лейбл `back-to:analysis`
|
||
2. 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. План запуска (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 и метрики
|
||
- [ ] Архитектура согласована
|
||
- [ ] План запуска реалистичен
|
||
- [ ] Риски приемлемы
|