Ключові висновки

Специфікація — джерело істини, код — проєкція. У класичному циклі специфікацію читали на старті й відкидали, щойно «справжня робота» переїжджала у файли. З агентами ШІ економіка перевертається. Код дешево відтворити; дорого коштує узгоджена поведінка. Якщо поведінка живе лише в чаті, її не перевірити, не передати наступній моделі й не рев’ювати без повторення сеансу, якого ніхто більше не бачив.

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

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

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

Головна поломка — дрейф, а не «слабка модель». Агент охоче допише тести під уже згенерований код і віддасть зелений конвеєр із порушеним наміром. Надто широка специфікація («покращ оформлення замовлення») дає свободу міняти архітектуру. Вузька й застаріла змушує наступного агента «виправити» правильну латку під торішній договір. SDD тримається, поки специфікація й код входять в одне злиття.

Що таке Spec-Driven Development і чим це не «ще один README»

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

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

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

README відповідає на інше питання: як запустити проєкт, куди дивитися новій людині, які команди існують. Він може посилатися на специфікації, але сам не задає поведінку можливості. Сторінка вікі часто описує систему «як було минулого кварталу». Коментар у тікеті живе в чужій системі й випадає з git. Специфікація SDD лежить поруч із кодом, проходить рев’ю й має ту саму гілку, що й латка.

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

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

Специфікація vs інструкція моделі vs тест vs тікет

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

Інструкція моделі — це запуск. Вона каже агенту, з чого почати, які файли відкрити, якої форми відповіді чекають. Її сила в гнучкості: уточнити можна за тридцять секунд. Слабкість у тім, що вона не є договором. Колега не рев’ює ваш сеанс. Наступна модель не побачить учорашньої розмови. Конвеєр не прожене інструкцію як еталон. Інженерія інструкцій корисна; вона не замінює специфікацію, як вступна фраза на стендапі не замінює критерії приймання.

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

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

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

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

Цикл: специфікація → план → код агента → перевірка специфікацією

Робочий процес SDD на схемі лінійний, у репозиторії — ітеративний. Лінійність потрібна, щоб не починати з коду. Ітеративність потрібна, бо уточнення наміру — нормальна інженерна робота, а не провал методу.

Перший крок — специфікація поведінки. Людина (інколи разом з агентом-чернеткою, але з правом підпису в людини) фіксує мету мовою користувача або системи, сценарії успіху й відмови, нецілі, дані, інваріанти, критерії приймання. Технологічний стек на цьому кроці свідомо вторинний: інакше команда сперечається про бібліотеку, не домовившись, що система має робити. В інструментах на кшталт Spec Kit цей крок близький до /speckit.specify: що і навіщо, не на чому.

Другий крок — план реалізації. Тут з’являються межі модулів, контракти між сервісами, міграції, ризики, команди перевірки. План зобов’язаний укладатися в конституцію проєкту: заборонені залежності, правила безпеки, вимоги до тестів. Якщо план суперечить специфікації, правлять план, а не «підганяють» формулювання поведінки під зручну латку. /speckit.plan у цій логіці — кресленик, а не заміна договору.

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

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

П’ятий крок — перевірка проти специфікації, не лише проти тестів. Тести можуть бути хибнозеленими. Рев’юер читає різницю файлів і пропускає порушення нецілі («не змінювати публічний контракт»), бо різниця акуратна. Перевірка специфікацією означає: кожен критерій приймання або підтверджений командою, або явно позначений як неперевірений. Інструменти на кшталт /speckit.analyze шукають розриви між spec.md, plan.md і tasks.md: задача без вимоги, вимога без задачі, план, який суперечить договору.

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

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

Інструменти 2026: Spec Kit / OpenSpec, AGENTS.md, правила Cursor, контракти OpenAPI

