Git worktrees и кодинг-агенты: параллельная работа без конфликтов

Кодинг-агент ускоряет написание кода в 3–5 раз — но только если одна задача выполняется за раз. Параллельно запустить двух агентов в одном репозитории невозможно: они перезапишут индекс, сломают друг другу файлы и запутают ветки. Git worktree решает эту проблему — каждая задача получает свою изолированную рабочую директорию при общем .git/. Ниже — как настроить параллельную работу агентов, на чём застревают и почему это критично даже в эпоху облачных агентов.

Что такое git worktree и почему это не просто «ещё одно клонирование»

Worktree — это привязанная к существующему репозиторию рабочая директория со своим HEAD, индексом и файлами на диске. От git clone отличается одним: общий каталог .git/ (объекты, ветки, конфиг) не дублируется. Команда создания выглядит так:

git worktree add ../hotfix hotfix-branch

Эта команда делает три вещи: создаёт директорию ../hotfix, чекаутит ветку hotfix-branch и связывает worktree с основным репозиторием через служебные файлы в .git/worktrees/ (документация git-worktree).

Важные свойства из документации:

• Каждая ветка чекаутится только в одном worktree — попытка создать второй worktree с той же веткой завершится ошибкой (нужен --force).
• Рабочее содержимое дублируется полностью — node_modules/, .env, индекс — у каждого worktree свои.
• Конфиг, хуки и объекты — общие — .git/config, .git/hooks/, .git/objects/ доступны из всех worktree.
• Субмодули — отдельные в каждом worktree.

Посмотреть список активных worktree:

git worktree list
# /path/to/main      abc1234 [main]
# /path/to/hotfix    def5678 [hotfix-branch]

Зачем агентам нужна изоляция рабочей директории

Кодинг-агент (Claude Code, Codex, Cursor, Aider) работает с файловой системой напрямую: читает файлы, пишет правки, запускает тесты. Если два агента работают в одной директории одновременно, возникают три проблемы:

1. Конфликт в индексе — агент A делает git add, агент B в тот же момент меняет индекс через git stash. Результат — потеря staged-файлов.
2. Перезапись файлов — агент A редактирует src/utils.ts, агент B перезаписывает тот же файл с другой правкой. Чья-то работа теряется.
3. Сломанная ветка — один агент коммитит на main, другой запускает git checkout -b feature. HEAD — один на директорию.

Worktree устраняет все три проблемы: у каждого агента своя директория, свой индекс, свой HEAD. При этом агенты делят одну копию истории коммитов и объектов — это не три полных клонирования по 2 ГБ, а три директории с уникальными файлами и общим .git/.

Три способа организации worktree для агентов

Дэвид Гомес (инженер Cursor) описал в примикре от 28 августа 2026 три модели использования worktree с кодинг-агентами за 12 месяцев опыта:

1. Worktree, управляемые продуктом (harness-managed)

Продукт (Cursor, Codex) сам создаёт worktree при запуске новой задачи. Пользователь не думает о путях и ветках — продукт вычисляет их автоматически.

# Пример: Cursor запускает агента в отдельном worktree
cursor --worktree -p "Refactor Layout.tsx to use Radix UI"

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

2. Worktree, создаваемые самим агентом (agent-generated)

Агент выполняет git worktree add через shell без какого-либо специального API. По наблюдениям Гомеса, модели начали делать это «инстинктивно» начиная с Opus 4.5, а после выхода GPT 5.5 это стало регулярным поведением.

Агент создаёт worktree когда:
— Пользователь просит выполнить две задачи и открыть PR для каждой из отдельных веток.
— Текущий чекаут «грязный» и агент не хочет портить незакоммиченные изменения.
— Агент хочет попробовать два разных решения одной задачи параллельно.

«Если бы я мог выбрать только один подход, я бы выбрал worktree, генерируемые агентом. Они гораздо более универсальны.» — Дэвид Гомес, davidgomes.com

Проблемы этого подхода:
— Агент может создать worktree в неожиданном месте — UI ломается, инструменты редактирования ограничены одной директорией.
— Зависимости не установлены (npm install не запускается автоматически в новой директории).
— В длинном диалоге агент может «забыть», в каком worktree работает, и начать править файлы в основной директории.

3. Явный вызов пользователем

Пользователь вручную создаёт worktree и запускает в нём агента:

