Plan-first и review-first workflow

1. «Делай» — самая дорогая команда

Доказательства собраны, критерии приёмки готовы — тянет сразу сказать Claude «правь». Не торопитесь. Самый дорогой артефакт на нетривиальной задаче — не плохой код, а плохой порядок работы. План починить дешевле, чем diff.

В нашем Commerce OS refund-запрос иногда обрабатывается повторно: платежи, внешняя интеграция, риск повторных списаний. Скажете «исправь refunds и покажи готовое» — Claude и сделает ровно это, быстро и с энтузиазмом. На выходе diff, где полезные правки перемешаны с лишним рефакторингом и «улучшениями», которых никто не просил.

Сравните:

Плохо:
«Исправь проблему с refund и сразу сделай всё, что нужно».

Лучше:
«Сначала исследуй refund flow, назови затронутые файлы, риски и план.
Код пока не меняй».

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

2. Шесть фаз цикла

У каждой фазы своя задача и свой результат. Это не бюрократия, а инженерная последовательность.

Цикл не линейный. Падают проверки на Verify — назад к Plan. На Review diff полез не в те файлы — откатываетесь, а не дожимаете.

flowchart TD
    A[Explore] --> B[Plan]
    B --> C[Implement]
    C --> D[Verify]
    D --> E[Review]
    E --> F[Commit / PR]
    D -- проверки не прошли --> B
    E -- scope поплыл или найден риск --> B

В этом и review-first: думаете не только как быстрее поменять, но и как другой человек — или вы сами через час — будет это читать и принимать.

3. Explore — карта до правок

Explore кажется скучной до первого «я и так всё понял», после которого нужная логика оказывается не там. Это исследование перед действием: вы не чините систему, а строите её рабочую карту. В refund-задаче просите Claude пройти цепочку возврата, назвать входные точки, сервисы, тесты и опасные места. Ключевое — без редактирования.

Исследуй refund flow. Код не меняй.
Верни:
1) затронутые файлы,
2) текущий путь данных,
3) существующие tests,
4) возможные риски.

Плохой результат: «кажется, проблема в PaymentClient». Хороший: «Возврат начинается в RefundController, идёт в RefundService, вызывает PaymentClient. Есть RefundServiceTest, но нет теста на повторный retry. Риск — изменить публичный refund API». Это ещё не Plan — пока карта местности.

Здесь и видно, зачем мы раньше собирали пакет доказательств. Дадите логи, affected files и reproduction steps — Claude исследует предметно. Дадите «refund работает странно» — начнёт гадать, причём уверенно.

4. Plan — договор, а не пожелание

После Explore есть материал, но нет управляемого движения. План — договорённость между исследованием и правкой: какие шаги, в каком порядке, где стоп, что считаем риском. Хороший план короткий — несколько шагов, которые проверяются глазами:

## План
1. Добавить защиту от повторной обработки в `RefundService`.
2. Пробросить идентификатор идемпотентности в `PaymentClient`.
3. Добавить regression test на повторный retry.

## Риски
- случайное изменение публичного refund API
- несовместимость с текущим retry-поведением

План на восемь файлов, три подпроекта и «очистку архитектуры заодно» — не глубина мысли, а scope, поплывший до первой правки.

Запишите ожидаемый workflow прямо в TASK_SPEC.md — отдельным разделом того же task package, рядом с критериями приёмки и планом проверки. Claude получает не только цель, но и порядок работы:

## Ожидаемый workflow
1. Explore: прочитать текущий refund flow без edits
2. Plan: вернуть шаги и риски
3. Implement: менять по одному шагу
4. Verify: выполнить проверки из плана проверки
5. Review: показать diff и ограничения

План утверждается до кода — и будущий diff удобно читать. Иначе заранее программируете себе тяжёлое ревью.

Тот же путь Explore → Plan → Review можно вынести в облачный планировщик — агента с расширенным контекстом и встроенной проверкой плана (условно /ultraplan или аналогичная команда; точное имя и доступность могут меняться от версии к версии). Подробнее разберём в следующих уровнях курса — сначала на реальной issue, затем на плане миграции.

