Ітерація промптів і антипатерни

1. Постановка завдання народжується не з першої спроби

Ідеальний запит з першого разу й бездоганний diff у відповідь — міф. Робоча постановка завдання дозріває до другої-третьої версії. Це не слабкість: означає, що завдання справжнє, а не навчальна загадка на три рядки.

Приклад із Commerce OS: повернення на суму більше 100 доларів ідуть в автообробку, хоча за бізнес-правилами мають чекати ручного підтвердження оператором. Напишете «полагодь обробку повернень» — Claude почне лагодити. Але що він вважатиме проблемою: поріг суми, UI, API, таблицю статусів, чергу задач, поле в базі? Вгадувати вашу думку він не зобов’язаний.

Сира постановка й крок до робочої:

Погано:
«Зроби нормальну обробку повернень у Commerce OS.»

Трохи краще:
«Виправ сценарій, за якого повернення понад 100 доларів
потрапляють в автообробку без ручного підтвердження.»

Другий варіант описує спостережувану проблему, але й він не фінал. Далі виникають запитання. Поріг у 100 доларів — жорстке правило чи налаштування? Хто підтверджує повернення: оператор, менеджер, фінансовий адміністратор? Змінювати лише серверну логіку чи ще показувати в UI статус «очікує підтвердження»? Що робити з уже створеними поверненнями «між світами»? Чи потрібна зворотна сумісність для API?

Ітерація — не бюрократія, а інженерна робота: ідея проблеми → звуження → відокремлення фактів від припущень → обмеження й перевірки. На виході — робочий контракт між вами, Claude і кодовою базою.

Правило: завдання зачіпає більше ніж один файл, змінює помітну поведінку або пахне грошима, доступами, конфігом — перше формулювання буде чернеткою. Гірше за все — самообман «і так зрозуміло», за яким три години розгрібання гігантського diff.

2. Claude interview pattern — запитання до коду

Завдання не вміщується в один прозорий запит — не пишіть одразу повний TASK_SPEC.md. Використовуйте Claude interview pattern: ви приносите робочу заготовку, Claude запитаннями витягує недостаючі деталі. На першому кроці він не пише код — він технічний інтерв’юер.

Патерн добрий, коли проблема зрозуміла за бізнес-сенсом, але не за інженерними межами. З поверненнями так і є: high-value refund не можна автоодобрювати, але де проходить межа змін — незрозуміло.

Короткий цикл:

flowchart TD
    A[Короткий опис проблеми] --> B[Claude ставить уточнювальні запитання]
    B --> C[Ви відповідаєте й звужуєте межі]
    C --> D[Збирається фінальний TASK_SPEC.md]
    D --> E[Нова чиста сесія на implementation]

Погляньте, як це може виглядати на живому прикладі:

Ви: У Commerce OS повернення понад 100 доларів іноді йдуть
в автообробку. Не редагуй код. Спочатку постав запитання,
яких тобі бракує для task spec.

Claude: 1) Де зараз перевіряється сума повернення?
2) Поріг 100 доларів жорстко заданий чи надходить із налаштування?
3) Потрібно блокувати лише автообробку чи й ручне створення теж?
4) Який статус має бачити оператор у UI?
5) Що вважається успішною перевіркою після фіксу?

Claude витягує неочевидне, і не лише про код: налаштування, UX, межі поведінки, верифікацію. Після ваших відповідей spec міцнішає — поріг лежить у конфігу refund.autoApprovalThreshold, схему бази не чіпаємо, публічний API не змінюємо, оператор бачить статус «очікує ручного підтвердження». «Полагодь повернення» стає контрольованою роботою з ясним scope.

Нюанс: Claude допомагає сформулювати завдання, але не затверджує його — це робите ви. Зайве запитання відкидаєте, недостачу ризику додаєте самі. Інакше схема небезпечна: Claude сам вигадав обмеження, сам перевірив, сам оголосив перемогу.

Ознака, що pattern спрацював: тексту не більше — невизначеності менше.

3. Реалізація — старт у новій сесії

Раунд запитань пройшов, контекст теплий — тягне одразу попросити Claude писати код. Тут починається болото. Збір spec і реалізація — дві різні фази, і жити їм корисно окремо.

