Специфікація: як описати продукт, щоб агент зробив саме те, що треба

1. Про заняття

Цей розділ — про початок четвертого заняття: що в ньому нового порівняно з С1–С3, що буде за дві години і в якому порядку, що знадобиться, щоб повторити все самостійно. Розбір завдання С3 тренер показує зі звіту перевірки — у слайдах і в конспекті його немає.

#Специфікація: як описати продукт, щоб агент зробив саме те, що треба

Слайд 145

С4 — четверте з дев'яти занять курсу «AI-агенти в роботі QA та BA». Воно відбулося в середу, 14.10.2026, і тривало дві години. Строк завдання С4 — вівторок, 20.10.2026, 23:59. Розбір завдання — на занятті С5, у середу, 21.10.2026.

На С3 ви бачили, що правда про функцію живе в трьох місцях: сторінка бази знань, журнал рішень і коментар у задачі. І ці місця розходяться. На С4 цю правду збирають в одне місце — специфікацію. З неї агент бере, що має бути правдою, а не вгадує. А ще вчаться змінювати специфікацію так, щоб кожну зміну було видно: пропозиція → перевірка → архів.

Навіщо? У С1–С3 ви перевіряли одну відповідь агента. Але функцію не описують за одну відповідь: ви уточнюєте, додаєте, переписуєте — і з кожною ітерацією агент «дрейфує»: додає своє, забуває домовлене, суперечить сам собі. Докладно — у розділі 2.

Нового вміння небагато — це нове місце для того, що ви вже вмієте. AC Given / When / Then із С2 стають сценаріями WHEN / THEN. Навичка С3 вирішувати за датами, яке правило чинне, лишає слід у рядку «Джерело: …» біля кожної вимоги.

Що ще нового в С4:

• Новий проєкт — gitlab.com/koldovsky/ai-qa-ba-c4. Форки С1–С3 не підходять, потрібен новий форк.
• Формат — OpenSpec, відкритий інструмент розробки від специфікації (spec-driven development). Його файли — звичайний Markdown, їх можна писати з будь-яким агентом чи чатом. Програма OpenSpec CLI — за бажанням.
• Основа завдання — функція вашого варіанту, того самого, що в С1–С3. Або, за бажанням, власна ідея: вигадана функція вигаданого продукту, без корпоративних даних і реальних компаній.
• Бали — як у С3: до 10 за кожен рівень, за частинами.
• Токен-звіт у С4 не потрібен. Він повернеться в С5.

Заняття вчить чотирьох речей:

1. Описувати функцію специфікацією разом з агентом: вимоги зі словами SHALL/MUST, сценарії WHEN/THEN і джерело біля кожної вимоги.
2. Перевіряти, що згенерував агент: що він вигадав, що пропустив, де взяв застаріле правило.
3. Змінювати вимоги через пропозицію (change proposal) і стежити, щоб після змін специфікація і похідні артефакти не суперечили одне одному.
4. За бажанням — перевіряти формат програмою: openspec validate перевіряє файли, openspec archive зливає прийняту зміну в специфікацію.

Для BA специфікація — пакет вимог, у якому видно кожну зміну. Для QA — джерело тестів: сценарій WHEN/THEN стає тест-кейсом.

#План: від розбору С3 до специфікації

Слайд 146

Після розбору С3 — чотири тематичні блоки, у трьох із них — демо наживо. Далі завдання С4 і питання.

Три демо йдуть ланцюжком на демо-варіанті «Зміна адреси доставки» (change-address) — тому самому, що в С2 і С3: кожне працює з результатом попереднього. Записи від 14.10.2026 — на сторінці демо.

• Підготовка — openspec init у теці здачі: запис.
• Демо 1 — агент через GitLab MCP читає джерела С2 і С3 і складає специфікацію функції, а ви перевіряєте, що він вигадав і що пропустив: запис.
• Демо 2 — зміна вимог за відкритою сторі [00-3] через пропозицію: proposal, delta і tasks. Двома способами: командою /opsx:propose (запис) і звичайним промптом без CLI (запис).
• Демо 3 — OpenSpec CLI у терміналі: перевірка формату, перегляд змін, архів (запис). Строга перевірка --strict знайшла задовгу вимогу — агент її виправив (запис).

Робота за демо-варіантом не зараховується — виконуйте свій варіант або власну ідею.

Що знадобиться, щоб повторити заняття самостійно:

• Репозиторій практики gitlab.com/koldovsky/ai-qa-ba-c4. README — завдання, таблиця варіантів з посиланнями на ваші джерела, бали, здача; OPENSPEC.md — CLI для охочих; templates/ — шаблони специфікації, зміни, звіту і ручного чек-листа; examples/00-demo/ — зразок за рівнями l1–l3, відкривайте після власної спроби.
• Сторінка демо — записані прогони трьох демо. Шпаргалка — промпти, команди, каркаси файлів і чек-лист для кожного кроку завдання на одній сторінці.
• Claude Code зі вступного пакета (інший агент чи AI-чат теж підійде, але інструкція до CLI — лише для Claude Code), акаунт на gitlab.com — той самий, що в С1–С3, і Git.
• Доступ агента до джерел. GitLab MCP із С3 працює тут, якщо ви підключали його для всіх проєктів (claude mcp add -s user …); підключений через .mcp.json копії С3 — лише в тій теці. Без MCP вставте текст файлів і задач (з коментарями) у чат агента або збережіть у підтеку sources/ своєї теки.

#Розбір С3 — у звіті перевірки

Слайд 147

Перші 15 хвилин — розбір завдання С3 зі звіту перевірки; у конспекті його немає.

Суперечності, які ви знаходили в С3, — і є причина, чому потрібна специфікація. Якщо правда розкидана по сторінках і коментарях, агент бере ту версію, яка трапилася першою.

2. Чому агенту потрібна специфікація

Цей розділ пояснює, чому одного промпту мало, коли функцію описують не одним запитом, а кількома ітераціями. Ви побачите, як агент «дрейфує» від ітерації до ітерації; чим «вайб»-промпт відрізняється від специфікації; чому специфікація — це контракт «що має бути правдою»; що вона дає BA і QA; як вона продовжує те, що ви робили в С1–С3; і що таке spec-driven development та OpenSpec.

Демонстрацій тут немає. Як влаштована специфікація зсередини і як агент пише її з джерел С2–С3 — у розділі 3 і в демо 1.

#Чому агенту потрібна специфікація

Слайд 148

Агент робить те, що описано. Чого не описано — додає сам. Він забуває домовлене і з кожною ітерацією відходить від того, що вирішила команда.

У С1–С3 ми давали агенту задачу і джерела, а потім перевіряли результат. Для однієї відповіді цього досить. Але функцію не описують за одну відповідь: ви уточнюєте, додаєте, переписуєте. Саме тут агент починає дрейфувати. У цьому розділі — п'ять тем:

1. Дрейф — як домовлене зникає між ітераціями.
2. Промпт і специфікація — у чому різниця.
3. Контракт — що саме описує специфікація.
4. BA і QA — що специфікація дає кожній ролі.
5. Spec-driven development — підхід та інструмент OpenSpec.

#Кожна ітерація «краща» — а домовлене зникає

Слайд 149

Таблиця нижче — узагальнена ілюстрація, а не запис реальної сесії. Функція знайома з С2 і С3: демо-варіант «Зміна адреси доставки». В агента в контексті є все, що ви бачили тоді: вимога версії 1.0 з С2 і сторінки бази знань С3 з пізнішими рішеннями. Ми просимо дрібні поліпшення — чотири звичайні запити поспіль.

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

Що діє насправді і звідки «повернулася» стара версія:

Жоден запит не просив змінити ці правила. Агент їх не «забув» зі зла: домовленість ніде не записана як правда, вона лише десь у чаті. Довгий чат стискається, а нова сесія чи /clear починає з нуля — і пояснювати треба знову.

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

#«Вайб»-промпт проти специфікації

Слайд 150

«Вайб»-промпт — це коли описуємо на відчуття і правимо, поки не сподобається. Звідси і слово «вайб-кодинг». Для прототипу на вечір це нормально. Для функції, яку будуть розробляти, тестувати й підтримувати, — ні.

Рядок за рядком:

• Що описує. «Як у нормальних сервісах» — і агент заповнить прогалини «звичайною практикою». Специфікація каже, що саме має бути правдою і звідки це правило.
• Де живе. Промпт — у вашому чаті. Специфікація — файл поруч з роботою. Його бачить команда, а не лише ви.
• Нова сесія. Промпт треба пояснювати знову. Файл агент просто перечитує.
• Як перевірити. Сценарій «коли … тоді …» — готова перевірка з відповіддю «так» або «ні». «Наче нормально» — не перевірка.
• Зміна правила. У чаті нове повідомлення лягає поверх старих, і вже невідомо, що з них діє. У специфікації зміна — окремий документ: що змінюємо, чому і з якого джерела.

Структурований промпт з п'яти частин із С1 нікуди не дівається. Ви й далі ставите задачу агенту промптом. Різниця в тому, що тепер промпт посилається на специфікацію: «працюй за специфікацією функції; чого в ній немає — питай».

#Специфікація — контракт: що має бути правдою

Слайд 151

Специфікація — контракт між усіма, хто працює з функцією: бізнесом, розробкою, тестуванням і агентом. Вона не каже, як зробити. Вона каже, що має бути правдою, коли зроблено.

Ось одна вимога демо-функції у форматі, з яким ми працюємо сьогодні. Це ілюстрація зі слайда, фрагмент файлу openspec/specs/change-address/spec.md:

### Requirement: Межа часу для зміни адреси
Система SHALL дозволяти зміну адреси до 20:00 за київським часом дня, що передує очікуваній даті доставки.
Джерело: decisions.md, 19.05.2026; [00-1].

#### Scenario: Спроба після межі
- **WHEN** о 20:01 дня перед очікуваною датою доставки отримувач відкриває картку посилки
- **THEN** кнопка «Змінити адресу» неактивна, під нею текст «Змінити адресу вже не можна.»

Кожна вимога складається з трьох речей:

Вимога — одне правило. Слово SHALL пишемо англійською: так прийнято у форматі, і саме так його розпізнає інструмент. Текст навколо — українською, за шаблоном «Система SHALL показувати …».

Рядок «Джерело» — вимога нашого курсу, а не самого формату: звідки правило і коли його вирішили. Це навичка з С3 — шукати рішення з датою.

Сценарій — конкретний приклад: коли … тоді … Зверніть увагу: у сценарії взято 20:01, а не рівно 20:00. Що буде рівно о 20:00, джерела однозначно не кажуть. Таке в специфікації не вигадуємо, а виносимо у відкриті питання — у звіті С4 для них є окремий пункт.

Специфікація описує поведінку, яку видно ззовні. Не «кнопка робить запит до сервера», а «отримувач бачить …». І одна вимога — це одна поведінка.

Формат по частинах — заголовки, ключові слова, сценарії — у розділі 3.

#Одна специфікація — дві роботи

Слайд 152

Той самий файл працює для обох ролей, але кожна бере з нього своє.

BA — пакет вимог під контролем. Ви й так ведете пакет вимог. Проблема, яку ми бачили в С3: правило змінюють у коментарі до задачі, а сторінка лишається старою. У специфікації інакше:

• поточна правда — один файл на функцію;
• зміна — окрема пропозиція: чому міняємо, що саме і на що це впливає;
• видно, що саме змінилося: вимогу додали, змінили чи прибрали — ADDED, MODIFIED, REMOVED;
• біля правила — хто і коли вирішив.

Виходить пакет вимог, де кожну зміну видно і її можна погодити. Як оформити зміну — у розділі 4.

QA — джерело тестів. Сценарій WHEN / THEN — це вже майже тест-кейс. Із С2 ви знаєте три типи: позитивні, негативні, межові. Межа 20:00 дає два межові тест-кейси — до і після межі. Правило про поштомат — негативний.

Коли вимога змінюється, ви бачите, які сценарії змінилися. А отже знаєте, які тест-кейси оновити, які додати, а які прибрати.

У завданні С4 це окремі пункти для кожної ролі:

Приклад рядка для BA з README завдання: «Джерело: decisions.md, запис 28.04.2026 — рішення власниці продукту Оксани».

#Від промпту — до одного джерела правди

Слайд 153

С4 продовжує три попередні заняття. Кожне дало навичку, яка тепер стає частиною специфікації.

У С3 ви бачили: сторінка каже одне, журнал рішень — інше, коментар у задачі — третє. У С4 ви збираєте правду в одне місце і змінюєте її під контролем.

Що саме переходить у специфікацію:

• Із С2. AC у форматі Given / When / Then стають сценаріями WHEN / THEN. Ті самі «коли … тоді …», лише в іншому файлі.
• Із С3. Рішення з датою стає рядком «Джерело: …» біля вимоги. Навичка С3 — вирішувати за датами, яке правило чинне, — тепер потрібна до того, як правило потрапить у специфікацію. Суперечність вирішують спершу, а в рядку «Джерело» лишається слід: звідки правило і коли його вирішили.

#Spec-driven development і OpenSpec

Слайд 154

Spec-driven development — розробка від специфікації. Спершу команда домовляється, що має бути правдою. Потім агент планує і робить від цього опису, а не від останнього повідомлення в чаті. А коли правило змінюється, спершу пишуть пропозицію зміни, а не правлять «як вийде».

