Специфікація замість здогадок: як розробляти з ШІ-агентом від специфікації, а не навмання

Коротко (TL;DR)

Spec-Driven Development (SDD) — це підхід, за якого ви спочатку пишете формальну специфікацію (що і як має працювати), а ШІ-агент за нею генерує план, а потім код, звіряючи результат із заданими критеріями. Специфікація стає контрактом між вами й агентом.

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

Що варто знати одразу:

• Основні інструменти — GitHub Spec Kit (open-source, MIT) і Kiro від AWS (платний, зі своєю нотацією вимог). Плюс підхід «CLAUDE.md як носій специфікації» — з важливим застереженням, про яке нижче.
• SDD — не новинка ШІ-епохи: формат тестованих вимог EARS прийшов з авіаційної інженерії, а сама ідея «код зі специфікації» вже провалювалася раніше під назвою Model-Driven Development.
• Головна розвилка — де це оверкіл. Є задокументовані кейси, де специфікація на тривіальну фічу розрослася до 1300 рядків, а рев’ю документа зайняло 3,5 години. Правило просте: завдання цілком уміщається в контекст агента — SDD радше зайвий.

Що таке SDD і чим це відрізняється від докладного промпту

Спершу застереження про терміни. Як зауважує Біргітта Бекелер з Thoughtworks, саме поняття SDD уже семантично розмите: частина індустрії називає «специфікацією» просто докладний промпт. Це не одне й те саме. Докладний промпт — разова інструкція; специфікація в SDD — живий документ, проти якого агент звіряє кожен крок плану і за яким потім перевіряється результат.

BINANCE SIMPLE EARNЗмусь крипту працюватиВідсотки на USDT і BTC без блокування — гроші лишаються під рукою.Розмістити

Звідки взагалі взявся підхід. За оцінкою аналітикині RedMonk Рейчел Стівенс, SDD — це пряма відповідь індустрії на провали вайб-кодингу в проді. Тригером стали гучні інциденти на кшталт видалення робочої бази даних ШІ-агентом — коли стало зрозуміло, що «пиши код як відчуваєш» погано масштабується на серйозні проєкти. Формальна специфікація повертає в процес те, що вайб-кодинг прибрав: явно зафіксований намір.

Генератор проти критика: як кілька ШІ ловлять баги, що пропускає один

«Готово» — це оцінка агента чи перевірки? TDD та eval-driven розробка зі ШІ

Як запускати кілька агентів Claude Code одночасно й не ловити конфлікти файлів

П’ять периметрів безпеки Claude Code: що реально налаштувати, а що вас здивує

Claude Code без інтерфейсу: headless-режим, Agent SDK і підводні камені автоматизації

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

Анатомія специфікації: з чого вона складається

Формальна специфікація — це не «побажання у вільній формі», а структура:

• Мета — яку проблему розв’язуємо і для кого.
• Користувацькі сценарії (user stories) — що і в якій ситуації робить користувач.
• Критерії приймання (acceptance criteria) — перевірювані умови «зроблено». Саме за ними агент (і ви) розумієте, що завдання закрито.
• Нефункціональні вимоги — продуктивність, безпека, обмеження.

Критерії приймання можна писати звичайною мовою, а можна — у нотації EARS, яку використовує Kiro. Формат жорсткий: «WHEN [подія] THE SYSTEM SHALL [поведінка]». Виглядає незвично, але за ним десятиліття практики: EARS придумали в авіаційному підрозділі Rolls-Royce, щоб формулювати вимоги, які можна однозначно протестувати. Для ШІ-агента це зручно — менше простору для «творчої інтерпретації».

Як агент генерує план і перевіряє його

Візьмемо GitHub Spec Kit як еталонний воркфлоу. Він розбитий на чотири фази: Specify → Plan → Tasks → Implement. Спочатку ви формулюєте специфікацію, потім агент будує з неї технічний план, далі план розбивається на конкретні завдання, і лише потім пишеться код.

Важлива деталь — constitutional gates (конституційні гейти). План не проходить далі, доки не пройде задані перевірки або доки виняток не задокументовано явно. Це і є механізм «агент звіряється з контрактом»: не просто написав код, а пройшов ворота, які ви поставили. Керується все слеш-командами — /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement та іншими.

Найнадійніші ворота — не текстові, а виконувані: тест, який або зелений, або ні. Як будувати такий цикл, щоб агент писав код під уже узгоджену перевірку, а не підганяв перевірку під свій код, розбираємо в уроці про Test-Driven Development зі ШІ.

BINANCE COPY TRADINGКопітрейдинг на BinanceВідкрита статистика трейдерів, старт з $10, вимкнення одним кліком.Обрати трейдера

Серед інструментів, де це працює, — VS Code, Cursor і сам Claude Code: в офіційному воркфлоу Spec Kit його CLI використовують як приклад агента. Тулкіт не прив’язаний до одного редактора й підтримує кілька ШІ-агентів.

Annotation cycle: як уточнювати специфікацію