# Создаём worktree для задачи
git worktree add ../task-auth -b feature-auth main

# Запускаем агента в этой директории
cd ../task-auth
claude -p "Add JWT authentication to the /api/login endpoint"

Это самый предсказуемый вариант, но требует ручной настройки каждого worktree — установки зависимостей, конфигурации среды.

Практический сценарий: три агента параллельно

Допустим, у вас задача: (а) добавить аутентификацию, (б) пофиксить баг #142 в обработке ошибок, (в) провести рефакторинг утилит. Без worktree последовательная работа займёт ~3 часа. С worktree — ~1 час, потому что агенты работают параллельно.

Пошаговая настройка

Шаг 1. Создаём worktree для каждой задачи:

# Основной репозиторий — dev-ветка
cd /projects/myapp

# Worktree для агента A: аутентификация
git worktree add ../myapp-auth -b feature-auth main

# Worktree для агента B: фикс бага
git worktree add ../myapp-bugfix -b fix-142 main

# Worktree для агента C: рефакторинг
git worktree add ../myapp-refactor -b refactor-utils main

Шаг 2. Устанавливаем зависимости в каждом worktree. Это критический шаг — без npm install (или pip install -e ., go mod download) агент не сможет запустить тесты и собрать проект:

cd ../myapp-auth && npm install
cd ../myapp-bugfix && npm install
cd ../myapp-refactor && npm install

Совет: автоматизируйте установку через скрипт. Дэвид Гомес описывает, что Cursor поддерживает настройку скрипта для worktree — при каждом создании worktree зависимости ставятся автоматически.

Шаг 3. Запускаем агентов:

# Терминал 1
cd ../myapp-auth && claude -p "Add JWT auth to /api/login, write tests"

# Терминал 2
cd ../myapp-bugfix && claude -p "Fix error handling in OrderProcessor (bug #142)"

# Терминал 3
cd ../myapp-refactor && claude -p "Extract shared utilities to utils/ module"

Шаг 4. Каждый агент коммитит в свою ветку, открывает PR:

# После завершения каждого агента
cd ../myapp-auth && git push -u origin feature-auth && gh pr create
cd ../myapp-bugfix && git push -u origin fix-142 && gh pr create
cd ../myapp-refactor && git push -u origin refactor-utils && gh pr create

Шаг 5. Удаляем worktree после мержа:

git worktree remove ../myapp-auth
git worktree remove ../myapp-bugfix
git worktree remove ../myapp-refactor

Автоматизация через скрипт

Для частого использования создайте скрипт-обёртку:

#!/bin/bash
# agent-worktree.sh — создать worktree и запустить агента
set -e

TASK_NAME=$1
PROMPT=$2
BASE_DIR=$(pwd)

git worktree add "../${TASK_NAME}" -b "agent/${TASK_NAME}" main
cd "../${TASK_NAME}"
npm install --silent
claude -p "$PROMPT"
cd "$BASE_DIR"
echo "Done: ${TASK_NAME}. Review and create PR manually."

Использование:

./agent-worktree.sh auth-refactor "Refactor auth to use passport.js"

На что обратить внимание при работе с worktree

Расход диска

Каждый worktree дублирует рабочее содержимое. Если репозиторий весит 500 МБ, три worktree потребуют ~1,5 ГБ плюс общие объекты. Для крупных репозиториев (1 ГБ+) это ощутимо — контролируйте количество одновременных worktree.

Зависимости и submodule

node_modules/, .venv/, vendor/ — у каждого worktree свои. Если у вас PostInstall-скрипты, они выполняются при каждом npm install. Субмодули тоже нужно инициализировать в каждом worktree отдельно:

cd ../myapp-auth
git submodule update --init --recursive
npm install

Хуки и конфиг

Гит-хуки (pre-commit, commit-msg) и основной конфиг — общие. Это удобно: один .pre-commit-config.yaml работает везде. Но если вам нужно изолировать конфиг (например, разные remote для разных worktree), включите расширение worktreeConfig:

git config extensions.worktreeConfig true

После этого git config --worktree создаёт отдельный файл конфига для каждого worktree (документация git-config).

Ограничение: одна ветка — один worktree

Если агент пытается создать worktree с веткой, которая уже чекаутнута в другом worktree, команда завершится ошибкой. Используйте уникальные имена веток для каждой задачи — feature-auth, fix-142, refactor-utils, а не все три на main.

Почему облачные агенты — будущее, но worktree остаются

Дэвид Гомес работает в Cursor и профессионально использует Cloud Agents. Его вывод после 12 месяцев:

«Cloud-агенты гораздо лучше для параллелизации работы, чем worktree. Однако я понимаю, что внедрение облака может быть сложным по техническим и комплаенс-причинам. Это значит, что worktree по-прежнему необходимы.» — Дэвид Гомес, davidgomes.com

Облачные агенты (Cursor Cloud Agents, Claude Code в облаке) не требуют worktree — каждый запуск работает в изолированном контейнере/VM. Но для локальных сценариев worktree остаются основным инструментом параллелизации: в примикре Гомеса перечисляются причины — стоимость облачной инфраструктуры, compliance-ограничения (секреты, юридические ограничения), сложность настройки облачной среды для некоторых проектов.

Честные ограничения

• Worktree не заменяют CI-изоляцию. Агент в worktree работает на вашей машине с вашими правами. Если агент выполнит враждебную команду или подхватит prompt injection через файл в репо, последствия будут на вашей файловой системе. Для безопасного автономного кодинга используйте песочницы (подробнее — в статье «Песочницы для ИИ-агентов»).
• Агенты «забывают» контекст worktree. В длинных сессиях (10+ итераций) модели могут начать работать в неправильной директории. Проверяйте pwd после каждого крупного шага или включите в AGENTS.md инструкцию проверять текущую директорию.
• Установка зависимостей — ручная. Не все продукты автоматизируют npm install для новых worktree. Cursor поддерживает worktree setup script, Claude Code — нет. Для остальных агентов пишите скрипт или включите установку в промпт.
• Диск — конечный ресурс. Три worktree крупного проекта = три копии node_modules/. На 256 ГБ SSD это терпимо; на 128 ГБ — уже нет. Регулярно удаляйте завершённые worktree.
• Не все продукты корректно работают с worktree. Некоторые IDE и агенты могут терять file watchers, ломать интеграцию с терминалом или путать внутреннее состояние. Протестируйте перед тем, как полагаться на этот workflow.

Российские реалии

Git — локальный инструмент, git worktree работает из России без ограничений и VPN. Проблемы начинаются на уровне агентов, потому что почти все облачные агенты требуют зарубежный аккаунт и оплату.

• Claude Code — вход через claude.ai или API-ключ Anthropic, оба недоступны из РФ без VPN; оплата подписки $20/мес или API-токенов — зарубежной картой. Реальные способы оплаты описаны в гайде «Как оплатить подписку ChatGPT из России в 2026 году» — для Anthropic схема та же.
• Cursor — работает с локальными моделями без подписки; облачные функции требуют подписки ($20/мес Pro), оплата — зарубежной картой или криптой.
• Codex — вход по ChatGPT-плану или API-ключу OpenAI; доступ с российских IP ограничен с декабря 2022.
• Aider — полностью локальный, работает с любым провайдером (включая Ollama), из РФ без ограничений (README).
• Локальная альтернатива — OpenCode с бесплатными моделями, работает из РФ без VPN. Локальные модели через Ollama разобраны в статье «Локальные нейросети для кодинга».

Русскоязычных материалов про git worktree в контексте ИИ-агентов на момент публикации нет. Основные источники — английскоязычные: документация Git, пост Дэвида Гомеса и форум Cursor. В рунете git worktree освещается в контексте обычной разработки — например, на Habr есть обзор команды и на vc.ru — гайд по parallel development, но без упоминания агентов.

Вывод

Git worktree — встроенный механизм для параллельной работы, который стал актуален с появлением кодинг-агентов. Каждый агент получает изолированную директорию, общую историю коммитов и нулевой риск конфликтов в индексе. Для параллелизации двух-трёх задач — это стандартный инструмент. Начните с git worktree add, запустите агента в новой директории и сравните время с последовательным вариантом. Стоимость — лишняя копия рабочих файлов на диске; выгода — параллельные PR вместо очереди из задач.

Дальше по теме: кейс: worktrees + кодинг-агенты — примикр Дэвида Гомеса, ИИ для Git: коммиты, PR и ревью, что такое агентный кодинг, автономные агенты: ночной прогон.