Планы исполнения как артефакты

План в чате исчезает вместе с контекстом. План в репозитории переживает компакцию, смену сессии, смену исполнителя и ревью. Команда OpenAI в статье «Harness engineering» называет планы полноценными артефактами: для мелких изменений хватает эфемерных, а сложная работа идёт по планам исполнения (execution plans) с журналами прогресса и решений, которые коммитятся в репозиторий. Разберём, как устроить такие планы и когда они окупаются.

Два вида планов

Эфемерные инструменты Codex полезны и сами по себе. Режим планирования (как им пользоваться — в уроке «Сначала план») заставляет агента сначала исследовать и предложить план, а update_plan держит чек-лист внутри хода. Но всё это живёт в контексте, а значит, подвержено тому, что разобрано в уроке о компакции.

PLANS.md: шаблон из OpenAI Cookbook

Самое подробное описание формата — статья «Using PLANS.md for multi-hour problem solving» в OpenAI Cookbook. На странице она помечена как архивная, с упоминанием устаревших моделей, но best practices Codex по-прежнему ссылаются на неё как на шаблон для длинной многошаговой работы.

Идея: в репозитории лежит файл PLANS.md, который определяет, что такое ExecPlan и как его писать. Сам термин «ExecPlan» модель не знает — он работает только потому, что его определяет файл. AGENTS.md ссылается на PLANS.md: для сложных фич и значимых рефакторингов использовать ExecPlan.

Требования к плану из этой статьи (пересказ):

• Самодостаточность. План содержит всё, что нужно новичку, без ссылок вида «как определено ранее» и без опоры на прошлые планы.
• Живой документ. План обновляется по мере продвижения, открытий и принятых решений; каждая версия остаётся самодостаточной.
• Перезапуск. Работу всегда можно продолжить по одному только плану.
• Наблюдаемый результат. Приёмка описана как поведение, которое человек может проверить, а не как перечень изменений в коде.
• Простой язык. Каждый специальный термин определён или не используется.

Разделы плана по шаблону: Purpose / Big Picture, Progress, Surprises & Discoveries, Decision Log, Outcomes & Retrospective, Context and Orientation, Plan of Work, Concrete Steps, Validation and Acceptance, Idempotence and Recovery, Artifacts and Notes, Interfaces and Dependencies. Четыре «живых» раздела — Progress, Surprises & Discoveries, Decision Log, Outcomes & Retrospective — обязательны и должны поддерживаться в актуальном состоянии.

Почему это работает

Наш анализ — у каждого живого раздела своя функция в harness:

• Progress — внешняя память. После компакции или в новой сессии агент читает, что сделано, вместо того чтобы восстанавливать это по git log и догадкам.
• Decision Log — защита от пересмотра. Без него агент в новой сессии может «улучшить» решение, от которого вчера отказались по веской причине.
• Surprises & Discoveries — сырьё для harness. Каждое неожиданное открытие («шаблон темы кэширует партиал, правка не видна без сброса кэша») — кандидат в docs/ или в AGENTS.md.
• Validation and Acceptance — критерий завершения хода, которого, как мы видели в уроке об агентном цикле, иначе нет.

И главное для техлида: план — самая дешёвая точка для человеческого суждения. Поправить подход в плане стоит минуты, поправить его в готовом диффе на 40 файлов — часы.

Как это выглядит в репозитории

## Планы исполнения
- Для задач дольше дня, затрагивающих несколько плагинов, или с миграцией данных
  сначала напиши ExecPlan по правилам docs/PLANS.md и дождись подтверждения.
- Активные планы: docs/exec-plans/active/. Обновляй Progress после каждого этапа.
- Завершённый план перенеси в docs/exec-plans/completed/, долг — в tech-debt-tracker.md.

Фрагмент плана для типовой задачи агентства:

# Отправка заявок с сайта в CRM

## Purpose / Big Picture
После отправки формы «Обсудить проект» заявка появляется в CRM с источником
и UTM-метками. Сейчас заявки уходят только на почту, менеджеры переносят их руками.

## Progress
- [x] (2026-10-20) Изучены форма и компонент обратной связи, найден AJAX-обработчик отправки.
- [x] (2026-10-21) Добавлен клиент CRM с повторными попытками, юнит-тесты зелёные.
- [ ] Очередь на случай недоступности CRM.
- [ ] E2E: отправка формы → запись в тестовой воронке CRM.

## Surprises & Discoveries
- CRM возвращает 200 с полем error при дубликате телефона. Обрабатываем как успех,
  дубликат помечаем. Добавлено в docs/integrations/crm.md.

## Decision Log
- 2026-10-21: отправка через очередь, а не синхронно — форма не должна ждать CRM.
  Отклонено: синхронный вызов с таймаутом 3 с (пользователь видит задержку).

## Validation and Acceptance
- `make test-agent` зелёный.
- На стенде: отправить форму с utm_source=test → карточка в тестовой воронке
  с source=site и utm_source=test в течение минуты.
- При выключенной CRM форма отвечает успехом, заявка доставляется после включения.

Обратите внимание: приёмка описана как наблюдаемое поведение, а не «добавлен класс CrmClient».

Жизненный цикл

У OpenAI каталог docs/exec-plans/ разделён на active/, completed/ и файл tech-debt-tracker.md. Наш вариант для GitLab-процесса:

1. Задача в трекере → агент пишет план в active/ с идентификатором задачи в имени файла.
2. Человек ревьюит план — отдельным коротким MR или первым коммитом в ветке задачи.
3. Агент работает по плану и обновляет Progress и Decision Log в тех же коммитах, что и код.
4. При закрытии: заполнен Outcomes & Retrospective, план перенесён в completed/, найденный долг — в трекер долга, открытия — в docs/.

Завершённые планы — история проекта, которую агент может прочитать: «как в прошлый раз делали интеграцию с платёжкой» становится поиском по completed/.

Когда план не нужен

План исполнения стоит времени на написание и ревью. Биргитта Бёкелер в разборе spec-driven инструментов замечает, что ревьюить объёмный markdown бывает утомительнее, чем код, а один процесс не подходит для задач всех размеров.

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

Прочитай docs/PLANS.md. Изучи код, затронутый задачей, и напиши ExecPlan
в docs/exec-plans/active/<id-задачи>.md. Код не меняй.
Приёмку опиши как поведение, которое можно проверить на стенде.