OpenSpec — один з відкритих інструментів для цього підходу. Ми беремо його, бо все в ньому — звичайні Markdown-файли в теці openspec/ поруч з проєктом. Вони читаються без програмування. Поточна версія станом на 13.10.2026 — 1.14.1.

Цикл OpenSpec — п'ять кроків:

<capability> — назва функції латиницею, наприклад change-address у демо-варіанті. <id> — назва зміни, теж латиницею, малими літерами, через дефіс, наприклад status-change-during-edit.

У завданні С4 коду немає. Для BA і QA «реалізація» — це сторі, UAT, сторінки бази знань, тест-кейси: усе, що треба оновити після зміни вимог.

Три речі про OpenSpec, які варто запам'ятати:

• Відкритий інструмент. Markdown-файли в теці openspec/, репозиторій на GitHub.
• Будь-який агент. Формат — звичайний Markdown. Заповнити його можна з Claude Code, з іншим агентом, у чаті або вручну.
• CLI — за бажанням. Команда /opsx:propose у Claude Code, openspec validate і openspec archive у терміналі — у розділі 5 і в демо 3.

Далі — як влаштована специфікація зсередини (розділ 3) і як агент пише її з джерел С2–С3 у демо 1.

3. Анатомія специфікації

У розділі 2 ми домовилися: специфікація — це контракт «що має бути правдою». Тут — як цей контракт виглядає у форматі OpenSpec: один файл на функцію, чотири види заголовків, слова SHALL і MUST, вимоги зі сценаріями. Далі — як писати вимогу, щоб розробка й агент зрозуміли її однаково, а QA взяв з неї тести. І головне — яка правда потрапляє у специфікацію: та, що діє сьогодні. Тут знадобиться навичка С3 — читати джерела за датами.

Наприкінці — демо 1: агент складає spec.md демо-функції «Зміна адреси доставки» з джерел С2–С3, а ми читаємо чернетку і перевіряємо її. У завданні С4 це рівень L1.

#Анатомія специфікації: що має бути правдою

Слайд 155

Специфікація OpenSpec — один файл на функцію. У ньому три речі: навіщо функція, які правила діють сьогодні і як перевірити кожне правило. Агент складає чернетку такого файлу з джерел, які ви знаєте з С2 і С3: вимога з матеріалами до неї, сторінки бази знань, задачі трекера з коментарями. Ви перевіряєте кожну вимогу.

Розділ іде в тому самому порядку, що й слайди:

1. файл spec.md і його заголовки;
2. сила вимоги: SHALL, MUST, SHOULD, MAY;
3. добра вимога і сценарії до неї;
4. поточна правда: що потрапляє у специфікацію, коли джерела розходяться;
5. демо 1 — агент пише spec.md, ми читаємо результат.

#Один файл — одна функція

Слайд 156

Де лежить. openspec/specs/<capability>/spec.md. У теці openspec/specs/ — по підтеці на кожну функцію. В OpenSpec функцію називають capability. Назва теки — латиницею, малими літерами, через дефіс. У завданні це назва теки вашого варіанту без номера: courier-slots, refuse-return, trusted-person, home-pickup, damage-claim, loyalty-points, partial-cod, notifications, locker-booking, promo-codes. У демо-варіанті — change-address. Власна ідея — своя назва за тими самими правилами. Один файл spec.md — уся поточна правда про функцію.

Каркас — з шаблону templates/spec-template.md (без коментарів-підказок і двох прикладів вимог):

# <capability> Specification

## Purpose

<2–4 речення: що робить функція і для кого>

## Requirements

### Requirement: <назва: одна поведінка>
Система SHALL <що робить і за яких умов>.
Джерело: <файл і розділ / задача і коментар із датою / власний запит, п. N>.

#### Scenario: <назва звичайного сценарію>
- **WHEN** <умова або дія>
- **THEN** <видимий результат>

#### Scenario: <назва негативного чи межового сценарію>
- **WHEN** <умова не виконана або на межі правила>
- **THEN** <що робить система>

Згори вниз:

• Перший рядок — # change-address Specification: назва функції і слово Specification.
• ## Purpose — 2–4 речення: що робить функція і для кого. Людині, яка відкрила файл уперше, цього має вистачити, щоб зрозуміти, про що він. Purpose, коротший за 50 символів, — попередження openspec validate.
• ## Requirements — список вимог. Кожна починається з ### Requirement: і назви. Під назвою — речення з SHALL або MUST: що робить система.
• «Джерело: …» — рядок під текстом вимоги: звідки правило і коли його ухвалили. Цього рядка OpenSpec не вимагає — його вимагає курс: так вимогу можна перевірити.
• #### Scenario: — приклад, як перевірити вимогу. Рядок - **WHEN** … — що відбувається, - **THEN** … — що має бути, за потреби - **AND** … — ще одна умова чи ще один результат.

На слайді — фрагмент демо-специфікації з вимогою про поштомат. Ось інша вимога того самого файлу, повністю, — зі зразка examples/00-demo/l1 репозиторію С4:

### Requirement: Межа часу для зміни адреси
Система SHALL дозволяти змінити адресу не пізніше 20:00 за київським часом дня, що передує очікуваній даті доставки. Після цієї межі кнопка «Змінити адресу» MUST бути неактивною, під нею — текст «Змінити адресу вже не можна.»
Джерело: `decisions.md`, 19.05.2026 (рішення Оксани, діє з 25.05.2026); `[00-1]`, коментар Оксани 19.05.2026; `overview.md`, «Коли можна змінити адресу». Замінило AC5 `requirement.md` (24 години).

#### Scenario: Зміна ввечері напередодні до 20:00
- **WHEN** доставка очікується в четвер, а отримувач відкриває картку посилки в середу о 19:59 за київським часом
- **THEN** кнопка «Змінити адресу» активна

#### Scenario: Межа 20:00 минула
- **WHEN** доставка очікується в четвер, а отримувач відкриває картку посилки в середу о 20:01 за київським часом
- **THEN** кнопка «Змінити адресу» неактивна
- **AND** під нею текст «Змінити адресу вже не можна.»

Що тут видно:

• Назва — одна поведінка: межа часу.
• SHALL і MUST — великими латинськими літерами, у тексті під заголовком. Тут обидва слова описують одне правило: що можна до 20:00 і що бачить отримувач після межі.
• «Джерело» — рішення з датою, хто вирішив і яке старе правило воно замінило: у вимозі С2 було «менш ніж за 24 години».
• Два сценарії — по обидва боки межі: 19:59 і 20:01. Тексти, які бачить отримувач, — дослівно.

Мінімум для L1 — щонайменше 6 вимог, у кожної — сценарій. Усі вимоги завдання — у розділі 6.

#Сила вимоги — одним словом

Слайд 157

Слова SHALL, MUST, SHOULD і MAY — зі стандарту RFC 2119. Одне слово каже, наскільки правило обов'язкове.

Для BA слово — це переклад сили правила з джерела. «Не більше двох змін» — SHALL. Не пом'якшуйте правило до SHOULD, якщо джерело цього не каже: «рекомендовано» і «обов'язково» — різні правила, це ми бачили в С3. У джерелах варіантів курсу майже всі правила — SHALL або MUST. Заборону пишуть як SHALL NOT або MUST NOT — так у зразку записано вимогу про посилки з післяплатою.

Для QA слово підказує вагу знахідки: порушене SHALL — дефект, порушене SHOULD — зауваження, відсутність того, що MAY, — не дефект.

Мова. Специфікація двомовна, і в цьому є система.

• Українською — Purpose, назви вимог і сценаріїв, усі речення. Шаблон речення: «Система SHALL …». Приклад зі слайда: «Система SHALL дозволяти не більше двох змін адреси на одну посилку.»
• Англійською — структурні заголовки ## Purpose, ## Requirements, ### Requirement:, #### Scenario: і слова SHALL/MUST. Так вимагає парсер OpenSpec: він шукає саме ці слова. Вимога без SHALL чи MUST — попередження openspec validate; з --strict перевірка через нього не проходить (позначка лишається ⚠ [WARNING]). SHALL лише в назві вимоги не рахується: слово має стояти в тексті під заголовком.
• **WHEN**, **THEN**, **AND** — теж англійською, для одноманітності. Validate їх не перевіряє, але так специфікації однакові в усіх, і їх легко порівнювати.

Хто працює з OpenSpec CLI: openspec init --tools claude --language "Ukrainian" записує правило про мову у файл openspec/config.yaml, і агент його бачить. У записаному прогоні цей фрагмент файлу виглядав так:

context: |
  Language: Ukrainian
  All artifacts must be written in Ukrainian.
  Keep OpenSpec structural headings and SHALL/MUST keywords in English.

Без CLI те саме правило дайте агенту в промпті, наприклад рядком із промпту демо 1: «заголовки, SHALL/MUST і WHEN/THEN — англійською, решта — українською».

#Добра вимога — одна поведінка

Слайд 158

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

Одна поведінка. Вимога з «і … і … і» — це кілька правил в одній. Тест до неї впаде, а яке з правил порушено — не видно. А коли зміниться одне з них — а в розділі 4 ми побачимо, що правила змінюються, — доведеться переписувати всю вимогу. Ознака з шаблону: «і ще», «а також» чи два різні правила в тексті — це дві вимоги. Друга ознака — довжина. Текст вимоги до першого сценарію — не більше 500 символів. Рядок «Джерело: …» стоїть до першого сценарію — він теж рахується; пишіть його стисло. Довший — попередження validate, а з --strict перевірка не проходить. Деталі й винятки — у сценарії.

Перевірювана. Пам'ятаєте AC2 з демо-вимоги С2: «зручно» і «швидко»? Тест до цього не напишеш. Що можна перевірити — лишаємо вимогою: нова адреса — лише в тому самому населеному пункті. «Швидко» без числа — у відкриті питання, а не вигадане «за 2 секунди».

Без «як». Поле профілю, запит, таблиця бази даних — це рішення розробки. Специфікація каже, що бачить і що отримує користувач. Інакше вимога застаріє з першою переробкою коду, а QA не зможе перевірити її ззовні. Назви кнопок і тексти повідомлень, які бачить користувач, — можна: це видима поведінка. Колір кнопки чи її місце на екрані — ні.

З джерелом. Рядок «Джерело: …» — файл і розділ або ключ задачі й коментар з датою. BA додає, хто вирішив: у демо це Оксана, власниця продукту. Без джерела вимогу не перевірити — і не сказати, чи вона ще чинна. Для власної ідеї — «Джерело: власний запит, п. N».

#Сценарій — заготовка тест-кейсу

Слайд 159

Трійка знайома з С2: позитивний, негативний і межовий сценарій. Тепер вона у форматі OpenSpec. Приклади — з демо-функції.

• Позитивний — правило працює. Такі сценарії агент пише охоче й багато.
• Негативний — умову порушено, і система відмовляє передбачувано: оплата не пройшла — адреса стара. Саме тут живуть дефекти, які доходять до клієнта.
• Межовий — край правила. Друга зміна — остання дозволена, третьої вже немає, і на межі — конкретний текст. Те саме з часом: о 19:59 напередодні ще можна, о 20:01 — уже ні. А рівно о 20:00? Джерела на це однозначно не відповідають. Тож це не сценарій із вигаданою відповіддю, а відкрите питання — про це в наступному підрозділі.

Як записати у файлі. Кожен рядок сценарію — пункт списку: - **WHEN** …, - **THEN** …, за потреби - **AND** …. На слайді зірочки прибрано, щоб легше читалося; у файлі вони потрібні. Порада з шаблону: назви сценаріїв — без чисел правила, «Строк минув», а не «8-й день». Коли правило зміниться, назву можна лишити, а зміна MODIFIED вимагає всіх старих назв сценаріїв (розділ 4).

QA: сценарій → тест-кейс. Сценарій — це вже половина тест-кейсу: WHEN — кроки й дані, THEN — очікуваний результат. У звіті QA — таблиця «сценарій → тест-кейс» з назвою і типом тест-кейсу. Для демо-варіанту вона могла б починатися так (сценарії — зі зразка examples/00-demo/l1):

BA: сценарій → приклад правила. Власник продукту бачить правило на прикладі і каже «так, саме так» ще до розробки. Ті самі сценарії — готова основа для UAT.

Скільки потрібно в завданні: для всіх — щонайменше два негативні або межові сценарії; для QA — щонайменше три і таблиця «сценарій → тест-кейс».

#У специфікації — те, що діє сьогодні

Слайд 160

Ми весь час кажемо «чинне правило». Яке саме — коли джерела розходяться? Навичка С3 — читати джерела за датами — тепер стає правилом відбору для специфікації. П'ять ситуацій зі слайда, усі — з демо-варіанту:

• Сторінка старша за рішення. Продуктову сторінку overview.md востаннє редагували 26.05, і там нове відділення «автоматично стає основним». А 12.08 у задачі [00-2] власниця продукту вирішила: основним — лише з галочкою «Зробити це відділення основним», за замовчуванням вимкненою; реліз 3.4 вийшов 01.09. У специфікації — галочка, а в «Джерело» — коментар із рішенням.
• Дві сторінки розходяться. FAQ контакт-центру (відповідь перевіряли 16.04) — будь-який поштомат міста. Журнал рішень, 28.04, — поштомат лише з підтвердженим номером, діє з 04.05. Вирішує дата рішення, а не те, що здається логічнішим.
• Обіцянку скасували. «Сайт у 3-му кварталі 2026» — рішення 21.07 переносить це на 2027. Скасованого в специфікації немає.
• Відкрита сторі. У [00-3] є AC і навіть рішення в коментарях, але сторі ще не випущена. Це не сьогоднішня правда, а зміна. Вона піде в L2; як — у розділі 4.
• Відповіді немає. Рівно о 20:00 — ще можна чи вже ні? Агент охоче допише «включно». Не дозволяйте: це відкрите питання у звіті — і кого спитати.

