SPEC.md як контракт довгої задачі

1. SPEC.md зʼявляється раніше за код

Коли задача маленька, частину речей справді можна втримати в голові: один баг, один тест, один екран — вистачає task spec на пів сторінки. Але capstone — штука довга, памʼять у нього гірша, ніж хотілося б, а сюрпризи зʼявляються частіше, ніж кава встигає охолонути. Тому починати його одразу з коду — усе одно що їхати у відпустку без квитків, маршруту й валізи, але з дуже впевненим обличчям.

На цей момент у вас є дві різні речі, і їх краще не плутати. CAPSTONE_BRIEF.md задає спільні правила capstone для всіх. SPEC.md — ваш особистий контракт: формат, один core flow, non-goals і спосіб перевірки вашого проєкту. Поряд згодом оселиться EVIDENCE.md, але поки контракту немає — журналу нічого фіксувати.

У звичайної задачі та в capstone різний масштаб невизначеності. Це добре видно в простій таблиці.

Саме тому SPEC.md — не папірець для галочки, а інженерний контракт довгої задачі. Він потрібен не тому, що документація — це святе, а тому, що без нього кожен додумує своє: Claude здогадується, ментор уточнює, ревʼюер сумнівається, а ви згадуєте, навіщо прибрали сповіщення і звідки взялася третя гілка «финал_точно_рабочий_2». Зручно думати про нього як про центральну точку узгодження:

Ідея проєкту
    ↓
`SPEC.md`
    ↓
Планування → реалізація → перевірки → demo
    ↑            ↑            ↑
  студент      Claude     mentor/reviewer

Сильний capstone починається не з фрази «зараз швидко накидаємо MVP», а з цього документа, який зменшує кількість здогадок. І не хвилюйтеся: це не роман на вісім розділів — це просто ясна домовленість про те, що ви будуєте, чого не будуєте й як зрозумієте, що все готово.

2. Склад SPEC.md за розділами

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

Проблема

Цільовий користувач

Поточний стан

Бажаний стан

Область змін

Не-цілі

Обмеження

Критерії приймання

План перевірки

Ризики й відкриті питання

Каркас може виглядати ось так:

# SPEC.md

## Проблема
## Цільовий користувач
## Поточний стан
## Бажаний стан
## Область змін
## Не-цілі
## Обмеження
## Критерії приймання
## План перевірки
## Ризики й відкриті питання

Зверніть увагу на дві речі. По-перше, розділу «зробімо красиво» тут немає — компʼютери, ревʼюери й дедлайни з цим критерієм працюють погано. По-друге, важлива не повнота заради повноти, а ясність. Уміщуєте проєкт на одному екрані — чудово. Довелося писати шість сторінок — можливо, річ у тім, що scope починає вириватися з клітки й тікати в ліс.

Щоб не змішувати capstone зі наскрізним CashFlow Dashboard, у прикладах далі візьму окремий навчальний проєкт студента — Subscription Watch. Це маленький сервіс для обліку підписок: користувач бачить активні підписки, найближчі списання і може позначити скасування непотрібної. Домен знайомий за фінансовою темою курсу, але це окремий репозиторій, а не продовження CashFlow.

Далі приклад буде ближчим до продуктового проєкту, бо на ньому найпростіше побачити різницю між проблемою, scope та перевірками. Але ті самі розділи працюють і для інших форматів. У modernization або migration Цільовий користувач — інженер, власник сервісу або сама команда, Поточний стан — legacy-поведінка або ручний крок, Бажаний стан — перевірена зміна або pilot slice. У DevOps automation і team workflow design специфікація крутиться навколо .claude/, .github/, docs/, scripts/ і набору перевірок: UI і src/ там не обовʼязкові. А Критерії приймання і План перевірки нікуди не зникають — замість UI-сценарію там регресійні перевірки, dry run, валідація hooks або evidence по пілотній міграції.

3. Пишемо Problem, Current state і Desired state

На початку SPEC.md потрібна не мрія, а спостережувана проблема. Найчастіша помилка звучить так: «Хочу зробити зручний сервіс підписок» — симпатична, чесна, але все ж мрія. Проблема починається там, де у користувача вже болить щось спостережуване: губляться гроші, пропускаються дати списання, немає єдиної картини витрат. Коли цього немає в тексті, Claude згодом починає допомагати не вам, а абстрактній ідеї зручності. А абстрактні ідеї, як відомо, дуже люблять розростатися.

Для нашого Subscription Watch перші розділи можна накидати так:

## Проблема
Користувач втрачає гроші на забутих підписках і не бачить,
які списання відбудуться в найближчі дні.

## Цільовий користувач
Фрилансер або соло-спеціаліст із 5–10 активними підписками.

## Поточний стан
Підписки зберігаються в нотатках або в голові. Єдиного списку немає.

## Бажаний стан
Користувач додає підписку, бачить дату наступного списання
і може позначити підписку як скасовану.

Тут важливо, що Current state і Desired state описують поведінку, а не архітектурні фантазії. Не «PostgreSQL і красивий React-інтерфейс», а «додає», «бачить», «може позначити» — саме це потім можна перевіряти. Корисно тримати в голові простий тест: виріжте назви технологій — сенс проєкту залишився? Коли ні, capstone швидко перетворюється на ремонт квартири за фразою «давайте щось сучасне»: зайві розетки, дивні рішення й дуже бадьорі виправдання.

Ще один важливий нюанс: Desired state не має обіцяти одразу весь прекрасний світ. Нагадування, імпорт банківських операцій, аналітика, мобільний застосунок, AI-класифікація витрат — не привід писати все в один розділ. Зафіксуйте один виразний результат; решта пізніше стане кандидатом у Non-goals.

