Воркфлоу агента: worktrees и субагенты (Phase 7)
Фаза 7 серии Harness Engineering: процесс работы с кодинг-агентами, а не сам harness. Краеугольный камень — один thread на одну задачу (не на проект): иначе контекст загрязняется, задача «завершается» раньше времени при переполнении, а история становится нечитаемой. Worktree-воркфлоу (создать worktree → запустить агента внутри → закончить → удалить), Plan mode для нетривиального, порог ExecPlan для длинного (кросс-линк, не пересказ), субагенты как граница делегирования и правило «3 спотыкания → следующая задача чинит среду». Артефакт — секция «Working with coding agents» в CONTRIBUTING.md. Стек-агностично.
СреднийDevOps с AI20 минgit worktree, CONTRIBUTING.md, Claude Code, subagents, ExecPlan
1
Краеугольный камень: один thread на задачу, не на проект
Phase 7 — это не про сам harness, а про процесс работы с агентом поверх него. Все предыдущие фазы строили среду; здесь мы фиксируем, КАК в этой среде работать, и записываем это в CONTRIBUTING.md, чтобы процесс был общим, а не «в голове у одного человека».
Краеугольное правило: один thread (чат-сессия с агентом) = одна задача. Не один thread на весь проект, не «продолжу в том же чате, раз агент уже в теме». Три причины. Первая — загрязнение контекста (context pollution): остатки прошлой задачи (отвергнутые подходы, чужие файлы, старые решения) сбивают агента на новой. Вторая — преждевременное «завершение»: когда контекст переполняется, агент склонен объявить задачу сделанной и оборвать работу, лишь бы закрыть переполненный thread. Третья — нечитаемая история: смешанный thread на десять задач невозможно ни заревьюить, ни передать новой сессии. Свежий thread на каждую задачу — это та же гигиена контекста, что и в context engineering, только на уровне рабочего процесса.
🟥 Один thread на проект
- Context pollution: хвосты прошлых задач
- Переполнение → «задача готова», работа обрывается
- История на 10 задач — не заревьюить
- Новая сессия реверс-инжинирит, что вообще шло
🟩 Один thread на задачу
- Чистый контекст под одну цель
- Агент не «закрывает» задачу ради разгрузки thread
- Читаемая история: один thread — одно решение
- Закончил → закрыл; ничего не тащит дальше
Соблазн «продолжу в том же чате, агент же уже в теме» — это и есть начало загрязнения. «В теме» означает «полон контекста прошлой задачи». Новая задача — новый thread, всегда.
2
Worktree-воркфлоу: создать → запустить → закончить → удалить
Если каждая задача — отдельный thread, ей нужна и отдельная рабочая директория, иначе параллельные задачи дерутся за один checkout. Решение стек-независимое — git worktree: на одном репозитории несколько рабочих копий, каждая на своей ветке. Цикл простой: создаёшь worktree под задачу → запускаешь агента ВНУТРИ него → доводишь задачу → удаляешь worktree. Команды git универсальны: они одинаковы для проекта на Go, Python или TypeScript — это не привязано к тулингу конкретного языка.
Ключевая опасность — утечка коммитов в main. Агент (или субагент), запущенный в worktree, обязан перед коммитом проверить `pwd` и текущую ветку и использовать пути относительно CWD этого worktree. Иначе абсолютный путь или забытый `cd` уведут изменения и коммит в основную ветку — ровно то, ради чего worktree и заводили, чтобы этого не случилось. Это правило прямо ложится в CONTRIBUTING.md как обязательный пункт для всех агентских задач.
Создать worktree + ветку под задачу
Запустить агента ВНУТРИ worktree
Перед commit: pwd + ветка + пути от CWD
Закончить задачу, смёрджить ветку
Удалить worktree — чисто
# Worktree-воркфлоу — команды git универсальны (любой стек) / stack-agnostic
# 1. Создать worktree под задачу на новой ветке / create a worktree on a new branch
git worktree add ../wt-<task-name> -b feature/<task-name>
# 2. Запустить агента ВНУТРИ этой директории / run the agent INSIDE this dir
cd ../wt-<task-name>
# ... агент работает здесь, на ветке feature/<task-name> ...
# 3. ОБЯЗАТЕЛЬНО перед коммитом / MANDATORY before committing:
pwd # подтверди, что ты в worktree, не в основном репо
git branch --show-current # подтверди ветку — НЕ main / NOT main
# пути в правках — относительно CWD worktree / paths relative to worktree CWD
# иначе коммит утечёт в main / else the commit leaks to main
# 4. Закончил → вернулся и удалил worktree / finish → remove the worktree
cd -
git worktree remove ../wt-<task-name>Удаление worktree — часть задачи, а не «приберусь потом». Брошенные worktree копятся, путают `git worktree list` и провоцируют запуск следующего агента в чужой полузакрытой директории.
3
Plan mode и порог ExecPlan: сколько планировать до старта
Перед тем как агент начнёт писать код, для нетривиальной задачи включай Plan mode: агент сперва излагает план — какие файлы тронет, какой подход, какие границы — и ждёт твоего апрува, не правя ничего. Это дёшево ловит непонимание до того, как агент нагенерил 200 строк не туда. Когда НЕ нужно: однострочный багфикс, локальная правка одной функции, точечный рефактор — там Plan mode только тормозит. Ориентир тот же, что и для эскиза: новая фича, изменения больше одного слоя или интеграция с внешней системой — планируй; однострочник — нет.
Есть верхний порог, за которым Plan mode уже мало. Правило серии: задача больше одного рабочего дня идёт через ExecPlan — живой план-файл в репо, который держит нить через перезапуски сессии. Здесь мы НЕ пересказываем шаблон ExecPlan — это отдельная фаза. Запомни границу: короткая задача — обычный цикл; нетривиальная — Plan mode перед стартом; длинная (>1 дня) — ExecPlan. За шаблоном, секциями и протоколом иди в рецепт про ExecPlan (ссылка ниже).
| Размер задачи | Что включаешь | Зачем |
|---|---|---|
| Однострочник / правка одной функции | Обычный цикл, без церемоний | План дороже самой правки |
| Нетривиальная: фича, >1 слоя, интеграция | Plan mode → апрув → код | Ловит непонимание до 200 строк не туда |
| Длинная: > 1 рабочего дня | ExecPlan — живой план-файл | Держит нить через рестарты сессии |
Plan mode и ExecPlan не конкурируют, а стоят на разных горизонтах: Plan mode — это апрув подхода в одном thread перед стартом; ExecPlan — письменная память, переживающая сам thread. Длинная задача часто использует оба.
4
Субагенты: граница делегирования
Субагент (subagent) — это дочерний агент, которому главный thread отдаёт ограниченный кусок работы со СВОИМ чистым контекстом и забирает обратно только результат. Это второй механизм параллелизма после worktree: worktree изолирует файлы, субагент изолирует контекст.
Граница простая. В субагент уходит работа ограниченная, параллелизуемая и со своим чистым контекстом: разведка незнакомого участка кода («как тут устроена авторизация?»), написание тестов к готовому модулю, триаж бага (собрать репро и факты). Главный thread не захламляется сотней прочитанных файлов — он получает выжимку. В главном thread остаётся ядро задачи и архитектурные решения: что именно строим, какие границы, какой подход, что мёрджим. Их нельзя делегировать — это и есть нить задачи, и размывать её по дочерним контекстам нельзя. Эвристика: если результат шага — это «решение» (что делать), он остаётся в main; если результат — это «материал» (факты, тесты, репро) под уже принятое решение, его можно отдать субагенту.
✅ В Субагент (subagent)
- Разведка незнакомого кода
- Написание тестов к готовому модулю
- Триаж бага: собрать репро и факты
- Ограниченное, параллелизуемое, свой контекст
🛑 Остаётся в Главный thread
- Ядро задачи: что именно строим
- Архитектурные решения и границы
- Выбор подхода, что мёрджим
- Нить задачи — её нельзя делегировать
Субагент, работающий в worktree, наследует то же правило: перед коммитом проверить pwd и ветку, пути — от CWD worktree. Дочерний контекст легко «забывает», где он, и роняет коммит в main за главного.
5
Правило 3 спотыканий: следующая задача чинит среду
Последнее правило воркфлоу — самое контринтуитивное. Если агент спотыкается об одно и то же три раза подряд (путает один и тот же путь, заново ломает один инвариант, переспрашивает то, что уже объясняли), СЛЕДУЮЩАЯ задача — не «почини баг ещё раз», а «почини среду». То есть: допиши документацию, поставь линтер, заведи skill или урок, который не даст агенту споткнуться в четвёртый раз.
Это тот же принцип, что и в lessons-ledger: агент чинит собственную среду, а повторяющаяся коррекция затвердевает в часть harness, а не остаётся ручной правкой раз за разом. Различие в природе ошибки: детерминируемое («снова импорт в обход слоя») лучше отдать в барьер — линтер/проверку; недетерминируемое (вкус, контекстный выбор) — в lessons-ledger как записанный урок. CONTRIBUTING.md фиксирует сам триггер «3 раза → меняем не код, а среду», а куда именно затвердевает урок — решает рецепт про lessons-ledger (ссылка ниже). Грань: чинить баг каждый раз заново — это работать ПРОТИВ harness; затвердить урок один раз — работать НА него.
Агент споткнулся 3× об одно и то же — что делать
Детерминируемое (путь, инвариант) → барьер: линтер/проверка
Недетерминируемое (вкус, выбор) → урок в lessons-ledger
Пробел в документации → допиши docs / AGENTS.md
Триггер «3 раза → чиним среду» записан в CONTRIBUTING.md
Чинить тот же баг руками 4-й, 5-й, 6-й раз
Счётчик «3» — не магия, а порог: один сбой случаен, два совпадение, три — это паттерн, и паттерн дешевле закрыть средой, чем платить за него каждой новой задачей.
6
Артефакт: секция «Working with coding agents» + что дальше
Все пять правил собираются в один артефакт — секцию «Working with coding agents» в CONTRIBUTING.md. Она делает воркфлоу общим достоянием команды, а не привычкой одного человека: новый участник читает её на онбординге и сразу работает с агентами по тем же правилам. Содержимое секции: один thread на задачу; worktree-цикл с обязательной проверкой pwd/ветки перед коммитом; когда Plan mode, а когда ExecPlan; граница делегирования субагентам; правило 3 спотыканий. Definition of Done фазы 7: секция есть в CONTRIBUTING.md, команда её прочитала, она — часть онбординга.
Где сидит Phase 7 и что дальше. Эта фаза — про процесс (как работать с агентом), тогда как фазы 2–5 были про сам harness (ExecPlan, барьеры, GC, lessons-ledger). Финальная фаза серии — Phase 8: template-репо и golden path, где весь собранный harness и этот воркфлоу упаковываются в стартовый шаблон, чтобы новый проект поднимался по проторённой дорожке. Ссылки на следующую фазу и на хаб серии — ниже.
Секция «Working with coding agents» в CONTRIBUTING.md
Один thread = одна задача
Worktree-цикл + проверка pwd/ветки перед commit
Когда Plan mode, когда ExecPlan (>1 дня)
Граница делегирования субагентам
Правило «3 спотыкания → чиним среду»
Команда прочитала, секция — часть онбординга
CONTRIBUTING.md — для людей (онбординг команды), AGENTS.md — для агента (его рабочие инструкции). Не сваливай воркфлоу в один файл: правило «один thread на задачу» адресовано человеку, который этот thread открывает.
Результат
Фаза 7 собрана как процесс, а не как код: краеугольное правило — один thread на одну задачу (против context pollution, преждевременного «завершения» и нечитаемой истории), worktree-цикл «создать → запустить агента внутри → закончить → удалить» со стек-агностичными командами git и обязательной проверкой pwd/ветки перед коммитом (иначе утечка в main), Plan mode для нетривиального и порог ExecPlan для длинного (>1 дня, кросс-линк, не пересказ), субагенты как граница делегирования (материал — в субагент, решения — в Главный thread) и правило «3 спотыкания → следующая задача чинит среду» (тот же принцип, что в lessons-ledger). Всё это записано секцией «Working with coding agents» в CONTRIBUTING.md, прочитано командой и встроено в онбординг. Дальше — Phase 8: template-репо и golden path.