Ще одне правило демо-варіанту змінювали — межу часу: у вимозі С2 (AC5) — «менш ніж за 24 години», а за рішенням 19.05 — до 20:00 напередодні очікуваної дати доставки. Повна таблиця «застаріле → чинне» для демо-варіанту — у README зразка. Порівнюйте зі своєю роботою після власної спроби.

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

BA: хто і коли вирішив. Для кожної вимоги, правило якої змінювали, BA вказує, хто і коли ухвалив рішення. Приклад із README: «Джерело: decisions.md, запис 28.04.2026 — рішення власниці продукту Оксани».

#Демо 1: агент пише spec.md

Слайд 161

Мета демо — показати, що специфікацію агент складає за хвилину, а цінність — у перевірці: чи взяв він чинне правило і чи нічого не вигадав. Запис прогону з усіма кроками агента — на сторінці демо.

Як записували. Claude Code у режимі claude -p, модель claude-sonnet-5-5, 14.10.2026. Клон проєкту С4, тека здачі після openspec init --tools claude --language "Ukrainian" (як це виглядає — підготовка на сторінці демо). З MCP-серверів підключено лише GitLab. Готові зразки examples/00-demo/l1–l3 з клону прибрали, щоб агент не міг у них підглянути.

Промпт. Ті самі чотири частини, що в С3: роль, джерела, задача, формат. На слайді — скорочений варіант. Ось повний текст, з яким записано прогін:

Ти — бізнес-аналітик команди «Мобільний застосунок» сервісу «Пакунок». Склади специфікацію функції «Зміна адреси доставки» у форматі OpenSpec: файл openspec/specs/change-address/spec.md.
Джерела (читай через GitLab MCP):
- koldovsky/ai-qa-ba-c2: materials/demo/change-address/ — requirement.md, sources.md, bug-report.md;
- koldovsky/ai-qa-ba-c3: kb/00-demo-change-address/ — overview.md, decisions.md, support-faq.md; задачі з міткою варіант::00 (відкриті й закриті) разом із коментарями.
Правила:
- спека описує поточну правду на 14.10.2026; де джерела розходяться — бери новіше рішення (дата, хто ухвалив);
- відкрита, ще не реалізована сторі — не поточна правда, у спеку її не включай;
- формат: # change-address Specification, ## Purpose (2–4 речення), ## Requirements; кожна вимога — ### Requirement: …, одна поведінка, «Система SHALL …»; під описом — рядок «Джерело: …» (файл і розділ або задача і коментар із датою); у кожної вимоги щонайменше один #### Scenario: з - **WHEN** … - **THEN** …; серед сценаріїв щонайменше два негативні або межові;
- заголовки, SHALL/MUST і WHEN/THEN — англійською, решта — українською;
- нічого не вигадуй: чого немає в джерелах — окремим списком «Відкриті питання» у відповіді, не в спеці.
Теку examples/ не відкривай.

Нове порівняно з С3 — у правилах: «спека описує поточну правду на 14.10.2026», «відкрита, ще не реалізована сторі — не поточна правда» і формат OpenSpec. І явне місце для невідомого: список «Відкриті питання» у відповіді, а не у файлі.

Що робив агент.

1. Прочитав через GitLab MCP файли С2 — requirement.md, sources.md, bug-report.md — і сторінки С3: overview.md, decisions.md, support-faq.md.
2. Шукав задачі з міткою варіант::00. Перший пошук повернув порожній список: у мітці агент змішав латинські й кириличні літери. Він повторив пошук із правильною міткою і знайшов три задачі: [00-1] і [00-2] закриті, [00-3] відкрита. Кожну прочитав разом із коментарями.
3. Записав openspec/specs/change-address/spec.md. Уся робота забрала 58 секунд.

Що вийшло. 10 вимог; у кожної — рядок «Джерело» і два сценарії. У відповіді агент пояснив, де джерела розходяться і що він узяв: межу 20:00 напередодні (рішення 19.05, [00-1]) замість «менш ніж за 24 години» з AC5; галочку для основного відділення (рішення 12.08, реліз 3.4 від 01.09, [00-2]) замість «автоматично»; поштомат лише з підтвердженим номером (рішення 28.04). Сайту у специфікації немає: зміну адреси на сайті перенесено на 2027 рік (рішення 21.07).

Окремо агент перелічив, що свідомо не включив. Відкриту сторі [00-3] — разом із рішенням про автоматичне повернення 30 грн з коментарів 14–15.09. Баг-репорт С2 про поштомати сусіднього міста: це дефект, а специфікація описує вимогу. Лист власниці продукту про «до трьох змін» із sources.md: журнал рішень від 17.03 каже «не більше двох».

Наприкінці — шість відкритих питань. Серед них: чи зараховується невдала спроба до ліміту двох змін (Марта питала 16.09 у [00-3], відповіді немає); як рахується межа 20:00, якщо очікувану дату доставки перенесли.

Три перевірки зі слайда — і що показав запис:

Що видно, якщо читати далі. Три перевірки агент пройшов. Але чернетка — ще не готова робота:

• Валідацію агент не запускав — так і написав у відповіді. Перевірка формату — ваш крок, див. нижче.
• Межовий сценарій — не на межі. У вимозі про межу часу сценарії — 19:30 і 20:01. 20:01 — край правила, а 19:30 — ні. У зразку examples/00-demo/l1 — 19:59 і 20:01.
• «Рівно 20:00» серед відкритих питань немає. Шість питань агент склав, а найочевиднішого для межі — ні. Таке додаєте ви.
• Шосте питання — не відкрите. Чи діють ті самі правила для контакт-центру — на це overview.md, розділ «Канали», відповідає: «правила ті самі». Бракує вимоги про канали, а не відповіді: у зразку l1 вона є. Відкрите питання — те, на що джерела не відповідають.
• Дві поведінки в одній вимозі — «Платна друга зміна», про неї вище. У демо 3 саме вона не пройшла --strict.
• Порівняння зі зразком. У examples/00-demo/l1 — 11 вимог: там є окрема вимога про канали (застосунок і контакт-центр, на сайті — ні) і окрема — про невдалу оплату другої зміни.

Як перевірити свою специфікацію. Ручний чек-лист templates/validation-checklist.md: для L1 — розділи А і В. Розділ А — ті самі правила, що перевіряє openspec validate: шлях до файлу, заголовки, сценарії з чотирма решітками, SHALL/MUST у тексті, не більше 500 символів. Розділ В — зміст, якого validate не бачить: «Джерело» біля кожної вимоги, лише чинні правила, відкрита сторі не стала вимогою, нічого не вигадано, одна вимога — одна поведінка, без «як», серед сценаріїв є негативні й межові.

З CLI: openspec validate <capability>, повна перевірка — openspec validate --all --strict (з --strict не проходять і попередження). Вивід або заповнений чек-лист — у розділ 5 звіту. Що агент вигадав, пропустив чи взяв застарілим і що ви виправили — у розділ 4 звіту. Без CLI бали ті самі.

Специфікація — це поточна правда. А правда змінюється: сторі [00-3] чекає своєї черги. Як змінювати вимоги через пропозицію — у розділі 4.

4. Зміна через пропозицію

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

Нижче — тека зміни і її файли, чотири розділи delta, погляд BA і QA, цикл propose → review → apply → archive і демо 2 на демо-варіанті «Зміна адреси доставки». У завданні це L2; повний цикл з archive — L3, команди CLI для нього — у розділі 5. Записи прогонів — на сторінці демо, промпти й команди — у шпаргалці.

#Зміна вимог — через пропозицію

Слайд 162

У С3 ви бачили, що буває, коли правило змінили в коментарі задачі, а сторінку бази знань не оновили: через кілька місяців ніхто не скаже, яке правило чинне. Зі специфікацією може статися те саме. Якщо щоразу правити spec.md напряму, за місяць знову не буде видно, що змінилося, коли і чому.

OpenSpec пропонує інший порядок. Кожна зміна — окрема пропозиція в окремій теці. Поки вона чернетка, її читають і правлять. Лише після перевірки вона стає частиною специфікації, а до того чинна специфікація лишається такою, як була.

#Не правити специфікацію, а пропонувати зміну

Слайд 163

Два підходи до однієї правки — і п'ять питань, які рано чи пізно поставлять до будь-якої вимоги:

## Why з джерелом — та сама простежуваність, що в L1, де під кожною вимогою стоїть «Джерело: …». Помилку агента видно в чернетці, а не в чинній специфікації; формат перевіряє openspec validate або ручний чек-лист templates/validation-checklist.md. А tasks.md — саме той крок, який загубили в демо-варіанті С3: рішення лишилося в коментарі задачі, а сторінку й FAQ ніхто не оновив.

Для BA це керування змінами вимог у малому форматі. Для QA — одразу видно, які тести зачепить зміна.

#Тека зміни openspec/changes/id-зміни/

Слайд 164

openspec/
├── specs/change-address/spec.md       ← чинна правда
└── changes/status-change-during-edit/
    ├── proposal.md                   ← навіщо і що
    ├── specs/change-address/spec.md  ← delta
    ├── tasks.md                      ← що зробити
    ├── design.md                     ← за бажанням
    └── .openspec.yaml                ← створює CLI

Основну специфікацію з демо 1 не чіпаємо, доки зміну не прийнято. Зміна — окрема тека в openspec/changes/, одна тека — одна зміна. Назва теки — id зміни: каже, що змінюється, а не «zmina-1».

proposal.md — навіщо і що:

• ## Why — одне-два речення: яку проблему розв'язує зміна або яке рішення її вимагає. Обов'язково з джерелом: задача і коментар із датою, рішення з журналу з датою, для власної ідеї — «власний запит, п. N». Без джерела незрозуміло, чи зміна справжня, чи її вигадав агент.
• ## What Changes — по пункту на кожну зміну; для зміненого правила — було і стало. Кожному пункту — вимога в delta, і навпаки.
• ## Capabilities — нові й змінені функції. У С4 нових зазвичай немає, змінена одна — функція вашого варіанту.
• ## Impact — кого і що зачіпає: сторі, сторінки бази знань, FAQ, тест-кейси, контакт-центр.

Каркас із шаблону templates/change/proposal.md, без коментарів-підказок:

# Proposal

## Why

<навіщо зміна, 1–2 речення. Джерело: …>

## What Changes

- <що додається: нова поведінка>
- <що змінюється: було → стало>

## Capabilities

### New Capabilities

- Немає

### Modified Capabilities

- `<capability>`: <які вимоги змінюються>

## Impact

- <кого і що зачіпає>

Бали L2 за proposal — за ## Why з джерелом, ## What Changes і ## Impact. openspec validate не перевіряє текст proposal.md: його якість — на вас.

Решта теки:

• delta specs/<capability>/spec.md — лише вимоги, які змінюються. Файл називається spec.md, тека функції — як в основній специфікації: change-address. Детально — далі;
• tasks.md — чек-лист: групи ## 1. … і пункти - [ ] 1.1 …;
• design.md — за бажанням: контекст, рішення, ризики. У С4 він не потрібен: якщо агент його створив, прочитайте — і лишіть або видаліть;
• .openspec.yaml створює CLI, коли відкриває нову зміну: у ньому записано схему зміни. Без CLI цього файлу немає — і це нормально.

Заголовки розділів — англійською, як в основній специфікації: за ними OpenSpec знаходить розділи. Текст — українською.

#Delta: лише вимоги, які змінюються

Слайд 165

Delta — не нова версія всієї специфікації, а лише вимоги, які змінюються, у чотирьох розділах:

ADDED. Правила ті самі, що в L1: одна поведінка, SHALL/MUST, «Джерело: …», щонайменше один сценарій #### Scenario: з WHEN/THEN. Перш ніж писати ADDED, перевірте, що такої вимоги в основній специфікації ще немає. Якщо є — це MODIFIED. У демо 2 ADDED — наприклад, автоматичне повернення 30 грн, якщо адресу не змінено після оплати.

MODIFIED — тут найчастіша помилка. Під час archive вимогу з тією самою назвою в основній специфікації замінить блок із delta — цілком. Чого в блоці немає, після archive зникне. Тому:

1. Скопіюйте з основної специфікації весь блок вимоги: заголовок, текст, «Джерело» і всі сценарії.
2. Лише потім правте: нове правило, нове джерело з датою, нові сценарії.
3. Назви старих сценаріїв не змінюйте. Сценарій суперечить новому правилу — перепишіть його WHEN і THEN, а назву лишіть.
4. Назва вимоги — дослівно як в основній специфікації, до літери і пробілу. Нова назва — це RENAMED.

Агент любить писати в MODIFIED лише новий сценарій. Тоді решта сценаріїв зникла б, і OpenSpec вважає це помилкою: MODIFIED "…" omits scenario(s) the current spec still has: …. Розбіжність у назві підступніша: openspec validate її пропускає — лише з рядком ℹ [INFO] … Archive would refuse this delta, — а archive зупиняється з Aborted. No files were changed.

