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

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

Что уже умеем / что добавим

Вы умеете запускать подагентов параллельно и знаете про лимиты одновременности. Вы понимаете, что форк наследует беседу, а обычный подагент стартует с чистым контекстом.

Теперь мы разберём вопрос, который параллельность неизбежно поднимает: как несколько агентов работают с файлами, не мешая друг другу. Добавим понятие git worktree, поле isolation: worktree во frontmatter, фоновые сессии и правила уборки за ними.

Что вы узнаете в рамках статьи

• Что такое git worktree и чем он отличается от ветки
• Как включить изоляцию подагента полем isolation: worktree
• От какой ветки создаётся worktree и как это изменить
• Что такое фоновая сессия и как её запустить
• Как переносить в worktree файлы, которых нет в git

Ключевые термины

• Git worktree — отдельная рабочая копия репозитория: свой каталог с файлами и своя ветка, но общая с основным чекаутом история и общий remote.
• Основной чекаут — ваш обычный рабочий каталог репозитория, тот, из которого вы запустили Claude Code.
• isolation: worktree — поле frontmatter подагента, дающее ему собственный временный worktree.
• Фоновая сессия — полноценная беседа Claude Code, работающая без привязанного терминала; запускается флагом --bg или командой /background.
• .worktreeinclude — файл в корне проекта, перечисляющий игнорируемые git файлы, которые нужно копировать в каждый новый worktree.

Что такое git worktree

Термин может быть незнаком, поэтому начнём с него. Git worktree — это отдельный рабочий каталог с файлами и своей веткой, при этом историю коммитов и remote он делит с вашим основным чекаутом. Проще говоря, это ещё одна копия рабочих файлов того же самого репозитория, живущая в другом каталоге.

Ключевое отличие от переключения веток: ветки сменяют друг друга в одном каталоге, а worktree существуют одновременно. Вы можете чинить баг в основном чекауте и параллельно делать фичу в worktree — оба каталога с файлами доступны в один и тот же момент.

Создать worktree можно и вручную, обычным git:

git worktree add ../project-feature-a -b feature-a
git worktree list
git worktree remove ../project-feature-a

Claude Code делает то же самое сам. Свои worktree он размещает в каталоге .claude/worktrees/ в корне репозитория. Этот путь стоит добавить в .gitignore, чтобы содержимое рабочих копий не мозолило глаза в git status основного чекаута.

Изоляция подагента

Чтобы подагент всегда работал в собственном worktree, достаточно одного поля во frontmatter:

---
name: refactorer
description: Выполняет механические рефакторинги сразу во многих файлах проекта
isolation: worktree
---

Выполните запрошенный рефакторинг во всех затронутых файлах,
затем прогоните тесты и сообщите результат.

Каждый запуск такого агента получает временный worktree. Если агент завершился, ничего не изменив, Claude Code удаляет worktree автоматически. Если изменения есть, каталог остаётся на диске до периодической уборки.

То же самое можно попросить разово, без правки файла:

Используй worktree для своих агентов: запусти двух подагентов
на рефакторинг модулей auth и payments параллельно

Пока агент работает в изолированном worktree, Claude Code блокирует попытки записать что-либо в основной чекаут: правки файлов вне worktree, команды с рабочим каталогом в основном чекауте, перенаправление git туда через git -C или переменные окружения. Агент видит отказ как ошибку инструмента с объяснением.

От какой ветки ответвляется worktree

Деталь неочевидная, но важная. По умолчанию worktree создаётся от ветки по умолчанию вашего репозитория — обычно это main на remote, а не ваш текущий HEAD.

Логика в том, чтобы агент стартовал с чистого дерева, совпадающего с remote. Но если вы работаете над фичей и хотите, чтобы агент продолжил именно вашу незакоммиченную ветку, поведение нужно изменить в настройках:

{
  "worktree": {
    "baseRef": "head"
  }
}

