Урок 3: Мультиагентные workflow

Чему вы научитесь

• Когда нужны мультиагентные системы (и когда они избыточны)
• DevSquad паттерн: один Manager, несколько исполнителей
• Как оркестрировать задачи между агентами
• Управлять состоянием между несколькими сессиями Claude Code
• Распределять большие проекты эффективно

Проблема: один агент — узкое место

Типичный сценарий:

• Проект из 5 микросервисов (разные языки)
• Deadline: 1 неделя
• Задачи независимые (backend, API, frontend, DevOps, docs)
• Один агент обрабатывает их по очереди → 5+ дней вместо 2-3

Решение: несколько агентов работают параллельно, каждый на своём модуле.

graph TB
    A["[AI] Engineering Manager<br/>(Claude)"] -->|"Задача: User Service"| B["[AI] Backend Agent"]
    A -->|"Задача: API Spec"| C["[AI] API Agent"]
    A -->|"Задача: Frontend"| D["[AI] Frontend Agent"]
    A -->|"Задача: DevOps"| E["[AI] DevOps Agent"]

    B -->|"готово: user_service.py"| A
    C -->|"готово: openapi.yaml"| A
    D -->|"готово: App.tsx"| A
    E -->|"готово: docker-compose.yml"| A

    A -->|"интеграция"| F["[+] Готовый проект"]

Часть 1: DevSquad паттерн

DevSquad — это паттерн организации, где:

1. Manager (Claude) — понимает весь проект, распределяет задачи, интегрирует результаты
2. Специалисты (Gemini, Code Llama, другие Claude sessions) — выполняют узкие задачи
3. Синхронизация — через файлы, API, shared state

Архитектура

graph LR
    subgraph "Project Manager (Claude)"
        M["Знает весь scope<br/>Распределяет задачи<br/>Контролирует сроки"]
    end

    subgraph "Backend Team"
        B["Python Backend<br/>SQL + FastAPI"]
    end

    subgraph "Frontend Team"
        F[" React Frontend<br/>TypeScript"]
    end

    subgraph "DevOps"
        D["Docker + K8s<br/>CI/CD"]
    end

    M -->|"Spec: User API"| B
    M -->|"Spec: UI Components"| F
    M -->|"Config: Deploy"| D

    B -->|"[+] user-service.py<br/>DB schema"| M
    F -->|"[+] UserList.tsx<br/>Hooks"| M
    D -->|"[+] docker-compose.yml<br/>GitHub Actions"| M

    M -->|"Интегрируем вместе"| G["Production Ready"]

Часть 2: Практический пример: DevSquad для стартапа

Сценарий: 3 разработчика должны сделать MVP за 3 дня

Проект: “ToDoApp” с backend, frontend, и DevOps.

Шаг 1: Manager создаёт план

File: project_spec.md

# ToDoApp MVP - 3 дня

## 1. Backend (Python)
- [ ] SQLAlchemy models (User, Todo)
- [ ] FastAPI endpoints (CRUD)
- [ ] JWT authentication
- [ ] Database migrations
- Deadline: День 1, 14:00

## 2. Frontend (React)
- [ ] Components: TodoList, TodoForm, UserProfile
- [ ] API integration (axios)
- [ ] Local state (zustand)
- [ ] Styling (Tailwind)
- Deadline: День 1, 18:00 + День 2, 10:00 (интеграция)

## 3. DevOps
- [ ] Docker для backend и frontend
- [ ] docker-compose (локальная разработка)
- [ ] GitHub Actions (CI)
- [ ] Deploy script (AWS)
- Deadline: День 2, 15:00

## Точки синхронизации
- День 1, 16:00: Backend готов, frontend интегрируется
- День 2, 11:00: Frontend + Backend работают вместе
- День 3, 10:00: DevOps интегрирует всё в CI/CD

Шаг 2: Manager распределяет задачи

Session 1 (Backend Agent):

claude "Ты разработчик backend-сервиса.

Требования из project_spec.md:
- SQLAlchemy models для User и Todo
- FastAPI endpoints (GET /todos, POST /todos, PUT /todos/{id}, DELETE /todos/{id})
- JWT authentication (login endpoint)
- Database migrations с Alembic

Файлы должны быть в папке backend/:
- backend/models.py
- backend/main.py
- backend/auth.py
- backend/migrations/ (init)

Тесты в backend/tests/:
- test_models.py
- test_auth.py

Deadline: 14:00 сегодня.
Синхронизируй OpenAPI spec в docs/api.yaml для frontend-команды."

Session 2 (Frontend Agent):

claude "Ты разработчик React frontend.

Требования:
- Компоненты в src/components/:
  - TodoList.tsx (список todos)
  - TodoForm.tsx (форма создания)
  - UserProfile.tsx (профиль юзера)
- API клиент в src/api/client.ts (axios)
- State в src/store/todoStore.ts (zustand)
- Используй OpenAPI spec из docs/api.yaml

Deadline: День 1 - компоненты готовы.
День 2 - интеграция с backend.

Файлы на выходе:
- src/components/
- src/api/
- src/store/"

