Оркестрация ИИ‑агентов: когда нужно поправить в одном месте и не сломать всё остальное

Оркестрация ИИ-агентов: когда нужно поправить в одном месте и не сломать всё остальное

Средний

12 мин

0

Кейс

Меня зовут Максим Никитин, я фаундер небольшой, но гордой студии ITSalt. Сегодня MVP или небольшую разработку для себя с ИИ-агентом может сделать каждый, и это действительно легко: открыл Claude Code или Codex, описал, что нужно, поправил пару раз, и готово. Сложности начинаются, когда мы доходим до продакшн-решений, нагруженных систем или проектов, где функциональных модулей или доменов предметной области больше одного.

Такие задачи встречаются у нас постоянно, возьму для примера одну из них. В проект zaryady.ru для управления зарядными станциями понадобилось добавить блок работы с корпоративными клиентами, а не только с частными лицами. После планирования стало понятно, что изменения нужно синхронно внести в 6 репозиториев, причём так, чтобы не просто не сломать то, что уже работает, а чтобы всё это ещё и заработало вместе. Задача меняет код сразу в нескольких местах, и очень легко поправить в одном месте и сломать в другом. Если разложить это на части, проблем у ИИ-агента на большой системе несколько, и все они давно известны.

• Агент видит только кусок системы. Всё, что он знает о проекте в данный момент, должно поместиться в его контекстное окно, а большая система туда не влезает. И даже то, что влезло, он использует хуже, чем хотелось бы: с ростом контекста ответы становятся менее надёжными (Context Rot, 2025), а середину длинного контекста модели замечают хуже, чем начало и конец (Lost in the Middle).

• Скрытые связи между модулями. Агент меняет функцию, формат ответа API или поле в базе и не знает, что тем же самым пользуются ещё три места в соседнем репозитории. Локально всё зелёное, а ломается то, что он даже не открывал.

• Агент проверяет себя сам. Тесты пишет тот же агент, что и код, поэтому они проверяют ровно то, о чём он подумал.

• Память заканчивается вместе с сессией. Решения, договорённости и причины, почему сделано именно так, живут в чате. Новая сессия начинает с нуля и легко отменяет то, о чём договорились вчера.

На маленьком проекте всё это почти не мешает: ты держишь систему в голове и ловишь ошибки глазами. До определённого масштаба всё можно делать нативно и итерационно, а после определённой точки так уже не получится.

Для работы со спецификацией уже есть методы вроде SDD (spec-driven development, разработка от спецификации) и наш NaCl, который развивает идеи SDD. С ними агент быстро разбирается в проекте и получает нужный контекст. Но я хочу поговорить о следующем этапе. Спецификация есть, но она очень большая и одним запуском в один контекст не помещается: модулей несколько, репозиториев несколько, предметная область объёмная или просто реализации много. Спецификацию корпоративных клиентов для zaryady.ru целиком в одну сессию агента не положишь.

Для этого я написал плагин pepper-orchestrator, который работает в Claude Code и в Codex.

Он делает три вещи. Берёт чёткую цель в виде программы, делит её на составляющие и запускает их. Ускоряет работу, потому что несвязанные или слабо связанные части идут параллельно, каждая у своего агента, и при этом контекст не теряется. И не просто машет дирижёрской палочкой, а отправляет каждый сделанный кусок на независимую проверку. В этой статье я расскажу, как устроены все три, и покажу их на реальном кейсе от первой команды до закрытия программы. А заодно и то место, где узким местом оказался не агент, а я сам :)

Откуда взялась концепция

Плагин вырос как раз из этого модуля zaryady.ru. Мы отладили на нём идею оркестрации (12 дней, около 40 пакетов работ, выкатка на прод), всё, что там ломалось, превратили в правила, а правила в код плагина. Дальше пользуемся им сами и предлагаем пользоваться всем.

Все связи идут через оркестратор: сессии модулей между собой не договариваются, задания, состояние и приёмка проходят через него, поэтому картину всей программы держит одно место. Ролей четыре.

• Владелец, то есть человек. Ставит цель, принимает решения по продукту и рискам, запускает сессии и делает всё необратимое: merge, деплой, прод, права.

• Оркестратор, одна сессия в домашнем репозитории программы. Единственная точка входа для владельца. Планирует, режет работу на пакеты, говорит, какую сессию запустить, проверяет результат и ведёт журнал. Код модулей не пишет никогда, даже “чуть-чуть поправить”.