Специфікація майже ніколи не народжується повною. У Spec Kit є акуратний механізм уточнення: прямо у файлі ви (або агент) ставите маркер [NEEDS CLARIFICATION: питання] там, де бракує даних. Команда /speckit.clarify потім проходить по цих місцях і ставить до п’яти уточнювальних питань за один прохід — це коротка сесія уточнень, а не безкінечний опитувальник.

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

Інструменти: Spec Kit, Kiro та CLAUDE.md

Три основні способи робити SDD — з різною ціною та ступенем прив’язки до вендора.

Spec Kit — найпопулярніший: близько 120 тисяч зірок на GitHub і понад 30 вбудованих інтеграцій з агентами станом на 11 липня 2026 року, ліцензія MIT, актуальна версія v0.12.11. Відкритий і не прив’язаний до вендора.

Kiro працює на моделях Claude (Opus, Sonnet, Haiku) та інших через AWS Bedrock. Тарифи станом на 11 липня 2026 року: безкоштовний рівень (50 кредитів), Pro за $20 (1000 кредитів), Pro+ за $40, Pro Max за $100, Power за $200; перевитрата — по $0,04 за кредит. За це ви отримуєте більш «ведений» трифазний воркфлоу та EARS-нотацію з коробки.

CLAUDE.md як носій специфікації — найдоступніший шлях, але з критичним застереженням, про яке майже ніхто не пише. За офіційною документацією Claude Code, CLAUDE.md — це не enforced-конфігурація, а user-повідомлення: агент читає його на початку сесії, але суворе дотримання не гарантоване. Тобто специфікація в CLAUDE.md — це сильна рекомендація, а не жорстке правило. Якщо потрібне саме примусове виконання (агент фізично не може порушити критерій), одного файлу замало — потрібен механізм перевірки на рівні хука. Як влаштований сам файл, розбираємо в окремому уроці курсу; тут важливе саме обмеження: не плутайте «агент прочитав» і «агент зобов’язаний».

Окрім великої трійки, є альтернативи — BMAD, OpenSpec, Tessl (підхід «специфікація як вихідний код»). Вони нішевіші, але показують, що ринок інструментів SDD активно зростає.

Greenfield проти brownfield: де специфікація буксує

Повна специфікація чудово лягає на новий проєкт з нуля (greenfield). А от на legacy-код (brownfield) «описати всю систему заздалегідь» практично не працює — системи надто великі й заплутані. Робочий підхід тут — change-level специфікація: формалізуємо не всю систему, а конкретну зміну.

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

Де SDD — оверкіл

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

• Команда marmelab (12 листопада 2025 року) описала, як SDD на тривіальну фічу розгорнувся у 8 файлів і близько 1300 рядків документації.
• Scott Logic (26 листопада 2025 року), прогнавши Spec Kit на реальному завданні, отримала 2577 рядків markdown проти 689 рядків коду — і 3,5 години лише на рев’ю самої специфікації.

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

Ризики й чесна критика

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

• Waterfall під новою назвою. Критики (та сама marmelab) прямо проводять паралель: «вся документація до коду» суперечить недетермінованій природі розробки. Історична пам’ять теж насторожує — ідея «код зі специфікації» вже провалювалася як Model-Driven Development. Досвідчена аудиторія має тримати це на думці: у підходу є шанс повторити старі граблі.
• Застаріла специфікація гірша за її відсутність. Якщо специфікація розійшлася з кодом, вона активно вводить агента в оману — він вірить документу, а не реальності.
• Подвійне рев’ю. Тепер ви перевіряєте і специфікацію, і код. На великих документах це відчутне навантаження (ті самі 3,5 години).
• Полярні відгуки про інструменти. Про Kiro пишуть і «подає надії», і «найгірший ШІ-редактор, який пробував». Особистий досвід сильно різниться — не беріть ні євангелізм, ні розгром за істину, тестуйте на своєму завданні.

Чим це відрізняється від щоденного методу роботи

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

FAQ

Чим специфікація відрізняється від докладного промпту? Промпт — разова інструкція, яку агент виконує і забуває. Специфікація — постійний документ-контракт, проти якого звіряється кожен крок плану й підсумковий результат. Плюс у SDD є механізм перевірки (гейти), якого у звичайного промпту немає.

З чого почати — Spec Kit чи Kiro? Spec Kit безкоштовний, відкритий і не прив’язаний до вендора — логічна точка входу, якщо ви вже працюєте у VS Code або Cursor. Kiro коштує грошей, але дає більш «ведений» воркфлоу та EARS-нотацію з коробки — має сенс, якщо потрібна структура «за руку». Почати дешевше зі Spec Kit.

Чи можна просто тримати специфікацію в CLAUDE.md? Можна, але пам’ятайте: CLAUDE.md за офіційною документацією не гарантує суворого дотримання — це рекомендація, а не жорстке правило. Для критичних вимог потрібен реальний механізм перевірки (хук), а не лише текст у файлі.

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

SDD — це не той самий Waterfall? Ризик є, і критики на нього прямо вказують. Різниця в тому, що специфікація в SDD — живий документ, який змінюється по ходу (annotation cycle), а не заморожене ТЗ на рік уперед. Але якщо перетворити специфікацію на незмінну «біблію», підхід справді вироджується у Waterfall з усіма його проблемами.