Supervisor + workers: паттерн координации

Спроектируй supervisor + workers систему для {{task_domain}}, workers: {{worker_count}}. Разделение труда — supervisor планирует и собирает, workers выполняют узкоспециализированные задачи.

1. Когда нужен паттерн (а когда нет)

Подходит когда:

• Задача распадается на N однотипных или разнотипных подзадач
• Workers могут быть узкоспециализированными (один tool-set, один фокус)
• Нужна изоляция контекста (worker не должен видеть всё)
• Supervisor не должен "пачкаться" исполнением

Не подходит когда:

• Одна линейная задача без декомпозиции (бери single agent)
• Workers зависят друг от друга на каждом шаге (бери pipeline)
• Цена spawn'а workers > выигрыша от параллели (короткие задачи)

2. Контракт supervisor → worker

worker_task:
  task_id: t_001
  type: "research" | "build" | "review" | "..."
  goal: "одно предложение"
  inputs:
    files: [...]    # минимально необходимое
    constraints: ["не трогай X"]
  tools_allowed: [Read, Grep, Bash]   # явный whitelist
  return_schema:
    status: "ok" | "partial" | "failed"
    output: <по типу task>
    evidence: [<пути/цитаты>]
    confidence: 0-100
  budget:
    max_tokens: 10000
    max_time_sec: 120

Каждое поле обязательное. Без tools_allowed worker выйдет за scope. Без budget — будет работать вечно.

3. Scoping контекста

Три уровня видимости:

Правило: никогда не передавай чат supervisor'а worker'у. Удваивает токены и смешивает контексты задач.

4. Race conditions и как их избегать

Сценарии:

• Два workers пишут в один файл → последний выигрывает
• Reviewer стартует пока builder не закончил → читает наполовину готовое
• Supervisor мержит результаты, пока worker ещё работает

Защита:

• Один writer на ресурс (worker A → apps/web, worker B → apps/api)
• Барьер sync перед мержем — supervisor ждёт все status перед сборкой
• Idempotent writes — если worker перезапущен, не должен сломать существующее
• Lease/lock на shared state — explicit acquire/release

5. Сборка результатов supervisor'ом

Алгоритм мержа:

1. Дождись все workers (или timeout) — собери все return-payload
2. Валидируй каждый по schema — отбрось malformed
3. Классифицируй: ok / partial / failed
4. Если все ok — мержи output по правилам типа task
5. Если есть partial — решай: достаточно для goal или нужно retry
6. Если failed ≥ threshold — escalate up (не маскируй провал)

Правила мержа зависят от типа:

• Research: union без дубликатов, source attribution
• Build: композиция файлов (один writer на файл — конфликта не будет)
• Review: список issues, дедуп по signature, приоритизация

6. Failure modes

7. Метрики

• dispatch_latency — от plan до старта worker'а (target ≤ 5s)
• worker_success_rate — ok / всего (target ≥ 80%)
• merge_conflicts — сколько раз пришлось решать конфликт writes (target = 0)
• supervisor_token_share — supervisor / total (target ≤ 20%, иначе он делает работу)
• rework_rate — workers переделали то, что supervisor зафиксировал (≥ 10% — слабый контракт)

8. Anti-patterns

• ❌ Supervisor сам читает 100 файлов и решает — это уже не координатор, а god-agent
• ❌ Workers получают весь чат supervisor'а — токены и потеря фокуса
• ❌ Свободная форма return вместо schema — supervisor не сможет автоматически мержить
• ❌ Нет budget на worker — "зависший" worker блокирует весь pipeline
• ❌ Два workers пишут в один файл — race на каждом запуске
• ❌ Supervisor стартует мерж до status всех workers — частичные данные
• ❌ Workers видят tools, которые им не нужны — выйдут за scope
• ❌ Failed worker маскируется как ok с пустым output — фейковый успех
• ❌ Один и тот же worker на похожие задачи последовательно — теряем смысл параллели
• ❌ Supervisor продолжает работу с partial без явного решения — деградация качества молча

Deliverable

• Диаграмма supervisor + N workers с явными контрактами
• Schemas: worker_task и worker_return (YAML / JSON)
• Алгоритм мержа для конкретного task_domain
• 6 метрик с порогами
• Список tool-whitelist для каждого типа worker'а