03 / 06 · Продвинутый

🌿 Git Worktrees + Claude Code

Работайте над 4–8 задачами параллельно без переключения веток. Каждый worktree — отдельная папка с отдельной веткой и отдельной сессией CC.

1. Что такое git worktree и зачем это нужно

Обычная работа с git выглядит так: одна папка проекта содержит одну активную ветку. Хочешь переключиться — нужно закоммитить или спрятать текущие изменения, только потом git checkout. Когда CC работает посередине большой задачи, прерываться мучительно.

Git worktrees решают это кардинально: можно создать сколько угодно дополнительных рабочих папок, каждая — на своей ветке, и все они разделяют один единственный .git-каталог основного репозитория. Нет дублирования истории, нет сложного синка.

Схема структуры

E:\Clients\myproject\ ← основная папка (main ветка)
E:\Clients\myproject\.git\ ← единый .git для всех worktrees

E:\Clients\wt\feat-auth\ ← worktree: ветка feat/auth
E:\Clients\wt\fix-orders\ ← worktree: ветка fix/orders
E:\Clients\wt\refactor-api\ ← worktree: ветка refactor/api

↑ все три используют один .git из myproject

Сравнение подходов

Без worktrees	С worktrees
1 папка = 1 активная ветка	N папок = N активных веток
Переключение = `git stash` или коммит	Переключение = открыть другой терминал
1 сессия CC на весь проект	N независимых сессий CC
Прерывать задачу при срочном баге	Срочный баг — новый worktree, не прерываясь
Контекст CC теряется при переключении	Контекст каждой сессии сохраняется

💡

Каждая папка worktree — полноценный git-репозиторий: там работает git, там запускается CC, там же лежат зависимости node_modules или vendor. Но история, объекты и конфигурация — одни и те же из .git основного репо.

2. Базовые команды

Действие	Команда
Создать worktree на существующей ветке	git worktree add <путь> <ветка>
Создать worktree с новой веткой	git worktree add <путь> -b <ветка>
Список всех worktrees	git worktree list
Удалить worktree	git worktree remove <путь>
Очистить устаревшие записи	git worktree prune
Переместить worktree	git worktree move <старый-путь> <новый-путь>
Заблокировать (защитить от prune)	git worktree lock <путь>

# Создать worktree на существующей ветке
git worktree add E:/Clients/wt/feat-auth feat/auth

# Создать worktree с новой веткой (самый частый случай)
git worktree add E:/Clients/wt/feat-auth -b feat/auth

# Список активных worktrees
git worktree list
# Вывод:
# E:/Clients/myproject   abc1234 [main]
# E:/Clients/wt/feat-auth  def5678 [feat/auth]

# Удалить worktree после завершения задачи
git worktree remove E:/Clients/wt/feat-auth

# Очистить stale-записи (если папку удалили вручную)
git worktree prune

⚠️

Ограничение: одна ветка не может быть открыта в двух worktrees одновременно. Попытка создаст ошибку fatal: already checked out. Для параллельной работы над одной задачей создай отдельную ветку от неё.

⚠️

Частая ошибка новичков: если несколько worktree-сессий CC используют одну и ту же базу данных — возникают race conditions: два агента одновременно пишут в одну таблицу, мигрируют схему, или читают устаревшие данные. Для параллельных задач с БД используйте отдельные тестовые БД (разные схемы или контейнеры) для каждого worktree.

3. Полный workflow с CC — шаг за шагом

1

Находимся в основном репо

Все команды git worktree выполняются из корня основного репозитория. Убедитесь, что ветка main обновлена.
2

Создать worktree для фичи

Указываем путь за пределами основной папки (в E:\Clients\wt\) и имя новой ветки.
3

Установить зависимости в worktree

node_modules, vendor и аналогичные папки не копируются автоматически — их нужно установить в каждом worktree отдельно.
4

Открыть терминал в папке worktree и запустить CC

Новая вкладка терминала, VSCode window или tmux-панель. CC запускается в контексте этой папки — со своим контекстом и историей сессии.
5

Параллельно — другой worktree, другая сессия CC

В отдельном терминале переходим в другой worktree и запускаем независимую сессию CC. Задачи выполняются одновременно без конфликтов.
6

Завершение: PR → merge → удалить worktree

После принятия PR удаляем worktree и прунируем записи. Ветка остаётся в git-истории.

Полный пример

# Шаг 1: обновляем main
cd E:\Clients\myproject
git pull origin main

# Шаг 2: создаём worktree для новой фичи
git worktree add E:/Clients/wt/payment-subscriptions -b feat/payment-subscriptions

# Шаг 3: устанавливаем зависимости (Laravel / PHP)
cd E:/Clients/wt/payment-subscriptions
composer install
cp .env.example .env && php artisan key:generate

# Шаг 4: запускаем CC в этом worktree
claude
# Внутри CC:
# "Реализуй шаг 2.1 из @docs/superpowers/plans/2026-05-08-payment-plan.md"

