Робочий процес plan-first і review-first

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 на два файли й двадцять рядків — із ним можна жити. Зачепили форматування в шести сусідніх класах — проблему видно одразу, поки вона ще маленька.

Після кожного суттєвого кроку дивіться хоча б зведення:

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. Немає циклу там, де він потрібен, — зненавидите свої diffʼи. Співвідносіть процес із ризиком задачі:

І памʼятайте: permission mode не замінює plan-first. Навіть якщо Claude править файли без підтверджень, задача зрозумілішою не стає. Швидкий хаос залишається хаосом — просто швидшим.

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

Так Claude перестає бути автоматом із видавання diffʼів і стає інженерним інструментом. Не тому, що порозумнішав, а тому, що ви перестали кидати його в код без карти, плану й точки приймання.