• Сессии модулей, каждая в каталоге своего репозитория или в своём worktree. Реализуют свой пакет: ветка, код, тесты, PR с отчётом. Не мержат и не деплоят.

• Субагенты оркестратора, одноразовые. Читают много файлов, ревьюят PR, гоняют тесты в одноразовом клоне и возвращают оркестратору выводы, а не содержимое файлов.

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

Кейс, на котором всё видно

Программу на 6 репозиториев и 40 пакетов в статью не уместить, поэтому покажу механику на кейсе поменьше, где она видна целиком за один день. Одна компания искала подрядчика на разработку крупного продукта и предложила потенциальным подрядчикам тестовое задание: за 4 часа собрать прототип для специалиста по закупкам. Закупщик загружает TXT-файлы договоров, допсоглашений и писем и получает таблицу “номер, поставщик, сумма, срок поставки” на дату проверки, где у каждого значения есть точная цитата из документа, а если значения нет, честное “нет данных”. Шесть учебных документов написаны с ловушками: аванс в 252 000 рублей рядом с ценой, лимит “не более 600 000” вместо суммы, срок оплаты рядом со сроком поставки. LLM внутри приложения задание не требовало и не запрещало, и я обошёлся без неё: за 4 часа промпты для надёжного разбора не отладить, а проверяющему пришлось бы подключать свои ключи. Поэтому документы разбирали алгоритмами по типовым ситуациям.

Репозиторий здесь один, но работа делится на пакеты, и при параллельной работе они правили общие файлы, так что основные проблемы большой разработки проявились и здесь, только в миниатюре. Код я не писал ни строчки, весь день был владельцем программы.

Первое: цель становится программой, программа становится пакетами

Всё начинается с того, что у программы одна цель и проверяемое условие завершения. Команда init создаёт рабочее пространство, а оркестратор до того, как что-то создать, задаёт вопросы: какие разрешения, как разложить репозитории, что с GitHub.

Каждый мой ответ записывается в журнал решений с номером, и на него потом ссылаются все сессии. Здесь я сразу отдал оркестратору то, что по умолчанию остаётся за мной: “Ты сам пушишь и мержишь”. Ручной merge это страховка для серьёзных проектов, а когда процесс можно упростить, почему бы этим не воспользоваться. Я разрешил оркестратору сливать принятые пакеты самому, но только своей командой доставки и только когда все проверки пройдены.

Дальше plan. Я попросил спланировать работу по заданию, задать вопросы по развилкам, взять дизайн-систему из нашего проекта procontent и обойтись без LLM. Продуктовые развилки оркестратор сам не решает, а выносит владельцу с вариантами и рекомендацией. Здесь их было четыре: стек, дизайн, как закупщик получает ответы на вопросы задания и откуда берётся дата проверки.

Результат планирования это не список задач, а пакеты работ, и именно в них решается проблема контекста. Сессия модуля не получает всю программу целиком. Она получает свой пакет: репозиторий, ветку, разрешённые пути, зависимости от других пакетов, факты, объём с явным “не входит”, проверяемые критерии приёмки и короткий стартовый промпт. Запускается она в каталоге своего модуля, поэтому подхватывает его CLAUDE.md, правила, MCP и скиллы. В контексте сессии одна задача, а вся программа живёт у оркестратора и в файлах, а если проект ведётся по методологии NaCl, то в графовой базе данных.

Так перестают быть скрытыми и связи между модулями. В плане записано, какой пакет от какого зависит и какие общие части они трогают, поэтому оркестратор запускает и сливает пакеты в правильном порядке и видит пересечения до того, как они что-то сломают.

В кейсе пакетов вышло три: движок разбора с тестами, интерфейс и записка. Модель выбирается под пакет, и Opus с высоким усилием достался движку, потому что работоспособность и источники вместе давали 55% оценки. А ловушки задания оркестратор вынес прямо в критерии приёмки движка, плюс отдельная проверка, что в коде нет вшитых номеров, сумм и имён файлов.

