Несколько ИИ-агентов в разных репозиториях

Несколько ИИ-агентов могут безопасно менять разные репозитории, только если работают по одному версионируемому плану изменений, а результат проходит исполняемые проверки. Одинаковое описание задачи в промпте каждого агента еще не создает координацию. Каждый агент по-своему заполнит пробелы, и вполне разумные локальные решения могут вместе привести к неработающему релизу.

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

Координация начинается с единого плана изменений

Единый план изменений должен описывать целевое состояние, промежуточные состояния и доказательства, необходимые для перехода между ними. Без этого каждый репозиторий становится отдельным источником истины. Агент, меняющий API, может считать, что клиенты обновятся первыми, а агент клиента может рассчитывать, что сервер некоторое время принимает оба формата. По отдельности оба патча выглядят правильными.

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

Для любого изменения через границу сервисов я использую такой манифест:

change_id: checkout-address-v2
contract_revision: 7c92e41
coordinator: platform-payments
repositories:
  - name: checkout-api
    owns: [openapi, compatibility-handler]
    base: 4db31c8
  - name: web-checkout
    owns: [client, browser-flow]
    base: 81f772a
  - name: order-worker
    owns: [event-consumer, replay-test]
    base: c602ab4
sequence:
  - checkout-api-compatible
  - order-worker-compatible
  - web-checkout-producer
remove_after: all-consumers-on-v2
proof:
  - provider-contract
  - consumer-contract
  - staging-address-flow

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

Плану также нужны инварианты на обычном языке. Например: старые клиенты могут отправлять address_line; новые клиенты отправляют address.lines; во время миграции API принимает оба варианта; событие содержит оба варианта, пока не подтверждено развертывание обработчика; ни один агент не может менять округление денежных сумм. Такие формулировки выявляют предположения, которые одна схема передать не может.

Зафиксируйте план на одну волну работ. Если агент обнаружит ошибку в контракте, он должен остановиться и предложить новую ревизию плана. Если разрешить ему незаметно улучшить контракт, в одной партии окажутся два поколения изменений.

Общие контракты должны исполняться

Контракт приносит пользу, когда CI может отклонить расхождение. Проектная записка помогает людям понять намерение, но не определит, что один агент переименовал допускающее null поле, изменил перечисление или истолковал отсутствие значения как ноль. Положите рядом с текстом машиночитаемые интерфейсы: OpenAPI для HTTP, Protocol Buffers или другую схему для сообщений, SQL-миграции для хранилища и явные фикстуры для поведения, которое система типов выразить не может.

Спецификация OpenAPI описывает API без доступа к исходному коду или сетевому трафику. Такое разделение как раз нужно для работы с несколькими репозиториями. Зафиксируйте документ по коммиту или неизменяемому дайджесту артефакта и генерируйте либо проверяйте каждую участвующую сторону по одной ревизии. Не поручайте двум агентам независимо создавать совпадающие схемы.

Компактный фрагмент совместимости может выглядеть так:

AddressInput:
  type: object
  properties:
    address_line:
      type: string
      deprecated: true
    address:
      type: object
      required: [lines]
      properties:
        lines:
          type: array
          minItems: 1
          items:
            type: string
  anyOf:
    - required: [address_line]
    - required: [address]

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

Команды часто называют сгенерированные типы контрактом. Так синтаксис смешивается с поведением. Типы могут доказать, что lines содержит массив строк, но ничего не скажут о правилах удаления пробелов, порядке, идемпотентности, авторизации, повторах или смысле пустого массива. Добавьте именованные примеры и проверки такой семантики. Если агент может написать две правдоподобные реализации, удовлетворяющие типу, контракт не завершен.

Здесь полезны контрактные тесты, управляемые потребителем, но с одной оговоркой. Документация Pact ясно описывает процесс: потребитель записывает свои ожидания, а поставщик воспроизводит эти взаимодействия на запущенном экземпляре. Pact также подчеркивает, что публикация контракта закрывает лишь половину цикла; командам нужны результаты проверки поставщика, чтобы понять, можно ли развернуть версию. Я согласен, но не позволяю потребителю диктовать незадокументированное поведение предметной области. Владелец интерфейса проверяет новые ожидания до того, как они станут условиями релиза.

Границы владения должны охватывать решения

Владение файлами не предотвращает несогласованные изменения, потому что опасные конфликты возникают между файлами. Один агент может владеть репозиторием API, а другой репозиторием обработчика, но оба независимо решат, что означают null, повторная попытка или повторная доставка. Сначала определите владельцев решений и инвариантов, затем свяжите эти решения с файлами.

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

Запись о владении может быть короткой:

• Команда checkout API владеет семантикой проверки адреса и документом OpenAPI.
• Веб-команда владеет поведением формы, но не может добавлять ожидания от сервера без проверки контракта.
• Команда заказов владеет обработкой событий и безопасностью повторного воспроизведения, но не определениями полей событий.
• Координатор владеет окном совместимости и очередью слияния.