Приклад із демо 2. В основній специфікації вимога «Платна друга зміна» мала два сценарії — «Оплата пройшла» і «Оплата не пройшла». Сторі [00-3] додає правило AC2: якщо умови зміни перестали виконуватися до оплати, оплата не починається. Агент записав MODIFIED так:

## MODIFIED Requirements

### Requirement: Платна друга зміна
Система SHALL вимагати за другу зміну адреси 30 грн, сплачені платіжною карткою до підтвердження зміни; якщо оплата не пройшла, система SHALL залишити попередню адресу, гроші не списуються; якщо до оплати умови зміни перестали виконуватися (статус чи часова межа), система SHALL NOT починати оплату й SHALL показати відповідне повідомлення про відмову.

Джерело: kb/00-demo-change-address/overview.md, розділ «Скільки разів і скільки коштує»; decisions.md, запис 17.03.2026; support-faq.md, питання про невдалу оплату (16.04.2026); задача 00-3, опис, AC2.

#### Scenario: Оплата пройшла
- **WHEN** отримувач підтверджує другу зміну й оплачує 30 грн карткою
- **THEN** адресу змінено

#### Scenario: Оплата не пройшла
- **WHEN** оплата 30 грн за другу зміну не пройшла
- **THEN** адреса лишається попередньою, гроші не списуються

#### Scenario: Умови змінилися до оплати через статус
- **WHEN** отримувач оформлює другу зміну, а до оплати посилка отримала статус «Прибула у відділення»
- **THEN** оплата не починається, він бачить «Посилка вже прибула у відділення. Адресу не змінено.», гроші не списуються

#### Scenario: Умови змінилися до оплати через межу 20:00
- **WHEN** отримувач оформлює другу зміну, а до оплати минуло 20:00 напередодні очікуваної дати доставки
- **THEN** оплата не починається, він бачить «Змінити адресу вже не можна.», гроші не списуються

Назва та сама, обидва старі сценарії на місці, два нові додано. У «Джерело» з'явилося «задача 00-3, опис, AC2», а назву питання FAQ агент переказав своїми словами: було «Оплата другої зміни не пройшла. Що з адресою?», стало «питання про невдалу оплату». Рядок джерела звірте самі. За формою це правильний MODIFIED, і openspec validate status-change-during-edit --strict його прийняв. Але в тексті вимоги тепер три правила: плата, невдала оплата і перевірка умов до оплати. Після archive openspec validate --all --strict видав попередження саме на цю вимогу: Requirement text is very long (>500 characters). Як агент це виправив — у демо 3.

REMOVED — коли правило скасували. Заголовок вимоги з назвою дослівно як в основній специфікації і два рядки, без сценаріїв:

### Requirement: <назва вимоги — дослівно як в основній специфікації>
**Reason**: <чому вимога більше не діє; джерело — рішення з датою>
**Migration**: <що діє замість неї>

Якщо назва в REMOVED не збіглася, archive лише попередить — і стара вимога лишиться в специфікації.

RENAMED — коли змінюється лише назва; буває рідко:

- FROM: `### Requirement: <стара назва — дослівно як в основній специфікації>`
- TO: `### Requirement: <нова назва>`

Для L2 найчастіше трапляються ADDED (нова поведінка зі сторі) і MODIFIED (сторі зачіпає чинне правило); REMOVED — коли пізніше рішення скасувало правило. Порожній розділ видаліть разом із заголовком. ## Purpose у delta не потрібен. Заголовки розділів — англійською і дослівно, з двома решітками, інакше OpenSpec їх не побачить: No delta sections found. Назви вимог і сценаріїв — українською.

#Одна зміна — два погляди

Слайд 166

Зміна та сама, а питання до неї в BA і QA різні:

Ілюстрація зі слайда — tasks.md для демо-варіанту; у вашому варіанті пункти свої:

## 1. BA
- [ ] 1.1 Сторі [00-3]: AC про повернення 30 грн
- [ ] 1.2 overview.md і FAQ: нове правило
- [ ] 1.3 UAT: сценарії для AC1–AC4
- [ ] 1.4 Погодити з власницею продукту

## 2. QA
- [ ] 2.1 Нові: статус змінився до «Підтвердити»
- [ ] 2.2 Нові: оплата пройшла → повернення
- [ ] 2.3 Застарілі: «Щось пішло не так» — переписати
- [ ] 2.4 Регресія: межа 20:00, ліміт двох змін

BA. Рішення про повернення 30 грн є лише в коментарях задачі [00-3]. Його треба внести в сторі, на сторінку і в FAQ — це та сама прогалина, яку шукали в С3.

QA. Сценарії WHEN/THEN з delta — прямий вхід для нових тест-кейсів. Тест-кейс, який чекав старої поведінки — повідомлення «Щось пішло не так», — після зміни застарів: його переписують. Регресія — суміжні правила, яких зміна не мала зачепити.

Формат для обох однаковий: групи ## 1. …, пункти - [ ] 1.1 …, виконане — - [x]. Задача — одна дія, яку можна позначити виконаною. Не «оновити документацію», а «оновити AC2 сторі … під нову вимогу «…»». У шаблоні templates/change/tasks.md дві групи, BA і QA: лишіть групу своєї ролі, другу — за бажанням.

OpenSpec створено для розробки, тож агент за замовчуванням пише в tasks.md задачі для коду. Скажіть йому прямо, що потрібні задачі вашої ролі. У демо 2 промпт містив «tasks.md — не код: група BA (…) і група QA (…)», і агент склав 9 задач BA і 7 задач QA.

#Цикл: propose → review → apply → archive

Слайд 167

1. Джерело. Для L2 за замовчуванням — відкрита сторі вашого варіанту з трекера С3, мітка тип::сторі. Поки вона не реалізована, вона не чинна правда: у L1 її немає, а її AC і рішення з коментарів стають delta.
2. propose. Агент створює теку зміни і пише чернетку: proposal, delta, tasks. У Claude Code з OpenSpec CLI — /opsx:propose, без CLI — звичайний промпт.
3. review. Найважливіший крок для нас. Читаєте чернетку, як відповідь агента в С3: джерела, вигадане, пропущене. Правите вручну або просите агента — з CLI для цього є /opsx:update. Формат — openspec validate або ручний чек-лист.
4. apply. У розробці тут пишуть код. У нас — виконати tasks.md: оновити сторі, сторінки, тест-кейси і позначити [x]. /opsx:apply у С4 не обов'язковий.
5. archive. Зміна стає правдою: delta зливається в основну специфікацію в порядку RENAMED → REMOVED → MODIFIED → ADDED, а тека переїжджає в changes/archive/YYYY-MM-DD-<id>/. Специфікація описує нове правило, архів пам'ятає, коли і чому.

Звідки зміна для L2, якщо сторі вже випущена. Закрита і випущена сторі (у варіантах 01, 02 і 08 це так) — частина чинної правди L1. Тоді візьміть питання з коментарів задач, на яке ще немає відповіді: оформіть зміну як пропозицію, а рішення лишіть відкритим питанням до власника. Або новий запит. Власна ідея — новий запит до своєї функції, записаний у звіті.

Archive. У терміналі — openspec archive <id> --yes: злиття за правилами OpenSpec, з перевіркою формату. У Claude Code — /opsx:archive <id>: зливає агент, тож потім перечитайте основну специфікацію. Без CLI — вручну, у тому самому порядку. Виконані задачі позначте до archive: з --yes він лише попереджає про невиконані, як у записі демо 3 — Warning: 16 incomplete task(s) found. Continuing due to --yes flag. Команди — у розділі 5, слайди 169–174.

До propose можна ще /opsx:explore — подумати разом з агентом, якщо варіантів зміни кілька; файли вона пише, лише якщо ви погодитеся.

#Демо 2: зміна за сторі [00-3]

Слайд 168

Чернетку зміни агент пише за хвилину-півтори. Цінність — у тому, що ви знайдете в ній за п'ять. Демо 2 перетворює відкриту сторі [00-3] «Статус посилки змінився під час оформлення зміни адреси» на пропозицію зміни. Що в сторі:

Рішення про повернення є лише в коментарях: агент, який дивиться лише на AC, його пропустить. А правило про ліміт спроб було б вигадкою — на питання від 16.09 ніхто не відповів.

Промпт з CLI. На слайді — скорочений текст, у записі — повний:

/opsx:propose status-change-during-edit — зміна до функції change-address за відкритою сторі [00-3] у koldovsky/ai-qa-ba-c3: опис, AC1–AC4 і всі коментарі 10–16.09 (читай через GitLab MCP). Чинна специфікація — openspec/specs/change-address/spec.md. Рішення з коментарів — теж джерело; у кожної вимоги в delta — рядок «Джерело: …». Якщо зміна зачіпає чинну вимогу — MODIFIED з повним текстом і всіма сценаріями. tasks.md — не код: група BA (сторі, UAT, сторінки бази знань, FAQ, хто погоджує) і група QA (тест-кейси додати, змінити, прибрати; регресія). Чого немає в джерелах — не вигадуй, винеси у відкриті питання.

Кожна частина закриває типову помилку: «всі коментарі» і «Рішення з коментарів — теж джерело» — щоб агент не обмежився AC; «MODIFIED з повним текстом» — щоб не загубив сценарії; «tasks.md — не код» — щоб не писав задачі розробки; «не вигадуй» — щоб ліміт спроб став відкритим питанням.

Що показав запис (демо 2):

• Прогін продовжує сесію демо 1: сторі [00-3] з коментарями агент прочитав через GitLab MCP ще там, тож тепер до GitLab не звертався. У новій сесії агент має прочитати сторі заново.
• /opsx:propose сам викликав OpenSpec CLI — openspec new change status-change-during-edit, openspec status, openspec instructions. Дві складні команди Bash Claude Code не пропустив під час перевірки дозволів, і файли агент записав інструментом Write.
• Створено proposal.md, delta і tasks.md. design.md агент пропустив як необов'язковий: openspec status показав 3 з 4 артефактів, і це нічому не заважає.
• Delta — 4 ADDED і 1 MODIFIED. ADDED: «Повторна перевірка статусу під час підтвердження» (AC1), «Повторна перевірка часової межі під час підтвердження» (AC3), «Автоповернення коштів, якщо адресу не змінено після оплати» (коментарі 10, 14 і 15.09), «Стан кнопки після відмови» (AC4). MODIFIED «Платна друга зміна» (AC2) — повний текст з усіма чинними сценаріями плюс два нові. У кожної вимоги — «Джерело: …».
• tasks.md — 9 задач BA (сторі, відкриті питання, UAT, overview.md, decisions.md, FAQ, погодження, архівування) і 7 задач QA (нові, змінені й застарілі тест-кейси, регресія).
• openspec validate status-change-during-edit --strict — Change 'status-change-during-edit' is valid.
• У відповіді — шість відкритих питань. Серед них ліміт спроб (Марта, 16.09; «Вимогу про це я не писав») і чи діє автоповернення, якщо між оплатою і збереженням настала межа 20:00: рішення говорить лише про статус.
• Наостанок агент запропонував /opsx:apply для реалізації. У С4 коду немає: задачі з tasks.md виконуєте ви.

Прогін — 90 с і 9 викликів інструментів.

Без CLI (демо 2 без CLI) — той самий запит звичайним промптом. Структуру файлів, яку з CLI дає OpenSpec, тут описуєте ви:

Підготуй зміну у форматі OpenSpec з id status-change-during-edit до функції change-address за відкритою сторі [00-3] у koldovsky/ai-qa-ba-c3: опис, AC1–AC4 і всі коментарі 10–16.09 (читай через GitLab MCP). Чинна специфікація — openspec/specs/change-address/spec.md.
Створи в openspec/changes/status-change-during-edit/:
- proposal.md — ## Why (1–2 речення з джерелом), ## What Changes, ## Impact;
- specs/change-address/spec.md — delta: ## ADDED Requirements для нової поведінки; ## MODIFIED Requirements, якщо зміна зачіпає чинну вимогу (повний текст вимоги з усіма сценаріями, потім правка); у кожної вимоги — рядок «Джерело: …» і сценарії WHEN/THEN;
- tasks.md — чек-лист - [ ] 1.1 …: група BA (сторі, UAT, сторінки бази знань, FAQ, хто погоджує) і група QA (тест-кейси додати, змінити, прибрати; регресія).
Рішення з коментарів — теж джерело. Чого немає в джерелах — не вигадуй, винеси у відкриті питання у відповіді.

Це окрема сесія, Bash у ній заборонено. Агент прочитав чинну специфікацію з теки (Read), а сторі [00-3] з коментарями — через GitLab MCP, і створив ті самі три файли. Сторінок kb/ він не відкривав і прямо написав про це — так само дивіться, що саме прочитав ваш агент. Розподіл інший: 3 ADDED і MODIFIED «Платна друга зміна», у якому і перевірка умов до оплати, і повернення 30 грн. Перевірок агент не запускав; пізніше в терміналі openspec validate status-change-during-edit --strict показав Change 'status-change-during-edit' is valid. Без CLI замість цієї команди — розділи Б і В ручного чек-листа.

Різний розподіл — нормально. З CLI — 4 ADDED і 1 MODIFIED, без CLI — 3 і 1, у готовому зразку examples/00-demo/l2/ — 2 і 2: там інакше вирішили, які правила змінити, а які додати. Правильний будь-який розподіл, якщо поведінка та сама, кожна MODIFIED — повна, а її назва дослівно збігається з назвою у вашій основній специфікації. Тому перевіряйте зміну лише разом зі своєю специфікацією.