Значение "fresh" — по умолчанию, ответвление от ветки по умолчанию на remote. Значение "head" — от вашего текущего локального HEAD, вместе с непушнутыми коммитами и состоянием фича-ветки. Именно оно нужно, когда вы изолируете агентов, работающих над незавершённой работой.

Ещё одна ловушка новичка: worktree — это свежий чекаут, и файлов, которые git игнорирует, в нём нет. Ваш .env туда не попадёт, и агент упрётся в отсутствующую конфигурацию. Чтобы такие файлы копировались автоматически, положите в корень проекта файл .worktreeinclude с синтаксисом .gitignore:

.env
.env.local
config/secrets.json

Копируются только те файлы, которые попадают под шаблон и при этом игнорируются git, так что отслеживаемые файлы не дублируются. Зависимости тоже нужно доустановить — попросите об этом Claude или сделайте сами в каталоге worktree.

Фоновые сессии

Подагент — работник внутри вашей беседы. Фоновая сессия — самостоятельная полноценная беседа Claude Code, живущая без привязанного терминала.

Запустить её можно из шелла или изнутри сессии:

claude --bg "разберись с падающим тестом SettingsChangeDetector"
claude --bg --name "flaky-test-fix" "почини нестабильный тест в модуле настроек"

/background прогони весь набор тестов и почини падения

Обзор всех фоновых сессий открывается отдельной командой:

claude agents

Это agent view — экран со списком сессий, их состоянием и тем, какие из них ждут вашего ответа. Функция в статусе research preview, детали интерфейса могут меняться. Управление доступно и из шелла:

claude attach <id>   # открыть сессию в этом терминале
claude logs <id>     # показать недавний вывод
claude stop <id>     # остановить сессию

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

{
  "worktree": {
    "bgIsolation": "none"
  }
}

Вторая: удаление сессии в agent view удаляет и созданный для неё worktree вместе с незакоммиченными изменениями. Поэтому фоновая сессия, сделавшая работу, получает указание её сохранить — закоммитить и запушить, при необходимости открыть черновой pull request, и ни в коем случае не пушить в main и не делать force-push.

Частые ошибки

• Ожидать, что worktree ответвится от вашей текущей ветки. По умолчанию он создаётся от ветки по умолчанию на remote. Для работы над незавершённой веткой поставьте worktree.baseRef в "head".
• Забыть про игнорируемые файлы. В свежем worktree нет .env и не установлены зависимости. Перечислите нужные файлы в .worktreeinclude, а зависимости доставьте отдельно.
• Удалить фоновую сессию с незакоммиченной работой. Удаление сессии в agent view уносит с собой её worktree. Сначала коммит, потом удаление.
• Не добавить .claude/worktrees/ в .gitignore. Иначе содержимое рабочих копий будет висеть неотслеживаемыми файлами в вашем основном чекауте.

Наиболее частые вопросы

• Чем worktree отличается от обычной ветки? — Ветки сменяют друг друга в одном каталоге, а worktree существуют одновременно, каждый со своим каталогом файлов и общей историей репозитория.
• Что будет, если агент в worktree попробует изменить файл основного чекаута? — Claude Code заблокирует операцию и вернёт агенту ошибку с указанием на изоляцию.
• Удаляется ли worktree подагента автоматически? — Да, если агент ничего не изменил. Worktree с изменениями остаётся до периодической уборки.
• Как перенести .env в новый worktree? — Через файл .worktreeinclude в корне проекта; он использует синтаксис .gitignore и копирует только игнорируемые файлы.
• Обязателен ли git для изоляции? — Для стандартного механизма да. Для других систем контроля версий изоляция настраивается хуками, о которых пойдёт речь в следующей главе.

Итоги

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

Отдельно стоит отметить нюансы, на которых спотыкаются даже опытные разработчики: отсутствие .env в свежем worktree и удаление незакоммиченной работы вместе с сессией. Вы теперь про них знаете. Остался финальный урок главы — самый практичный: разберём, как выбирать между скиллом, подагентом и отдельной сессией, чтобы не городить сложность там, где хватит одной строки в CLAUDE.md.