Это не бюрократия ради процесса. Агентам разработки нужна узкая область решений. Промпт «обнови обработчик для address v2» подталкивает агента исправить соседние схемы, переименовать общие понятия и нормализовать данные по локальным правилам. Задание «используй ревизию контракта 7c92e41, сохрани воспроизведение v1, меняй только эти пути и сообщи о любом недостающем семантическом правиле» оставляет свободу реализации, но не передает архитектурные полномочия.

Закрепите ту же границу политикой репозитория. Проверка владельцами кода должна охватывать файлы контрактов, миграции базы данных, общие определения рабочих процессов и адаптеры совместимости. Запретите ручные правки сгенерированных результатов. Если агент затронул путь за пределами заявленной области, CI должен направить изменение координатору, даже когда тесты проходят.

Не размывайте владение между группой участников. Если два агента могут менять канонический контракт, вы создали гонку. Один добавит поле ради своих тестов, пока другой сузит перечисление ради другого потребителя. Поручите одному заданию изменить контракт, влейте или зафиксируйте эту ревизию, а затем дайте агентам реализаций использовать ее.

Агентам нужна изолированная работа и закрепленные входы

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

Запишите базовые коммиты и ревизию контракта до начала волны. Агент должен указать их в результате вместе с измененными путями и командами тестов. Тогда координатор отклонит патч с устаревшей базой, не читая весь diff.

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

Долго работающим агентам нужна проверка расхождения. Перед передачей результата агент должен получить целевую ветку, найти общего предка и показать diff от этой точки. Команда Git merge-base находит лучшего общего предка для трехстороннего слияния, а git diff origin/main...HEAD показывает работу после этой общей точки. Для проверки это надежнее, чем воспоминания агента о сделанных изменениях.

git fetch origin main
git merge-base origin/main HEAD
git diff origin/main...HEAD

Ожидаемый результат состоит из хеша коммита и патча. Координатор сравнивает хеш с базой в манифесте и сверяет измененные пути с объявленным владением. Если целевая ветка сдвинулась, перестройте ветку на новой базе и повторно запустите приемочные тесты до попадания в очередь интеграции.

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

Интеграционные тесты должны стоять на стыках сервисов

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

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

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

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

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

Относитесь к тестовым артефактам как к доказательствам для релиза. Храните вместе версию поставщика, версию потребителя, ревизию контракта, окружение и результат. Фразы «CI был зеленым» недостаточно, если пять конвейеров работали с разными коммитами. Координатор должен ответить, какая точная комбинация прошла проверку.

Локально зеленое изменение все равно может сломать релиз

Представим checkout API, браузерный клиент и обработчик заказов в разных репозиториях. Три агента получают одну просьбу: заменить address_line на структурированные строки адреса. Каждый создает разумный патч и проходит локальные тесты.

Агент API делает address обязательным и перестает выдавать address_line. Его тесты используют новые фикстуры. Агент браузера отправляет address и принимает новый ответ API. Агент обработчика читает address.lines[0], но в тестах строит события напрямую и не берет записанное событие v1. Все репозитории становятся зелеными.

Первым сливается браузер. В рабочей среде все еще работает старый API, поэтому запросы оформления заказа не проходят проверку или незаметно теряют новый объект, в зависимости от старого обработчика. Если первым слить API, старые браузерные клиенты перестанут работать, потому что сервер теперь требует новое поле. Если развернуть API и браузер вместе, новый обработчик все равно аварийно завершится на событиях v1 в очереди. Дефект не находится в одном патче. Он появился в незапланированных промежуточных состояниях.

Исправление требует последовательности «расширить, перенести, сузить». Сначала API принимает оба вида запросов и выдает события обоих видов. Затем развертывается обработчик, который понимает оба варианта и доказывает способность воспроизвести сохраненную фикстуру v1. После этого браузер начинает отправлять v2. Когда данные о развертывании показывают отсутствие активных производителей v1 и проходит срок хранения сообщений в очереди, отдельное изменение по очистке удаляет v1.

Обратите внимание на то, что не исправило бы этот сбой. Более качественные промпты не заставят агентов выбрать одинаковое предположение о развертывании. Увеличенное общее окно контекста даст им больше информации, но не модель полномочий. Запуск всех модульных тестов репозиториев в одном задании повторит те же слепые зоны. Не хватало последовательности совместимых состояний, подтвержденной тестами на стыках.

Изменения базы данных создают ту же картину. Переименование столбца одной миграцией, пока другой сервис продолжает к нему обращаться, не считается конфликтом репозиториев, и Git его не обнаружит. Добавьте новый столбец, при необходимости записывайте оба представления, выполните перенос с наблюдаемым прогрессом, переключите читателей и только затем уберите старый столбец в следующей волне. Координатор решает, когда доказательств достаточно для каждого перехода.

Совместимости нужен явный бюджет

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

Рассматривайте бюджет совместимости по четырем направлениям: принимаемые данные, выдаваемые данные, сохраненные данные и рабочие процедуры. API может принимать запросы обоих видов, но выдавать лишь новый ответ, и это небезопасно, если старый потребитель читает ответ. Обработчик может понимать события обеих версий, пока инструмент воспроизведения все еще пишет только v1. База данных может содержать оба столбца, а процедура отката возвращать код, который знает лишь старый. План должен охватывать каждый путь, остающийся активным во время миграции.

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

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

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

