Spec-first розробка: домовтеся про намір до того, як ШІ напише код

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

Усі вгадували

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

Конкретно: хтось бере задачу, вимоги до якої такі:

• заголовок тікета в один рядок,
• гілка в Slack, яка заглохла,
• і припущення, яке всі вважали спільним, хоча це було не так.

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

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

Чому агенти змінюють розрахунок

Агенти перевернули економіку за одну ніч. Десятиліттями написання коду було дорогим і обережним кроком, і всі процеси будувалися навколо нього. Агент же — швидкий і впевнений вгадувач. Дайте йому розмитий промпт, і за секунди він поверне правдоподібний, гарно структурований і цілком хибний код. Генерація тепер майже безкоштовна. Вирішити, що правильно, — ось і вся робота.

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

Що означає розробка через специфікації

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

Одразу виникають три заперечення, тож ось чим це не є:

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

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

Ваша посадова інструкція змінюється

Усе інше тримається на одному зсуві в мисленні. Ваша головна відповідальність тепер — писати сильні специфікації, рев'юїти їх і правити код руками лише там, де ШІ не дає ради.

Це перевертає те, чого вчили більшість розробників. Раніше роботою було писати код. Тепер це те, що ви робите найменше. Справжня робота за важливістю починається зі специфікації та її рев'ю, і лише потім іде код, написаний вручну.

Шість принципів, які варто повторювати

Коли питають, скільки специфікації достатньо, раз у раз звучать ті самі відповіді:

• Спершу домовтеся. Напишіть або оновіть специфікацію, отримайте швидке рев'ю і лише потім реалізуйте.
• Тримайте специфікації поруч із кодом. Вони лежать у репозиторії, проходять рев'ю в тій самій зміні й належать тим, хто володіє цим кодом.
• Малі дельти кращі за великі переписування. Кожна зміна каже, що додано, змінено чи видалено, а не переказує весь світ наново.
• Описуйте поведінку сценаріями, які можна перевірити. Де щось можна протестувати, використовуйте given/when/then, а не прозу.
• Лишайтеся гнучкими. Якщо реальність розійшлася зі специфікацією, оновіть специфікацію, а не дайте їй згнити.
• Кожна можливість має мати одне джерело правди — одне місце, де описано її поточну поведінку.

Щоденний цикл

Підхід не залежить від інструментів. Звичайних Markdown-файлів у теці specs/ достатньо. Та трохи інструментів зменшує тертя, і OpenSpec — це open-source процес роботи зі специфікаціями, який під'єднується до ШІ-агентів і дає слеш-команди під цей цикл:

1. Дослідження, за бажанням. Коли форма зміни розмита, хай агент прочитає код, зважить варіанти й накидає план до того, як ви візьмете на себе зобов'язання.
2. Пропозиція. Дайте опис в один рядок, і інструмент згенерує пропозицію, коротку дизайн-нотатку, список задач і дельту специфікації — найважливішу частину, бо вона показує, як зміниться жива специфікація.
3. Спершу рев'ю специфікації. У цьому вся гра. Пропозицію й дельту переглядають до того, як з'явиться хоч рядок коду, бо змінити речення дешево, а змінити викочену реалізацію — ні.
4. Застосування. Будуйте за погодженою специфікацією, самі або з агентом.
5. Перевірка. Запустіть перевірки, в ідеалі з приймальними сценаріями, які напряму перетворюються на тести.
6. Архівування. Влийте дельту в живу специфікацію, щоб вона завжди описувала теперішнє, а пропозицію відправте в історію.

Якщо лишити тільки один крок, лиште третій: рев'ю специфікації до коду.

Налаштування OpenSpec з ШІ-агентом

Сучасні агенти на кшталт Claude Code можуть вивчити цей процес і вести його разом із вами, тож не доведеться проговорювати кожен крок. OpenSpec пакує ці знання в навички агента й слеш-команди. Дві команди під'єднують його до репозиторію та до агента:

# install the CLI (drives everything below)
npm install -g @fission-ai/openspec@latest

# scaffold the spec structure AND generate agent skills + slash commands
openspec init --tools claude

Крок init робить дві речі. По-перше, створює місце для специфікацій: теку specs/ для живих специфікацій, теку changes/ для пропозицій у роботі й невеликий конфіг, де ви описуєте стек і домовленості. По-друге, встановлює навички агента. Для Claude це файли навичок плюс команди /opsx:*: explore, propose, apply, archive і sync. Навички вчать агента складати пропозицію, робити дельту специфікації, реалізовувати за нею і вливати результат назад у живу специфікацію.

Як виглядає зміна

Уявіть фонову задачу, якій потрібен налаштовуваний таймаут. Задача, що перевищила ліміт, має скасовуватися й позначатися як timed_out.

Усе починається з дельти специфікації, тобто диффу відносно живої специфікації, який точно показує, що зрушить:

### Requirement: Job timeout
- The system SHALL run a job to completion.
+ The system SHALL cancel a job that exceeds a configurable timeout
+ (default 30s) and record the outcome as `timed_out`.+ #### Scenario: Job exceeds the configured timeout
+ - GIVEN a job configured with a 5s timeout
+ - WHEN the job has run for 5s without completing
+ - THEN the system cancels the job
+ - AND sets its status to `timed_out`
+ - AND emits a `JobTimedOut` event with the job id

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

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

Специфікація чи дизайн-документ

Їх плутають, і це веде до дублювання та плутанини. Поділ, який прижився:

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

На практиці досліджуйте варіанти й ухвалюйте рішення в дизайн-документі, фіксуйте довготривалу поведінку в специфікації та пов'язуйте їх посиланням, а не дублюйте. Якщо ту саму поведінку підтримують в обох місцях, скоротіть дизайн-документ до посилання.

Запровадження в команді

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

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

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

Спробуйте на наступній зміні

Не потрібна велика ініціатива чи вказівка згори. Під час наступної нетривіальної зміни до коду запишіть, що вона має робити, у вигляді кількох сценаріїв given/when/then. Попросіть колегу спершу глянути на ці сценарії. Потім будуйте, досягніть проходження сценаріїв і закомітьте специфікацію разом із кодом.

От і все. Зробіть так кілька разів, хай ваші пул-реквести тихо стануть кращими, і команда почне питати вас, де специфікація.

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