Перейти к основному содержимому

Руководство: Мультиагентные проекты

Когда использовать мультиагентную координацию​

Ваша фича охватывает несколько доменов — бэкенд API + фронтенд UI + схема базы данных + мобильный клиент + QA-ревью. Один агент не справится с полным объёмом, и домены должны продвигаться параллельно, не затрагивая файлы друг друга.

Мультиагентная координация подходит когда:

  • Задача затрагивает 2+ домена (frontend, backend, mobile, db, QA, debug, pm)
  • Есть API-контракты между доменами
  • Нужно параллельное выполнение для сокращения времени
  • Нужно QA-ревью после реализации по всем доменам

Полная последовательность: /plan до /review​

Шаг 1: /plan — Требования и декомпозиция задач​

Рабочий процесс /plan выполняется инлайн и создаёт структурированный план: сбор требований, анализ целесообразности через MCP, определение API-контрактов, декомпозиция задач с приоритетами и зависимостями, ревью с пользователем, сохранение в .agents/results/plan-{sessionId}.json.

Шаг 2: /work или /orchestrate — Выполнение​

Аспект/work/orchestrate
ВзаимодействиеИнтерактивное — подтверждение на каждом этапеАвтоматическое
PM-планированиеВстроено (Шаг 2)Требует plan от /plan
ЧекпоинтПосле ревью плана (Шаг 3)Перед стартом (план обязателен)
ПостоянныйДаДа
Лучше дляПервое использование, сложные проектыПовторные запуски, чёткие задачи

Шаг 3: agent:spawn — CLI-управление агентами​

oma agent:spawn backend "Implement user auth API with JWT" session-20260324-143000 -w ./api

Шаг 4: /review — QA-верификация​

Полный пайплайн: автоматические проверки безопасности, OWASP Top 10, производительность, доступность WCAG 2.1 AA, качество кода. С --fix — цикл Fix-Verify до 3 раз.

Стратегия ID сессий​

Формат: session-YYYYMMDD-HHMMSS. Используется для именования файлов памяти, отслеживания процессов через PID-файлы, корреляции логов и группировки результатов.

Назначение рабочих пространств​

Автоматическое определение​

CLI сканирует конфигурации монорепозитория (pnpm-workspace.yaml, package.json, lerna.json, nx.json, turbo.json, mise.toml), оценивает директории по ключевым словам агента. Точное совпадение = 100, содержит = 50, путь содержит = 25.

Резервные кандидаты​

  • frontend: apps/web, apps/frontend, apps/client, packages/web, frontend, web, client
  • backend: apps/api, apps/backend, apps/server, packages/api, backend, api, server
  • mobile: apps/mobile, apps/app, packages/mobile, mobile, app

Явное переопределение​

oma agent:spawn frontend "Build landing page" session-id -w ./packages/web-app

Правило контрактов в первую очередь​

  1. Контракты определяются до реализации (Шаг 3 /plan)
  2. Каждый агент получает релевантные контракты
  3. Контракт определяет: HTTP метод/путь, схемы запроса/ответа, аутентификацию, формат ошибок
  4. Нарушения контрактов обнаруживаются при мониторинге через MCP
  5. QA проверяет соответствие контрактам

Шлюзы слияния: 4 условия​

  1. Сборка успешна — код компилируется без ошибок
  2. Тесты проходят — существующие тесты + новые для реализации
  3. Только запланированные файлы изменены — без побочных эффектов
  4. QA-ревью пройдено — ноль CRITICAL, ноль HIGH

Примеры запуска​

# Параллельный запуск из YAML
oma agent:parallel tasks.yaml

# Инлайн-режим
oma agent:parallel --inline \
  "backend:Implement user auth API:./api" \
  "frontend:Build login page:./web" \
  "mobile:Implement auth screens:./mobile"

# Фоновый режим
oma agent:parallel tasks.yaml --no-wait

Анти-паттерны​

  1. Пропуск плана — /orchestrate без plan file откажет. Всегда /plan или /work.
  2. Пересекающиеся рабочие пространства — два агента в одной директории = конфликты файлов.
  3. Отсутствие API-контрактов — несовместимые допущения о форматах данных.
  4. Игнорирование QA — CRITICAL/HIGH замечания = реальные баги в продакшене.
  5. Ручная координация файлов — автоматический пайплайн надёжнее.
  6. Преждевременный параллелизм — P1 до завершения P0 нарушает зависимости.
  7. Пропуск верификации — agent:spawn без verify.sh пропускает сбои сборки.

Кросс-доменная валидация интеграции​

  1. Соответствие API-контрактов — MCP-инструменты проверяют совпадение
  2. Консистентность типов — одинаковые имена полей и типы
  3. Поток аутентификации — JWT корректно передаётся и обновляется
  4. Обработка ошибок — все клиенты обрабатывают документированные ошибки
  5. Соответствие схемы БД — ORM-модели совпадают со схемой

Когда готово​

  • Все агенты во всех приоритетных уровнях завершены
  • Скрипты верификации проходят для каждого агента
  • QA: ноль CRITICAL и ноль HIGH
  • Соответствие API-контрактов подтверждено
  • Сборка успешна, все тесты проходят
  • Финальный отчёт записан в память
  • Пользователь дал финальное одобрение