Що перевірити в чернетці — три питання зі слайда:

1. Джерела. Why і кожна вимога — з [00-3], коментарем і датою? У записі з CLI кожна вимога delta має «Джерело: …», а ## Why посилається лише на сторі, без коментарів і дат, хоча зміна спирається на рішення 14–15.09. Таке варто дописати. Без CLI ## Why називає і Марту 10.09, і Богдана 14.09, і Оксану 15.09.
2. Пропущене. Рішення 14–15.09 про повернення 30 грн — у delta? У записі — так: з CLI окрема ADDED-вимога з двома сценаріями, без CLI — частина MODIFIED. Агент узяв рішення, бо промпт прямо назвав коментарі. У своєму варіанті перевірте це першим.
3. Вигадане. Ліміт спроб? В обох прогонах питання від 16.09 — у відкритих питаннях, а не у вимогах.

І ще кілька перевірок, яких validate не зробить: ADDED — справді нова поведінка, а не друга версія чинної вимоги; ## What Changes збігається з delta; тексти повідомлень — дослівно, як у сторі; tasks.md — задачі BA і QA, а не «реалізувати API»; одна вимога — одна поведінка. Остання перевірка спрацювала б на MODIFIED «Платна друга зміна»: у ньому три правила, і після archive саме він не пройшов --strict (демо 3).

Якщо в чернетці чогось бракує — виправте одним промптом, а не переписуйте зміну з нуля. Наприклад, якщо агент пропустив повернення, вигадав ліміт спроб і написав задачі для розробки:

Додай ADDED-вимогу про повернення 30 грн за коментарями 14.09 і 15.09 — зі сценарієм і джерелом. Правило про ліміт спроб прибери — винеси у відкриті питання. Перепиши tasks.md для BA і QA.

З CLI той самий опис дають командою /opsx:update <id> — вона узгоджено править proposal, delta і tasks. У записаному прогоні такої правки не знадобилося: це приклад для вашої чернетки.

Чернетку з демо 2 тут не архівували: у демо 3 її перевірили openspec validate, переглянули openspec show status-change-during-edit --diff і заархівували (розділ 5).

5. OpenSpec CLI — за бажанням

Формат OpenSpec — звичайний Markdown. У розділах 3 і 4 специфікацію і зміну писали разом з агентом, і для завдання С4 цього досить. OpenSpec CLI — програма, яка додає дві речі: готові команди /opsx:* у Claude Code і перевірку та злиття змін у терміналі. CLI — за бажанням: бали за нього не додають і не знімають.

Нижче — як встановити CLI і підключити його до своєї теки здачі, які команди з'являються в Claude Code і в терміналі, чим відрізняються два способи archive. Далі — демо 3 зі справжнім виводом команд: попередження про невиконані задачі, перевірка --strict, яка не пройшла, і як агент це виправив. Останній підрозділ — для тих, хто працює без CLI. Повна інструкція — OPENSPEC.md у репозиторії С4, усі команди коротко — у шпаргалці.

#OpenSpec CLI у Claude Code — за бажанням

Слайд 169

Файли OpenSpec можна написати з будь-яким агентом або вручну — формат від цього не залежить. CLI робить дві речі:

1. Дає команди /opsx:* у Claude Code. Агент уже знає формат OpenSpec: які потрібні теки, файли і заголовки. Пояснювати це в кожному промпті не треба. Одну таку команду, /opsx:propose, ви бачили в демо 2.
2. Перевіряє і зливає зміни в терміналі. openspec validate перевіряє формат, openspec archive зливає зміну в основну специфікацію. Це робить програма, а не модель, тож результат щоразу той самий.

Без CLI — те саме завдання. Файли пишете за шаблонами з templates/, замість openspec validate — ручний чек-лист templates/validation-checklist.md, archive робите вручну. Вимоги до файлів і бали однакові. Як саме — у підрозділі «Без CLI» наприкінці розділу.

#Встановити і підключити до теки здачі

Слайд 170