Session 3 (DevOps Agent):

claude "Ты DevOps инженер проекта ToDoApp.

Требования:
- Dockerfile для backend (Python 3.11)
- Dockerfile для frontend (Node.js)
- docker-compose.yml (локальная разработка)
- GitHub Actions CI (.github/workflows/ci.yml):
  - Lint backend + frontend
  - Run tests
  - Build images
- Deploy script в scripts/deploy.sh

Синхронизируйся с backend-командой по DB migrations.
Синхронизируйся с frontend-командой по build command.

Deadline: День 2, 15:00"

Часть 3: Синхронизация между агентами

Метод 1: Общие файлы (git)

Manager проверяет статус:

# День 1, 15:00 - проверка прогресса

# Backend ready?
ls -la backend/main.py backend/models.py

# Frontend готов?
ls -la src/components/TodoList.tsx

# DevOps?
ls -la docker-compose.yml Dockerfile

# Всем: обновитесь в git!
git pull origin main
git push origin my-feature

Метод 2: Shared context (промпт-файл)

flowchart LR
  B["Backend Agent"] --> I["INTEGRATION.md"]
  F["Frontend Agent"] --> I
  D["DevOps Agent"] --> I
  I --> M["Manager проверяет"]
  M --> Q{"Blocker?"}
  Q -->|Да| N["Уведомление агенту"]
  Q -->|Нет| OK["Продолжение работы"]

File: INTEGRATION.md — синхронизационный файл

# Integration Status

## [+] Backend (завершено)
- API: http://localhost:8000
- OpenAPI docs: http://localhost:8000/docs
- Database: PostgreSQL localhost:5432/todoapp
- Credentials: demo/demo123

**Endpoints готовые:**
- GET /api/todos (список)
- POST /api/todos (создание)
- PUT /api/todos/{id} (обновление)
- DELETE /api/todos/{id} (удаление)
- POST /auth/login (авторизация)

**JWT format:**
- Header: Authorization: Bearer <token>
- Token lifetime: 24h

## Frontend (в процессе)
- API client: `src/api/client.ts`
- Готовые компоненты: TodoList, TodoForm
- Нужно: интеграция с backend (Day 2)

## DevOps (в процессе)
- docker-compose.yml для локальной разработки
- Нужно: GitHub Actions, deploy

---

## Blocking Issues
- Frontend: ждёт стабильного API (backend готов!)
- DevOps: ждёт список всех env variables

## Next Sync
- Time: День 2, 10:00
- Participants: все три агента
- Agenda: интеграция Backend + Frontend

Метод 3: API для синхронизации

Если агенты работают параллельно, используй shared API:

# sync_api.py - простой endpoint для синхронизации

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

# Shared state between agents
agent_status = {
    "backend": {"status": "in_progress", "completion": 80},
    "frontend": {"status": "blocked", "completion": 30},
    "devops": {"status": "waiting", "completion": 0},
}

@app.get("/status")
def get_status():
    """Получить статус всех агентов"""
    return agent_status

@app.post("/status/{agent_id}")
def update_status(agent_id: str, status: str, completion: int):
    """Обновить статус агента"""
    if agent_id not in agent_status:
        raise HTTPException(status_code=404)
    agent_status[agent_id] = {
        "status": status,
        "completion": completion,
    }
    return {"updated": agent_id}

@app.get("/blockers")
def get_blockers():
    """Получить список blocking issues"""
    return {
        "blocked_agents": [
            agent for agent, info in agent_status.items()
            if info["status"] == "blocked"
        ]
    }

Каждый агент может вызвать:

curl http://localhost:8000/status
# -> {"backend": {"status": "done", ...}, ...}

# Frontend узнал, что backend готов
# можно начинать интеграцию!

Часть 4: Когда нужны мультиагенты?

Используй мультиагенты, если:

[+] Проект большой: 5000+ LOC [+] Разные компетенции: backend, frontend, DevOps, docs — разные узкие места [+] Tight deadline: нужна параллелизация (3 дня вместо 10) [+] Разные языки: Python backend + React frontend + Bash DevOps [+] Большая команда: 3+ разработчика параллельно [+] Independent tasks: разные модули не блокируют друг друга (после спеки)

НЕ используй мультиагенты, если:

[-] Маленький проект: < 1000 LOC, 1-2 файла [-] Связанные задачи: backend зависит от API spec, которая еще не написана [-] Прототип: быстрое MVP, не важна архитектура [-] Один разработчик: один агент может обработать всё [-] Один язык: монолит на одном языке [-] Overhead > benefit: управление агентами займёт больше времени, чем выигрыш

Таблица: 1 агент vs мультиагенты

Часть 5: Инструменты для оркестрации

Вариант 1: claude-squad (самодельный)

# claude_squad.py

import subprocess
import json
import time

class Agent:
    def __init__(self, name, task_file):
        self.name = name
        self.task_file = task_file

    def run(self, prompt: str) -> str:
        """Запустить агент с промптом"""
        cmd = ["claude", prompt]
        result = subprocess.run(cmd, capture_output=True, text=True)
        return result.stdout

