ExecPlan: агент на задачах 7–25 часов (Phase 2)
Фаза 2 серии Harness Engineering: ExecPlan — живой план в репозитории, который держит агента на длинной автономной задаче (7–25 часов, десятки файлов) без потери контекста. Когда применять и когда пропустить, какие секции пишет человек до старта (Context, Goal, Out of scope, Approach), а какие агент заполняет по ходу (Progress, Decisions, Surprises). Копируемый шаблон ExecPlan, 30-минутная диагностика готовности и дисциплина live-update. Стек-агностично.
СреднийDevOps с AI20 минExecPlan, Claude Code, Plan mode
1
Зачем ExecPlan: длинная автономия без потери нити
ExecPlan — это живой план в репозитории (один markdown-файл), который позволяет агенту вести одну задачу на протяжении многих часов и многих файлов, не теряя нить. Хаб серии (см. рецепт «Harness Engineering») показывает, что задача едет по четырём фазам; ExecPlan — это артефакт фазы дизайна, который держит контекст на самых длинных из них.
Проблема, которую он решает, простая. На задаче, которая идёт 7–25 часов и затрагивает десятки файлов, агент (и человек) забывает, что уже сделано, какие решения приняты и почему, на какие сюрпризы наткнулись по дороге. Чат прокручивается, контекст вытесняется, и через час работы агент «не помнит», что час назад уже отверг один из подходов. ExecPlan выносит это из эфемерного чата в файл: единый источник правды по этой конкретной задаче, который переживает перезапуск сессии. Это не привязано к стеку или конкретному агенту — это процессный артефакт: так же работает для рефакторинга на Go, миграции БД на Python или новой фичи на TypeScript.
Без ExecPlan
- Контекст живёт в чате — вытесняется на длинной задаче
- Через час агент «не помнит» отвергнутые подходы
- Перезапуск сессии = старт почти с нуля
- Решения и причины нигде не зафиксированы
С ExecPlan
- Единый файл-источник правды по этой задаче
- Progress / Decisions / Surprises переживают рестарт
- Стек-агностично: Go, Python, TS — одинаково
- Человек ревьюит по плану, а не по логу чата
ExecPlan — это не тикет и не ADR. Тикет говорит «что хотим», ADR фиксирует одно архитектурное решение навсегда; ExecPlan — рабочая память одной длинной задачи, которая живёт ровно пока задача в работе.
2
Когда применять — порог
ExecPlan не бесплатен: его написание и поддержка стоят времени, поэтому он нужен не для всякой задачи. Порог из rollout-плана: задача больше одного рабочего дня и/или затрагивает более 5 файлов — тогда ExecPlan оправдан. Всё, что меньше, делается обычным циклом без отдельного плана: однострочный багфикс, локальная правка одной функции, добавление пары тестов плана не требуют.
Типичные кандидаты на ExecPlan — нетривиальная работа: крупные рефакторинги, новые фичи больше рабочего дня, миграции. Их объединяет то, что задача не помещается в один заход внимания и должна быть разбита на milestones, каждый со своим Definition of Done. Если сомневаешься — посмотри не на сложность, а на горизонт: задача, которую агент будет вести часами через перезапуски сессии, без письменного плана разваливается; короткая — нет.
Нужен ли здесь ExecPlan?
Задача больше одного рабочего дня
Затрагивает более 5 файлов
Крупный рефакторинг, новая фича, миграция
Бьётся на milestones, каждый со своим DoD
Однострочный багфикс — плана не требует
Локальная правка одной функции — без плана
Порог «>1 дня / >5 файлов» — фильтр, а не мандат. Цель не «писать больше планов», а не тащить длинную задачу без письменной памяти. Если короткая задача внезапно разрослась — заведи ExecPlan по ходу, это нормально.
3
Структура шаблона: секция / кто пишет / когда
Сила ExecPlan в чётком разделении ответственности: одни секции — это вход от человека ДО старта, другие агент заполняет ПО ХОДУ, последняя пишется человеком В КОНЦЕ. Отсутствие любой обязательной секции — признак плохого плана.
Человек до старта пишет четыре секции: Context (задача, мотивация, ограничения), Goal — одно предложение, что считается успехом, Out of scope (что сознательно НЕ делаем) и Approach — 5–10 пунктов, как собираемся двигаться, разбивка на milestones с Definition of Done каждого. Это рамки, в которых агент потом работает автономно. Агент по ходу ведёт три секции: Progress (что сделано, обновляется после каждой фазы), Decisions — каждое принятое решение и причина, и Surprises — что пошло не так, с короткими доказательствами (вывод тестов идеален). В конце человек пишет Definition of Done по факту: что реально получилось, ретроспектива. Все примеры в секциях держи стек-агностичными — план не должен выглядеть как привязанный к одному фреймворку.
| Секция | Кто пишет | Когда |
|---|---|---|
| Context — задача, мотивация, ограничения | Человек | До старта |
| Goal — одно предложение, что есть успех | Человек | До старта |
| Out of scope — что НЕ делаем | Человек | До старта |
| Approach — 5–10 пунктов, milestones + DoD | Человек | До старта |
| Progress — что сделано | Агент | По ходу, после каждой фазы |
| Decisions — решение и причина | Агент | По ходу |
| Surprises — что пошло не так + пруф | Агент | По ходу |
| Definition of Done — итог, ретроспектива | Человек | В конце |
Goal — ровно одно предложение. Если успех не помещается в одну фразу, задача либо размыта, либо это две задачи. Out of scope так же важен, как Goal: он явно отрезает то, что агент иначе додумает и сделает «заодно».
4
Копируемый шаблон ExecPlan
Вот сам шаблон — положи его в репо как docs/templates/ExecPlan.md, а конкретный план сохраняй как docs/plans/YYYY-MM-DD-short-name.md. Скопируй блок ниже как есть; примеры в нём стек-агностичные, замени их под свою задачу.
Обрати внимание на пример Surprises: короткое доказательство, а не «кажется, не так». Идеальное доказательство — вывод теста или команды. И про тесты по-честному: упавший тест в Surprises ценнее зелёного дашборда — агент не правит и не удаляет существующие тесты, лишь бы «фаза прошла».
# ExecPlan: <short task name>
## Context
Why this task exists, the motivation, and the constraints.
e.g. Search endpoint p95 latency is ~1.8s; product needs < 500ms.
Constraint: public API response shape must not change.
## Goal
ONE sentence describing success.
e.g. Search p95 latency under 500ms with the same response shape.
## Out of scope
What we deliberately will NOT do in this task.
e.g. No new caching layer; no schema migration; no UI changes.
## Approach
5–10 bullets. Split into milestones, each with a Definition of Done.
- M1: add a benchmark that reproduces the slow path. DoD: a failing
perf test that prints current p95.
- M2: profile and isolate the hot query. DoD: profile saved, top
cost identified.
- M3: fix the hot path. DoD: perf test passes, existing tests stay
green (do NOT weaken tests to pass).
- M4: document the change. DoD: short note + plan retrospective.
## Progress # filled by the agent, AFTER EACH milestone
- [x] M1 done — benchmark added, baseline p95 = 1.82s.
- [ ] M2 in progress.
## Decisions # filled by the agent, as it goes
- Reuse the existing query builder instead of raw SQL — keeps the
module boundary; raw SQL would cross it.
## Surprises # filled by the agent, with a SHORT proof
- N+1 query in the list path. Proof:
$ run perf-test
queries executed: 142 (expected ~3)
## Definition of Done # filled by the HUMAN, at the end
What actually shipped, and a short retrospective. Left empty until
the task closes.Примеры в шаблоне держи реалистичными и стек-агностичными, а не «lorem ipsum». Пустой шаблон агент заполняет наугад; шаблон с живым примером показывает ожидаемую плотность и тон — особенно для секции Surprises с пруфом.
5
Live-update: Progress / Decisions / Surprises по ходу
Главная дисциплина ExecPlan — обновлять его ПО ХОДУ, а не в конце. Это правило прямо из rollout-плана: агент обновляет Progress и Decision Log по ходу работы, не в конце. Соблазн «допишу всё, когда закончу» убивает смысл плана: если контекст вытеснится или сессия упадёт до того, как агент дописал — рабочая память потеряна, и восстанавливать её придётся из лога чата (которого может уже не быть).
Ритм простой: завершил milestone → сразу отметил в Progress; принял решение с развилкой → записал в Decisions с причиной; наткнулся на сюрприз → записал в Surprises с коротким доказательством. Каждая запись — отдельная правка файла, не пакетом. Тогда в любой момент план — это актуальный снимок состояния задачи, и новая сессия (или человек на ревью) стартует с него, а не реверс-инжинирит происходящее. Тесты тут — сигнал здоровья: вывод упавшего теста в Surprises показывает реальную проблему; маскировать её, ослабляя тест, запрещено.
Закрыл milestone
Отметил в Progress
План = актуальный снимок
Развилка → Decisions + причина
Сюрприз → Surprises + пруф
Правило батча: одна правка файла на одно событие, а не «допишу всё в конце». Если поймал себя на «обновлю Progress, когда закончу фазу» — это уже отложенная потеря контекста. Обновляй сразу.
6
30-минутная диагностика готовности + что дальше
Прежде чем запускать агента на длинную задачу, прогони диагностику готовности: можешь ли ты за 30 минут написать первые четыре секции — Context, Goal (одно предложение), Out of scope, Approach (5–10 пунктов)? Если за полчаса не получается — задача ещё не готова к запуску. Это не значит «думай дольше»: это значит, что задача недопонята, размыта в целях или скрыто состоит из нескольких — и агент, запущенный на неё, потратит часы автономии не туда.
Диагностика дешёвая и честная: 30 минут письма ловят проблему до того, как агент сожжёт 10 часов на неверно понятой задаче. Если первые четыре секции пишутся легко — рамки ясны, можно запускать: дальше агент ведёт Progress / Decisions / Surprises сам, а ты подключаешься на ревью и в конце пишешь Definition of Done.
Куда дальше по серии. Этот рецепт — фаза 2 (ExecPlan-шаблон и протокол). Карта всей серии — в хабе Harness Engineering. Следующая фаза — архитектурные барьеры: как превратить «нельзя ломать» из Approach в детерминированные машинные проверки, чтобы агент на длинной задаче не уехал за рамки незаметно.
Чего ExecPlan честно НЕ делает: он не проверяет функциональную корректность (делает ли код то, что нужно пользователю — остаётся на человеке и продуктовых тестах) и не заменяет ревью человеком. Он держит нить и структуру длинной задачи — но смысл по-прежнему задаёшь ты.
30-минутная диагностика: готова ли задача к запуску?
Context пишется за минуты — задача и ограничения ясны
Goal помещается в одно предложение
Out of scope явно очерчен
Approach — 5–10 пунктов с milestones и DoD
Не можешь написать 4 секции за 30 мин → задача не готова
Запускать агента на размытую цель «разберётся по ходу»
Не можешь написать первые четыре секции за 30 минут — это не сигнал «пиши план дольше», а сигнал «задача не дозрела». Доформулируй или раздели её, и только потом запускай агента — иначе автономия уйдёт впустую.
Результат
Вы понимаете ExecPlan как живой план-файл в репозитории, который держит агента на длинной автономной задаче (7–25 часов, десятки файлов) без потери нити. Знаете порог применимости (>1 рабочего дня и/или >5 файлов — иначе пропустить), кто и когда пишет каждую секцию (человек — Context / Goal / Out of scope / Approach до старта; агент — Progress / Decisions / Surprises по ходу; человек — Definition of Done в конце), и держите два правила: live-update после каждой фазы (не пакетом в конце) и 30-минутную диагностику готовности перед запуском. У вас есть копируемый шаблон ExecPlan. Всё стек-агностично; тесты — сигнал здоровья, а не KPI. Дальше по серии — архитектурные барьеры.