Сначала план: спецификация задачи и режим планирования

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

Карточка в трекере — ещё не спецификация

Типичная карточка в Kaiten: «Добавить фильтр по городам в каталог объектов». Человеку из команды этого хватает: он видел макет, помнит обсуждение, знает, как устроен каталог. У агента этого контекста нет. Ему нужны четыре вещи, которые вы разбирали в уроке «Как ставить задачу агенту»: цель, контекст, ограничения и критерий готовности (в документации OpenAI — Goal, Context, Constraints, Done when).

Цель: на странице /catalog добавить фильтр по городу с мультивыбором.
Контекст: каталог — компонент Catalog в плагине acme/realty
(plugins/acme/realty/components/Catalog.php), города — модель City.
Макет фильтра — на скриншоте.
Ограничения: без новых composer-зависимостей; фильтр работает вместе
с фильтрами по цене и типу; выбор отражается в URL, чтобы ссылку
можно было отправить.
Готово, когда: фильтр работает, есть тест на выборку по двум городам,
composer test и npm run build проходят.

Обратите внимание, чего в спецификации нет: как именно реализовать. Решения о реализации — работа плана.

Режим планирования

Plan mode включается командой /plan или сочетанием Shift+Tab. В этом режиме Codex собирает контекст, задаёт уточняющие вопросы и предлагает план до того, как менять код. Задачу можно передать сразу: /plan Предложи план добавления фильтра по городам. Пока агент уже работает над ходом, /plan недоступен — включайте его в начале.

Дальше агент читает код (компонент, модель, шаблоны, тесты) и возвращается с вопросами: «Учитывать только активные объекты?», «Что показывать, если город удалили?». После ответов он выдаёт план: какие файлы изменить, в каком порядке, как проверить.

Руководство OpenAI по лучшим практикам советует планировать сложные, неоднозначные и трудно описываемые задачи. Для правки опечатки план не нужен.

Уровень рассуждений для режима планирования задаётся отдельно от основного — ключом plan_mode_reasoning_effort. Например, планировать на high, а реализовывать на уровне по умолчанию:

plan_mode_reasoning_effort = "high"

Какие уровни доступны, зависит от модели — см. урок «Модели и уровень рассуждений».

Режим интервью

Бывает, что вы сами не до конца понимаете задачу: карточка в духе «сделать личный кабинет удобнее». Тогда полезнее попросить агента сначала расспросить вас — этот приём тоже есть в руководстве OpenAI.

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

Результат интервью — та же спецификация из первого раздела, только собранная вместе с агентом. Перенесите её в карточку: аналитику и тестировщику она тоже пригодится.

Как проверять план

План читается за пару минут, и это самые выгодные минуты в задаче. На что смотреть:

• Файлы. Все ли нужные места затронуты? Если в проекте фильтры живут в отдельных скоупах модели, а агент собирается писать условия прямо в компоненте, правьте план, а не код потом.
• Переиспользование. Агент склонен писать новое вместо того, чтобы найти существующее. Спросите прямо: «Есть ли в проекте похожие фильтры? Сделай по их образцу».
• Порядок шагов. Миграция, модель, логика, шаблон, тесты — можно ли проверить результат после каждого шага?
• Проверка. Какими командами агент докажет, что задача решена? Если в плане нет тестов или их запуска — допишите.
• Чего в плане нет. Агент не упомянул кэш, права доступа, мобильную вёрстку? Если это важно, скажите.

Правки вносите обычным сообщением: «Шаг 3 — через существующий скоуп scopeApplyFilters, тест — в tests/CatalogFilterTest.php». Когда план согласован, выходите из режима планирования и просите его выполнить.

План как файл

Для задачи на час план может жить в переписке. Для задачи на несколько дней — нет: переписка сожмётся (см. урок о контексте), сессия закончится, а план нужен завтра — вам или коллеге. Попросите сохранить его в файл:

Сохрани согласованный план в docs/plans/task-1234.md: цель, принятые
решения и почему, шаги чекбоксами, команды проверки. По ходу работы
отмечай выполненные шаги.

Новая сессия начинается с фразы «прочитай docs/plans/task-1234.md и продолжи с первого невыполненного шага». Руководство OpenAI идёт дальше и предлагает шаблон PLANS.md — единый формат планов исполнения для длинных многошаговых задач. Подробнее — в гайде по exec plans и в уроке «Планы исполнения как артефакты».

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

• Изменение в одном-двух местах, и вы точно знаете, что делать.
• Механическая правка по чёткому образцу.
• Вопрос «как это устроено?» — там нужен не план, а исследование.

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