Current vs desired behavior: мова фактів

1. Одного goal мало

Гарна мета лишає дірки. «Додати поле notes у refund-request» не відповідає: поля немає зовсім чи воно є, але не зберігається? notes лише у формі чи ще й у деталях повернення? потрапляє в подію для інших сервісів? є обхідний шлях? У цих дірках Claude імпровізує — закриває порожнечі здогадками. Чим більше порожнеч, тим сильніше він «лікує проєкт по фотографії»: бачить ідею, не бачить проблему.

Goal задає напрямок, але не розрив між «зараз» і «треба». Розрив описують ще два блоки:

Goal — «Куди хочемо прийти?»

Current behavior — «Що відбувається зараз?»

Desired behavior — «Як має виглядати правильний стан?»

Три частини поруч — і задача перестає бути побажанням.

2. Current behavior: фіксуємо реальність

Задача блоку одна: описати, що спостерігається зараз, без здогадок про причину. Спершу факти, потім версії. Інакше в spec поїде ваша інтерпретація, а Claude схопиться за неї.

Для бага сюди входять симптом, кроки відтворення, фактичний результат, іноді оточення, логи, вплив на користувача. Для фічі — поточне обмеження, обхідний шлях і бізнес-проблема. Current behavior — не тільки для багфіксів.

Одні й ті самі елементи в задачах двох типів:

Крихітний bugfix:

## Поточна поведінка

1. Відкрити `/login`
2. Ввести коректний email і неправильний пароль
3. Натиснути кнопку «Увійти»

Фактичний результат: екран стає порожнім, повідомлення про помилку немає.
Спостерігається у: локальному запуску та staging.

Ні «зламалася backend-валидація», ні «React десь падає». Поки не доведено — це не факт, а версія.

Для фічі логіка та сама: не рішення, а поточний стан — чого немає, як обходяться, чому незручно.

3. Desired behavior: спостережуваний результат

Друга сторона розриву. Пастка — абстракції «має працювати нормально», «зробити зручно»: Claude не знає, де у вас «нормально». Гарний desired такий, що після реалізації проходиш очима по пунктах: так, є; ні, немає.

Описуйте результат зі сторони користувача, інтерфейсу, API, даних, граничних випадків — без технічного рішення. «Використати таку-то бібліотеку» — це шлях реалізації; desired відповідає на «що стане істинним після зміни».

Гарний desired буває коротким, але точним:

## Бажана поведінка

Після неправильного пароля сторінка не стає порожньою.
Користувач залишається на `/login` і бачить зрозуміле повідомлення про помилку.
Успішний логін продовжує працювати без змін.

Останній рядок — про те, що не має випадково зламатися. Ще не розділ про межі задачі, а нагадування про наявну коректну поведінку.

Для фіч desired не дає Claude обмежитися половиною. Не напишете, що поле має і зберігатися, і відображатися, і потрапляти в подію — зробить одну частину і вирішить, що молодець.

4. Hypothesis vs evidence: здогадка і факт

Мозок миттєво підсовує пояснення: «мабуть, валідація», «скоріше за все, міграція», «подію не оновили». Без гіпотез інженерії немає. Біда — коли гіпотеза потрапляє в spec як факт.

Різниця між «спостерігаємо X» і «причина в Y» для Claude критична. Запишете припущення в current behavior без маркування — агент прийме його за дані й почне лагодити цю ділянку. Так народжується random patching: причина не перевірена, код уже правлять.

Evidence — те, що спостерігаємо і можемо показати.

Hypothesis — те, як пояснюємо спостережуване.

Орієнтир за формулюваннями:

Робоча форма запису:

Гіпотеза: проблема може бути в backend-валидації.
Спершу перевір, перш ніж редагувати.

Приписка робить дві речі: зберігає думку і не перетворює її на команду «йди прав backend». Claude отримує сигнал: версія є, спочатку підтвердь.

Процес:

flowchart TD
    A[Спостереження] --> B[Гіпотеза]
    B --> C{Є перевірка?}
    C -- Ні --> D[Не редагуємо код так, ніби причина вже доведена]
    C -- Так --> E[Отримуємо evidence]
    E --> F[Тільки потім змінюємо код]

Маленька схема, а економить час — особливо там, де хочеться «одразу почати виправляти».

5. Commerce OS: F-03, current і desired

Переносимо все у наскрізний проєкт курсу. Задача з Commerce OS: F-03: Add notes field to refund-request. Фіча, не багфікс — і на ній видно, що current behavior потрібен не тільки для помилок.

Робочий фрагмент TASK_SPEC.md draft, який уже можна давати Claude:

## Поточна поведінка

Оператор створює refund-request з `admin/orders/{id}`.
Немає поля, щоб додати контекстну нотатку, наприклад:
«клієнт подзвонив, узгодили часткове повернення».

Зараз нотатка зберігається в окремому коментарі до сапорт-тикета
і не пов’язана із записом повернення.

У підсумку фінансові ревізори не бачать логіку оператора
під час подальшого аудиту повернень.

Гіпотеза: колонка `notes` може вже існувати в таблиці `refunds`
зі старої міграції. Спершу перевір поточну схему, перш ніж редагувати.

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

Цільовий стан:

## Бажана поведінка

- форма refund-request у `admin/orders/{id}` містить необов’язкове поле `notes`
  (textarea, до 1000 символів);
- під час надсилання форми `notes` зберігається разом із записом повернення;
- у картці повернення нотатка відображається в окремій секції;
- payload події `refund.created` містить поле `notes`;
- наявні повернення без нотатки рендеряться коректно, без помилок.

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

Після цих двох блоків Claude бачить увесь розрив, а не один рядок на фронтенді, і не фантазує про причину без перевірки схеми. Приклад сам підводить до потрібних запитань: де живе форма, як зберігається запис, чи є колонка в БД, хто формує refund.created, як рендеряться старі записи. Не «вгадати фікс», а зрозуміти систему за фактами.

6. Спершу перевірка, потім правки

Блоки описані — не просіть Claude «одразу зробити фічу». Нехай спершу прочитає їх як інженерний вхід. Не задасте ритм — він кинеться правити код раніше, ніж підтвердить версії.

Працює коротка інструкція «спершу розберись із фактами»:

Прочитай блоки `Current behavior`, `Desired behavior` і `Hypothesis`.
Спочатку переліч:
1. які твердження вже підтверджені фактами;
2. які потрібно перевірити в коді або схемі;
3. які файли та сутності, ймовірно, пов’язані із задачею.

Код поки не змінюй.

Щоб акуратніше відділити факти від здогадок, тримайте в чорновику TASK_SPEC.md шаблон:

## Поточна поведінка
...

## Бажана поведінка
...

## Гіпотези для перевірки
- ...
- ...

## Відомі докази
- ...
- ...

Не переплутайте рівні. Current behavior і Desired behavior — стійкі частини spec. Hypotheses to verify і Known evidence — тимчасові нотатки: тримайте до правок, після перевірки стисніть або приберіть. Навіть короткий Known evidence привчає питати: «це я спостерігав чи красиво здогадуюся?»

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