Написання якісних специфікацій

Рідко доводиться писати специфікацію з чистого аркуша. Ви описуєте зміну простою мовою, /opsx:propose створює чорнові вимоги та сценарії, а потім ви робите їх якісними. Ця сторінка про цю останню частину — як виглядає "якісна" специфікація та як спрямувати ШІ до неї.

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

Специфікація — це поведінка, а не код

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

### Requirement: Session Timeout
The system SHALL expire a session after 30 minutes of inactivity.

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass with no activity
- THEN the session is invalidated and the user must re-authenticate

Залиште як — чергу, бібліотеку, схему таблиці — у design.md або коді. Коли поведінка та реалізація змішуються в одній вимозі, вимага перестає бути перевіряваною і починає застарівати в той момент, коли змінюється код.

Що робить вимогу якісною

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

• Одне твердження — один SHALL/MUST. Якщо вимага має три пункти "а також", насправді це три вимоги. Розділіть їх.

• Спостережність. Хтось поза кодом повинен мати змогу визначити, чи виконується вона. "Система ПОВИННА показувати банер помилки, коли завантаження перевищує 10 МБ" — спостережливо. "Система ПОВИННА елегантно обробляти великі завантаження" — ні.

• Правильна сила (ступінь обов'язковості). OpenSpec використовує ключові слова RFC 2119, і вони мають різне значення:

  Ключове слово	Значення
  MUST / SHALL	Жорстка вимага. Без компромісів.
  SHOULD	Сильна рекомендація, з можливістю виправданого винятку.
  MAY	Дійсно необов'язково.

  За замовчуванням використовуйте MUST/SHALL. Застосовуйте SHOULD лише тоді, коли ви дійсно маєте на увазі "якщо немає вагомої причини не робити цього".

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

Що робить сценарій якісним

Сценарії — це те, де вимага виправдовує свою значущість. Кожен із них — це конкретна конструкція GIVEN / WHEN / THEN, яка може стати автоматизованим тестом.

• Він перевіряє свою вимогу. Сценарій, який просто перефразує вимогу іншими словами, нічого не тестує. Зробіть його конкретною ситуацією з конкретним результатом.
• Охоплюйте важливі випадки, а не лише щасливий шлях. Валідний вхід — це легко. Порожнє поле введення, прострочений токен, друге натискання, щось, що йде не так — ось де живуть баги і де сценарій приносить найбільше користі.
• Назвіть випадок у заголовку. "Сценарій: Відхиляє прострочений токен" одразу повідомляє рецензенту, що охоплено; "Сценарій: Тест 2" — ні.

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

Вибирайте правильний тип дельти

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

• ## ADDED Requirements — абсолютно нова поведінка, якої раніше не існувало.
• ## MODIFIED Requirements — поведінка, яка вже існувала та змінюється. Включіть повну нову версію; коротка нотатка про те, що змінилося, допоможе рецензенту.
• ## REMOVED Requirements — поведінка, що припиняється, з рядком про причину.

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

Правильний обсяг зміни

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

Якісна зміна має один намір, який можна висловити одним реченням. "Додати перемикач темного режиму." "Обмежити частоту запитів на кінцеву точку входу." "Перенести сесії з кукі-файлів." Якщо для опису зміни потрібно багато "а також", це сигнал розділити її.

Ознаки того, що зміна занадто велика:

• Обсяг пропозиції читається як список непов'язаних функцій.
• Її перегляд займе весь день, тому ніхто цього не зробить.
• Два людини не змогли б працювати над нею без конфліктів.
• Половина завдань могла б бути випущена самостійно.

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

Також трапляється протилежне: виправлення однорядкової друкарської помилки не потребує трьох вимог і документа з дизайну. Підбирайте рівень формалізму відповідно до важливості завдання.

Як спрямувати ШІ до якісної чернетки

Оскільки /opsx:propose створює першу чернетку, якість того, що ви отримуєте, залежить від якості того, що ви надаєте. Вам не потрібно писати вимоги вручну — вам потрібно добре націлити ШІ:

• Визначте намір та межі. "Додати перемикач темного режиму, який слідує налаштуванням ОС при першому завантаженні — не чіпати існуючий API тем." Частина поза обсягом має таке ж значення, як і частина в обсязі.
• Назвіть випадки, які вас цікавлять. "Переконайтеся, що є сценарій для користувача, який вже вручну вибрав тему." ШІ охоплює те, на що ви вказуєте.
• Потім редагуйте. Це простий Markdown. Уточніть розмитий SHALL, видаліть сценарій, який нічого не тестує, додайте випадок, який був пропущений — або попросіть ШІ: "вимага до тайм-ауту розмита, прив'яжіть її до 30 хвилин."

Чернетка, уточнення, повторити. Кілька раундів такого процесу дадуть специфікації, якій ви довіряєте, і в цьому полягає суть.

Короткий контрольний список

• [ ] Кожна вимага — це одна спостережувана поведінка з SHALL/MUST.
• [ ] У вимоги не вбудовані деталі реалізації.
• [ ] Кожна вимага має принаймні один сценарій, який реально її перевіряє.
• [ ] Важливі граничні та помилкові випадки мають сценарії, а не лише щасливий шлях.
• [ ] Дельти правильно використовують ADDED / MODIFIED / REMOVED відносно поточної специфікації.
• [ ] Зміна в цілому має один намір, який можна висловити одним реченням.

Куди далі

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