Как определить параллельность агентов программирования по возможностям репозитория

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

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

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

Параллельные сессии не равны пропускной способности

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

Это важно, потому что результат агентов появляется в начале конвейера. Медленные этапы находятся в конце. Если агенты создают pull request быстрее, чем команда их объединяет, каждая дополнительная сессия увеличивает возраст открытых веток. Старые ветки чаще конфликтуют, требуют rebase и заставляют ревьюеров сравнивать предлагаемое изменение с постоянно меняющейся целью.

Команды часто видят первые признаки проблемы и выбирают неверное решение. Они добавляют еще одного ревьюера, просят агентов делать меньшие diff или предлагают всем закрыть отставание по pull request в пятницу. Это может ненадолго помочь, но не меняет скорость поступления работы.

Считайте каждого агента источником запросов на изменения. У репозитория есть несколько ограничений следующего этапа:

• сколько изменений может безопасно одновременно затрагивать один модуль;
• сколько времени проходит до достоверной обратной связи от тестов;
• сколько слияний основная ветка может принять за день;
• сколько времени на ревью есть у людей, способных одобрить работу.

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

Это не призыв к искусственному дефициту. Это отказ считать количество вкладок браузера или терминальных сессий показателем поставки.

У репозитория есть четыре отдельных ограничения

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

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

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

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

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

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

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

Пересечение модулей задает жесткий предел активной работе

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

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

• миграции базы данных, ORM-модели и сгенерированные схемы;
• аутентификация, авторизация, изоляция арендаторов и события аудита;
• общие API-контракты и генерация клиентов;
• файлы сборки, конфигурация развертывания и шаблоны окружения;
• основные пакеты, которые импортируют многие сервисы или приложения.

Отметьте эти области как зоны ограниченного доступа. Один активный агент, пишущий код, владеет такой зоной, пока его pull request не объединен или задача не остановлена. Другие агенты могут исследовать проблему, написать проектную заметку, добавить тесты в действительно отдельной области или подготовить задачу. Они не должны редактировать ту же границу в надежде, что Git разберется с остальным.

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

Создайте легкий файл владения, который даст диспетчеру понятный набор правил. Он не обязан заменять CODEOWNERS. Он отвечает на другой вопрос: кто может прямо сейчас активно менять область.

# .agent-capacity.yml
zones:
  billing:
    paths:
      - services/billing/**
      - packages/contracts/subscription.ts
      - db/migrations/**
    max_active_agents: 1
    required_checks:
      - unit
      - integration
    reviewer_group: billing-owners

  web-ui:
    paths:
      - apps/web/**
    max_active_agents: 3
    required_checks:
      - unit
      - browser
    reviewer_group: web-owners

  docs:
    paths:
      - docs/**
    max_active_agents: 4
    required_checks:
      - markdown
    reviewer_group: docs-owners

Обычная проблема, которую это предотвращает: два агента меняют packages/contracts/subscription.ts, один добавляет поле, а другой меняет смысл статуса. Обе ветки проходят локальные тесты. После слияния первой вторая может успешно пройти rebase, но все равно содержать устаревший контракт. Конфликт был смысловым, а не текстовым.

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

Время тестов определяет, насколько устаревают ветки

Ветка, которая сорок минут ждет содержательных проверок, расходует не только время исполнителя. Она удерживает предположение о состоянии репозитория, пока продолжают объединяться другие изменения. Поэтому медленные тесты снижают безопасную параллельность агентов, даже если сами исполнители не загружены полностью.

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

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

Используйте каждую неделю один и тот же тип запроса. Точные команды зависят от провайдера, но данные должны отвечать на четыре вопроса по каждому pull request: когда пришел первый коммит, когда завершились обязательные проверки, сколько было повторных запусков и требовался ли rebase перед слиянием. Достаточно простой выгрузки.

PR    first_push           checks_green         reruns  rebased  merged
481   09:12                09:31                0       no       10:05
482   09:18                10:04                2       yes      11:16
483   09:22                09:41                0       no       09:58

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

Документация GitHub Actions описывает управление параллельностью workflow и job с помощью групп concurrency. В том числе можно выбрать, отменять ли более старые ожидающие запуски или оставлять их в очереди. Используйте эту возможность для процессов, которые нельзя запускать одновременно, особенно для развертываний и общих тестовых окружений. Но не путайте параллельность workflow с параллельностью агентов программирования. Первая защищает ресурс выполнения. Вторая регулирует объем неразрешенных изменений, поступающих в репозиторий.

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

Ревьюеры, это ограниченный производственный ресурс

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

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

Используйте три группы ревью:

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

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

Рекомендации GitHub для pull request здесь полезны. В них говорится, что ревьюерам нужно понимать мотивацию pull request, чтобы делать комментарии точными и содержательными. Это очевидно, но многие задачи для агентов порождают diff без нормального объяснения решения. Тогда ревьюеры сначала восстанавливают причину изменения, и только потом оценивают его корректность.

Требуйте, чтобы каждый pull request, созданный агентом, содержал четыре простых факта:

• какое пользовательское или эксплуатационное поведение изменилось;
• какие модули и контракты затронуты;
• какие команды запускались и что они проверяли;
• что ревьюеру нужно изучить особенно внимательно.

Не просите театральное эссе. Нужен контекст, который избавит от необходимости восстанавливать задачу по diff.

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

Очередь слияния показывает, правильно ли установлен предел

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

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

Можно рассчитать осторожный предел на основе недавних наблюдений. Пусть:

M = медианное число объединенных pull request за рабочий день
T = медианное число рабочих дней от первой отправки до слияния
R = доступное число слотов ревью за рабочий день для этого класса работ
O = безопасное число активных изменений в одной зоне модулей

начальный предел агентов = min(округлить_вниз(M * T), R, O)

Это не универсальный закон, а практическая отправная точка. M * T оценивает объем работы, который обычно находится в процессе. R не позволяет считать ревьюеров неограниченным ресурсом. O блокирует одновременную работу там, где пересечение создает смысловые конфликты.

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

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

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

Используйте классы работ вместо одного общего предела

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

Разумная начальная схема состоит из четырех классов. Названия можно адаптировать к организации, но различия должны оставаться четкими.

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

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

Диспетчер должен резервировать слот агента, когда задача переходит к реализации, а не когда кто-то придумал тикет. Планирование может идти параллельно. Изменения кода в закрытых зонах, нет.

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

Описание задачи должно делать границы проверяемыми

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

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

Task: Add a validation message when a workspace name exceeds the existing limit.

Allowed paths:
- apps/web/src/features/workspaces/**
- apps/web/src/features/workspaces/*.test.tsx

Do not change:
- shared API contracts
- database schema
- authorization code

Acceptance:
- existing server validation remains unchanged
- browser test covers visible message
- run pnpm test workspaces and pnpm lint

If the UI lacks the required validation data, stop and open a note explaining
which contract must change. Do not modify the contract in this task.

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

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

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

Повышайте пропускную способность, устраняя настоящее узкое место

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

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

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

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

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

Если открытые pull request стареют, ревьюеры постоянно просят делать rebase, а одни и те же файлы появляются в нескольких активных ветках, на этой неделе уменьшите предел агентов. Измеряйте ситуацию две недели. Затем устраните ограничение, которое проявляется в очереди. Team & AI Audit полезен, когда данные уже есть, но у команды нет времени превратить их в рабочую модель, которой она действительно будет придерживаться.

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