Сам оркестратор свой контекст тоже бережёт. Всё, что требует чтения многих файлов или долгого прогона, уходит субагенту, а в контексте остаются выводы. Состояние программы живёт не в памяти сессии, а в файле состояния: таблица пакетов, очередь владельца и журнал событий, где каждая строка подтверждена фактом. Любую сессию оркестратора можно потерять, открыть новую, сказать resume, и она восстановится по файлам плюс сверке с реальностью: живые сессии, PR, CI, ветки.

Второе: параллельно, но без конфликтов

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

Ответ был честный: да, минут на 30-45, но только на той работе, которая не ждёт движка. Мешало одно правило плагина: в одной копии репозитория пишет только одна сессия, иначе агенты затирают правки друг друга. Поэтому оркестратор предложил вынести дизайн-систему из интерфейса в отдельный пакет и пустить три пакета параллельно (движок вместе с экраном результатов, дизайн-систему и записку), каждый в своей копии репозитория и со своими файлами. Общие файлы, которые нужны всем, правит по очереди кто-то один, и сливаются пакеты тоже по очереди. Так пересечения видны заранее, ещё до того, как два агента полезли в один файл.

Я согласился. Оркестратор перестроил план, выдал мне команды для запуска новых сессий и сам предупредил уже работающую сессию движка, что правила поменялись. Сессии и оркестратор пишут друг другу только короткое “готово, смотри там-то”, а всё содержимое лежит в файлах: сообщение может потеряться, файл нет. Если сообщение всё же не дошло, оркестратор сам увидит готовую работу в репозитории.

Ещё в кейсе нашлась ошибка в самом плагине. Его очередь слияний ждала проверки на стенде, а у локального приложения стенда нет, так что второе слияние не случилось бы никогда. Оркестратор обошёл проблему, записал это в журнал и спросил меня, публиковать ли отчёт об ошибке. Я сказал да, так появился issue #43 в репозитории плагина.

Третье: независимая проверка

Правило концепции звучит так: сообщение агента “готово” это заявление, а не факт. Когда сессия сдаёт пакет, оркестратор не принимает его на слово. Первую сдачу проверяет субагент-рецензент с чистым контекстом, и бриф у него устроен строго. Он читает код только из репозитория, в рабочую папку исполнителя не заходит, а тесты гоняет в отдельной одноразовой копии. Получает не “проверь всё”, а конкретные вопросы по рискам этого пакета. И нарочно ломает код: убирает ключевую строку и смотрит, заметят ли это тесты.

Дизайн-систему приняли с первого раза. С движком вышло интереснее. Его сессия сдала работу, все её тесты были зелёными, на учебных договорах всё сходилось. Рецензент, для которого код был чужим, пересказал те же пункты договора своими словами, десятью разными способами, и на трёх движок ошибся. Причём ошибся уверенно, без пометки о сомнении: аванс в 252 000 рублей принял за сумму договора, лимит “не более 600 000” тоже за сумму, а срок оплаты за срок поставки.

Все тесты зелёные, а сумма договора неверная.

Это ровно те ловушки, что были в задании, только сказанные чуть иначе, чем в учебном файле, на котором агент писал свои тесты. Тесты, которые написал тот же агент, проверяют то, о чём он подумал, а чужой взгляд находит то, о чём он не подумал. Оркестратор вернул пакет на доработку с точным списком, что и где сломано, и, судя по тону отчёта, разве что не потирал ручки. Вторую сдачу он проверил уже сам: теперь на сомнительных формулировках движок не угадывает, а честно помечает значение как требующее проверки. Пакет приняли.

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

Что мы ставим поверх плагина

К 13:32, через 1 час 52 минуты после начала, оркестратор решил, что всё сделано, и предложил закрыть программу. Все пакеты закрыты, незавершённых работ нет, формально так и было. Но любая сдача у нас проходит проверку методом старухи Шапокляк: на продукт смотрят три клиента, которые не видели кода. Лояльный проверяет ровно то, что написано в задании. “Дурак” делает всё не так, как задумано, и всё равно хочет, чтобы работало. Конкурент хочет нас завалить и ищет каверзы на краях задания. Это не правило плагина, а наша методика, оркестратор просто удобно её запускает.

Каждого клиента сыграл субагент с чистым контекстом. Ему дали задание, README и учебные документы, и он написал свои сценарии, а оркестратор прогнал все 48 в настоящем браузере, пока я пил кофе.

