Оправдывают ли Git worktree для агентов программирования такую дисциплину?

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

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

В руководстве Git linked worktree описан как еще одно рабочее дерево, подключенное к тому же репозиторию. Каждое дерево может переключиться на свою ветку, а история и объекты репозитория остаются общими. Для агентов это подходящий уровень разделения: отдельные файлы и локальное состояние при одном источнике истины для коммитов.

Агентам нужны отдельные checkout, а не общая осторожность

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

Просьба к агентам «быть осторожнее» - не средство контроля. В общем checkout один index и один рабочий каталог. В index Git записывает содержимое следующего коммита, поэтому один участник может незаметно добавить в него изменения другого. Это не особый недостаток AI. Люди годами делают то же самое друг с другом.

Worktree дает каждому агенту собственный каталог, checkout ветки, index и HEAD. По умолчанию Git также не позволяет подключить одну ветку сразу к нескольким worktree. Не обходите эту защиту. Если двум агентам нужно менять одну ветку, они не являются независимыми исполнителями. Им нужна передача работы.

Практическое различие легко упустить:

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

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

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

repos/
  billing-api/                 # основной checkout и контроль интеграции
  billing-api-wt/
    agent-auth-refresh/
    agent-invoice-export/
    agent-test-repair/
    integrate-release-184/

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

Граница задачи должна быть уже расплывчатой функции

Worktree не заставит пересекающиеся изменения объединиться без проблем. Он лишь не дает пересечению испортить checkout до того, как вы его заметите. Задаче по-прежнему нужна граница, способная выдержать соседство с другими ветками.

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

До создания worktree опишите каждое назначение в пяти полях:

1. Имя ветки и родительский коммит.
2. Файлы или модуль, за которые отвечает агент.
3. Интерфейсы, которые он может менять.
4. Команды, подтверждающие работоспособность изменения.
5. Ветка или задача, которые должны попасть в продукт раньше.

Четвертое поле выявляет распространенную проблему. Команды просят агента «добавить тесты», но не уточняют, должен ли набор тестов проходить отдельно, после появления зависимой ветки или только в объединенном продукте. Агент сообщает об успехе в своем worktree, а после слияния все ломается, потому что ожидаемого API не было в интеграционной ветке.

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

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

Создавайте worktree от именованной базовой точки

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

Пусть main актуальна, корень репозитория находится в ~/repos/billing-api, а worktree - в ~/repos/billing-api-wt. Оператор может создать worktree и ветку так:

cd ~/repos/billing-api
git fetch origin
git switch main
git pull --ff-only
git worktree add -b agent/auth-refresh \
  ../billing-api-wt/agent-auth-refresh main

git worktree add -b создает ветку и подключает ее в новом каталоге. Git рассматривает это как штатную операцию, а не обходной путь через клоны или скопированные каталоги. Linked worktree хранит отдельные служебные данные, поэтому Git различает рабочие каталоги.

Не используйте git checkout -b внутри скопированного каталога. Скопированные репозитории занимают место, расходятся в настройках remote и hook и скрывают, действительно ли ветки относятся к одному рабочему набору. Главное, они подталкивают агентов использовать случайно найденный устаревший клон.

Для одноразового расследования создайте detached worktree:

cd ~/repos/billing-api
git worktree add -d ../billing-api-wt/repro-payment-timeout main

Detached worktree подходит для воспроизведения производственной ошибки, сравнения производительности или проверки рискованной команды генерации кода. Для задачи, которую нужно слить, он не подходит. Агент может создавать коммиты в detached HEAD, но у них нет имени ветки, которое понесет их дальше. Это плохое место для работы, которую завтра должен найти другой человек.

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

Очередь слияний следует зависимостям, а не времени завершения

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

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

Для релиза с API-контрактом, реализацией сервиса, изменением UI и регрессионными тестами вероятен такой порядок:

1. Слить ветку контракта или миграции.
2. Слить реализацию сервиса после ее обновления под результат первого шага.
3. Слить ветку UI после проверки финального контракта.
4. Слить регрессионные тесты и эксплуатационную документацию, когда они соответствуют выпущенному поведению.

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

Сделайте порядок исполняемым с помощью интеграционной ветки:

cd ~/repos/billing-api
git worktree add -b integrate/release-184 \
  ../billing-api-wt/integrate-release-184 main

cd ../billing-api-wt/integrate-release-184
git merge --no-ff agent/auth-refresh
git merge --no-ff agent/invoice-export

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

Документация Git по merge объясняет, что fast-forward может просто передвинуть указатель ветки, а --no-ff создает merge-коммит, даже если Git мог выполнить fast-forward. Команды могут предпочитать любую форму истории. Не путайте видимый merge-коммит с дисциплиной интеграции. Доверие к интеграционной ветке создают тесты, проверка и порядок.

Один integration worktree владеет конфликтами между ветками

Разрешайте конфликты между ветками в integration worktree, а не в worktree агента, который оказался вторым при слиянии. Это правило не дает параллельной работе запутать активные ветки.

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

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

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

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

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

Worktree изолирует файлы, но не все общие ресурсы

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

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

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

# .env.local, не добавлять в репозиторий
APP_PORT=4312
TEST_DATABASE_URL=postgres://localhost/billing_agent_auth_refresh
TMPDIR=/tmp/billing-agent-auth-refresh

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

Git также разделяет объекты репозитория и ссылки между связанными worktree. Это удобно: коммиты одного агента сразу доступны integration worktree. Но это означает, что worktree не является границей безопасности между ненадежными участниками. Если агенту нельзя видеть историю, секреты или remote репозитория, не давайте ему worktree этого репозитория.

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

Перед удалением заброшенной работы сначала примите решение

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

Начните с инвентаризации:

cd ~/repos/billing-api
git worktree list -v
git status --short --branch

Запустите git status и внутри подозрительного worktree. Первая команда показывает известные Git worktree, подключенную в каждом ветку и считает ли Git отсутствующий путь доступным для очистки. Вторая показывает, есть ли в текущем checkout незакоммиченные изменения. В руководстве Git git worktree list -v описана как команда, раскрывающая дополнительное состояние, например заблокированные worktree и worktree, доступные для очистки.

Затем примите одно из трех решений.

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

Удаляйте чистый worktree через Git:

cd ~/repos/billing-api
git worktree remove ../billing-api-wt/agent-test-repair

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

Если кто-то уже удалил каталог worktree в файловой системе, Git может сохранить устаревшие метаданные. Сначала проверьте их, затем выполните очистку:

cd ~/repos/billing-api
git worktree prune -n -v
git worktree prune -v

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

Блокируйте worktree только тогда, когда реальному оператору нужно защитить его от случайного удаления, например во время долгого расследования релиза. Блокировка не заменяет владение. Если у задачи нет владельца, запишите причину ее существования или завершите ее.

Небольшой договор с оператором полезнее сложной оркестрации агентов

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

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

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

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

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

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

Первое полезное правило - перестать сливать изменения с рабочих мест агентов

Самое быстрое полезное изменение простое: агенты работают в собственных worktree, а cross-branch merge выполняется только в integration worktree. Одно это правило предотвращает большинство случаев случайного добавления файлов в index, нарушения checkout и незаметного разрешения конфликтов.

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

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