Исследования · Агенты и MCP

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

Один оркестратор, три узкие роли и изолированные worktree. Что сработало, когда восемь агентов строили восемь модулей в одной ветке, и с какими сбоями мы столкнулись по пути.

· 5 мин чтения

Запустить несколько агентов для написания кода одновременно легко, довести их работу до конца трудно. Проблема редко в скорости. Проблема в том, что происходит, когда их работа встречается: два агента правят один файл, скрипт одного агента затирает скрипт другого, а возобновлённый агент работает в двух экземплярах. В этой статье — схема, к которой мы пришли с июля по ноябрь 2026 года, один конкретный запуск, где восемь агентов построили восемь модулей личного приложения в одной ветке, и сбои, которые мы задокументировали по дороге.

Три роли, а не рой

Мы не пускаем равноправных агентов работать как попало. Одна сессия — оркестратор. Она планирует, делит работу на части, сама делает самое сложное рассуждение и сама пишет рискованный код. Субагенты нужны ровно по двум причинам: держать контекст оркестратора небольшим и получать взгляд, не привязанный к его собственному мнению. Каждая роль — короткий Markdown-файл со списком инструментов и настройкой модели.

Роль Модель Инструменты Контракт
Глубокий аналитик та же, что у сессии только чтение (Read, Grep, Glob, Bash) Возвращает вердикт, доказательства с file:line, риски и неизвестное, отвергнутые варианты. Выводы, а не выгрузку файлов.
Быстрый исполнитель небольшая дешёвая модель полные инструменты правки Выполняет инструкции буквально. Если что-то неоднозначно или не выполнено предусловие, останавливается и сообщает, а не импровизирует.
Критик та же, что у сессии только чтение Пытается опровергнуть артефакт. Сообщает только о блокирующих или серьёзных находках, не больше пяти, каждую с конкретным сценарием поломки. Если находок нет, прямо так и говорит.
Рисунок 1

Два решения пришли из опыта. Во-первых, глубокий аналитик работает на той же модели, что и оркестратор. Обычный совет — отдавать рассуждение более сильной модели, но у нас оркестратор и так самая сильная модель. Ценность делегирования не в дополнительном интеллекте, а в изоляции контекста и независимом втором мнении. Во-вторых, ограничения критика — часть описания его работы. Критик без ограничений выдаёт длинный список замечаний по стилю, и единственная настоящая ошибка теряется в нём. Ответ «существенных находок нет» должен быть допустимым, иначе критик что-нибудь придумает.

Случай: восемь агентов, одна ветка

26 октября 2026 года мы за один заход построили большой пакет функций для личного приложения планирования жизни. Функции разделились на восемь областей: привычки, поклонение, рост, тело, деньги, близкие, внутреннее состояние и платформа. Последовательность:

  1. ФундаментОркестратор первым коммитит общие контракты: интерфейсы, регистрацию через сканирование сборки, заготовки модулей.
  2. ИзоляцияКаждый агент получает свой git worktree, ветку, порты API и веба и свою базу данных.
  3. СборкаАгенты работают параллельно по письменному контракту, и создавать миграции им запрещено.
  4. ИнтеграцияОркестратор сливает восемь веток, чинит стыки и генерирует одну миграцию.
  5. ВыпускОдин pull request, одно ревью, один деплой, перед ним снимается резервная копия базы.
Рисунок 2

Основную работу по превращению параллельности в безопасную сделал фундаментальный коммит. Ещё до старта агентов оркестратор добавил точки расширения, которые понадобятся каждому модулю: интерфейсы для команд бота, текста, медиа и callback-кнопок; единый сервис уведомлений, через который проходит каждое напоминание; регистрацию MCP-инструментов через сканирование сборки, чтобы новый класс инструментов не требовал правки центрального файла. Для каждой области была создана и заготовка модуля. После этого агент мог добавить целую функцию, не трогая файлы, принадлежащие другому агенту.

Контракт был коротким общим документом с портами, именами баз, скриптами запуска и правилами. Одно правило оказалось решающим: агенты не создают миграции базы данных. Если бы каждый из восьми агентов сгенерировал миграцию от одного и того же снимка модели, при слиянии они бы конфликтовали. Вместо этого оркестратор слил все восемь веток, написал один интеграционный коммит и сгенерировал единственную миграцию из объединённой модели. Результат вышел одним pull request, в заголовке которого перечислены все восемь областей, и в тот же день был слит и задеплоен.

Что всё равно сломалось