Лояльный и “дурак” почти ничего не нашли. А конкурент нашёл два места, где программа уверенно ошибалась: в сумме договора и в том, какое допсоглашение действует. Рецензент проверял код, а конкурент проверял продукт, поэтому и нашёл то, до чего рецензент не дошёл.

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

Где ошибся я

Сдали мы работающее приложение: все тесты зелёные на чистой машине, повторная приёмка тремя клиентами прошла без провалов, агент развернул приложение по инструкции. По токенам весь день съел примерно 10% недельного лимита тарифа Claude Max. А вот по календарю вышло 5 часов 16 минут при бюджете 4 часа, и это моя ошибка как менеджера.

После прогона тремя клиентами, через 2 часа 23 минуты после начала, работу уже можно было сдавать. Я принял другое решение: сначала исправить то, что нашёл конкурент, а упаковать сдачу потом. Рисков этого решения я не проработал, и они сработали все сразу. Доработки заняли больше времени, чем казалось. Железо перестало тянуть: тесты и эмуляция браузера шли на одном VPS с 8 ядрами и 18 ГБ памяти, где крутились и другие проекты.

Мы начали торопиться, и оркестратор, спеша к дедлайну, стал ошибаться в собственных скриптах. А когда я попросил проверить, заведётся ли всё у проверяющего, он разогнался до матрицы из трёх версий Node в чистых контейнерах, и пришлось тормозить: “Не перемудри”. Оставалось 20 минут, ладошки начинали потеть.

Всё это последствия, а причина одна: неверное управленческое решение. Сначала нужно было упаковать сдачу и только потом улучшать, и истина “лучшее враг хорошего” подтвердилась ещё раз. Оркестратор снимает с владельца диспетчерскую работу, но цель, приоритеты и умение вовремя остановиться остаются за человеком.

Когда это нужно

Оркестратор окупается там, где начинаются проблемы масштаба: работа затрагивает два и больше репозитория, модуля или домена, не влезает в одну сессию, есть прод и риск сломать соседнее, а по ходу нужны решения владельца. Для одной правки в одном репозитории это лишние накладные расходы. Мой кейс был на нижней границе: прототип без прода, но с жёстким окном в 4 часа и параллельной работой на общих файлах. На программе в 6 репозиториев и 40 пакетов те же три механизма работают так же, просто дольше.

Агентов оркестратор умнее не делает. Он меняет то, как устроена работа вокруг них, и поэтому с ними можно работать дальше и после той точки, где нативно и итерационно уже не получается. Попробовать проще всего на задаче, которая затрагивает хотя бы два репозитория или модуля с общими частями: на одной правке в одном месте разницы вы не увидите. Как поставить плагин, ниже. А если что-то сломается, пишите issue: оркестратор, как вы видели, сам поможет его оформить.

Дополнительные материалы

• Плагин pepper-orchestrator: https://github.com/ITSalt/PepperSkills/tree/main/plugins/pepper-orchestrator (README на русском и концепция с правилами работы).

• Фреймворк NaCl для полного цикла разработки: https://github.com/ITSalt/NaCl

• Полный лог тестового задания с 61 скриншотом: https://itsalt.github.io/stn-contract-checker/

• Репозиторий результата: https://github.com/ITSalt/stn-contract-checker (приложение, отчёт о вайбкодинге в README, материалы эксперимента в docs/experiment/: план, решения, отчёты ревью, приёмка тремя клиентами, снимки версий).

Установка в Claude Code:

/plugin marketplace add ITSalt/PepperSkills
/plugin install pepper-orchestrator@pepperskills

Установка в Codex:

codex plugin marketplace add ITSalt/PepperSkills
codex plugin add pepper-orchestrator@pepperskills

features/<program>/
  README.md        что за программа, где что лежит
  PLAN.md          цели, объём, волны, гейты, риски
  status.md        единственный источник состояния: пакеты, очередь владельца, журнал
  decisions.md     решения D-n, допущения A-n, вопросы Q-n (только дописывается)
  work-packages/   WP-<MOD>-NN-<slug>.md
  reports/         отчёты ревью, проверок, гейтов
  release/         листы выкатки, runbook, rollback

DRAFT → READY → DISPATCHING → IN_PROGRESS → REVIEW
  ├─ REVISE (точечные пункты) → пересдача → REVIEW
  └─ ACCEPTED → MERGED → проверка на стенде → PROD → DONE