4. Scope, Non-goals і Constraints

Саме тут capstone найчастіше рятують від героїчної, але марної загибелі. Поки проєкт живе в голові, усе здається розумним: «Ну список зроблю, і ще сповіщення, і раз уже пішла така справа — інтеграцію з банком теж». Потім настає момент, коли список завдань уже схожий на резюме трьох різних стартапів. Щоб такого не сталося, Scope і Non-goals пишуться рано й чесно:

## Область змін
- список активних підписок
- картка підписки із сумою та датою наступного списання
- позначка «скасовано»
- просте нагадування про близьке списання

## Не-цілі
- інтеграція з банком
- мобільний застосунок
- автоматична категоризація через AI
- production deployment

Це той випадок, коли короткий список економить дуже багато часу. Scope відповідає на запитання «що ми реально довозимо». Non-goals — «на що буде спокуса відволіктися, але ми цього не робимо». І саме другий розділ часто виявляється важливішим за перший: люди не забувають додати задачу в проєкт — вони забувають вчасно її не додати.

Після цього йдуть Constraints — жорсткі технічні та процесні межі:

## Обмеження
- без нових платіжних сервісів
- без складної авторизації
- один основний користувацький сценарій
- проєкт має запускатися локально за README
- усі зміни мають бути перевірюваними вручну та тестами

Constraints корисні тим, що не дають вам самим красиво себе обманути. Фраза «зробимо складну авторизацію потім» майже завжди означає, що ви її вже впустили в проєкт. А capstone дуже не любить незваних гостей. Тому коли ви заздалегідь знаєте, що без production deploy і важкої auth-задачі проєкт буде сильнішим, — краще записати це прямо. Не варто покладатися на внутрішню стійкість: вона працює рівно до першої думки «та це ж невелике доопрацювання».

5. Критерії приймання і План перевірки

Дуже багато проєктів ламаються не на коді, а на фразі «ну ніби готово». В інженерній розробці це небезпечні слова, у capstone — особливо. Тому Критерії приймання і План перевірки зʼявляються ще до реалізації. Один відповідає за те, що має бути істинним у результаті, другий — чим ви це доведете.

Критерії приймання для Subscription Watch можуть бути такими:

## Критерії приймання
1. Можна додати підписку з назвою, сумою та датою списання.
2. На головному екрані видно лише активні підписки.
3. Скасована підписка зникає з активного списку.
4. Користувач бачить найближче списання без переходу до деталей.

А поруч — план перевірки:

## План перевірки
- `./gradlew test` проходить без помилок
- застосунок запускається локально за інструкцією з README
- вручну: додати підписку, позначити її скасованою, знову відкрити список
- вручну: перевірити відображення найближчої дати списання
- у разі падіння перевірки зафіксувати це в `EVIDENCE.md`

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

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

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

6. Claude як редактор SPEC.md, а не телепат

Claude чудово знаходить двозначності, прихований overscope і слабкі місця в постановці. Але є один нюанс: він уміє це робити після того, як ви самі сформулювали думку, а не замість неї. Інакше починається класична історія: ви просите «придумай мені capstone», він чесно вигадує, а ви пів курсу зʼясовуєте, чи подобається вам чужа ідея, яку самі ж попросили згенерувати.

Безпечний спосіб — використовувати Claude як уважного редактора та інтервʼюера:

Перевір мій `SPEC.md`.
Не пропонуй реалізацію і не пиши код.
Знайди:
1) двозначні місця,
2) прихований overscope,
3) слабкі критерії приймання,
4) відсутні перевірки,
5) технічні ризики.
Поверни зауваження за розділами.

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

Подивися на мій `SPEC.md` і постав до 7 уточнювальних запитань.
Не пропонуй код і не розширюй scope.
Твоє завдання — знайти місця, де проєкт поки сформульований неясно.

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

Важливо і те, як ви реагуєте на відповіді. Іноді модель намагається непомітно подарувати вам ще одну фічу, бо їй здається, що так буде краще. Тут допомагає просте правило: коли пропозиція збільшує scope, автоматично в документ вона не потрапляє. Спершу запитання: «Це допомагає основному сценарію чи робить проєкт важчим заради краси?» Дивовижно, скільки ідей не проходять цей фільтр.

7. SPEC.md — живий документ, а не камʼяна плита

Було б приємно один раз ідеально написати специфікацію й більше до неї не повертатися, але на практиці так майже не буває: у довгій задачі ви щось уточнюєте, щось свідомо прибираєте, десь змінюєте спосіб перевірки. Це нормально. Ненормально робити такі зміни мовчки — тоді за тиждень ви вже не памʼятаєте, чому відмовилися від push-сповіщень і з якої радості ручна перевірка стала основною замість тесту.

Тому зрілий SPEC.md — живий документ. Змінюєте scope, non-goals або план перевірки — оновлюєте файл і коротко фіксуєте причину в EVIDENCE.md:

## 2026-05-24
Змінив scope: прибрав push-сповіщення, залишив лише e-mail.
Причина: другий канал ускладнював demo і ламав локальну перевірку.
Оновив у `SPEC.md`: розділи Scope, Non-goals, План перевірки.

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

І ось тут capstone стає по-справжньому керованим. Не тоді, коли ви з першого разу все вгадали ідеально, а тоді, коли можете показати: ось початкова постановка, ось чому скоригували межі, ось як це вплинуло на перевірки, ось чим підтверджується поточний стан. Коли SPEC.md живе разом з evidence, проєкт перестає бути туманною «фінальною роботою» і стає серією ясних рішень, кожне з яких можна прочитати, перевірити й захистити.