Multi-agent: координатор и специалисты

Спроектируй multi-agent систему для цели {{goal}}. Координатор + специалисты, без хаоса.

1. Когда нужна команда (а не один агент)

Multi-agent оправдан, если:

• Цель распадается на 3+ разных навыка (research / code / review / deploy)
• Большая часть подзадач параллелится
• Нужна изоляция контекста (специалист не должен видеть всё)
• Один агент с 30 tools начинает путаться

Иначе — один агент с хорошим промтом дешевле и надёжнее.

2. Роли

Правило: координатор не делает работу, только разбивает и собирает. Если он начал писать код — это уже один большой агент, не команда.

3. Контракт между координатором и специалистом

Координатор передаёт:

{
  goal: "одно предложение",
  context: { ... минимум, без лишнего ... },
  constraints: ["не трогай X", "уложись в N токенов"],
  return_schema: { ... жёсткая форма ... }
}

Специалист возвращает:

{
  status: "ok" | "partial" | "failed",
  output: <по схеме>,
  evidence: [<ссылки на файлы/цитаты>],
  open_questions: [],
  confidence: 0-100
}

Без жёсткой схемы — координатор не сможет автоматически мержить.

4. Передача контекста

Три уровня:

• Shared brief — общий контекст цели, статичен (видит каждый)
• Task input — что нужно именно этому специалисту
• Working state — что нашёл текущий агент (его и только его)

Никогда не передавай весь чат координатора специалисту — это удваивает токены и сбивает фокус.

5. Параллель vs последовательность

Параллель когда:

• Задачи независимы (research API A и research API B)
• Нет shared write-target
• Контракт возврата простой

Последовательность когда:

• Выход одного — вход другого (research → plan → build → review)
• Нужен gate (review перед deploy)
• Меняется один файл несколькими шагами

Параллель + последовательность нормально комбинируется: research (parallel x3) → plan (one) → build (one) → review (parallel x2).

6. Race conditions

Когда они появятся:

• Два builder'а правят один файл
• Reviewer стартует пока builder не закончил
• Координатор читает результат до того как агент дописал

Защита:

• Один writer на файл (builder A → apps/web, builder B → apps/api)
• Явные barrier'ы: координатор ждёт все status: ok перед следующей фазой
• Идемпотентность: повторный вызов специалиста с теми же входами — тот же результат
• Атомарные коммиты: специалист коммитит сразу после своей фазы, не оставляет грязное дерево

7. Дедупликация

В команде легко повторить работу:

• Два специалиста читают один и тот же огромный файл → cache в shared brief
• Координатор повторно зовёт research после небольшого изменения цели → diff и переиспользуй

Введи "memo" — то что уже найдено и проверено. Перед спавном агента — посмотри в memo.

8. Обработка отказов

Координатор не должен слепо доверять — он арбитр, не клерк.

9. Метрики системы

• Глубина цепочки (хорошо ≤ 3 уровня)
• Wall-clock vs sum of tokens (есть ли реальный параллелизм)
• % retry от specialist'ов (>20% = слабые промты или плохая декомпозиция)
• Cost per goal (растёт нелинейно с количеством агентов — следи)

10. Анти-паттерны

• Координатор делает работу сам
• Специалисты пишут в один и тот же файл
• Передача 100% контекста каждому
• Цепочка > 4 уровней
• Нет жёсткой схемы возврата — мерж "глазами"
• Один specialist берёт сразу 5 целей

На выходе

• Список ролей с tools и зонами ответственности
• Диаграмма (ASCII): кто кого спавнит, что передаёт
• Шаблон контракта запрос/ответ
• Правила параллели и barriers
• 3 e2e сценария — happy / partial-failure / race