Эффективная работа с git worktree

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

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

Дальше по порядку: какие проблемы возникают и как я их решаю.

Работа без переключения веток

Раз выбран этот путь, скажите агенту прямо: переключать ветки в основной папке нельзя, для каждой задачи создаётся отдельный worktree. Запишите это в инструкции проекта (CLAUDE.md, AGENTS.md). Без такого правила рано или поздно один агент переключит ветку и сломает работу остальным.

Подготовка и уборка дерева

В новом worktree есть только файлы из репозитория. Зависимостей, .env и всего остального, без чего проект не запускается, там нет, поэтому ни приложение, ни тесты сразу не заработают. Эти шаги нужно один раз оформить командой, например в Makefile или в скрипте package.json, и указать в инструкциях, что агент вызывает её при создании дерева. Так же нужна команда уборки, которая удаляет дерево и всё, что для него создавалось. Её удобно привязать к концу задачи, например к моменту, когда отправлен PR.

Своя база данных для каждого дерева

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

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

Свои порты

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

Очередь для тяжёлых проверок

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

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

Общие зависимости и кеши

Последнее - зависимости и кеши. Если в каждом дереве лежит своя полная копия зависимостей, место на диске кончается очень быстро. Выбирайте инструменты, которые умеют безопасно хранить такие данные в общем месте, или настройте на это те, что уже используете. Например, pnpm здесь удобнее npm: он держит пакеты в одном общем хранилище и подключает их в проекты ссылками, поэтому каждое новое дерево почти не занимает места под зависимости.

После этих изменений работать сразу в нескольких worktree действительно удобно и быстро.