Поки ви обговорювали завдання, у контексті осіли чорнові гіпотези, відкинуті варіанти, старі припущення. Для вас це мислення. Для моделі — робочий матеріал, який вона продовжує враховувати. Так народжується забруднена сесія: занадто багато слідів тимчасових рішень.

Розділяйте фази явно:

Сесія 1: refund-approval-spec
Результат:
- TASK_SPEC.md
- EVIDENCE_LOG.md

Сесія 2: refund-approval-implementation
Вхід:
- фінальний TASK_SPEC.md
- підтверджений пакет доказів

Три виграші. Implementation стартує на чистому контракті, а не на півтора десятка повідомлень. Зламалося — spec не губиться, живе окремим артефактом. Наступній людині не потрібно перечитувати весь діалог, щоб відрізнити фінальну думку від учорашньої здогадки о 22:47.

Забруднення розпізнається за земними ознаками:

Нова сесія — не втрата прогресу, а спосіб зберегти здоровий глузд. Довга розмова без чіткої межі працює проти вас.

Правило: завдання пройшло через запитання, уточнення й збір TASK_SPEC.md — отже, заслуговує на чистий старт реалізації. Інакше ви побудували креслення, а пишете по пам’яті, поглядаючи на неактуальні чернетки.

4. Антипатерни в prompting

Антипатерн — це не лише погана фраза. Частіше ламається поведінка: запит ввічливий, а процес побудований так, що завдання приречене на хаотичний diff і слабке приймання. Це повторювані збої workflow.

Найшкідливіші:

Два найпідступніші варто розібрати. Fix everything для Commerce OS небезпечний: повернення, замовлення, підтримка та платежі виглядають пов’язаними, і Claude заодно «підчистить» сервіс, DTO, UI-статуси та кілька тестів у сусідньому модулі. Підсумок — величезний diff.

Claude said it works означає одне: модель сформулювала впевнену пропозицію природною мовою. diff себе не прочитав, тести себе не інтерпретували, межі ніхто не перевірив. Впевнений тон — не доказ.

5. Фінальний шаблон Task Spec

Тепер у вас є все для фінального шаблону, який не соромно віддати Claude, колезі й собі завтра. Це робочий контракт, а не папірець для порядку. Заповнений по-справжньому — знімає купу хаосу до першої правки. Заповнений формально — гарний, але марний ритуал.

Верх шаблону — Ціль і бажаний результат, Поточна поведінка і бажане, Межі завдання, Обмеження — був потрібний і раніше. Сьогодні додаємо фактичну базу, критерії приймання, план перевірки, Готовність задачі й очікуваний workflow:

# TASK_SPEC.md

## Ціль і бажаний результат
## Поточна поведінка і бажане
## Межі завдання (scope і non-goals)
## Обмеження та межі змін
## Пакет доказів (коротка витиска + посилання на EVIDENCE_LOG.md, якщо його винесено окремо)
## Критерії приймання
## План перевірки
## Готовність задачі
## Очікуваний workflow
## Очікуваний артефакт

За кожним рядком — робота. Верхні секції захищають завдання від розповзання й «корисного, але небезпечного» надмірного розширення меж. Пакет доказів прив’язує його до фактів; якщо повний журнал у EVIDENCE_LOG.md, тут вистачить витиски й посилання. Критерії приймання, План перевірки, Готовність задачі заздалегідь відповідають, за чим приймаєте результат. Очікуваний workflow нагадує маршрут для нетривіального завдання: Explore → Plan → Implement → Verify → Review → Commit/PR. Очікуваний артефакт фіксує, що ви хочете на виході: аналіз, diff, тести, документацію або зміну під рев’ю.

Заповніть шаблон під Commerce OS — і абстракція стане робочою річчю. Відкриваєте його в новій сесії: «Ось затверджена spec. Працюй лише в цих межах. Упрешся в суперечність — зупинися й постав запитання». Доросла позиція не в довжині документа, а в тому, що головні інженерні рішення ухвалені заздалегідь: що змінюємо, чого не змінюємо, як перевіряємо і коли задача готова.