admin/wiki

Fork 0

Files

Stream 8b5546fb05 auto-sync: 2026-05-15 01:50:01

2026-05-15 01:50:01 +03:00

29 KiB

Raw Blame History

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/регресс, оформляет отчёт
Deployer	Claude Code CLI	Деплой в test/prod, smoke-тест, rollback

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, Deployer (через Claude Code CLI)
Quality Gates: QG-0 → QG-7 (полный конвейер)
Пилотный проект: Enduro Trails

Вне скоупа (v1)

Designer-агент (UI-дизайн пока ручной)
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, регресс, отчёт)
Внедрение — Claude Code CLI (merge, deploy, smoke-тест)

Пропущен на пилоте: Дизайн (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: Инфраструктура (фундамент)

Цель: всё готово для ручного запуска агентов.

Фичи:

ID	Фича	Описание
F0-1	Установка Node.js	Установить Node.js LTS на mva154 (для Claude Code CLI)
F0-2	Установка Claude Code CLI	`npm install -g @anthropic-ai/claude-code`, авторизация через Max
F0-3	Git repo Enduro Trails	Создать репо в Gitea, структура по канону (src/, tests/, docs/, scripts/)
F0-4	Service account claude-bot	Создать пользователя в Gitea, PAT-токен, без права push в main
F0-5	CLAUDE.md	Паспорт проекта: стек, команды, конвенции, правила для агентов
F0-6	Gitea Actions CI	Workflow: lint + build + unit tests на каждый push/PR
F0-7	Branch protection	main: только через PR, require CI green, require 1 review
F0-8	System prompts агентов	`.openclaw/agents/{architect,developer,reviewer,tester,deployer}.md`

Критерий выхода: claude -p "Прочитай CLAUDE.md и выведи стек проекта" — работает.

Фаза 1: Ручной конвейер (валидация подхода)

Цель: убедиться что агенты справляются с задачами. Всё руками, без автоматизации.

Фичи:

ID	Фича	Описание
F1-1	Тестовая задача в Plane	Создать Feature в Plane, описать бизнес-требование
F1-2	BRD/ТЗ/AC	Стрим пишет артефакты анализа, коммитит в ветку
F1-3	Ручной запуск Architect	SSH на хост → `claude -p` с system prompt architect.md → ADR + требования
F1-4	Ручной запуск Developer	`claude -p` с developer.md → код + unit-тесты + PR
F1-5	CI прогон	Gitea Actions: lint + test + build на PR
F1-6	Ручной запуск Reviewer	`claude -p` с reviewer.md → review comments / approve
F1-7	Ручной запуск Tester	`claude -p` с tester.md → e2e тесты + test-report
F1-8	Ручной запуск Deployer	`claude -p` с deployer.md → merge PR, deploy, smoke-тест
F1-9	Merge и проверка	Проверка что deploy прошёл, smoke OK
F1-10	Ретроспектива	Оценка: справились ли агенты, где застряли, что доработать в промптах

Критерий выхода: одна фича прошла полный цикл (Analyst → Architect → Developer → Reviewer → Tester → merge). Код рабочий, тесты зелёные.

Фаза 2: Orchestrator MVP

Цель: автоматизировать запуск агентов после CI/review событий.

Фичи:

ID	Фича	Описание
F2-1	Orchestrator skeleton	FastAPI приложение, Docker-контейнер, healthcheck endpoint
F2-2	Gitea webhook receiver	Эндпоинт `/webhook/git`, парсинг событий push/PR/CI/review
F2-3	Agent launcher	Модуль запуска Claude Code CLI: subprocess, timeout, stdout capture
F2-4	Auto-Reviewer	При CI green на PR → автоматический запуск Reviewer
F2-5	Auto-Tester	При review approve → автоматический запуск Tester
F2-5a	Auto-Deployer	При QG-6 green → автоматический запуск Deployer (merge + deploy + smoke)
F2-6	FIFO-очередь	Один агент одновременно, задачи в очереди по приоритету
F2-7	Идемпотентность	Lock по plane_id + stage, дедупликация webhook-событий (event_id)
F2-8	Журнал запусков	SQLite: timestamp, agent_role, plane_id, status, duration_sec, tokens_est
F2-9	Error handling	Retry ≤3 при crash/timeout, уведомление при исчерпании попыток

Критерий выхода: после push в ветку — Reviewer и Tester запускаются автоматически без участия Стрим.

Фаза 3: Plane интеграция

Цель: Plane как единая витрина, approve через reactions.

Фичи:

ID	Фича	Описание
F3-1	Plane webhook receiver	Эндпоинт `/webhook/plane`, парсинг событий work_item/comment
F3-2	QG-0: auto-bootstrap	При `work_item.created` → создать ветку + 7 подзадач + папку docs/
F3-3	Reaction listener	Парсинг `:approved:` / `:rejected:` → триггер QG-перехода
F3-4	Auto-Architect	При :approved: на подзадаче «Анализ» → QG-1 → запуск Architect
F3-5	Stage labels	Автоматическое обновление `stage:*` лейблов при переходах
F3-6	Custom fields sync	Заполнение qg_status, repo_branch, repo_pr через Plane API
F3-7	Progress checklist	Обновление чек-боксов в description Feature при прохождении QG
F3-8	Эскалация	При 3x back-to или timeout → лейбл `escalation:*` + уведомление Славе
F3-9	Plane → Стрим notify	Уведомление Стрим (через OpenClaw) когда нужен approve или эскалация

Критерий выхода: Слава создаёт Feature в Plane → ставит :approved: на ТЗ → дальше всё автоматически до "Готово, проверь".

Фаза 4: Полный конвейер

Цель: автономная работа с обратной связью и самовосстановлением.

Фичи:

ID	Фича	Описание
F4-1	Back-to: Reviewer→Dev	При request-changes → лейбл back-to:dev, перезапуск Developer (≤3)
F4-2	Back-to: Tester→Dev	При failed tests → issue в Plane, перезапуск Developer
F4-3	Back-to: Architect→Analyst	При противоречии в ТЗ → уведомление Стрим, ожидание правки
F4-4	Exponential backoff	При rate limit / timeout CLI → retry с 30s, 60s, 120s
F4-5	Метрики collection	Сбор: lead_time, tokens_spent, cost_usd, iterations_count
F4-6	Метрики в Plane	Обновление custom fields tokens_spent_usd, lead_time_hours
F4-7	Health dashboard	Plane View: blocked >24h, cost > threshold, back-to >2
F4-8	Graceful degradation	CLI недоступен → задача в очередь (не теряется), алерт
F4-9	QG-override	Поддержка `:break-glass:` от Owner для аварийного обхода QG
F4-10	Audit log	Полный журнал: запуски, QG-вердикты, overrides, эскалации

Критерий выхода: 5 фич подряд проходят конвейер без человеческого вмешательства (кроме постановки и финального approve).

Фаза 5: Оптимизация (v2)

Цель: масштабирование и расширение возможностей.

Фичи:

ID	Фича	Описание
F5-1	Designer-агент	Генерация UI-макетов (Figma MCP или HTML/CSS прототипы)
F5-2	Deployer: canary + rollback	Расширенный deploy: canary %, авто-rollback при ошибках
F5-3	Visual regression	Playwright screenshots + pixel diff, порог допустимых отклонений
F5-4	a11y тесты	axe-core интеграция в Tester, блокирующие нарушения = fail
F5-5	Performance scan	Lighthouse CI, бюджет метрик (LCP, CLS, FID)
F5-6	Security scan	Dependency audit + SAST (semgrep), блокирующие findings = fail
F5-7	Параллельные задачи	Второй аккаунт Max или API-ключ, 2 агента одновременно
F5-8	Multi-project	Поддержка нескольких репо (fr24-noisemap, snowbike-rag)
F5-9	Plane MCP-сервер	Обёртка над Plane REST API как MCP-tools для агентов
F5-10	Ephemeral preview	Docker-based preview env на каждый PR, auto-cleanup

Критерий выхода: система обслуживает 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 (фазы) реалистичен
Риски приемлемы

29 KiB Raw Blame History Unescape Escape

BRD — Мультиагентная разработка ПО

1. Цель и метрика успеха

2. Стейкхолдеры

3. Scope

В скоупе (пилот)

Вне скоупа (v1)

4. Архитектура (высокий уровень)

5. Производственный процесс

5.1. Структура репозитория (канон)

5.2. CLAUDE.md (паспорт проекта)

5.3. Формат запуска агентов

5.4. Обратная волна (back-to)

5.5. Эскалация

5.6. Идемпотентность и очередь

5.7. Service account в Git

5.8. Plane → Orchestrator: события

5.9. Tester — scope на пилоте

6. Quality Gates

7. Инфраструктура (что нужно поднять)

8. Бюджет и ограничения

9. Риски

10. Roadmap (фазы)

Фаза 0: Инфраструктура (фундамент)

Фаза 1: Ручной конвейер (валидация подхода)

Фаза 2: Orchestrator MVP

Фаза 3: Plane интеграция

Фаза 4: Полный конвейер

Фаза 5: Оптимизация (v2)

11. Definition of Done (BRD)

29 KiB

Raw Blame History