Claude Code Worktree — git-изоляция для непересекающихся параллельных агентов
Каждая сессия Claude Code или субагент получает свой git worktree; правки файлов не пересекаются; автоочистка при отсутствии изменений.
Что такое worktree и зачем он нужен
git worktree — дополнительный рабочий каталог того же репозитория с собственным рабочим деревом и веткой, разделяющий .git-историю и remote с основным checkout. Claude Code привязывает каждую параллельную сессию или субагента к своему worktree — сессия A пишет фичу X, сессия B чинит баг Y, и файловые правки не перекрывают друг друга.
Инструмент EnterWorktree и конфиг isolation
В сессии Claude Code достаточно сказать «work in a worktree», и модель вызовет EnterWorktree для создания нового. В frontmatter кастомного субагента можно указать isolation: worktree — тогда при каждом dispatch агент будет получать изолированный worktree. С v2.1.x фоновые сессии тоже поддерживают worktree bg isolation.
/team-build — параллельный режим для нескольких агентов
Когда /team-build диспатчит сразу несколько агентов, каждый автоматически получает изоляцию worktree и работает в пересекающихся доменах без конфликтов. Пример: три агента параллельно а) рефакторят auth, б) добавляют юнит-тесты, в) пишут миграции — файлы не сталкиваются, merge выполняется руками в конце.
Автоочистка, типовые ошибки, командные соглашения
При выходе worktree без коммитов и untracked-файлов автоматически удаляется вместе с временной веткой; иначе путь и имя ветки возвращаются в результате. Типичные ошибки: коллизии имён веток между агентами; untracked-файлы блокируют очистку; при использовании worktree-from-origin-main нужно сначала сделать fetch origin. Рекомендуется единый префикс веток wt/agent-<name>-<ts>.
FAQ
Чем worktree отличается от обычной ветки git?
Ветка — это указатель на commit; переключение требует checkout, который перезаписывает файлы. Worktree — отдельный рабочий каталог; несколько веток могут быть одновременно checkout в разные физические пути. Это предпосылка истинно параллельной работы агентов.
Не загрязняют ли worktree субагентов основной репозиторий?
Нет. Пути worktree находятся вне основного checkout, git отслеживает их в .git/worktrees/<id>. При выходе без коммитов весь worktree и временная ветка удаляются автоматически.
Можно ли использовать worktree с Claude Code из Китая?
Да. Worktree — локальная фича git и клиента Claude Code, работающая на вашей машине без сетевых ограничений. Инференс модели идёт через прозрачный шлюз QCode.
Связанные руководства
Запускайте параллельных агентов Claude Code через QCode
QCode даёт прозрачный доступ ко всем моделям Claude изнутри Китая — параллельные worktree-воркфлоу работают без дополнительной настройки.
Подключить план QCode