Стыки сломались там, где контракт молчал. Бот маршрутизирует нажатия кнопок по короткому префиксу в данных callback. Два агента в отдельных worktree оба выбрали префикс md: один для кнопок лекарств, другой для кнопок настроения. Каждый модуль проходил свои тесты. Вместе же один модуль молча перехватывал кнопки другого. Исправление вышло тоже 26 октября: один префикс переименовали и добавили тест, который падает, если два модуля регистрируют одинаковый префикс. Общий урок: каждому общему пространству имён нужен реестр и тест на уникальность. Это касается префиксов callback, путей маршрутов, имён инструментов и ключей настроек. Одной фразы в контракте недостаточно.

Перед тем деплоем мы также пропустили полный сквозной прогон восьми наборов тестов на объединённом коде. Коллизия префиксов — ровно тот класс ошибок, который такой прогон ловит. Теперь интеграционные тесты на слитом коде мы считаем частью слияния, а не необязательной полировкой.

Задокументированные сбои

Вот те, что стоили реального времени, и правило, которое из каждого вышло.

  • Общая черновая папка. Субагенты одной сессии делят одну черновую папку. Один агент импортировал вспомогательный скрипт с общим именем, но другой агент уже заменил этот файл своей версией, нацеленной на другой репозиторий. В итоге в чужом репозитории появилось 43 дублирующихся issue. Все они были закрыты как «not planned», а не удалены, чтобы история оставалась честной. Правило: каждый агент работает в подпапке с именем своего проекта, имена скриптов несут префикс проекта, а любой скрипт, пишущий во внешнюю систему, получает цель явным аргументом.
  • Призрачные возобновления. После перезапуска интерфейс сообщил, что несколько агентов «не завершились». Мы их возобновили. На самом деле исходная сессия была жива, и теперь каждый агент работал дважды в одном worktree. Один из агентов заметил правки, которых не делал, остановился и спросил. Правило: перед возобновлением проверять, нет ли живой соседней сессии и свежих изменений файлов. В каждом задании также пишется: если git показывает правки, которых ты не делал, не трогай их и сообщи.
  • Команды остановки на всю систему. Шаг агента «остановить API» убил все запущенные процессы .NET, включая серверы других агентов. Правило: останавливать процессы по порту, а не по имени.
  • Потолки ресурсов. Каждый локальный API занимал примерно 1–2 ГБ памяти, поэтому восемь API и восемь браузеров одновременно на одной рабочей станции были нереальны. Правило: одновременно не больше одного API и одного headless-браузера, очередь определяет оркестратор.
  • Слишком много мелких pull request. В одном репозитории один запрос породил 12 pull request за день. Каждый запускал полный CI со сквозными тестами. При ограниченном бюджете CI это дорого. Правило: один запрос — одна ветка, отдельные коммиты, один pull request, один прогон CI, один деплой и меньше push.

Что теперь входит в каждое задание

Субагент знает только то, что написано в задании, поэтому большинство этих правил живёт именно там:

  1. Цель и то, что уже исключено.
  2. Конкретные файлы, worktree, порт и база, которыми он владеет, и то, чего ему трогать нельзя.
  3. Контракт результата: для анализа — вердикт и доказательства, для исполнения — точный список изменений и результаты тестов.
  4. Условия остановки: неоднозначность, неожиданные правки, невыполненное предусловие.
  5. Для записи во внешние системы цель называется явно и никогда не выводится из общих файлов.

Чего мы пока не знаем

  • У нас нет контролируемого сравнения одной и той же работы, сделанной одним агентом и восемью, поэтому мы не можем назвать цифру ускорения.
  • Лимит критика в пять находок — решение на глаз. Мы не измеряли, как часто он скрывает важную шестую находку.
  • Наши данные получены на одной рабочей станции и нескольких закрытых репозиториях. На удалённых изолированных раннерах проблемы общего состояния могут выглядеть иначе.

Повторите сами

Репозитории закрыты; эти команды воспроизводят ту же схему изоляции (по одному worktree и ветке на агента) в любом git-репозитории.

$ git worktree add ../app-habits -b life/habits
$ git worktree list
$ mkdir -p ~/.claude/agents
Репозиторий
Репозиторий закрыт; команды используют только публичные инструменты.
Материалы
wonmortech/research

Источники

  1. Agent role definitions in ~/.claude/agents (deep-reasoner, fast-worker, critic), 2026-07
  2. dtwinuz/dtwin PR #16 (eight modules, merged 2026-10-26) and PR #38 (callback prefix fix, 2026-10-26)
  3. dtwinuz/med-dtwin issues #57 to #99 (closed as not planned, 2026-11-02)
  4. Internal engineering notes, 2026-07 to 2026-11

Похожие материалы

Смотреть ещё