Оркестрация AI-агентов для программирования: уроки Brigadier

В Syncra мы делаем Brigadier (откроется в новой вкладке) — local-first десктопное приложение для длительных сессий программирования с AI-агентами. Оно в разработке, а его исходный код открыт на GitHub.

Идея простая. Вы общаетесь с одним оркестратором. Он планирует работу, раздаёт задачи воркерам, проверяет то, что они возвращают, и отчитывается перед вами. Воркеры — это агенты для программирования, которые уже установлены на вашей машине и в которых вы уже авторизованы; для начала это Claude Code и Codex. Под капотом — демон на Rust, который продолжает работать после закрытия окна, десктопная оболочка на Tauri и интерфейс на React.

Для широкого использования Brigadier пока не готов. Но проектные решения уже устоялись настолько, что их можно записать, и большинство из них пригодится любому, кто запускает больше одного агента одновременно.

1. Оркестратор только разговаривает

Оркестратор никогда не читает репозиторий, не выполняет команды и не редактирует файлы. Его единственные инструменты — те, что даёт ему Brigadier: делегировать задачу, написать воркеру, прочитать отчёт, задать вопрос пользователю, предложить план. Всё, что нужно изучить, уходит воркеру — часто разведчику с доступом только на чтение.

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

2. Воркеры отчитываются в фиксированном формате

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

Фиксированный формат делает отчёты сравнимыми, а пробелы — заметными. Отчёт с пустым разделом о проверке говорит сам за себя. Кроме того, Brigadier проверяет отчёты механически. Если в отчёте упомянут несуществующий файл или файл, который воркер оставил во временной папке, отчёт не принимается, а возвращается с инструкциями.

3. Один git worktree на воркера

Каждая задача, которая пишет код, выполняется в собственном git worktree, созданном от последнего состояния ветки сессии. Параллельные воркеры не могут перезаписать файлы друг друга, а неудачный эксперимент выбрасывается простым удалением папки. Параллельно выполняется только работа над разными файлами.

Вливание работы намеренно строгое. Готовая работа попадает в репозиторий коммитом от вашего git-имени. В вашу собственную рабочую копию она вливается только через fast-forward. Если вы переключили ветку, если ветка неожиданно сдвинулась или если будет перезаписан неотслеживаемый файл, работа ждёт в статусе «ready to land» («готово к вливанию»), и ничего не меняется. Ваши незакоммиченные изменения никогда не перезаписываются.

Агенты быстро пишут код и не особенно следят за тем, куда он попадает, поэтому аккуратным должен быть инструмент.

4. Ревью силами другого вендора

Модель, проверяющая собственную работу, склонна соглашаться сама с собой. В Brigadier работу проверяет модель другого вендора: работу Claude — Codex, работу Codex — Claude. Каждая фаза сессии завершается новым верификатором, который сам проводит это ревью и по-настоящему проверяет каждый критерий завершения.

«По-настоящему» здесь ключевое слово. Верификация — это проверка типов, линтер, сборка, существующий набор тестов и смоук-проверка в рантайме, а не модель, которая говорит, что работа выглядит правильно. В итоговом отчёте точно указано, что и как проверено, так что вы знаете, что проверили, а что нет.

5. Передача дел вместо сжатия контекста

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

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

За этим стоит то, что мы называем Project Brain: хранилище того, что Brigadier уже знает о проекте — модулях, соглашениях, прошлых решениях, — где у каждого знания записано, откуда оно взялось. На вопрос, на который уже однажды ответили, не нужно снова отправлять разведку. Когда меняются файлы, на которых основан ответ, ответ помечается как возможно устаревший.

6. Внешние действия остаются за людьми

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

Что ещё требует вашего одобрения, решаете вы, выбирая один из трёх уровней. В режиме Ask for approval вы утверждаете каждый план и каждое изменение, а воркеры работают в песочнице операционной системы. В режиме Approve for me Brigadier одобряет действия от вашего имени внутри песочницы и спрашивает только о том, на что можете ответить лишь вы. В режиме Full access воркеры работают так же, как ваш собственный терминал, а пока режим включён, на экране висит заметное предупреждение.

7. Не оставлять мусора

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

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

8. Используйте инструменты, которые у людей уже есть

Brigadier управляет консольными утилитами claude и codex ровно в том виде, в каком они установлены на вашей машине. Их учётные данные он никогда не читает. У Brigadier нет бэкенда, нет аккаунтов и нет телеметрии. Ваш код, ваши разговоры и то, что Brigadier узнаёт о вашем проекте, остаются на вашем компьютере.

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

Что сейчас

Brigadier в разработке. Исходный код открыт на GitHub (откроется в новой вкладке), а план в репозитории описывает, куда движется проект: сначала macOS, затем Windows и Linux.

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