Три кроки: встановити програму (один раз на комп'ютер), підключити її у своїй теці здачі, перезапустити Claude Code.

Що потрібно. OpenSpec — програма на Node.js, тож спершу потрібен Node.js 20.19 або новіший. Перевірка в терміналі (Windows — PowerShell, macOS — Terminal):

node --version

Підходить v20.19.0 і новіші, наприклад v22.… чи v24.…. v18.… або v20.18.… — застара. Node.js немає — встановіть версію LTS з nodejs.org. На робочому ноутбуці для цього можуть знадобитися права адміністратора.

Крок 1 · встановити.

npm install -g @fission-ai/openspec@latest
openspec --version

openspec --version має показати номер версії. На момент заняття це 1.14.1. Ставте завжди з @latest: інші мітки версій у npm застарілі. Через npx OpenSpec не запускайте: команди /opsx:* викликають openspec напряму, тому потрібне саме глобальне встановлення (-g). На Windows потрібна версія 1.13.2 або новіша — @latest це забезпечує.

Якщо щось пішло не так:

Робочий комп'ютер. Там глобальне встановлення може бути заборонене. Тоді — вдома або без CLI. Обходити правила компанії не треба.

Телеметрія. OpenSpec за замовчуванням надсилає авторам статистику використання. Вимкнути:

openspec config set telemetry.enabled false

Інший спосіб — змінна середовища OPENSPEC_TELEMETRY=0.

Оновлення. Та сама команда npm install -g @fission-ai/openspec@latest, потім openspec update у теці, де лежить openspec/: вона оновить файли для Claude Code.

Крок 2 · підключити у своїй теці. Не в корені репозиторію, а в submissions/ваш-username/ (замість ваш-username — ваш username на gitlab.com):

cd ~/ai-qa-ba-c4/submissions/ваш-username
openspec init --tools claude --language "Ukrainian"

--tools claude — налаштувати OpenSpec для Claude Code без додаткових запитань. --language "Ukrainian" записує в openspec/config.yaml правило для агента: усі файли — українською, структурні заголовки і SHALL/MUST — англійською. Це те саме правило, що в розділі 3.

openspec init створює:

submissions/ваш-username/
├── openspec/
│   ├── config.yaml     # налаштування: тексти українською, заголовки і SHALL/MUST — англійською
│   ├── specs/          # основні специфікації (L1)
│   └── changes/
│       └── archive/    # заархівовані зміни (L3)
└── .claude/            # 6 команд /opsx:* і 6 скілів OpenSpec для Claude Code — у MR не додавати

Так виглядав вивід openspec init у записаному прогоні — тека здачі в клоні проєкту С4, OpenSpec 1.14.1, 14.10.2026 (див. сторінку демо):

- Creating OpenSpec structure...
▌ OpenSpec structure created
- Setting up Claude Code...
✔ Setup complete for Claude Code

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Note: 6 more workflows are available (new, continue, ff, bulk-archive, verify, onboard).
Add them with `openspec config profile`.

Learn more: https://github.com/Fission-AI/OpenSpec
Feedback:   https://github.com/Fission-AI/OpenSpec/issues

Головне тут — рядки 6 skills and 6 commands in .claude/ (це команди /opsx:* з наступного підрозділу) і Config: openspec/config.yaml. Note: 6 more workflows… — розширений набір команд, його вмикають через openspec config profile. Для С4 він не потрібен.

Натрапите в інтернеті на openspec/project.md чи openspec/AGENTS.md — це інструкції до версії 1.0. Зараз цих файлів немає: контекст проєкту — в openspec/config.yaml.

Крок 3 · перезапустити Claude Code саме в цій теці. Якщо claude уже працює — /exit, потім у тій самій теці знову claude. Як зі скілами на С3: Claude Code бере команди з теки, де його запустили. Без перезапуску нових команд не буде. Перевірка: наберіть /opsx — Claude Code покаже шість команд.

Команди openspec … і claude запускайте з submissions/ваш-username/: там лежить openspec/.

#Шість команд /opsx:* у Claude Code

Слайд 171

Після init і перезапуску в Claude Code з'являються шість команд. Агент уже знає формат OpenSpec — пояснювати, які заголовки й теки потрібні, не треба.

propose — головна команда для L2: одна команда — і є тека зміни з чернетками. Працює вона через CLI. У записаному демо 2 агент після /opsx:propose сам запускав openspec new change, openspec status і openspec instructions. Тому CLI і потрібен встановлений глобально.

Чернетку після propose читайте як роботу колеги, так само як у демо 2: чи є біля кожної вимоги джерело, чи взято рішення з коментарів, чи не вигадав агент правило чи ліміт.

design.md. Propose може його створити або пропустити. У С4 він не потрібен: можна видалити або лишити. У демо 2 агент його пропустив як необов'язковий, тому openspec status показав 3 з 4 артефактів — це нормально.

apply у програмістів реалізує задачі з tasks.md. У С4 коду немає: tasks.md — чек-лист для людей (BA — що оновити, QA — які тест-кейси). Задачі виконуєте ви самі або з агентом звичайним промптом і позначаєте виконане - [x]. Наприкінці демо 2 агент запропонував запустити /opsx:apply — для завдання С4 цей крок не потрібен.

update — знайшли помилку в чернетці: /opsx:update <id> і що виправити. Агент узгоджено поправить proposal, delta і tasks. Або правте Markdown самі.

sync зливає delta в основну специфікацію силами агента, а зміна лишається активною — коли ви ще над нею працюєте.

archive перевіряє зміну, пропонує sync і переносить теку в архів з датою. Злиття тут пише модель. Чим це відрізняється від archive у терміналі — нижче, у «Зафіксувати зміну».

Приклад команди для L2 з OPENSPEC.md — замініть дужки своїм:

/opsx:propose <id> Зміна до функції <capability> за сторі <номер> з трекера С3: візьми AC і рішення з коментарів, з датами. Delta: ADDED — нова поведінка; MODIFIED — якщо змінюється чинна вимога, з повним текстом і всіма її сценаріями. tasks.md — група BA або QA. Біля кожної вимоги — «Джерело: …». Чого немає в джерелах — не вигадуй.

Якщо /opsx немає в списку. Найчастіше Claude Code запущено до openspec init або не в тій теці: /exit → cd ~/ai-qa-ba-c4/submissions/ваш-username → claude. Перевірте, що в теці є .claude/commands/opsx/. Не допомогло — викличте ті самі скіли напряму: /openspec-propose … тощо.

#Термінал: перевірити і зафіксувати

Слайд 172

Ці команди запускаєте у звичайному терміналі, у теці, де лежить openspec/, — у вас це submissions/ваш-username/. Працює програма, не модель: на тих самих файлах результат щоразу той самий.

validate. Відповідь — англійською, і це нормально:

• Change '<id>' is valid (для специфікації — Specification '<capability>' is valid) — структура правильна;
• Change '<id>' has issues — нижче перелік проблем з файлом і вимогою: ✗ [ERROR] — помилка, ⚠ [WARNING] — попередження;
• з --all — рядок ✓ або ✗ для кожної специфікації і зміни і підсумок Totals: ….

Ілюстрація зі слайда — найчастіша помилка: сценарій під ### замість ####. OpenSpec такий сценарій мовчки пропускає, тож для нього вимога лишається без сценарію. Вивід openspec validate status-change-during-edit:

Change 'status-change-during-edit' has issues
✗ [ERROR] change-address/spec.md: ADDED "Повернення 30 грн" must include at least one scenario

validate перевіряє структуру, а не зміст. Чи правильне правило, чи є джерело, чи воно не застаріле — перевіряєте ви. Слова WHEN/THEN і текст proposal.md validate теж не перевіряє.

show --diff показує, що саме змінює зміна, вимога за вимогою. MODIFIED — як diff: що було і що стало. Для BA це те, що піде на погодження. Для QA — які тест-кейси зачепить зміна. Окремої команди openspec diff немає — лише show --diff.

--strict. Без нього попередження перевірку не зупиняють, з ним — зупиняють. Два попередження, які трапляються найчастіше: у тексті вимоги немає SHALL чи MUST великими латинськими літерами; текст вимоги довший за 500 символів. Для L3 у звіт іде вивід openspec validate --all --strict.

Що означають типові повідомлення (повна таблиця — в OPENSPEC.md, розділ «Якщо не працює»):

#Зафіксувати зміну: агент чи програма

Слайд 173

Зафіксувати зміну (archive) — значить перенести delta в основну специфікацію specs/<capability>/spec.md, а теку зміни — в архів. Обидва способи переносять теку в changes/archive/YYYY-MM-DD-<id>/, але зливають по-різному.

/opsx:archive — зливає агент. Злиття пише модель. Вона може переформулювати вимогу чи загубити сценарій — той самий дрейф, з якого почалося заняття (розділ 2). Після такого archive обов'язково перечитайте основну специфікацію.

openspec archive <id> --yes — зливає програма. Спершу вона перевіряє формат: зміну з помилками не зливає. Потім показує статус задач з tasks.md і що зміниться. Далі зливає у сталому порядку — перейменовані, видалені, змінені, додані вимоги — і переносить теку. MODIFIED замінює вимогу на її місці, ADDED додається в кінець розділу ## Requirements. --yes означає «без запитань-підтверджень». Для L3 радимо саме цей спосіб: результат передбачуваний, вивід легко вставити у звіт.

Задачі в tasks.md позначте - [x] до архівування. Якщо цього не зробити, openspec archive --yes попередить про невиконані задачі — і все одно заархівує зміну. Так і сталося в демо 3.

Назви мають збігатися дослівно. MODIFIED і REMOVED шукають вимогу в основній специфікації за назвою:

• назва в MODIFIED (або в рядку FROM розділу RENAMED) не збіглася — validate проходить, але з рядком ℹ [INFO] … Archive would refuse this delta: …, а archive пише Aborted. No files were changed.;
• назва в REMOVED не збіглася — archive лише попереджає (… REMOVED requirement "…" is not in the current spec; treating it as already removed.), а стара вимога лишається в специфікації.

Копіюйте назви з основної специфікації — до літери і пробілу.

Після archive основна специфікація — нова поточна правда. Прочитайте її. Це частина L3: чи немає суперечностей між вимогами, чи кожен сценарій відповідає чинному правилу. Друга зміна L3 — з новим id, і її MODIFIED беріть з уже злитого тексту основної специфікації, а не зі старої версії.

Без CLI archive роблять вручну — у тому самому порядку. Кроки — у підрозділі «Без CLI» нижче.

#Демо 3: validate → diff → archive

Слайд 174

Демо 3 — продовження демо 2, та сама зміна status-change-during-edit за відкритою сторі [00-3] «Статус посилки змінився під час оформлення зміни адреси». Тепер зміну перевіряють, дивляться, що вона змінює, і фіксують в основній специфікації change-address. Нижче — записаний прогін 14.10.2026: OpenSpec 1.14.1, термінал у теці здачі в клоні проєкту С4, після демо 1 і 2. Вивід — без змін. Кожен крок окремо — на сторінці демо.

openspec validate status-change-during-edit
openspec show status-change-during-edit --diff
openspec archive status-change-during-edit --yes
openspec list --specs
openspec validate --all --strict

На слайді — перші чотири команди. П'ята — перевірка для L3, і саме вона показала найцікавіше.

1 · validate.

Change 'status-change-during-edit' is valid

Формат правильний. Але validate не скаже, чи правильно взято зміст. Чи є в зміні рішення 14–15.09 про автоматичне повернення 30 грн і чи не вигадав агент відповідь на питання Марти від 16.09 — це перевіряє людина.

2 · show --diff. Спершу команда друкує proposal — розділи ## Why, ## What Changes, ## Capabilities, ## Impact. Потім — розділ Specifications Changed (diffs). Для change-address у ньому чотири ADDED з повним текстом:

• «Повторна перевірка статусу під час підтвердження»;
• «Повторна перевірка часової межі під час підтвердження»;
• «Автоповернення коштів, якщо адресу не змінено після оплати»;
• «Стан кнопки після відмови».

І один MODIFIED — «Платна друга зміна». Він показаний як diff: рядок з - — що було, з + — що стало. Початок цього фрагмента:

  MODIFIED: Платна друга зміна
    @@ -1,12 +1,20 @@
     ### Requirement: Платна друга зміна
    -Система SHALL вимагати за другу зміну адреси 30 грн, сплачені платіжною карткою до підтвердження зміни; якщо оплата не пройшла, система SHALL залишити попередню адресу, гроші не списуються.
    +Система SHALL вимагати за другу зміну адреси 30 грн, сплачені платіжною карткою до підтвердження зміни; якщо оплата не пройшла, система SHALL залишити попередню адресу, гроші не списуються; якщо до оплати умови зміни перестали виконуватися (статус чи часова межа), система SHALL NOT починати оплату й SHALL показати відповідне повідомлення про відмову.

Далі в diff — змінений рядок «Джерело» і два нові сценарії: «Умови змінилися до оплати через статус» і «Умови змінилися до оплати через межу 20:00». У «Джерело» додано «задача 00-3, опис, AC2», а назву питання FAQ агент переказав своїми словами — «питання про невдалу оплату». Старі сценарії «Оплата пройшла» і «Оплата не пройшла» лишилися без змін: сценарії скопійовано повністю. Рядок джерела звірте самі.

Читаючи diff, спитайте себе: які тест-кейси це зачіпає (QA)? Що піде на погодження (BA)?

3 · archive --yes.

Task status: 0/16 tasks
Warning: 16 incomplete task(s) found. Continuing due to --yes flag.

Specs to update:
  change-address: update
Applying changes to openspec/specs/change-address/spec.md:
  + 4 added
  ~ 1 modified
Totals: + 4, ~ 1, - 0, → 0
Specs updated successfully.
Change 'status-change-during-edit' archived as '2026-10-14-status-change-during-edit'.

Читаємо згори вниз:

• Task status: 0/16 tasks і Warning: 16 incomplete task(s) found. Continuing due to --yes flag. — жодну з 16 задач у tasks.md не позначено виконаною, а з --yes archive продовжує. У демо це очікувано: сторі, FAQ і тест-кейси ще ніхто не оновлював. У своїй роботі спершу виконайте задачі і позначте їх - [x].
• + 4 added і ~ 1 modified — чотири нові вимоги і одна змінена, як у diff.
• Останній рядок — тека зміни переїхала в openspec/changes/archive/2026-10-14-status-change-during-edit/, з датою дня архівування.

4 · list --specs.

Specs:
  change-address     requirements 14

У специфікації з демо 1 було 10 вимог. Archive додав 4 нові, а змінену замінив на її місці — разом 14.

5 · validate --all --strict — не пройшло.

- Validating...
✗ spec/change-address
  ⚠ [WARNING] requirements[7]: Requirement text is very long (>500 characters). Move examples and edge cases into scenarios, or split it into separate requirements that each state one behavior.
Totals: 0 passed, 1 failed (1 items)
Details: openspec validate change-address --type spec

Що сталося:

• requirements[7] — номер вимоги з нуля, тобто восьма вимога. Це «Платна друга зміна» — та, яку змінив MODIFIED.
• Текст вимоги рахується від заголовка до першого сценарію — так і в ручному чек-листі. Саме правило після злиття — приблизно 350 символів, рядок «Джерело: …» під ним — ще приблизно 200. Разом — понад 500.
• Це попередження, а не помилка: без --strict перевірка пройшла б. З --strict — ✗.
• У демо 2 агент перевіряв саму зміну командою openspec validate status-change-during-edit --strict — і вона пройшла. Задовгу вимогу спіймала лише перевірка основної специфікації після злиття. Тому для L3 — openspec validate --all --strict саме після archive.

6 · виправлення: агент скорочує текст вимоги — умови вже є в сценаріях (сторінка демо). У Claude Code (claude -p, модель claude-sonnet-5-5, та сама тека здачі) агенту дали текст попередження і правило «одна вимога — одна поведінка»:

openspec validate --all --strict показує: ✗ spec/change-address — [WARNING] requirements[7]: Requirement text is very long (>500 characters). Знайди цю вимогу в openspec/specs/change-address/spec.md після archive і виправ: кожна вимога — одна поведінка, приклади й винятки — у сценарії. Зміст, тексти повідомлень і рядки «Джерело: …» не змінюй і нічого не додавай від себе. Потім запусти openspec validate --all --strict.

Агент знайшов заголовки вимог пошуком за ### Requirement:: 14 вимог, «Платна друга зміна» — восьма. Він прочитав її і зробив одну правку — у тексті вимоги лишив тільки основну поведінку:

Система SHALL вимагати за другу зміну адреси 30 грн, сплачені платіжною карткою до підтвердження зміни.

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

- Validating...
✓ spec/change-address
Totals: 1 passed, 0 failed (1 items)

Чому зміст не загубився. Умови, які прибрали з тексту, уже були в сценаріях цієї вимоги: «Оплата не пройшла», «Умови змінилися до оплати через статус», «Умови змінилися до оплати через межу 20:00». Агент сам про це написав і чесно попередив: окремого SHALL NOT починати оплату в тексті вимоги більше немає, ці умови тепер описані лише сценаріями. Прийняти так чи винести «не починати оплату» в окрему вимогу — рішення людини. OPENSPEC.md допускає обидва шляхи: деталі перенести в сценарії або розділити вимогу на дві.

Відповідь агента — теж чернетка. Наостанок агент запропонував так само скоротити MODIFIED у delta і назвав шлях openspec/changes/status-change-during-edit/…. Але після archive цієї теки там уже немає — вона в changes/archive/2026-10-14-status-change-during-edit/. Наступна зміна бере MODIFIED з уже злитого і виправленого тексту основної специфікації. Читайте відповідь агента так само уважно, як файли, які він створив.

Специфікацію після archive і виправлення можна завантажити на сторінці демо.

cd examples/00-demo/l2
openspec validate --all --strict
openspec show status-change-during-edit --diff
openspec list --specs

Щоб відтворити archive, скопіюйте теку l2 за межі своєї копії репозиторію — archive змінює файли — і в копії виконайте openspec archive status-change-during-edit --yes.

#Без CLI: чек-лист замість validate, archive вручну

Слайди 169–173

Ті самі файли — вручну або з агентом у будь-якому чаті. Вимоги до файлів і бали ті самі, що з CLI.

1. L1. Скопіюйте templates/spec-template.md у openspec/specs/<capability>/spec.md і заповніть.
2. L2. Створіть теку openspec/changes/<id>/ і скопіюйте в неї шаблони з templates/change/: proposal.md → openspec/changes/<id>/proposal.md, tasks.md → openspec/changes/<id>/tasks.md, delta-spec.md → openspec/changes/<id>/specs/<capability>/spec.md. Файл delta називається spec.md, а тека — як в основній специфікації.
3. Перевірка — ручний чек-лист templates/validation-checklist.md замість openspec validate (нижче).
4. Archive (L3) — вручну, у тому самому порядку, що в програми (нижче).
5. Лише браузер. Файлами не виходить — вставте вміст кожного файлу у звіт блоками коду, розділ «Додаток» шаблону звіту. Зараховується так само.

Ручний чек-лист — ті самі правила, що в openspec validate, плюс перевірка змісту. У ньому чотири розділи:

Конкретно: L1 — розділи А і В; L2 — Б і В для кожної зміни; L3 — Б, В і Г після обох змін. У чек-листі є два рівні. Помилка — openspec validate такий файл не пропустить. Попередження — openspec validate пропустить, а openspec validate --strict — ні. Виправляйте і те, й інше. Перевіряйте сирий текст файлу — у редакторі або кнопкою Display source на gitlab.com: на відображеній сторінці не видно решіток заголовків.

Archive вручну — у файлі openspec/specs/<capability>/spec.md, у такому порядку:

1. RENAMED — змініть назву вимоги з FROM на TO;
2. REMOVED — видаліть вимогу цілком, з усіма сценаріями;
3. MODIFIED — замініть вимогу цілком на блок із delta;
4. ADDED — додайте нові вимоги в кінець розділу ## Requirements.

Потім перенесіть теку openspec/changes/<id>/ у openspec/changes/archive/YYYY-MM-DD-<id>/, де дата — день злиття, наприклад 2026-10-18-status-change-during-edit.

Після злиття основна специфікація має знову пройти розділ А чек-листа — разом із правилом «текст вимоги не довший за 500 символів». Саме на цьому спіткнулася злита MODIFIED-вимога в демо 3. Розділ Б для зміни цього не ловить: у delta довжину перевіряють лише для ADDED.

6. Завдання С4

Цей розділ — про практичне завдання четвертого заняття. Ви повторюєте на своїй функції те, що на занятті показали в трьох демо. Спершу збираєте чинні правила в специфікацію OpenSpec, потім змінюєте її через пропозицію. Нижче — основа завдання, ваш варіант і джерела, рівні L1–L3, бали, здача і строк.

Усе для завдання — у новому публічному проєкті gitlab.com/koldovsky/ai-qa-ba-c4. Там README із завданням, OPENSPEC.md з інструкцією до CLI, шаблони в templates/ і зразок на демо-варіанті в examples/00-demo/. Каркаси файлів, команди і чек-лист зібрано на одній сторінці — у шпаргалці.

#Завдання С4: ваша функція в одній специфікації

Слайд 175

Зберіть чинні правила своєї функції «Пакунку» зі сторінок і задач С2–С3 у специфікацію OpenSpec. Потім змінюйте її контрольовано — через пропозицію. Кроки завдання відповідають трьом демо заняття:

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

Основа завдання — одна з двох:

• За замовчуванням — ваш варіант. Функція «Пакунку» за першою літерою прізвища — та сама, що в С1–С3. Специфікація описує правду на 14.10.2026: що чинне, вирішують дати рішень.
• За бажанням — власна ідея. Вигадана функція одного продукту, розміром як варіант. Правила — нижче.

Ще чотири правила зі слайда:

• це новий проєкт — koldovsky/ai-qa-ba-c4; форки С1–С3 не підходять;
• OpenSpec CLI — за бажанням: бали за нього не дають і не знімають;
• агент — будь-який: Claude Code, інший агент або AI-чат у браузері; інструкція до CLI — лише для Claude Code;
• демо-варіант 00, як завжди, не зараховується.

Що потрібно, щоб почати:

Без CLI завдання виконується повністю: файли пишете з агентом за шаблонами з templates/, а замість openspec validate — ручний чек-лист templates/validation-checklist.md.

Власна ідея — правила з README:

• Вигадана функція вигаданого продукту. Жодних реальних компаній, корпоративних даних, внутрішніх правил і назв систем із вашої роботи.
• Розмір — одна функція, як у варіантах: наприклад, «бронювання переговорної кімнати» чи «повернення товару в інтернет-магазині». Не цілий продукт.
• Джерело — «сирий запит». Спершу запишіть у звіті короткий запит від замовника: 5–10 пронумерованих пунктів. Біля вимог — «Джерело: власний запит, п. N». Чого в запиті немає — у відкриті питання, а не в специфікацію.
• Зміни для L2 і L3 — нові запити до тієї самої функції. Запишіть їх у звіті: це джерело зміни.
• Номер варіанту і роль усе одно вкажіть — у звіті й у назві MR.

Бали за власну ідею ті самі, за тими самими частинами.

#Ваш варіант — той самий, що в С1–С3

Слайд 176

Варіант — за першою літерою прізвища, номер той самий, що в С1–С3. Нова колонка — capability: назва теки вашої функції латиницею, малими літерами, через дефіс. Це назва теки варіанту без номера. Вона стоїть у шляху openspec/specs/<capability>/spec.md і в першому рядку специфікації, наприклад # courier-slots Specification. У демо це change-address.

Таблиця — з README проєкту С4, посилання ведуть на ваші джерела:

Джерела — ті, з якими ви вже працювали:

• С2: requirement.md — вимога, sources.md — матеріали до неї, bug-report.md — звіт про дефект;
• С3: overview.md — продуктова сторінка, decisions.md — журнал рішень, support-faq.md — FAQ контакт-центру;
• задачі трекера С3 з міткою варіант::NN — і відкриті, і закриті. Посилання в таблиці вже показує обидва стани: у ньому є state=all. Рішення часто лише в коментарях задач, тож читайте й коментарі.

Як дати джерела агенту. Агент має працювати з джерелами, а не з пам'яті. Два способи — з README, крок 4:

• GitLab MCP із С3 — якщо ви підключали його для всіх проєктів (claude mcp add -s user …). Попросіть агента прочитати сторінки й задачі з коментарями в koldovsky/ai-qa-ba-c3 і файли варіанту в koldovsky/ai-qa-ba-c2. MCP, підключений через .mcp.json копії С3, працює лише в тій теці.
• Без MCP — відкрийте файли й задачі за посиланнями з таблиці. Вставте текст у чат агента або збережіть у підтеку sources/ своєї теки. У задачах копіюйте й коментарі.

Перевірте, що агент отримав усі джерела, — і лише потім просіть специфікацію.

Демо-варіант — «Зміна адреси доставки» (change-address): матеріали С2, kb/00-demo-change-address і задачі варіант::00. Готовий зразок — тека examples/00-demo/ проєкту С4: результат за рівнями в підтеках l1, l2, l3 і копії джерел у sources/. Порівнюйте з ним свою роботу після власної спроби. Робота за демо-варіантом не зараховується.

#L1 для всіх: специфікація вашої функції

Слайд 177

L1 — те, що ви бачили в демо 1. Дві частини: файл специфікації і звіт.

Специфікація openspec/specs/<capability>/spec.md у форматі OpenSpec:

• # <capability> Specification, потім ## Purpose — 2–4 речення: що це за функція і для кого, — і ## Requirements;
• щонайменше 6 вимог ### Requirement: <назва>. Кожна — одна поведінка, з SHALL або MUST (SHOULD чи MAY — де доречно). Без «як реалізувати»: жодних технологій, полів бази даних, API і верстки. Назви кнопок і тексти повідомлень, які бачить користувач, — можна: це видима поведінка;
• у кожної вимоги — щонайменше один сценарій #### Scenario: з рядками - **WHEN** … і - **THEN** …. Серед сценаріїв — щонайменше 2 негативні або межові: що буде, якщо не можна, якщо пізно, якщо рівно на межі;
• під текстом кожної вимоги — рядок «Джерело: …»: файл і розділ або задача і коментар із датою. Власна ідея — «Джерело: власний запит, п. N».

Мовне правило: текст — українською. Структурні заголовки (## Purpose, ## Requirements, ### Requirement:, #### Scenario:) і слова SHALL/MUST — англійською: саме за ними OpenSpec знаходить вимоги. **WHEN**, **THEN**, **AND** — теж англійською, для одноманітності. Шаблон фрази: «Система SHALL показувати …». Сценарій — це чотири решітки. З трьома OpenSpec сценарію не бачить, і вимога лишається без сценарію. Як писати добру вимогу і сценарій — слайди 158–159.

Так виглядає одна вимога зі специфікації, яку агент написав у демо 1:

### Requirement: Поштомат лише з підтвердженим номером телефону
Система SHALL пропонувати поштомат як нову адресу лише отримувачу, який підтвердив номер телефону кодом із SMS; решті отримувачів система SHALL показувати в списку тільки відділення.

Джерело: kb/00-demo-change-address/overview.md, розділ «Куди можна змінити»; decisions.md, запис 28.04.2026 (діє з 04.05.2026).

#### Scenario: Номер підтверджено
- **WHEN** отримувач із підтвердженим кодом із SMS номером відкриває список нових адрес
- **THEN** у списку є і відділення, і поштомати його населеного пункту

#### Scenario: Номер не підтверджено
- **WHEN** отримувач із непідтвердженим номером відкриває список нових адрес
- **THEN** у списку лише відділення, поштоматів немає

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

Промпт. Приклад промпту для L1 з OPENSPEC.md — замініть дужки своїм:

Ти — бізнес-аналітик. Склади openspec/specs/<capability>/spec.md у форматі OpenSpec за джерелами: <файли й задачі варіанту з коментарями>.
Опиши поточну правду на сьогодні: де джерела розходяться — бери пізніше рішення і вкажи його дату.
Кожна вимога — одна поведінка, перший рядок «Система SHALL …», під ним рядок «Джерело: …». У кожної вимоги — щонайменше один сценарій #### Scenario: з WHEN/THEN, серед сценаріїв — негативні й межові.
Відкриті, ще не реалізовані сторі трекера не включай. Чого немає в джерелах — не вигадуй, випиши окремим списком відкритих питань.

Повний промпт демо 1, з переліком джерел, — на сторінці демо. Для L1 команди /opsx:* не потрібні: поточну правду пишуть одразу в openspec/specs/, звичайним промптом.

Звіт c4.md — за шаблоном templates/c4-report.md:

• промпт(и) і що зробив агент;
• перевірка згенерованого: що агент вигадав, що пропустив, де взяв застаріле правило, що ви виправили;
• валідація — вивід openspec validate <capability> або заповнений ручний чек-лист: для L1 — розділи А і В;
• відкриті питання — чого немає в джерелах;
• висновок — 2–3 речення.

За роллю — ще одна частина:

#L2 — зміна, L3 — репетиція фіналу

Слайд 178

L2 · зміна через пропозицію (change proposal). Це справжня зміна вимог до вашої функції — така, якої ще немає в чинній специфікації L1. BA дивиться на зміну як на пакет вимог, QA — як на зміну тестів.

Що змінювати:

• за замовчуванням — задача-сторі вашого варіанту з трекера С3, мітка тип::сторі. Її AC і рішення з коментарів стають delta — ADDED або MODIFIED;
• сторі вже закрита і випущена — у варіантах 01, 02 і 08 це так. Тоді вона — частина чинної правди L1. Для L2 візьміть питання з коментарів задач, на яке ще немає відповіді. Оформіть зміну як пропозицію і лишіть рішення відкритим питанням до власника — не вигадуйте його. Або візьміть новий запит;
• власна ідея — новий запит до своєї функції; запишіть його у звіті.

Зміна — це тека openspec/changes/<id>/ з трьох файлів:

Id зміни — латиницею, малими літерами, через дефіс: status-change-during-edit. Delta називається саме spec.md, а тека <capability> — та сама, що в openspec/specs/. Що таке delta і чотири її розділи — слайд 165.

З CLI — команда в Claude Code. Приклад з OPENSPEC.md:

/opsx:propose <id> Зміна до функції <capability> за сторі <номер> з трекера С3: візьми AC і рішення з коментарів, з датами. Delta: ADDED — нова поведінка; MODIFIED — якщо змінюється чинна вимога, з повним текстом і всіма її сценаріями. tasks.md — група BA або QA. Біля кожної вимоги — «Джерело: …». Чого немає в джерелах — не вигадуй.

/opsx:propose пише ще й design.md — у С4 він не потрібен: можна видалити або лишити. Без CLI створіть теку зміни і скопіюйте шаблони з templates/change/: proposal.md, tasks.md і delta-spec.md. Останній ляже в теку зміни як specs/<capability>/spec.md.

Перевірка у звіті. Що агент зробив не так у чернетці і що ви виправили. Наприклад: MODIFIED без частини сценаріїв, зміна без джерела, ліміт, якого немає в джерелах. Плюс валідація: openspec validate <id> або ручний чек-лист, розділи Б і В.

Одна сторі — кілька правильних delta. У зразку examples/00-demo/l2/ її розбито ще інакше: MODIFIED — вимоги про статус посилки і межу 20:00, ADDED — перевірка умов перед оплатою і повернення 30 грн. Головне — щоб кожен пункт ## What Changes мав свою вимогу в delta і навпаки.

L3 · репетиція фінального проєкту — змінити вимоги і перевірити узгодженість. Чотири кроки:

1. Застосуйте зміну L2 до основної специфікації: openspec archive <id> --yes у терміналі. Або вручну: злийте delta в specs/<capability>/spec.md у порядку RENAMED → REMOVED → MODIFIED → ADDED і перенесіть теку зміни в changes/archive/YYYY-MM-DD-<id>/.
2. Друга зміна, що зачіпає ту саму поведінку: пізніше рішення або новий запит, що перетинається з першою. Повний цикл: proposal → delta → tasks → archive. Її MODIFIED беріть із уже злитого тексту основної специфікації.
3. Перевірка узгодженості після обох змін: між вимогами немає суперечностей, кожен сценарій відповідає чинному правилу, похідні артефакти оновлено.
4. У звіті — таблиця «що перевірили → що знайшли → що виправили» і вивід openspec validate --all --strict або ручний чек-лист: розділи Б, В і Г.

Похідні артефакти — за роллю:

Посилання — в обидва боки. Артефакт посилається на вимогу в spec.md і на зміну. Зміна — у tasks.md або в ## Impact — посилається на артефакт. Артефакт — це файл у вашій теці (наприклад, uat.md чи tests.md) або розділ звіту.

Archive можна зробити двома способами, і вони різні по суті — слайд 173. openspec archive у терміналі зливає зміну за правилами OpenSpec і перевіряє формат. /opsx:archive у Claude Code зливає агент — після нього обов'язково перечитайте основну специфікацію.

У зразку examples/00-demo/l3/ дві заархівовані зміни. Друга — failed-attempt-rules: відповідь власниці продукту на відкриті питання першої зміни. Цей запит вигадано для прикладу. У джерелах варіанту 00 такого рішення немає, тож посилатися на нього як на джерело не можна. Одна з її MODIFIED — вимога, яку додала перша зміна. Тому застосувати другу зміну можна лише після archive першої. Приклад таблиці «що перевірили → що знайшли → що виправили» — не в теці l3/, а в README зразка, розділ про l3.

#Бали — як у С3: до 10 за рівень

Слайд 179

Схема та сама, що в С3: кожен рівень оцінюється до 10 балів, і в кожної частини своя вага. Таблиця — з README:

Найбільша вага в L1 — у вимог, 3 бали: одна поведінка, SHALL або MUST, без «як реалізувати». У L2 найважча частина — delta, 4 бали: саме тут MODIFIED з повним текстом. У L3 по 4 бали — за застосовану зміну і за другу зміну з похідними артефактами.

Як рахують бали:

• бали знімають за недоліки — наприклад, п'ять вимог замість шести чи вимоги без джерел. Недоробка знімає бали лише за свою частину, а не за весь рівень;
• порожній розділ — 0;
• рівні рахуються окремо;
• без CLI — ті самі бали: замість openspec validate — ручний чек-лист templates/validation-checklist.md, правила ті самі. За CLI бали не додають і не знімають;
• формальності — −1 за кожну, разом до −2 за роботу: файл не в submissions/ваш-username/c4.md, назва MR не за шаблоном, не вказано варіант чи прізвище та ім'я;
• робота за демо-варіантом не зараховується.

#Здача: звіт і тека openspec/

Слайд 180

Головна різниця з С3: у здачі не один файл, а звіт і тека openspec/ поруч із ним. Усе лежить у теці submissions/ваш-username/ вашої копії:

submissions/ваш-username/
├── c4.md                                   # звіт за шаблоном templates/c4-report.md
└── openspec/
    ├── specs/<capability>/spec.md          # L1: специфікація функції (поточна правда)
    └── changes/
        ├── <change-id>/                    # L2: зміна
        │   ├── proposal.md
        │   ├── tasks.md
        │   └── specs/<capability>/spec.md  # delta: ADDED / MODIFIED / REMOVED
        └── archive/YYYY-MM-DD-<id>/        # L3: заархівовані зміни (після archive)

specs/ — це L1. changes/ з вашою зміною — L2. Після archive тека зміни переїжджає в changes/archive/ з датою — це L3. Якщо є похідні артефакти (uat.md, tests.md тощо), вони теж лежать у вашій теці.

Кроки — як у README, розділ «Як виконати і здати»:

Команди кроку 2 (Windows — PowerShell, macOS — Terminal):

cd ~
git clone https://gitlab.com/ваш-username/ai-qa-ba-c4.git
cd ai-qa-ba-c4

Команди кроку 3:

mkdir submissions/ваш-username
cd submissions/ваш-username
claude

З CLI зручніше форкнути на початку і працювати в копії на диску. Без CLI форк можна зробити й наприкінці. Команди openspec … і claude запускайте з submissions/ваш-username/: там лежить openspec/. Як це виглядає — запис openspec init на сторінці демо. Як встановити CLI і що робити, якщо /opsx не з'явилося, — OPENSPEC.md і слайди 170–171.

Крок 8 — три способи відправити файли:

• Агент через GitLab MCP: «Відправ усі файли з теки submissions/ваш-username, крім .claude/, у нову гілку c4 моєї копії ваш-username/ai-qa-ba-c4 одним комітом». Коміт піде від вашого акаунта з прихованою поштою (крок 0).
• Git. Спершу пошта: git config user.email з адресою з Edit profile → Commit email, вигляду …@users.noreply.gitlab.com. Без цього кроку комітів не робіть: локальний коміт бере пошту з налаштувань git — часто робочу, — і вона стане публічною у форку. Далі в корені клону:

git switch -c c4
git add submissions/ваш-username/c4.md submissions/ваш-username/openspec
git status
git commit -m "С4: моя робота"
git push -u origin c4

Інші свої файли додайте так само: git add submissions/ваш-username/tests.md. У git status не має бути .claude/.

• Браузер. У своїй копії Code → Branches → New branch → c4 → Create branch. Перемкніть гілку на c4 → + → New file. У назві — повний шлях, наприклад submissions/ваш-username/openspec/specs/courier-slots/spec.md: теки з'являться самі. Вставте текст → Commit changes у гілку c4. Так — для кожного файлу.

Тека .claude/, яку створює openspec init, у MR не додається: там команди і скіли OpenSpec для Claude Code. openspec/config.yaml можна лишити.

Лише браузер. Якщо теки й файли не виходять, вставте вміст кожного файлу у звіт блоками коду — розділ «Додаток» шаблону, з назвою файлу над кожним блоком. Зараховується так само, як файли.

Крок 9 — merge request. У своїй копії Code → Merge requests → New merge request. Зліва — ваша копія і гілка c4, справа — koldovsky/ai-qa-ba-c4 і main → Compare branches and continue. Назва — за шаблоном; для власної ідеї — другий рядок:

С4 · ваш-username · варіант NN
С4 · ваш-username · варіант NN · власна ідея

Далі шаблон опису C4, чек-лист → Create merge request.

У С4 задач у трекері не створюють: Issues у проєкті вимкнено, усе — файлами.

Звіт. Шапка шаблону templates/c4-report.md (підказки «← …» тут прибрано):

**Прізвище та ім'я:** Прізвище Ім'я
**Варіант:** NN
**Основа:** функція варіанту / власна ідея
**Роль:** QA / BA
**Виконані рівні:** L1 · L2 · L3
**Функція (capability):** `назва-функції`

Прізвище та ім'я — як у списку учасників курсу, прізвище першим. Номер варіанту потрібен і для власної ідеї. У заголовку файлу «С4 · Звіт · ваш-username» впишіть свій username на gitlab.com.

Посилання на файли у звіті — повні, на gitlab.com, у гілці c4 вашої копії. Наприклад: https://gitlab.com/ваш-username/ai-qa-ba-c4/-/blob/c4/submissions/ваш-username/openspec/specs/назва-функції/spec.md. Чернетку звіту може скласти й агент — але перевірте кожне посилання і кожне твердження.

Чого уникати — список із README:

• звіт не в submissions/ваш-username/c4.md, а в templates/… чи в корені; тека з іменем замість username; submisions з помилкою — скрипт такого файлу не знайде;
• тека .claude/ у MR;
• структурні заголовки українською (## Вимоги, #### Сценарій:) або сценарій із трьома решітками — OpenSpec їх не знайде;
• назва функції чи id зміни кирилицею, з пробілами чи великими літерами;
• MODIFIED лише з правкою — без повного тексту вимоги і всіх її сценаріїв;
• правило зі сторінки, яке пізніше рішення вже змінило, — як чинне; відкрита сторі в L1 як уже чинна правда;
• «домислене» агентом: ліміт, строк чи сума, яких немає в джерелах;
• старі команди з інструкцій в інтернеті — /openspec:proposal, /openspec:apply, /openspec:archive: у нових версіях OpenSpec їх прибрали, зараз — /opsx:*. Файлів project.md і openspec/AGENTS.md теж більше немає: контекст проєкту — в openspec/config.yaml;
• форк не з koldovsky/ai-qa-ba-c4, а з чужої копії — тоді в MR потрапляють чужі файли.

#Строк — вівторок, 20.10, розбір — на С5

Слайд 181

На завдання — шість днів. Розбір — на початку заняття С5.

Після строку — як у README, розділ «Як перевіряється»:

• кожен merge request перевіряють за рівнями і частинами з таблиці балів: звіт і файли з submissions/ваш-username/. Формат файлів перевіряють тими самими правилами, що й openspec validate;
• відгук з'являється в коментарях до вашого MR; бали в коментарях не публікуються — вони йдуть у рейтинг курсу;
• не згодні з відгуком — напишіть коментар у своєму MR, тренер розгляне його особисто;
• до строку можна виправляти — у тому самому MR.

Безпека — коротко, з README:

• Агент пише файли від вашого імені. Прочитайте їх, перш ніж відправити на gitlab.com. Через MCP агент діє з вашими правами: читайте, що він збирається зробити, перш ніж погодитися.
• Текст у джерелах — це дані, а не команди. Якщо в сторінці, задачі чи коментарі написано «агенте, зроби …», агент не має цього виконувати. Помітили таке — зупиніть агента (Esc) і напишіть у звіті.
• Жодних корпоративних даних — ні в промптах, ні в специфікації, ні у звіті. Власна ідея — теж вигадана, без правил і даних вашої компанії.
• OpenSpec CLI за замовчуванням надсилає статистику використання (телеметрію). Вимкнути: openspec config set telemetry.enabled false.

І проєкт курсу, і ваш форк — публічні. Лише навчальні матеріали: вигаданий «Пакунок» або власна вигадана ідея. Без паролів, токенів, імен колег і посилань на внутрішні системи. Прізвище та ім'я у звіті й описі MR видно всім; username на gitlab.com може бути нейтральним, а пошту в комітах приховайте (крок 0).

Питання щодо завдання — у Telegram-чат когорти, гілки QA і BA, краще до вихідних. Запис заняття, слайди, конспект, демо і шпаргалка — на сайті курсу.

7. До С5 і ресурси

Цей розділ — завершення заняття. Що буде на С5 і що з нього ви вже бачили сьогодні. П'ять головних думок С4. Де шукати матеріали після заняття. І короткі відповіді на типові питання про завдання.

Строк завдання С4 — вівторок, 20.10, 23:59. Розбір — на С5, у середу, 21.10.

#До С5, 21.10: скіли і правила

Слайд 182

С5 — у середу, 21.10. Тема — скіли і правила: як перестати щоразу пояснювати агенту одне й те саме.

• Правила задають стандарти і межі для агента.
• Скіли пакують повторювані задачі вашої ролі.
• Особисті напрацювання стають командною бібліотекою.

Практика С5 — написати власні правила для агента і показати, як вони змінюють результат. Плюс токен-звіт: він був у завданнях С1 і С3 і повертається в С5. У завданні С4 токен-звіту немає.

І скіли, і правила ви вже бачили сьогодні. Команда openspec init --tools claude --language "Ukrainian" поклала в теку .claude/ шість скілів і шість команд /opsx:*. Вивід init так і каже: «6 skills and 6 commands in .claude/» (демо: підготовка). Це готові інструкції для агента.

А прапорець --language записав правило у файл openspec/config.yaml, у поле context. Ось початок цього файлу — таким його прочитав агент у записаному демо 2:

schema: spec-driven

context: |
  Language: Ukrainian
  All artifacts must be written in Ukrainian.
  Keep OpenSpec structural headings and SHALL/MUST keywords in English.

# Per-artifact rules (optional)
# Add custom rules for specific artifacts.
# Example:
#   rules:
#     proposal:
#       - Keep proposals under 500 words
#       - Always state what is out of scope
#     tasks:
#       - Break tasks into chunks of max 2 hours

У context — правило для агента в одному проєкті: усі артефакти — українською, структурні заголовки і SHALL/MUST — англійською. Нижче — окреме поле rules. Поки що це лише закоментований приклад правил для окремих артефактів — proposal і tasks. На С5 такі правила ви писатимете самі.

#П'ять речей, які забираєте

Слайд 183

Кожен пункт — один із блоків заняття. І кожен перевіряється в завданні С4: вимоги зі сценаріями і джерелами — L1, зміна через пропозицію — L2, узгодженість після двох змін — L3.

Як пункти 2–5 виглядали в записаних демо і в завданні:

• Одна поведінка. У демо 3, після archive, openspec validate --all --strict не пройшов: ⚠ [WARNING] requirements[7]: Requirement text is very long (>500 characters). У вимозі «Платна друга зміна» разом стояли плата, невдала оплата і перевірка умов до оплати. Валідатор сам радить: приклади й межові випадки — у сценарії, або окремі вимоги з однією поведінкою кожна. Агент лишив у тексті одне речення — «Система SHALL вимагати за другу зміну адреси 30 грн, сплачені платіжною карткою до підтвердження зміни.» Умови вже були в сценаріях, і повторна перевірка пройшла: ✓ spec/change-address (демо 3: виправлення).
• Джерело і дата. У демо 1 агент прочитав через GitLab MCP матеріали С2, сторінки бази знань С3 і задачі [00-1]–[00-3] з коментарями. У кожній з 10 вимог — рядок «Джерело». Де джерела розходилися, узяв новіше рішення: межа 20:00 напередодні (рішення 19.05.2026) замість «менш ніж за 24 години»; галочка «Зробити це відділення основним» (рішення 12.08.2026, реліз 3.4) замість автоматичного призначення. Зміну адреси на сайті перенесли на 2027 рік, тож сайту в специфікації немає. Відкриту сторі [00-3] агент не включив, невідоме виписав у відкриті питання (демо 1).
• Зміна через пропозицію. У демо 2 сторі [00-3] стала зміною status-change-during-edit: proposal, delta з 4 ADDED і 1 MODIFIED, tasks для BA і QA. Повернення 30 грн агент узяв із коментарів 14–15.09. Питання, чи зараховується невдала спроба до ліміту змін, лишив відкритим: відповіді в джерелах немає (демо 2). Демо 3 злило зміну в специфікацію: + 4 added, ~ 1 modified (демо 3).
• BA і QA. У завданні це окремі пункти для ролей. BA біля кожної вимоги, правило якої змінювали, пише, хто і коли вирішив. QA додає щонайменше 3 негативні або межові сценарії і таблицю «сценарій → тест-кейс».

#Ресурси

Слайд 184

У examples/00-demo — готовий зразок на демо-функції change-address, за рівнями:

• l1 — специфікація демо-функції;
• l2 — зміна з демо 2, status-change-during-edit;
• l3 — специфікація після archive і дві заархівовані зміни. Друга з них — приклад для L3. Це новий запит, вигаданий для прикладу: у джерелах варіанту 00 такого рішення немає.

Поруч, у sources/, — джерела демо-функції. Зразок підготовлено заздалегідь, а демо на сторінці записано окремими прогонами агента. Тому кількість вимог і формулювання в них різні: у зразку l1 — 11 вимог, у записаному демо 1 — 10.

Порівнюйте зі зразком після власної спроби. Демо-варіант не зараховується.

cd examples/00-demo/l2
openspec validate --all --strict
openspec show status-change-during-edit --diff
openspec list --specs

Питання між заняттями — у Telegram-чат когорти, гілки QA і BA.

#Питання

Слайд 185

Типові питання про завдання С4 і короткі відповіді:

Можна працювати у форку С3? Ні. С4 — новий проєкт: новий форк із koldovsky/ai-qa-ba-c4.

Обов'язково ставити OpenSpec CLI? Ні. Бали за CLI не дають і не знімають. Без нього — шаблони з templates/, а замість openspec validate — ручний чек-лист templates/validation-checklist.md.

Якою мовою писати специфікацію? Текст — українською. Структурні заголовки (## Purpose, ## Requirements, ### Requirement:, #### Scenario:, ## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements) і слова SHALL/MUST — англійською. **WHEN**, **THEN**, **AND** — теж англійською. У сценарії — рівно чотири решітки.

Відкриту сторі включати в L1? Ні: її ще не реалізовано, тож вона не чинна правда. Це ваша зміна для L2.

Власна ідея — що з номером варіанту? Вказати все одно: С4 · ваш-username · варіант NN · власна ідея. Ідея — лише вигадана: жодних реальних компаній і корпоративних даних.

Працюю лише в браузері, файлами не виходить? Вставте вміст кожного файлу у звіт c4.md блоками коду — у розділ «Додаток» шаблону. Зараховується так само.

Теку .claude/ додавати в MR? Ні. openspec/config.yaml можна лишити.

Підійде інший агент чи AI-чат? Так: файли OpenSpec — звичайний Markdown. Але інструкція до OpenSpec CLI — лише для Claude Code.

На Windows openspec не знайдено? Тека, яку показує npm prefix -g, має бути в змінній Path. Після зміни закрийте термінал і відкрийте знову. Покроково — в OPENSPEC.md. Без CLI завдання виконується повністю.

Токен-звіт у С4 потрібен? Ні. Він повертається в С5.

Можна взяти демо-варіант? Ні, робота за ним не зараховується.

Питання, на які не вистачило часу, — у чат когорти. Дві дати: