Как запускать несколько агентов Claude Code одновременно и не ловить конфликты файлов

Коротко (TL;DR)

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

Что важно знать сразу:

• В Claude Code есть два уровня этой изоляции: флаг --worktree для целой сессии, которую вы запускаете руками, и поле isolation: worktree для субагента, которого Claude делегирует сам. Ветвятся они одинаково (от дефолтной ветки), а различаются областью действия и тем, как убираются, — и эту разницу стоит понимать, чтобы не потерять работу при авто-очистке.
• Комфортный предел — 3–5 параллельных worktree. Это же называет «самым мощным апгрейдом продуктивности» один из создателей Claude Code Борис Черни (пост в X от 31 января 2026).
• worktree убирает файловую гонку на диске, но не отменяет конфликты слияния: если две ветки правили один файл, конфликт всё равно всплывёт при git merge — просто позже и осознанно.
• Что понадобится: git версии 2.5+ (worktree в нём с 2015 года), Claude Code с нативной поддержкой --worktree (появилась с начала 2026 года) и дисциплина по границам задач.

Дальше — как это устроено, точные команды, карта авто-очистки и разбор рисков (включая реальный кейс, где 50 worktree съели 10 ГБ оперативной памяти).

Зачем вообще параллельные агенты

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

BYBIT COPY TRADINGКопитрейдинг на BybitОткрытая статистика трейдеров, старт с $10, отключение в один клик.Выбрать трейдера

Проблема в том, что по умолчанию все они работают в одном каталоге. Один персональный агент (например, OpenClaw) живёт в одной рабочей папке — и этого достаточно. Но как только агентов становится двое и больше, они начинают писать в одни и те же файлы: пока первый сохраняет package.json, второй его перезаписывает. Git видит хаос из смешанных изменений, а вы — сломанную сборку.

Генератор против критика: как несколько ИИ ловят баги, которые пропускает один

«Готово» — это оценка агента или чека? TDD и eval-driven разработка с ИИ

Пять периметров безопасности Claude Code: что реально настроить, а что вас удивит

Claude Code без интерфейса: headless-режим, Agent SDK и подводные камни автоматизации

Чаты Claude утекли в поиск: у страниц с общими ссылками не было запрета на индексацию

Есть три способа развести агентов физически:

1. Несколько клонов репозитория — рабочее, но тяжёлое: каждый клон тянет всю историю заново, занимает диск и живёт своей жизнью (свои remote, свои настройки).
2. Ветки в одной папке — не помогает: в один момент времени в рабочем каталоге может быть выкачена только одна ветка. Переключение ветки затрагивает всех.
3. git worktree — золотая середина: отдельные рабочие папки с разными ветками, но одна общая история и один .git.

Третий вариант и стал индустриальным стандартом для работы с флотом ИИ-агентов.

Типичный расклад выглядит так. Вы открываете три worktree: в первом агент переписывает модуль авторизации, во втором — добавляет поиск, в третьем сидит «наблюдатель», который читает логи и не имеет права коммитить. Все трое работают с одним проектом, но каждый — в своей папке и на своей ветке. Пока они трудятся, вы занимаетесь ревью готовых кусков, а не ждёте, пока один агент освободит файл для другого. Именно эта одновременность и даёт выигрыш по времени — при условии, что задачи действительно независимы (к границам задач ещё вернёмся, это ключевой нюанс).

Что такое git worktree простыми словами

git worktree — это отдельная рабочая директория со своими файлами и своей веткой, которая делит историю коммитов, объекты и remote с основным репозиторием. По сути вы получаете второй (третий, пятый) «стол» для работы над тем же проектом, не копируя проект целиком.

Отличие от git clone принципиальное: клон дублирует весь .git (историю, объекты), а worktree его переиспользует. Поэтому создание worktree — почти мгновенное и дешёвое по диску (дублируется только рабочий чекаут файлов, не история). Есть и приятный побочный эффект: коммит, сделанный в одном worktree, сразу виден остальным как часть общей истории — не нужно ничего пушить и подтягивать между локальными копиями, как было бы с несколькими клонами.

Что понадобится. git с поддержкой worktree — она встроена начиная с версии 2.5 (2015 год), так что на любой актуальной системе всё уже есть; проверить можно командой git --version. Плюс Claude Code с нативной поддержкой флага --worktree (появилась с начала 2026 года) — если флаг не срабатывает, обновите CLI. Всё остальное — обычные git-команды, которые вы и так знаете.

BYBIT EARNЗаставь крипту работатьПроценты на USDT и BTC без блокировки — деньги остаются под рукой.Разместить

Базовые команды, которые стоит знать:

Эти четыре команды покрывают 90% повседневной работы. Всё остальное — надстройка, которую Claude Code делает за вас.

Два уровня изоляции в Claude Code

В Claude Code worktree-изоляция работает на двух уровнях, и их полезно не путать.

Уровень 1 — целая сессия (--worktree / -w). Вы запускаете Claude Code с флагом --worktree, и он создаёт изолированный worktree и стартует сессию прямо в нём. По умолчанию worktree появляется в .claude/worktrees/<имя>/ в корне репозитория, на новой ветке worktree-<имя>. Если имя не задать, генерируется случайное (вроде bright-running-fox). Такую сессию вы заводите и закрываете сами — она запускает свой экземпляр Claude Code, например на модели Claude Sonnet 5, независимо от остальных.

Уровень 2 — отдельный субагент (isolation: worktree). В frontmatter кастомного субагента можно прописать поле isolation: worktree. Тогда субагента, которого Claude делегирует сам по ходу вашей сессии, он запускает во временном worktree — изолированной копии репозитория. Если субагент не внёс изменений, его worktree удаляется автоматически.

Чем эти уровни реально различаются — не базой ветвления (она у них общая), а областью действия и очисткой:

• Область действия. --worktree — отдельная сессия, которую вы запускаете вручную под конкретную задачу. isolation: worktree — субагент, которого Claude поднимает автоматически внутри работы.
• Очистка. worktree, созданные руками через --worktree, авто-свипка не трогает — за ними следите вы. А worktree субагентов и фоновых сессий убираются автоматически по возрасту (cleanupPeriodDays), если в них нет несохранённых изменений.

А вот где уровни ведут себя ОДИНАКОВО — и это тоже стоит знать. Оба ветвятся от дефолтной ветки репозитория (origin/HEAD), а не от текущего состояния (HEAD) вашей сессии. Если хотите, чтобы worktree ответвлялся от локального HEAD со всеми вашими наработками, это меняется одной глобальной настройкой — worktree.baseRef: "head" — и она действует сразу на оба уровня.

Почему это важно на практике. Вы в основной сессии набросали новую функцию, но не закоммитили её. Запускаете субагента (или новую --worktree-сессию), чтобы написать тесты. По умолчанию он стартует от дефолтной ветки и вашей несохранённой функции просто не увидит — тесты выйдут «в пустоту». Решения два: закоммитить наработку перед запуском либо выставить worktree.baseRef: "head", чтобы ответвление шло от текущего состояния. Понимание этой развилки экономит час недоумённого дебага — а большинство вторичных гайдов её вообще не упоминают.

Четыре сценария, где это реально нужно

worktree оправдан не всегда — накладные расходы на координацию растут с числом веток. Вот четыре ситуации, где выигрыш очевиден, с привязкой к командам:

Пара уточнений по сценариям. Миграции — самый очевидный выигрыш: крупное обновление легко ломает сборку на полдня, и держать его в стороне от основной работы просто безопаснее. Параллельные фичи оправданы, только когда они реально независимы — если обе трогают один и тот же слой (общий роутер, общий стор), выигрыш от worktree съедается конфликтами на слиянии. Аудиты и A/B-подходы — недооценённые сценарии: worktree стоит почти ничего, поэтому «прогнать задачу двумя способами и сравнить диффы» перестаёт быть роскошью.

Отдельно отметим приём, который редко встречается в англоязычных руководствах: держать один worktree как аналитический, только для чтения — агент в нём смотрит логи и запросы к базе, но не имеет права коммитить. Так вы получаете «наблюдателя», который не участвует в гонке правок, но при этом видит актуальное состояние проекта.

Что убирается само, а что нет

Фраза «worktree чистятся сами» — полуправда. На деле есть четыре разных исхода, и их полезно различать:

Настройка cleanupPeriodDays управляет тем, через сколько дней авто-свипка убирает worktree субагентов и фоновых сессий (при условии, что там нет незакоммиченных изменений, untracked-файлов и незапушенных коммитов). Если вы гоняете много коротких субагентов, короткий период держит диск в чистоте; если worktree живут долго и вы к ним возвращаетесь — период стоит увеличить, чтобы система не удалила то, что вам ещё нужно. Важный нюанс: эта свипка не трогает worktree, которые вы создали руками через --worktree, — за ними вы следите сами.

Пока агент работает, Claude Code выполняет git worktree lock на его worktree, чтобы параллельная очистка не снесла активную работу; блокировка снимается по завершении агента. Забытый worktree, который свипка «щадит», убирается вручную: git worktree remove <путь>, а если там есть несохранённые изменения — с флагом --force (он безвозвратно отбрасывает эти изменения, так что сначала проверьте, что там).

Практика: команды, .env и типичные грабли

Несколько вещей, на которых спотыкаются даже опытные разработчики.

Одна ветка = один worktree. Git не даст выкачать одну и ту же ветку в два worktree сразу. Попытка вернёт ошибку fatal: '<branch>' is already checked out at <path>. Это защита от того, чтобы вы случайно не рассинхронизировали состояние ветки.

Файл .env не переедет сам. worktree — это свежий чекаут, поэтому гитигнорированные файлы (.env, .env.local) в нём отсутствуют. Чтобы Claude Code копировал их при создании worktree, добавьте в корень проекта файл .worktreeinclude — синтаксис как у .gitignore. Копируются только те файлы, которые совпадают с паттерном И при этом гитигнорированы; отслеживаемые файлы не дублируются никогда.

node_modules не шарятся. Каждый worktree делит package.json из общего репозитория, но имеет свою папку node_modules. Значит, npm install (или его аналог) нужно прогнать в каждом worktree отдельно. Это же — источник главного риска по ресурсам, о котором ниже.

Не только git. Если вы на SVN, Perforce или Mercurial, worktree-изоляцию настраивают через хуки WorktreeCreate и WorktreeRemove. Хук WorktreeCreate полностью заменяет дефолтную git-логику (в том числе отключает обработку .worktreeinclude), а WorktreeRemove отвечает за очистку при завершении сессии.

Лайфхак от команды Claude Code — короткие shell-алиасы (za, zb, zc) для мгновенного переключения между несколькими worktree. Когда их 3–5, прыгать между полными путями руками утомительно.

Стратегия слияния: как не утонуть в конфликтах

Когда три worktree готовы и пора собирать всё в main, соблазн «слить всё разом» заканчивается кашей из конфликтов. Практика команд, работающих с флотом агентов, — последовательное слияние с ребейзом:

1. Слейте первую ветку как обычно: git checkout main && git merge feature-auth.
2. Перед слиянием второй ветки переведите её на свежий main: git checkout feature-search && git rebase main. Теперь вторая фича видит уже влитую первую, и конфликты (если они есть) вы решаете здесь — в изоляции одной ветки, а не всех сразу.
3. Слейте вторую: git checkout main && git merge feature-search. Повторите для остальных.

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

Экосистема инструментов

Вокруг worktree выросла целая обвязка. На момент написания (июль 2026) русскоязычный обзор на Habr сравнивает шесть инструментов-надстроек: CCManager, Claude Squad, Crystal, Auto-Claude, Conductor и Cursor 2.0. Все они — терминальные или графические обёртки поверх того же примитива: создают worktree, запускают в каждом свою сессию и дают единый дашборд для мониторинга флота агентов.

Разница между ними в основном в интерфейсе: одни (CCManager, Claude Squad) — терминальные и удобны тем, кто живёт в консоли; другие (Crystal, Conductor) дают графический дашборд со списком активных агентов и их статусами. Но выбирать инструмент до того, как вы поняли базовый механизм, — путь к магическому мышлению «оно само разрулит».

