Перевірка змін

Основна обіцянка OpenSpec полягає в тому, що ви і ваш ШІ узгоджуєте, що саме будувати, перш ніж буде написано жоден рядок коду. Ця домовленість має сенс лише тоді, коли ви насправді перевіряєте, що наклав ШІ. Ця сторінка присвячена цим двом хвилинам — що відкрити, в якому порядку і на що звертати увагу.

Ставка проста: виправити помилковий напрямок у плані з одного абзацу майже не коштує нічого. Виправити ту саму помилку в 300 рядках коду — вже ні. Перевірка — це момент, коли ви отримуєте виграш від цієї ставки.

Два моменти для перевірки

Іх рівно два:

/opsx:propose ──► ПЕРЕВІРКА ПЛАНУ ──► /opsx:apply ──► ПЕРЕВІРКА КОДУ ──► /opsx:archive
                  (до написання коду)                    (/opsx:verify)

1. Після /opsx:propose (або /opsx:ff), перед /opsx:apply — прочитайте план, поки він ще складається лише з тексту.
2. Після реалізації, за допомогою /opsx:verify — перевірте, що код насправді зробив те, що було зазначено в плані.

Перша перевірка дає найбільше користі, і саме її найчастіше пропускають. Більшу частину цієї сторінки ми присвячуємо саме їй.

Читайте в такому порядку

Зміна — це папка з простим Markdown у openspec/changes/<name>/. Читайте файли в порядку, який дозволить вам зупинитися якомога раніше, якщо щось не так:

openspec/changes/add-dark-mode/
├── proposal.md      1. мета та область застосування   ← якщо тут щось не так, зупиніться тут
├── specs/…/spec.md  2. вимоги       ← серце перевірки
├── design.md        (лише для великих змін) — технічний підхід
└── tasks.md         3. план робіт

Вам не потрібно читати кожен рядок. Вам потрібно відповісти на три запитання, по одному на кожен файл.

Пропозиція: чи це та проблема, яку потрібно вирішувати?

Спочатку відкрийте proposal.md. У ньому зазначені «чому» і «що» — мета, область застосування, підхід в одному або двох абзацах.

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

Червоні прапорці:

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

Запитання, на яке потрібно відповісти: Чи це відповідає тому, що я насправді просив, і чи щось непомітно додається? Якщо відповідь «ні», зупиніться — не читайте далі, виправте пропозицію (див. Заперечувати).

Дельта специфікацій: чи правильно визначено «готово»?

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

## ADDED Requirements

### Requirement: Dark Mode Toggle
The system SHALL let a user switch between light and dark themes.

#### Scenario: Respects the OS preference on first load
- GIVEN a user who has never set a theme
- WHEN they open the app on a device set to dark mode
- THEN the app renders in dark mode

Як виглядає хороша вимога: одне чітке твердження з SHALL/MUST, яке можна передати тестувальнику, і щонайменше один сценарій, у якому GIVEN/WHEN/THEN насправді перевіряє це твердження.

Червоні прапорці:

• Нечітка вимога. «Система SHALL бути швидкою» не може бути реалізована або протестована. Що вважається швидким?
• Вимога без сценарію, або сценарій, який не перевіряє вимогу, під якою він розміщений.
• Найцінніше, що ви можете знайти: те, чого немає. ШІ вірно записує те, що ви сказали. Ваше завдання — помітити те, що ви забули сказати. Якщо вам найбільше важливий сценарій із врахуванням налаштувань ОС, а в жодному сценарії про нього не згадується, це означає, що перевірка вже окупила себе.

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

Завдання: чи логічний план робіт?

Відкрийте tasks.md останнім. Це контрольний список реалізації, за яким ШІ буде працювати.

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

Червоні прапорці:

• Завдання без відповідної вимоги (звідки воно взялося?).
• Один величезний пункт «реалізувати функцію», який приховує всі реальні рішення.
• Завдання, яке торкається чогось поза межами області застосування, яку ви щойно затвердили.

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

Заперечувати дешево

Якщо відповідь на будь-яке з трьох запитань виявилася негативною, скажіть про це. Немає фаз і ніщо не закріплено — ви виправляєте це і рухаєтеся далі. Два способи, точно як у розділі Редагування зміни:

• Відредагуйте файл самі. Це простий Markdown; змініть рядок з областю застосування, уточніть вимогу, видаліть завдання.
• Скажіть ШІ, що не так, і дозвольте йому переробити: «прибери зміни, пов'язані з автентифікацією — це поза межами області застосування», «додай сценарій для випадку, коли користувач вже вибрав тему», «розділи завдання 3 на схему та інтерфейс».

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

Після написання коду: перевірка

Коли робота завершена, /opsx:verify — це ваша друга перевірка. Вона повторно перевіряє артефакти і код, і повідомляє про невідповідності за трьома вимірами:

Вимір	Що перевіряється
Повнота	Всі завдання виконані, всі вимоги реалізовані, сценарії покриті тестами
Коректність	Реалізація відповідає меті специфікації, оброблені крайові випадки
Цілісність	Технічні рішення насправді відображаються в коді

You: /opsx:verify

AI:  Verifying add-dark-mode...

     COMPLETENESS
     ✓ All 8 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "Respects the OS preference on first load" has no test coverage

Вона позначає проблеми як CRITICAL, WARNING або SUGGESTION, і не блокує архівацію — вона виявляє прогалини і залишає рішення за вами. Це різниця між запитаннями «чи ШІ написав код» і «чи він збудував те, про що ми домовилися».

/opsx:verify є в розширеному профілі. Якщо у вас його немає, увімкніть його за допомогою openspec config profile (потім openspec update), або просто перечитайте зміну і diff самі.

Адаптуйте перевірку під розмір зміни

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

Двохвилинний контрольний список

• [ ] Мета пропозиції відповідає тому, що я просив.
• [ ] Нічого зайвого не потрапило в область застосування.
• [ ] Кожна вимога достатньо конкретна, щоб її можна було протестувати.
• [ ] Кожна вимога має сценарій, який насправді її перевіряє.
• [ ] Найважливіший для мене випадок покритий.
• [ ] Завдання відповідають вимогам; немає загадкових пунктів або тих, що поза межами області застосування.
• [ ] Я буду спокійний, якщо ШІ збудує точно це і нічого більше.

Якщо всі сім пунктів пройдені, запустіть /opsx:apply з упевненістю. Якщо хоча б один не пройшов, це не поразка — це дві хвилини, що виконують свою роботу.

Куди рухатися далі

• Написання якісних специфікацій — зворотна сторона: як складати вимоги і сценарії, варті затвердження.
• Редагування та ітерації зміни — механіка зміни плану після початку роботи.
• Робочі процеси — місце перевірки в більшому циклі.