# Параллельно — другой worktree для срочного бага
cd E:\Clients\myproject
git worktree add E:/Clients/wt/fix-auth-bug -b fix/auth-bug

cd E:/Clients/wt/fix-auth-bug
composer install
claude
# Внутри CC:
# "Исправь баг с CSRF токеном в LoginController, тест уже упал"

# После merge feat/payment-subscriptions в main:
cd E:\Clients\myproject
git worktree remove E:/Clients/wt/payment-subscriptions
git worktree remove E:/Clients/wt/fix-auth-bug
git worktree prune
git branch -d feat/payment-subscriptions fix/auth-bug

4. CLAUDE.md для worktrees

CLAUDE.md из корня основного репо автоматически читается в любом worktree, так как все worktrees указывают на один .git. Добавь в свой CLAUDE.md раздел о worktree-workflow:

# Worktree workflow

## Правила
- Каждая фича или фикс = отдельный worktree в `E:\Clients\wt\<feature-name>`
- Создать: `git worktree add E:/Clients/wt/<name> -b feat/<name>`
- Запустить CC: `cd E:/Clients/wt/<name> && claude`
- Удалить после PR: `git worktree remove E:/Clients/wt/<name> && git worktree prune`
- Никогда не редактировать один и тот же файл в двух worktrees одновременно

## Соглашение по именам папок
- `E:\Clients\wt\feat-<name>`  — для фич
- `E:\Clients\wt\fix-<name>`   — для фиксов
- `E:\Clients\wt\chore-<name>` — для рефакторинга / docs

## Зависимости
- После создания worktree: `composer install` / `npm install` / `pip install -r requirements.txt`
- .env файлы: скопировать вручную из основного репо

ℹ️

CC читает CLAUDE.md из каталога, в котором запущен. Поскольку worktree разделяет один .git, файл CLAUDE.md в корне основного репо доступен во всех worktrees через ссылку. Проверь наличие: ls E:\Clients\myproject\CLAUDE.md.

5. Параллельные задачи — реальная схема

4–8

оптимальное количество параллельных worktrees Меньше 4 — не используешь потенциал. Больше 8 — сложно отслеживать прогресс каждой задачи и держать в голове их контекст.

Терминал 1

E:\Clients\wt\payment

feat/payment-subscriptions

CC сессия — реализация оплаты

Терминал 2

E:\Clients\wt\fix-login

fix/login-csrf

CC сессия — фикс CSRF

Терминал 3

E:\Clients\wt\docs-upd

chore/docs-update

CC сессия — обновление документации

Терминал 4

E:\Clients\myproject

main

review, merge, координация

↓

Периодически (в каждом worktree):
git fetch origin main && git rebase origin/main ← обновляемся от main
git push -u origin <branch> ← пушим прогресс

После завершения:
gh pr create --title "..." --body "..." ← открываем PR
git worktree remove E:/Clients/wt/<name> ← удаляем worktree

Как не запутаться в задачах

Один PR = один worktree. Не смешивай несвязанные изменения.
Имя папки = имя задачи. wt/feat-payment сразу понятно что внутри.
Список через CLI: git worktree list — всегда видно что активно.
Закрывай завершённые — не копи мёртвые worktrees, они занимают место и внимание.

6. Проблемы и решения

Проблема	Причина	Решение
`fatal: already checked out`	Эта ветка уже открыта в другом worktree	Создай новую ветку: `-b feat/name-v2`, или удали старый worktree сначала
Накопились stale-записи после ручного удаления папок	Git не знает, что папка удалена	`git worktree prune` — очищает висячие записи
CLAUDE.md не читается в worktree	CC ищет файл в текущей папке, а там его нет	Убедись, что `CLAUDE.md` есть в корне основного репо; либо создай символическую ссылку
Конфликт изменений между worktrees	Один и тот же файл редактировался в двух местах	Никогда не работай с одним файлом в двух worktrees — это единственное железное правило
`node_modules` или `vendor` нет в worktree	Зависимости не копируются автоматически	`npm install` / `composer install` в папке каждого worktree
`.env` файл отсутствует	Gitignore не пускает .env в историю, не копируется	Скопируй вручную: `cp .env E:/Clients/wt/name/.env`
`git worktree remove` отказывает — "dirty worktree"	В worktree есть незакоммиченные изменения	Закоммить или выбросить: `git worktree remove --force <путь>`
CC видит неправильный корень проекта	CC запущен не из папки worktree	Всегда запускай `claude` непосредственно из папки worktree, а не из подпапки

7. Git aliases для быстрой работы

Добавь в ~/.gitconfig (или C:\Users\<user>\.gitconfig) алиасы для частых операций:

# ~/.gitconfig — секция [alias]
[alias]
  wt-new = "!f() { git worktree add E:/Clients/wt/$1 -b feat/$1; }; f"
  wt-fix = "!f() { git worktree add E:/Clients/wt/$1 -b fix/$1; }; f"
  wt-chore = "!f() { git worktree add E:/Clients/wt/$1 -b chore/$1; }; f"
  wt-list = worktree list
  wt-rm = "!f() { git worktree remove E:/Clients/wt/$1; }; f"
  wt-clean = "!git worktree prune && echo 'Pruned stale worktrees'"

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

