Между "понять" и "изменить" стоит отдельная фаза, и смешивать их - дорогая ошибка. Plan mode нужен именно тогда, когда ошибка пересекает несколько модулей, а цена неверного патча выше цены короткого исследования. В таких задачах сначала строят карту, а уже потом принимают решение. Включают режим командой /plan или передают inline-цель; результат - план, который вы одобряете до того, как будет тронут хоть один файл.
Смысл plan mode - отделить исследование от реализации, а не спрятать реализацию под другим названием. В этом режиме агент читает файлы и прослеживает реальные точки входа, вызывающих и тесты, но не редактирует исходники. Это техническая гарантия того, что фаза понимания не превратится незаметно в правки. Но гарантия не отменяет необходимости ясной задачи: режим ограничивает действия, а не заменяет собой формулировку цели и границ.
Хороший план узнаваем по конкретике, а не по общим глаголам. В нём есть не "обнови сервис, добавь тест, проверь", а конкретные файлы и символы, которые будут изменены, зависимости между шагами, тестовый сигнал, вопрос миграции данных и отката, и отдельно - неизвестные, требующие вашего решения. План из трёх общих фраз не даёт точки контроля: по нему нельзя судить, что именно произойдёт, а значит, нельзя и вовремя возразить.
Полезно один раз увидеть формулировку, которая заставляет план быть конкретным. Ниже - запрос на проектирование миграции auth middleware: сначала проследить реальные entry points, callers и tests, файлы не редактировать, а в плане указать порядок, затронутые контракты, откат и проверку каждого этапа. К этой форме возвращаются, когда план вышел общим: она выносит наружу предположения и превращает набросок в проверяемую последовательность шагов.
Самое ценное в плане - вынесенные наружу предположения. Именно они показывают, где план стоит на догадке, а не на прочитанном коде, и где вам, возможно, придётся вмешаться до реализации, а не после. Когда агент явно перечисляет, что он предполагает, но ещё не подтвердил, вы видите слабые места заранее. Скрытое предположение, наоборот, всплывает уже в готовом diff - там его исправлять и дороже, и рискованнее.
Не каждая задача заслуживает плана, и это важно. Для однострочного исправления опечатки с очевидным тестом сложный план добавляет только церемонию: время уходит на оформление того, что и так понятно. Planning применяют там, где discovery способно изменить само решение, - где результат исследования может показать, что первоначальная идея была неверной. Использовать тяжёлый план на тривиальной задаче так же неразумно, как обходиться без плана на рискованной миграции.
Принятие плана - это точка контроля направления, и её проходят осознанно. Перед переходом к записи проверяют git-состояние; если параллельно работает другой агент, берут отдельный worktree. Затем выходят из plan mode, одобряют план и явно повторяют границы: какие шаги реализовать, чего не делать, где остановиться, чтобы показать diff. Повтор границ при одобрении дешевле, чем откат уже сделанных лишних изменений, - это дисциплина, а не лишний ритуал.
Типичные провалы этой фазы предсказуемы. Позволить агенту сразу редактировать плохо понятый код вместо исследования. Одобрить план из общих глаголов без файлов, зависимостей и проверок. Спрятать в реализацию предположение, которое стоило вынести наружу. И потратить тяжёлый план на тривиальную правку. Сначала карта и конкретный план, затем одобрение с границами - и фаза между "понять" и "изменить" перестаёт быть местом, где рождаются красивые, но неверные решения.
/plan Спроектируй миграцию auth middleware.
Сначала проследи реальные entry points, callers и tests.
Не редактируй файлы. В плане укажи order, affected contracts,
rollback и проверку каждого этапа.
Отдельно перечисли предположения, ещё не подтверждённые кодом.