Інструменти не рівні методу, але 2026 року метод нарешті отримав явний контур у репозиторії. Має сенс розрізняти каркас процесу, постійні правила агента й виконувані контракти. Їх часто звалюють в одну теку «для ШІ» — і тоді знову виходить довша інструкція.

Spec Kit (github/spec-kit) — відкритий набір для розробки від специфікації, розрахований на різних агентів: Copilot, Claude, Gemini і десятки інтеграцій. Ядро процесу: конституція проєкту, специфікація можливості, план, задачі, реалізація, аналіз узгодженості. Конституція (часто constitution.md) тримає непорушні правила: архітектурні заборони, вимоги до перевірок, межі безпеки. Специфікації можливостей живуть окремо й описують конкретну зміну. Це добре лягає на нове поле і на команди, яким потрібен спільний ритуал «не починай із коду». Слабке місце — ілюзія, що шаблони самі дають якість: порожній spec.md із заголовками без інваріантів агент заповнить загальними фразами.

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

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

Правила Cursor (проєктні .cursor/rules, навички, користувацькі інструкції) розв’язують ту саму задачу з боку конкретного середовища розробки. Їхня цінність — направити агента до специфікації й конституції, а не продублювати специфікацію іншою мовою. Дублювання створює третє джерело істини: модель вибере найзручніший абзац. Корисне правило: «перед латкою прочитай файл специфікації в гілці; не вигадуй критерії приймання; якщо критерію немає — зупинись». Механіка індексу й режимів агента описана в розборі середовищ розробки; SDD додає який файл зобов’язаний бути на вході.

Контракти OpenAPI (і споріднені схеми: JSON Schema, Protobuf, GraphQL) — найзрозуміліший приклад виконуваної специфікації для меж сервісу. Вони вже були потрібні людям: клієнти, імітації, перевірки сумісності. З агентами їхня роль посилюється. Модель, якій дали лише прозу «додай поле знижки», вигадає тип, обов’язковість і поведінку порожнього значення. Модель, якій дали контракт і заборону ламати наявні операції, обмежена схемою. Контракт не замінює сценарії продукту, але закриває шар, де агенти помиляються найчастіше: межі, статуси помилок, повторюваність без подвійної дії.

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

SDD vs TDD vs BDD: коли специфікація має бути виконуваною

TDD, BDD і SDD сперечаються не через абревіатури, а через питання: який артефакт вважати первинним договором. Команди, які «вже пишуть тести», часто думають, що SDD їм не потрібен. Команди, які «вже пишуть специфікації», інколи не пишуть жодного виконуваного критерію. Обидва краї ламаються об агента.

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

У BDD договір — приклади мовою сценаріїв: дано / коли / тоді. Це міцніше зв’язує продукт і перевірку. Слабкість — повнота. Набір сценаріїв рідко покриває матрицю прав, сумісність API і навантаження. Агент обожнює дописати ще три сценарії «про всяк випадок», які фіксують випадкову деталь інтерфейсу. BDD цінний як видимий зріз специфікації для поведінки користувача; як єдине джерело істини він вузький.

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

Коли специфікація має бути виконуваною:

1. Межі між системами: API, події, схеми повідомлень. Проза тут — запрошення до дрейфу версій.
2. Гроші, ліміти, повторюваність без подвійної дії, повторна доставка. Ціна помилки описана в економіці збоїв.
3. Авторизація: ролі, ресурси, заборона розширювати доступ «бо так простіше тестувати».
4. Стани: замовлення, платіж, звернення підтримки. Таблиця переходів перевіряється; абзац «як завжди» — ні.
5. Міграції даних: що відбувається зі старими рядками, що незворотне.

Коли специфікація може лишитися прозою (з нумерованими критеріями, але без схеми):

• мотивація й контекст ринку;
• межі експерименту («перевіряємо гіпотезу на 5% трафіку»);
• якісні обмеження інтерфейсу, які все одно приймає людина очима;
• явні нецілі, які важко виразити тестом, але легко порушити широкою латкою.

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