Избегайте двустороннего преобразования, если бизнес-задача его не требует. Команды часто предлагают универсальный адаптер, потому что он кажется гибким. На практике перевод v2 в v1 и обратно может терять структуру, значения по умолчанию или происхождение данных, а агенты по-разному реализуют спорные места. Выберите одно каноническое внутреннее представление, однократно преобразуйте в него каждый принимаемый устаревший формат и выдавайте старый формат лишь на границах с известными устаревшими потребителями.

Сделайте бюджет заметным в коде. Давайте адаптерам совместимости имена, связанные с идентификатором изменения, добавляйте счетчики для каждой устаревшей ветви и связывайте условие удаления с ее тестами. Обычный помощник с именем normalizeAddress может жить годами, потому что никто не понимает, требуется ли еще его странное поведение. Имя acceptCheckoutAddressV1DuringV2Migration подсказывает владельцу очистки, что искать и зачем существует этот код.

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

Порядок слияния входит в проект решения

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

Постройте граф зависимостей, где узлы обозначают изменения. Ребро означает, что одному изменению нужна другая ревизия контракта, сгенерированный артефакт или развернутое поведение. Сначала сливайте самые небольшие изменения, которые создают совместимость, затем потребителей, потом производителей, а очистку оставляйте напоследок. Цикл показывает, что предложенные патчи нельзя развернуть независимо; разорвите цикл адаптером или разделением патча.

Порядок слияния и порядок развертывания связаны, но не совпадают. Неактивное изменение потребителя можно слить под флагом функции до развертывания поставщика. Миграцию схемы иногда нужно развернуть до слияния кода приложения, если тесты обращаются к общему окружению. Когда последовательности различаются, запишите обе, а также условие включения неактивного пути.

Очередь слияния защищает целевую ветку от изменений, которые проходят проверки по отдельности, но ломаются вместе. Документация GitLab о merge trains точно описывает сбой: два запроса на слияние могут независимо пройти конвейер с результатом слияния и все равно сломать целевую ветку в сочетании. Поезд проверяет каждый запрос вместе со всеми запросами впереди него. Эта модель работает внутри одного репозитория, но поезд через несколько репозиториев требует внешнего координатора, который продвигает набор закрепленных коммитов.

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

Если зависимость ломается после готовности зависимого патча, аннулируйте и повторно проверьте зависимый кандидат. Успех с ревизией контракта 7 не доказывает совместимость с исправленной ревизией 8. По возможности используйте исходные изменения повторно, но никогда не переносите доказательства на изменившуюся зависимость.

Один координатор должен владеть общим состоянием

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

Координатор ведет небольшой автомат состояний для каждого репозитория: запланирован, в работе, проверен локально, проверен интеграцией, готов к слиянию, слит, развернут и наблюдается. Для переходов нужны артефакты, а не текстовые заявления. Например, интеграционная проверка требует результата, привязанного к коммиту-кандидату и ревизии контракта. Развертывание требует неизменяемого идентификатора релиза из настоящего окружения.

Храните общее состояние вне истории разговоров с агентами. Диалоги сложно сравнивать, они легко обрезаются и плохо подходят автоматизации. Записывайте решения и хеши кандидатов в манифест, а каждого агента заставляйте читать его в начале задания. Если координатор меняет решение, он создает новую ревизию и помечает затронутые доказательства устаревшими.

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

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

Компаниям, которым пора перейти от случайного применения агентов к контролируемой системе поставки, Team & AI Audit от oleg.is поможет нанести на карту репозитории и пробелы во владении, а также спроектировать первый конвейер из нескольких агентов до того, как инструменты и промпты умножат существующую неопределенность.

Параллелизм должен учитывать радиус конфликта

Безопасное количество одновременно работающих агентов зависит от объема общего смысла, которого касаются их задачи. Десять агентов, меняющих независимые адаптеры, могут быть безопаснее двух агентов, которые меняют одну публичную схему и ее миграцию. Считайте семантические столкновения, а не репозитории.

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

Ограничьте каждую волну объемом работы, который координатор успеет интегрировать и проверить до расхождения входов. Если проверки, окружения или контрактные тесты образуют очередь, дополнительные агенты реализаций лишь быстрее создадут устаревшие ветки. Сократите параллелизм, пока доказательства не начнут проходить через контроль без накопления.

Отслеживайте несколько рабочих сигналов: как часто задачи останавливаются из-за отсутствующих правил контракта, сколько патчей затрагивают незаявленные пути, как часто интеграция отклоняет локально зеленую работу и как долго кандидаты ждут зависимостей. Эти числа диагностируют координацию. Частые ранние остановки могут быть полезны, потому что агенты обнаруживают неопределенность до попадания кода в основную ветку; регулярные поздние сбои интеграции указывают на слабый план или тесты стыков.

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

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