Важная оговорка: список таких инструментов быстро устаревает, поэтому воспринимайте его как контекст, а не как рейтинг «лучших». Базовый механизм под всеми ними один — git worktree, и понимание именно его переживёт любую конкретную обёртку.

Риски и слабые места

У worktree есть цена — вот из чего она складывается.

Раздувание RAM и диска. Главный практический риск — накопление. Реальный кейс из соцсетей (X, 11 июля 2026): одно окно VS Code тихо съедало 10 ГБ оперативной памяти. Причина — 50 накопленных worktree, 45 из которых имели собственные node_modules, и все они индексировались файловым watcher-ом редактора. Это единичный пример, не статистическая норма, но механизм реальный: каждый worktree со своими зависимостями — это ещё один каталог, который кто-то мониторит. Отсюда практическое правило: держать не больше 5 активных worktree и удалять отработавшие.

Конфликты слияния не исчезают, а откладываются. Это ключевая переформулировка, которую многие материалы упускают. worktree защищает от того, чтобы два агента одновременно топтали один файл на диске. Но если две ветки правили один и тот же файл, конфликт всплывёт в момент git merge — ровно так же, как при обычной работе с ветками. worktree лишь переносит момент столкновения на слияние, где его можно разрешить осознанно. Как именно собирать ветки, чтобы конфликты не наваливались разом, — в разделе про стратегию слияния выше.

Дисциплина задач важнее инструмента. Проблемы начинаются, когда оба агента лезут в общие файлы — package.json, конфигурацию, shared-утилиты. worktree тут не спасёт: изоляция файлов не задаёт границы задач. Их задаёте вы — явной формулировкой, что каждому агенту можно трогать, а что нет. На практике это одна-две строки в задании: «работай только внутри src/auth/, не меняй общие утилиты и конфиги; если нужна правка вне этой папки — сначала спроси». Такая рамка стоит десяти минут, но экономит часы разбора конфликтов, когда два агента независимо переписали один и тот же общий модуль. Чем крупнее проект и чем больше в нём shared-кода, тем важнее разводить агентов не только по worktree, но и по зонам ответственности.

Типичные грабли, если собрать в список:

1. Запуск агентов в одной директории вместо отдельных worktree.
2. Общий закоммиченный .env вместо .env.local под каждый worktree.
3. Отсутствие явных границ задачи — агент лезет в общие утилиты и конфиги.
4. Слияние без ревью диффа.
5. Забытые или конфликтующие миграции базы при параллельном изменении схемы.

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

FAQ

Сколько worktree — это нормально? Комфортный предел для большинства — 3–5 активных worktree одновременно. Дальше накладные расходы на координацию и ревью начинают съедать выигрыш в скорости. Технического лимита нет, но 5 — разумный потолок и с точки зрения ресурсов.

Что делать с забытым worktree? Сначала посмотрите список: git worktree list. Ненужный удалите через git worktree remove <путь>; если там остались несохранённые изменения и они вам не нужны — добавьте --force. Если папку worktree вы уже снесли вручную, подчистите записи командой git worktree prune.

А если у меня не git, а Mercurial или SVN? Механизм git worktree работает только с git. Для SVN, Perforce и Mercurial изоляцию настраивают через хуки Claude Code WorktreeCreate и WorktreeRemove — они задают свою логику создания и очистки рабочих копий.

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

Чем worktree лучше нескольких клонов репозитория? Несколько клонов тоже разводят агентов по разным папкам, но каждый клон дублирует всю историю коммитов и объекты, занимает больше диска и живёт отдельной жизнью — со своими remote и настройками, между которыми приходится пушить и подтягивать изменения. worktree переиспользует один общий .git, поэтому создаётся мгновенно, весит меньше, а коммиты сразу видны во всех рабочих копиях. Для параллельной работы над одним проектом это заметно удобнее.

Как понять, в каком worktree я сейчас нахожусь? Команда git worktree list показывает все рабочие копии, их пути и выкаченные ветки — текущая помечена в выводе. Это же первый шаг, когда нужно навести порядок: сначала смотрим список, потом удаляем лишнее через git worktree remove.

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