class Squad:
    def __init__(self):
        self.agents = {}
        self.results = {}

    def add_agent(self, name: str, task_file: str):
        """Добавить агента в squad"""
        self.agents[name] = Agent(name, task_file)

    def run_parallel(self, prompts: dict) -> dict:
        """Запустить всех агентов параллельно"""
        import concurrent.futures

        with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
            futures = {
                name: executor.submit(self.agents[name].run, prompt)
                for name, prompt in prompts.items()
            }

            results = {}
            for name, future in futures.items():
                results[name] = future.result()

        return results

    def wait_for_blockers(self, check_status_func, timeout=600):
        """Ждать, пока все blocking issues не разрешатся"""
        start = time.time()
        while time.time() - start < timeout:
            status = check_status_func()
            if not status.get("blockers"):
                return True
            time.sleep(30)
        return False
# Использование
squad = Squad()
squad.add_agent("backend", "backend_spec.md")
squad.add_agent("frontend", "frontend_spec.md")
squad.add_agent("devops", "devops_spec.md")

prompts = {
    "backend": "Напиши FastAPI приложение для todos с моделями...",
    "frontend": "Напиши React компоненты для todos...",
    "devops": "Напиши docker-compose и CI/CD...",
}

results = squad.run_parallel(prompts)
# Все три агента работают одновременно!

Вариант 2: OpenClaw — персональный AI-ассистент с поддержкой агентов

OpenClaw — open-source персональный AI-ассистент для управления email, календарём, браузером и чатами (WhatsApp/Telegram). Поддерживает запуск нескольких изолированных агентов, в том числе coding-агентов на разных LLM (Claude, GPT и др.).

Установка:

curl -fsSL https://openclaw.ai/install.sh | bash

Когда OpenClaw подходит:

• Нужно запустить несколько изолированных агентов (включая coding) в одном окружении
• Хочется управлять задачами через единый персональный ассистент
• Нужна поддержка разных LLM в одном интерфейсе

Когда лучше использовать другие инструменты:

• Для специализированной coding-оркестрации между агентами — используй Claude Squad (https://github.com/smtg-ai/claude-squad) или встроенные subagents Claude Code (Вариант 3)
• 1-2 агента — claude-squad.py из варианта 1 достаточно

Вариант 3: Subagents в Claude Code (встроенный механизм)

Claude Code нативно поддерживает систему subagents — специализированных агентов, которые работают в своём контексте и параллельно выполняют задачи.

Создание subagent — файл .claude/agents/backend.md:

---
name: backend-agent
description: Python/FastAPI разработчик, реализует backend задачи
---

Ты Python Backend разработчик.
Используй FastAPI, SQLAlchemy, pytest.
Следуй структуре проекта из AGENTS.md.

Делегирование задач через Agent tool (ранее Task tool, alias поддерживается; встроен в Claude):

claude "Ты Project Manager для ToDoApp.

Параллельно делегируй задачи subagents:
- backend-agent: создай SQLAlchemy модели User и Todo
- frontend-agent: создай React компоненты TodoList и TodoForm

Когда оба завершат — интегрируй результаты и убедись, что API и UI совместимы."

# Claude Code сам запустит subagents параллельно
# через встроенный Agent tool (Task tool — поддерживаемый alias)

Встроенные subagents Claude Code: Explore (исследование кода), Plan (планирование) и кастомные из .claude/agents/.

Антипаттерн: “Мультиагенты для всего”

[-] Неправильно:

Даже для маленькой задачи:
- Agent 1: валидирует email
- Agent 2: сохраняет в БД
- Agent 3: отправляет письмо

Результат: 3 сессии, 3 контекста, хаос синхронизации

[+] Правильно:

Маленькая задача → 1 агент за 5 минут
Большой проект → 3 агента параллельно, сроки критичны

Попробуйте сами

Задача: Создать мультиагентный workflow для маленького проекта.

1. Создайте project_spec.md с 3 независимыми задачами:

   ## Task 1: Backend (FastAPI)
   - [x] Endpoints
   
   ## Task 2: Frontend (React)
   - [x] Components
   
   ## Task 3: Tests
   - [x] Unit tests

2. Создайте 3 сессии Claude (или 3 /task в одной):

   # Session 1: Backend
   claude "Напиши FastAPI... (из Task 1)"
   
   # Session 2: Frontend (параллельно)
   claude "Напиши React... (из Task 2)"
   
   # Session 3: Tests (параллельно)
   claude "Напиши тесты... (из Task 3)"

3. Синхронизируйте результаты в INTEGRATION.md

4. Посмотрите на время: мультиагенты vs один агент

Ключевые выводы

1. Мультиагенты полезны только для больших проектов с параллельными задачами
2. DevSquad паттерн: 1 Manager + N специалистов
3. Синхронизация через git, файлы, или API
4. Overhead может быть больше, чем выигрыш на маленьких проектах
5. Масштабирование: когда контекст одного агента переполняется, мультиагенты спасают

Следующий урок

В уроке 4 мы разберём 10 антипаттернов, которые саботируют работу с AI-агентами, и как их избежать.