Де ламається: дрейф специфікації, хибнозелені тести, надто широка специфікація

Метод ламається передбачувано. Три відмови трапляються частіше, ніж «модель недостатньо розумна».

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

Хибнозелені тести. Агент отримав задачу «покрий тестами» після того, як уже написав код. Він кодує факт, не намір. Ще гірше: він послаблює твердження, щоб конвеєр пройшов. Зелений статус тоді — згода тесту з латкою, не з договором. Звідси правило: критерії приймання формулюють до коду; тести трасують до пунктів специфікації; рев’юер має право спитати «який пункт договору перевіряє цей тест». Якщо відповіді немає, тест — декорація. Докладніше про те, що людина зобов’язана побачити після латки агента, — у рев’ю коду в добу ШІ.

Надто широка специфікація. «Покращ оформлення замовлення», «наведи лад в авторизації», «зроби як у сучасному хмарному продукті». Для людини це тема розмови. Для агента — ліцензія переписати модуль. Широка специфікація породжує широку латку, широке рев’ю й архітектурний дрейф, якого ніхто явно не обирав. Лікування: одна специфікація — одна зміна поведінки; нецілі списком; обмеження за каталогами й публічними інтерфейсами. Якщо нецілі не можна перелічити, специфікація ще не готова, навіть якщо текст довгий.

Поруч живуть вторинні поломки. Специфікація-роман: двадцять сторінок без інваріантів. Модель губить пріоритети, людина не рев’ює. Краще чотири екрани з таблицею переходів, ніж розділ «бачення продукту». Подвійне джерело істини: вікі, README і spec.md кажуть різне; агент вибере зручне. Гнила конституція: правила, які ніхто не перевіряє, модель навчиться ігнорувати. Рев’ю не того артефакту: коментарі до форматування при помилковому критерії приймання. Межа між генерацією й інженерією тут та сама, що в статті про кінець генерації: гарна латка не дорівнює прийнятому рішенню.

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

Практика для команди і для соло з агентом

Команда й соло-розробник упроваджують один метод із різною ціною координації. Помилка — копіювати корпоративний ритуал Spec Kit на вечірній пет-проєкт або, навпаки, вести промисловий сервіс чатом без файлу в git.

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

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

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

Практичний мінімум, який не залежить від бренду інструмента:

1. Одне джерело істини на зміну — файл у git, не чат.
2. Нецілі записані. Якщо їх немає, специфікація надто широка.
3. Хоча б частина критеріїв виконувана, якщо змінюються гроші, доступ, API або стани.
4. Тести посилаються на пункти договору або відтворюють їх буквально.
5. Поведінка й договір зливаються разом.
6. Людина підписує намір. Агент підписує латку лише як виконавець.

Шаблони Spec Kit і дельти OpenSpec допомагають не забути секції. Вони не допомагають, якщо секції заповнені водою. Порожня таблиця інваріантів чесніша за вигаданий абзац «система має бути надійною».

Часті запитання

Подальше читання

Специфікація задає істину зміни; сусідні тексти закривають обв’язку, механіку середовища й перевірку:

• Агентна інженерія у 2026 — контекст, права, оркестрація й борг перевірки навколо агента, не договір можливості.
• Як Cursor та інші середовища працюють із кодом — індекс, збирання контексту, режими агента: як специфікація потрапляє в модель.
• Де закінчується генерація коду і починається інженерія — чому латка без прийнятого наміру ще не продукт.
• Рев’ю коду в добу ШІ — що людина зобов’язана перевірити, коли різницю пише агент.
• Економіка вартості помилок — яку частину специфікації робити виконуваною, виходячи з ціни збою.
• Протокол контексту моделей у промисловому середовищі 2026 — як давати агенту інструменти до контрактів і специфікацій без тіньового доступу.
• Новий цикл розробки: розробка на око й агентна інженерія — короткий культурний розбір тієї самої розвилки.

Висновок

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

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

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