Subagents and Parallel Sessions

Субагент — отдельный экземпляр Claude со своим системным промптом, своим набором инструментов и, главное, своим контекстным окном. Основная сессия ставит ему задачу, субагент работает автономно и возвращает только финальный отчёт. Все промежуточные шаги — десятки прочитанных файлов, вывод grep, тупиковые ветки поиска — остаются в его окне и не засоряют ваше.

Свои субагенты описываются файлами в .claude/agents/ (проектные) или ~/.claude/agents/ (личные):

---
name: code-searcher
description: Ищет код и отвечает на вопросы о структуре репозитория.
  Только чтение, ничего не меняет.
tools: Read, Grep, Glob
---
Ты — поисковый агент. Находи точные пути файлов и возвращай краткие
выводы со ссылками на строки. Не предлагай правок.

Frontmatter задаёт имя, описание — по нему главный агент решает, кого позвать под задачу, — и белый список инструментов. Поисковому агенту незачем Edit и Bash: ограничение — не паранойя, а предсказуемость. Агент без прав на запись гарантированно ничего не сломает, поэтому его можно запускать смело, пачками и параллельно. Управлять набором субагентов удобно через команду /agents: она показывает доступных, помогает создать нового и проверить, какие инструменты ему выданы.

Делегирование окупается в двух случаях. Первый — поиск и анализ: вопрос «найди все места, где мы валидируем email» заставит основной контекст проглотить десятки файлов; субагент проглотит их сам и вернёт три пути с выводами. Второй — независимые области: фронтенд, бэкенд и документация могут идти параллельно у трёх агентов, если не трогают общие файлы.

Формула хорошей постановки: цель, границы, формат отчёта. Не «посмотри авторизацию», а «найди, где выдаётся JWT, перечисли файлы и функции, ничего не меняй, отчёт списком путей». Чем точнее рамка, тем меньше агент фантазирует и тем короче полезный отчёт.

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

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

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

git worktree add ../myapp-auth -b feat/auth
git worktree add ../myapp-search -b feat/search

# терминал 1
cd ../myapp-auth && claude
# терминал 2
cd ../myapp-search && claude

# после вливания веток
git worktree remove ../myapp-auth
git worktree prune

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

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

Сведём дисциплину в короткий свод — каждое правило выстрадано реальными инцидентами.

• Никогда git add . при параллельной работе: команда захватит незакоммиченный WIP соседней сессии, и в вашем коммите окажется чужая полуготовая работа. Только поимённо: git add src/auth/jwt.ts src/auth/jwt.test.ts.
• Один файл — один агент. Задачи, трогающие общий файл, выполняются последовательно, даже если это медленнее.
• Зависимые шаги — последовательно: сначала А, дождаться отчёта, передать результат в Б.
• Чтение параллелится без ограничений: поисковые и ревью-агенты можно запускать пачками — они ничего не ломают по построению.
• «Готово» без вывода команд — не готово. В отчёте параллельной задачи должны быть прогон тестов и git status.

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

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