Одно неизменно: решение «берём этот план в работу» остаётся за человеком. Планировщик ускоряет проработку и даёт второе мнение, но утверждает план разработчик.

5. Implement — по одному шагу

План утверждён — тянет сказать «делай до конца». На простых задачах проходит. На многофайловых и рискованных — режим один шаг плана за раз. Маленький diff легче понять, проверить и откатить.

Для первой итерации:

Сделай только шаг 1 из плана.
Не переходи к шагу 2.
Меняй только `RefundService` и связанный test, если это действительно нужно.
После правок покажи diff и остановись.

Это не лимит объёма, а защита Review. Diff на два файла и двадцать строк — с ним можно жить. Тронул форматирование в шести соседних классах — проблема видна сразу, пока маленькая.

После каждого meaningful step смотрите хотя бы сводку:

git diff --stat
# RefundService.java     | 12 +++++++++---
# RefundServiceTest.java |  8 ++++++++

Локально и предсказуемо. Вместо двух файлов одиннадцать — момент нажать на тормоз, а не «потом разберёмся».

Plan-first не запрещает скорость. Он не даёт ей перейти в беспорядок.

6. Verify и Review — это разные фазы

Здесь спотыкаются: обе фазы вроде про проверку. Но Verify отвечает на «работает ли решение по критериям?», а Review — на «готовы ли принять именно такое изменение в проект?».

Сравнить это удобно в маленькой таблице:

Запустили проверку из плана проверки:

./gradlew :billing:test --tests RefundServiceTest
# BUILD SUCCESSFUL

Verify прошла. Праздновать рано: тесты зелёные, а diff мог изменить публичный метод, добавить рефакторинг или тихо поменять поведение в соседнем классе. На Review вы смотрите на diff глазами. Почему правка полезла в эти файлы? Не проскочил ли «заодно» рефакторинг? Не исчезли ли важные комментарии? Не изменился ли внешний контракт? Это не недоверие к Claude, а приёмка инженерного изменения.

Запомните: зелёный тест доказывает, что в проверяемом месте ничего не сломалось. Не то, что изменение хорошее, чистое и безопасное.

7. Commit / PR — фиксация решения

Тянет закончить на «тесты зелёные, значит готово». Но пока результат не упакован в commit или PR-описание, у вас не завершённая задача, а набор изменений в рабочем каталоге. Даже один аккуратный commit меняет качество работы:

Плохо:
misc fixes

Лучше:
fix(refunds): предотвратить дубликат возврата при повторе

Во втором случае сразу понятно, что произошло. Ещё лучше — описание в стиле PR-summary:

## Что изменено
Защита от повторной обработки refund при retry.

## Как проверено
Regression test + локальный сценарий из плана проверки.

## Риски
Нужно следить за совместимостью текущего retry-поведения.

Оформляете не «лишь бы закоммитить», а чтобы следующее чтение было лёгким. Через два дня деталей в голове не останется, а commit message и summary хранят смысл лучше памяти. Коммит — не археологический слой из случайных правок и комментариев «потом убрать». Он фиксирует принятое решение.

8. Когда plan-first обязателен, а когда короче

Полный цикл на всё подряд — возненавидите свой workflow. Нет цикла где он нужен — возненавидите свои диффы. Соотносите процесс с риском задачи:

И помните: permission mode не заменяет plan-first. Даже если Claude правит файлы без подтверждений, задача понятнее не становится. Быстрый хаос остаётся хаосом — просто быстрее.

Правило на каждый день: появился хотя бы один признак риска — несколько файлов, неочевидная причина бага, чувствительная зона, угроза совместимости — включаете паузу до редактирования. Сначала Explore, потом Plan, и только потом Implement.

Так Claude перестаёт быть автоматом по выдаче diff'ов и становится инженерным инструментом. Не потому, что поумнел, а потому, что вы перестали бросать его в код без карты, плана и точки приёмки.