# Создать worktree для новой фичи
git wt-new payment-subscriptions
# Эквивалентно: git worktree add E:/Clients/wt/payment-subscriptions -b feat/payment-subscriptions

# Создать worktree для фикса
git wt-fix auth-csrf
# Эквивалентно: git worktree add E:/Clients/wt/auth-csrf -b fix/auth-csrf

# Посмотреть список
git wt-list

# Удалить по имени
git wt-rm payment-subscriptions

# Очистить stale-записи
git wt-clean

💡

Алиасы wt-new, wt-fix, wt-chore автоматически добавляют префикс ветки (feat/, fix/, chore/). Так имя ветки всегда соответствует соглашению, а папка называется без префикса — коротко и удобно.

8. Windows-специфика Windows Server WSL2

Пути: слэши и форматы

# Git и CC одинаково принимают оба формата:
git worktree add E:/Clients/wt/feat-auth -b feat/auth   # forward slash — предпочтительно
git worktree add E:\Clients\wt\feat-auth -b feat/auth   # backslash — тоже работает

# В PowerShell — экранируй backslash или используй forward slash:
cd E:/Clients/wt/feat-auth
claude

# Если CC запущен в WSL2 — используй путь в WSL-формате:
git worktree add /mnt/e/Clients/wt/feat-auth -b feat/auth
cd /mnt/e/Clients/wt/feat-auth
claude

# Или через UNC (менее надёжно в WSL2):
# \\wsl$\Ubuntu\... — не рекомендуется для git-операций

Важные замечания для Windows

Папка E:\Clients\wt\ — создай заранее: mkdir E:\Clients\wt. Git не создаёт промежуточные папки.
WSL2 и Windows — разные файловые системы. Если проект живёт в E:\, запускай CC из PowerShell или Git Bash (не из WSL2) — производительность I/O будет лучше.
Docker-тома: при работе с docker-compose в worktree — монтируй именно папку worktree, не основного репо. Пример: volumes: ["E:/Clients/wt/feat-auth:/var/www"].
Git Bash PATH: Docker не в PATH по умолчанию в Git Bash. Используй MCP (mcp__docker__*) или добавь путь явно — см. E:\Clients\CLAUDE.md.
Права на папки: Windows Server 2025 может требовать явного создания папки с правами. Если git worktree add падает с ошибкой прав — создай папку вручную перед командой.
Длинные пути: включи поддержку длинных путей в Windows: git config --global core.longpaths true.

# Создать корневую папку для всех worktrees
New-Item -ItemType Directory -Force -Path E:\Clients\wt

# Включить длинные пути (один раз)
git config --global core.longpaths true

# Убедиться в правах (Windows Server)
icacls E:\Clients\wt /grant "$env:USERNAME:(OI)(CI)F"

9. Связь с мульти-агентностью

🔗

Worktrees + несколько сессий CC = ручная мульти-агентность.
Ты сам координируешь задачи: создаёшь worktrees, запускаешь сессии, следишь за прогрессом. Это надёжно, предсказуемо и даёт полный контроль.

Для полностью автоматической параллельности — когда агенты сами создают задачи, делегируют и синхронизируются — смотри Мульти-агентность. Там описаны swarm-координация, автоматическое распределение задач и паттерны orchestrator/worker.

Когда что выбирать

Ситуация	Подход
2–8 известных задач, ты координируешь вручную	Worktrees + несколько CC-сессий
Большие задачи с подзадачами, автоматическое делегирование	Мульти-агентность (swarm)
Одна задача, максимальная изоляция от основной ветки	Один worktree + одна CC-сессия
Срочный баг во время работы над фичей	Новый worktree для бага, не прерывая фичу
Code review + доработка параллельно	Worktree для review-фиксов, основная сессия продолжает

10. Быстрый старт — шпаргалка

# === НАЧАЛО ФИЧИ ===
cd E:\Clients\myproject
git pull origin main
git worktree add E:/Clients/wt/my-feature -b feat/my-feature
cd E:/Clients/wt/my-feature
composer install          # или npm install, pip install...
cp ../.env .env           # скопировать .env
claude                    # запустить CC

# === ВНУТРИ CC ===
# /write-plan — создать план
# "Реализуй шаг 1 из @docs/superpowers/plans/my-feature-plan.md"

# === СИНК С MAIN (периодически) ===
git fetch origin main
git rebase origin/main

# === ЗАВЕРШЕНИЕ ===
git push -u origin feat/my-feature
gh pr create --title "feat: my feature" --body "..."

# === ПОСЛЕ MERGE ===
cd E:\Clients\myproject
git worktree remove E:/Clients/wt/my-feature
git worktree prune
git branch -d feat/my-feature