Розробка, заснована на специфікаціях, з використанням штучних інтелектуальних агентів для кодування: практичний посібник
Розробка, заснована на специфікаціях, з використанням штучних інтелектуваних агентів для кодування: чотириетапний процес роботи, файли AGENTS.md та SPEC.md, ролі багатьох агентів, рівні зрілості та способи виявлення відхилень.
Джерела: Spec-Driven Development with AI Coding Agents: The Definitive Guide
Інструменти на кшталт Claude Code, GitHub Copilot, Cursor та Windsurf тепер створюють, переструктурують та тестують код набагато швидше, ніж це може зробити будь-яка людина. Однак швидкість без точності часто стає перешкодою. Багато команд, які використовують ці інструменти, працюють у циклі: формулювання запитів, отримання результатів, виправлення помилок та знову формулювання запитів, причому цей цикл погіршується зі зростанням кодової бази. Причиною зазвичай є не сама модель — а відсутність у людей дисциплінованого способу пояснення агенту того, що потрібно.
Розробка, заснована на специфікаціях (SDD), є однією з рішень. Вона розглядає структуровану специфікацію як основний продукт процесу розробки: документ, з якого формується, перевіряється та керується код.
Концептуальна основа
Чому підхід vibe coding зазнає невдачі
„Кодування на основі атмосфери“ означає опис бажаного результату у розмовній формі та керування результатом за допомогою неформальних запитань. Цей підхід добре підходить для окремих завдань, швидких прототипів та експериментів, що тривають одну сесію. Однак він погано працює у масштабних проектах, і причина цього варта розуміння.
Занепад контексту
Кожна сесія відбувається в межах вікна контексту — обмеженої кількості інформації, яку агент може обробляти одночасно. Під час кодування на основі атмосфери стан проекту існує лише в історії чату. У міру подовження розмови ранні архітектурні рішення, вимоги до безпеки та вибір бібліотек виходять за межі цього вікна. Тоді агент замінює їх на правдоподібні альтернативи, часто не зазначаючи цього. Це і є занепад контексту.
Його типовою ознакою є відхилення під час реалізації: поступове розходження між тим, що агент вважає створеним, та тим, про що спочатку просила компанія. Код проходить тести, працює самостійно та виглядає коректно, проте порушує раніше встановлені структурні чи бізнес-правила. У корпоративних системах саме такі дефекти найважче діагностувати та найдорожче усувати.
Основна ідея
SDD ґрунтується на одному архітектурному принципі: специфікація є основним документом, а реалізація формується на її основі. Це більше, ніж просто зміна процесу роботи. Це перевертає традиційну модель догори дригом, де спочатку йде код, а документація слідує пізніше.
У цьому підході специфікація є машинночитабельною, контрольованою за версіями, постійно оновлюваною та виконуваною. Вона виступає як контракт між намірами людини та виконанням агента, причому агент працює в межах цього контракту, а не припускає щось наосліп. Точний контракт забезпечує прогнозований результат, тоді як неоднозначний — варіації. Коротко кажучи, ви не можете контролювати те, що створює агент, поки не визначите точно, що саме хочете отримати.
Шість елементів машинночитабельної специфікації
Специфікація, призначена для агента, має долати неоднозначності природної мови. Шість елементів, які зазвичай вважаються необхідними для того, щоб агент не робив небажаних припущень, є наступними:
- Результати — це ті досягнення, яких має бути досягнуто в результаті роботи.
- Обсяг — включає те, що прямо не враховується.
Робочий процес SDD
Чотири фази з людськими контрольними точками
Робочий процес складається з чотирьох послідовних фаз, кожна з яких містить момент, коли необхідна участь людини. Ці людські контрольні точки — це не бюрократія. Вони запобігають посиленню помилок у подальшому процесі, а спроба пропустити їх, щоб „швидше просунутися“, зазвичай призводить до протилежного ефекту.
Етап 1: визначення деталей. Розробник описує загальну мету на високому рівні, а потім або агент, або сам розробник перетворює цей опис на структуровану функціональну специфікацію: шляхи дії користувача, бізнес-результати, критерії прийняття та чіткі межі обсягу робіт. Завданням спеціаліста тут є архітектурний огляд — перевірка результату на наявність хибних припущень, пропусків та неправильних інтерпретацій перед початком будь-якого планування. Відкладіть етап 2, поки етап 1 не буде позбавлений неоднозначностей: розмита специфікація рідко призводить до розмитої реалізації, а радше до такої, яка є впевненою у собі, але помилковою.
Етап 2, планування. Як тільки специфікація схвалена, агент розробляє технічний план, який охоплює рішення щодо архітектури, моделі даних, контракти API та вибір технологій. У плані враховуються організаційні обмеження, такі як «зберігати дані в PostgreSQL» або «кожен кінець API вимагає автентифікації JWT». Перевірка людиною на цьому етапі дозволяє виявити архітектурні помилки до того, як вони потраплять у тисячі створених рядків коду.
Етап 3, розбивка завдань. Схвалений план розділяється на невеликі завдання, кожне з яких можна протестувати окремо. Гранулярність, ймовірно, є найбільш недооціненою змінною у SDD. Завдання має бути можливим до реалізації та перевірки протягом одного запуску агента, і якщо воно змушує агента одночасно вирішувати більше трьох окремих проблем, воно занадто велике. Добре розділений список також слугує основою для розробки, орієнтованої на тестування, адже кожне завдання має чітку умову успіху ще до початку роботи, і проект має часті точки перевірки.
Етап 4, реалізація та перевірка. Агент пише код по черзі, виконуючи кожне завдання, з фокусованим результатом, який можна перевірити та прив’язати до конкретної вимоги. Цей етап поєднується з паттерном верифікатора, де один агент генерує код, а другий агент або автоматизований набір тестів перевіряє його згідно з критеріями прийняття.
Оновлення специфікації в обох напрямках
Однією з найважливіших практик, яка часто порушується, є двонаправлене оновлення. Припустимо, що на 4-му етапі агент приймає рішення, яке не передбачено специфікацією, наприклад, обирає бібліотеку з міркувань продуктивності або вирішує крайній випадок непрямим способом. Це рішення слід негайно записати назад у специфікацію.
Якщо це не відбувається, накопичується „борг специфікації“: задум, задокументований у специфікації, віддаляється від фактичної поведінки. Це відхилення перетворює актуальну специфікацію на застарілий документ, якому ніхто не довіряє та який зрештою ніхто не читає, і він стає марним саме тоді, коли він найбільше потрібен — під час подальших змін за допомогою ШІ. Правило просте: коли реалізація відхиляється від специфікації, оновлюйте її відразу, а не на наступному циклі роботи. Борг специфікації зростає швидше, ніж технічний борг, оскільки він отруює основу для кожної наступної версії програмного забезпечення.
Артефакти стабільності та конституція проекту
Чому агентам потрібна конституція
Агент для програмування не має пам’яті між сеансами. Кожен новий сеанс починається лише з того, що ви введете до його контексту. Через відсутність механізму зберігання кожен сеанс є чистим аркушем, без жодного уявлення про ваші стандарти безпеки, конвенції найменування, заборонені бібліотеки чи архітектурні рішення.
„Конституція проекту“ — це набір постійних елементів, які вирішують цю проблему. Це структуровані файли, які зберігаються у репозиторії поруч із вихідним кодом, надаючи агенту інституційні знання для роботи як члену команди, який обізнаний у всіх аспектах, а не як сторонній користувач.
Основні елементи
AGENTS.md або CLAUDE.md – керівництво з експлуатації. Це найважливіший документ: README для агента, який читають на початку кожної сесії, щоб дізнатися, як працює цей конкретний проект. Його слід писати так, щоб його міг обробляти комп’ютер, а не людина. Ефективний файл містить три види інформації:
- Оперативні деталі, які агент не може вивести самостійно: точні команди збірки з прапорцями, спосіб виконання тестів, налаштування лінтера та назви змінних середовища.
- Конвенції найменування та структури: для чого призначений кожен каталог, як називаються файли та як організовані модулі.
.env та не змінюйте логіку автентифікації без попереднього перегляду.SPEC.md – жива специфікація. Це авторитетний опис того, що має робити система. Це не історичний запис; він відображає поточну бажану поведінку, включаючи кожне рішення, прийняте під час реалізації. Якщо код відхиляється від SPEC.md, файл оновлюється, а коли змінюються вимоги, спочатку редагується SPEC.md, а потім – реалізація.
PLAN.md – запис архітектури. У ньому зберігаються архітектурні рішення, вибір технологій та обмеження для всієї системи. Він відповідає на запитання «чому це побудовано саме так?», надаючи обґрунтування, яке заважає подальшим агентам та інженерам скасовувати ретельно зроблені вибори.
Файли конфігурації для конкретних інструментів. Кожен інструмент має власні правила форматування файлів правил. Варто згадати формат .mdc від Cursor, оскільки він поєднує Markdown із YAML-метаданими для прив’язки правил до шаблонів імен файлів. Правила бекенду, такі як вимоги до автентифікації та схеми доступу до бази даних, можуть застосовуватися лише тоді, коли агент працює з файлами бекенду, що дозволяє уникнути впливу нерелевантного контексту під час роботи з фронтендом.
Оркестрація кількох агентів
Чому одного агента недостатньо
Один агент, який відповідає за весь кодовий базис підприємства, стикається з серйозною обмеженням — вікном контексту. Велика система з 100 000+ файлів, кількома сервісами, складними потоками даних та повним набором тестів не може вміститися в контекст одного агента. Агент змушений вирішувати, що включити, і ці рішення створюють «сліпі зони».
Ідея оркестрації кількох агентів полягає у наслідуванні роботи сильної людської команди з чітко визначеними ролями, організованою передачею обов’язків та єдиною специфікацією, яку всі вважають істиною.
Три ролі
Координатор. Цей агент виконує функції менеджера проекту та архітектора. Він має повну картину ситуації, тобто всі технічні вимоги, список завдань та архітектурні обмеження. Він розділяє загальні вимоги на підвимоги, передає їх виконавцям, стежить за конфліктами між паралельними потоками роботи та переконується, що виконання одного завдання не пошкодить архітектуру в цілому.
Виконавець. Виконавці — це спеціалісти. Кожен з них отримує підвимоги, які стосуються одного завдання або невеликої групи пов’язаних завдань, та працює у ізольованій робочій структурі Git, щоб уникнути конфліктів на рівні файлів з іншими виконавцями, які працюють паралельно. Він нічого не знає про роботу поза своїми обов’язками та не несе за неї відповідальності. Ця ізоляція не є обмеженням — саме вона робить результати роботи детермінованими, піддаємими тестуванню та перевірці.
Перевірювач. У перевірювача протилежна мета: тоді як реалізатор намагається завершити завдання, перевірювач намагається знайти місце, де результат не відповідає специфікації. Ця суперечлива структура запозичена з формальної верифікації та досліджень у сфері безпеки, і вона належить до найсильніших механізмів контролю якості, які пропонує SDD. Перевірювач тестує результати виконання за критеріями прийнятності та шукає функціональні недоліки, порушення політики безпеки, порушення обмежень щодо продуктивності та відхилення від специфікації. Знайшовши неузгодження, він не виправляє код, а надсилає звіт координатору із структурованим описом, який простежує причину несправності до конкретної вимоги.
Для продуктивних систем такий адверсарійський верифікатор не повинен бути необов’язковим. Агент, який пише та перевіряє власний код, майже завжди вважатиме свою роботу прийнятною, тож цінність верифікатора полягає у його незалежності від реалізатора та протистоянні йому.
Паралельна експлуатація з робочими деревами
Однією з найцінніших характеристик багатоагентних SDD є паралелізм: кілька реалізаторів одночасно працюють над різними функціями чи сервісами, кожен у власному робочому дереві. Для великих проєктів із мінімальною кількістю залежностей між завданнями час виконання може значно скоротитися.
Git-робочі дерева уможливлюють це. Кожен агент має окремий робочий каталог, приєднаний до того ж репозиторію, тож конфлікти файлів уникаються, тоді як координатор стежить за прогресом у всіх робочих потоках з одного місця. Після схвалення верифікатором координатор об’єднує завершені робочі дерева та підтримує чистоту головної гілки.
Діаграми як код
Чому діаграми мають бути у специфікації
Архітектурні діаграми традиційно створювалися пізніше, як документація до вже існуючого коду. У підході SDD вони формуються на ранніх етапах, як частина специфікації та плану, ще до початку реалізації.
Причина цього — діагностична. Коли від агента вимагають створити коректну діаграму Mermaid на основі специфікації, це змушує його чітко аналізувати потоки даних, залежності сервісів та переходи станів перед написанням коду. Неорганізована чи несуцільна діаграма на цьому етапі є надійним ознакою того, що специфікація є неоднозначною або має структурні недоліки, а виправлення таких проблем у діаграмі коштує значно менше, ніж у вже розгорнутому коді.
Формати
Формати на основі тексту, зокрема Mermaid та D2, краще підходять для цієї мети, ніж бінарні зображення. Їх можна версіонувати та порівнювати, а агенти можуть читати їх безпосередньо. Їх також можна оновлювати у міру розвитку специфікації, що дозволяє підтримувати синхронність структурної документації та реалізації.
Три рівні зрілості
Експерти визначили три рівні SDD. Це не драбина, яку кожна команда повинна підніматися по порядку. Це різні профілі компромісів для різних ситуацій, і розуміння того, який з них підходить вашій ситуації, є важливим перед будь-яким впровадженням.
Рівень 1: спочатку специфікація. Для кожного завдання складається детальна специфікація. Як тільки реалізація завершена та перевірена, специфікацію вважають тимчасовою: її можна зберігати для посилання, але не підтримувати. Цей підхід підходить для ізольованих функцій, одноразових міграцій та експериментів, де підтримка на рівні 2 є недоцільною. Захисники цього підходу стверджують, що він забезпечує приблизно 60% користі від SDD за значно менші витрати, що робить його розумною відправною точкою для початківців. Використовуйте його для нової функції з чіткими критеріями прийняття, без залежностей між сервісами та з термінами виконання, виміряними у днях.
Рівень 2, орієнтований на специфікацію (рекомендований стандарт). Специфікація є рівноправним партнером коду протягом усього життєвого циклу проекту, і обидва елементи підтримуються. Коли змінюються вимоги, спочатку змінюється специфікація, а коли реалізація відхиляється, специфікацію негайно оновлюють, щоб задокументувати фактичну поведінку та обґрунтування. Це може здатися подвійною підтримкою, але на практиці це знижує загальні витрати: це запобігає занепаду контексту між сеансами, дозволяє новим членам команди (людям та ШІ) ефективно інтегруватися та робить подальші зміни за допомогою ШІ набагато надійнішими. Це є базовим стандартом для продакшн-систем, командних проектів та всього, що має продовжувати розвиватися.
Рівень 3, специфікація як джерело (експериментальний). Специфікація є єдиним основним документом. Код розглядається як скомпільований результат, генерується за потребою та ніколи не редагується вручну. Це теоретична кінцева мета підходу SDD, де інженери піклуються про специфікації, а ШІ — про їх реалізацію. Існує нерозв’язана проблема — детермінізм. Ідентичні специфікації можуть призводити до синтаксично різного, хоча функціонально еквівалентного коду при кожному запуску, що значно ускладнює порівняння, виправлення помилок та перевірку. Вважайте цей підхід експериментальним. Він може підійти для проектів з нуля з дуже повними специфікаціями, сильним керуванням за допомогою ШІ та толерантністю до незрілих інструментів, але на 2026 рік не рекомендується для критичних виробничих систем.
Інструкції за ролями
Інженери та архітектори
Основною навичкою інженера стає інженерія контексту. Правильне написання синтаксису — це те, що агенти роблять зі швидкістю машини, тому цінність інженера полягає у визначенні точного архітектурного контексту, підборі того, що може бачити агент, та перевірці того, чи відповідає його результат структурним цілям системи. Це включає створення якісних файлів AGENTS.md та SPEC.md, встановлення правил керування бібліотеками (чіткий список дозволених та заборонених залежностей), формулювання вимог до безпеки та відповідності у форматі, зрозумілому машинам, а також структурування завдань так, щоб проблеми залишалися окремими.
Початкова процедура для інженерів:
- Перед розробкою будь-якої функції з використанням ШІ створіть або оновіть файл SPEC.md, щоб він містив шість елементів, описаних раніше.
- Перегляньте файл AGENTS.md та переконайтеся, що команди збірки, шаблони тестування, правила найменування та ієрархія серйозності все ще відображають реальність.
Блок обмежень — це зручний шаблон, який можна додати до будь-якої специфікації. Він містить перелік технологій (кожна необхідна технологія), заборонених бібліотек (з повним написанням назв), вимог до безпеки (як користувачі автентифікуються, яке шифрування очікується, як можуть оброблятися дані), обмеження продуктивності (цільова затримка та пропускна здатність), вимоги до тестування (поріг покриття та необхідні типи тестів) та архітектурні шаблони (те, що є обов’язковим, та те, що слід уникати).
Технічні менеджери продуктів
Від документів вимог до продукту до коротких описів поведінки. Класичний документ вимог до продукту передбачає наявність інженерів, які будуть його читати, обговорювати та впроваджувати, керуючись власним судженням. У підході SDD результат роботи TPM має бути коротким описом поведінки — машинночитабельним описом того, як продукт має реагувати на конкретні потреби користувачів, із точними вимогами до виконання дій агентом.
Різниця полягає не лише у стилі. У документі вимог може бути написано "покращити процес оформлення замовлення". Короткий опис поведінки має вказувати, що саме робить поточний процес оформлення, які проблеми виникають у користувачів, які зміни в поведінці вважаються покращенням, як вимірюється успіх, які межові випадки потрібно враховувати та що система ні в якому разі не повинна робити.
Цикл прототипування. SDD дозволяє TPM скоротити звичайний процес передачі проекту від дизайнерів до інженерів. Замість того, щоб чекати на макети від дизайнерів, а потім, поки інженери їх створюють, TPM може генерувати інтерактивні прототипи безпосередньо на основі опису поведінки та оцінювати їхню роботу, а не лише статичні екрани. Якщо прототип не відповідає поставленим вимогам, специфікація оновлюється, і система знову створює реалізацію, тож цикл зворотного зв’язку працює на основі специфікації, а не коду. Це усуває кілька етапів передачі інформації (PRD, подальша передача проекту дизайнерам, потім інженерам), під час яких наміри часто втрачаються.
CTO та керівники інженерних відділів
Управління. Пріоритетом CTO в організації, яка ставить агентів на перше місце, є система управління, яка дозволяє ШІ прискорювати процес реалізації без погіршення якості, безпеки чи дотримання стандартів. SDD забезпечує шар керування, але лише за умови наявності організаційної дисципліни. На великих масштабах важливі три механізми:
- Контроль версій специфікацій. Файли SPEC.md, PLAN.md та AGENTS.md знаходяться в тому ж репозиторії, що й код, і проходять ту саму процедуру перевірки та схвалення.
- Хроніки аудиту. Кожна зміна, створена за допомогою ШІ, має бути пов’язана з конкретною вимогою специфікації, що є обов’язковим у регульованих галузях.
- Контроль з боку людей на кожному етапі переходу. Ніщо не може автономно переходити від етапу формулювання до планування та подальшої реалізації без схвалення на кожному кроці.
Керівники відділів технологій також повинні оцінювати інструменти програмування на основі ШІ згідно з цією схемою, з’ясовуючи, наскільки добре кожен з них підтримує постійні файли правил, процедури перевірки, можливості відстеження та робочі процеси з багатьма агентами.
Вимірювання ефективності. Організації, які впроваджують SDD, часто повідомляють, що розробка здається повільнішою протягом перших двох–чотирьох тижнів, оскільки інженери витрачають час на розробку специфікацій замість того, щоб приступати до написання коду. Це спостереження є правильним, але його інтерпретація вводить в оману. Робота над специфікаціями — це не новий додатковий тягар. Це робота, яку раніше виконували неформально, непослідовно та після реалізації, коли вона коштувала найбільше. Показники, які відображають справжню ефективність, знаходяться далі в процесі:
- час від формулювання вимог до готового до використання коду, тобто коду, який був перевірений, проаналізований та розгорнутий, а не просто написаний,
- відсоток переробки — частка готових функцій, які потрібно переробити через неправильне розуміння вимог,
- час відновлення робочої ситуації — скільки часу потрібно розробнику або агенту, щоб стати продуктивним у роботі з кодом, який не змінювався протягом 30 днів, та
- частка виявлених дефектів — частка дефектів, виявлених під час перевірки специфікації, у порівнянні з тими, що знаходяться після розгортання.
За повідомленнями, команди, які застосовують розвинені практики SDD, спостерігають зниження кількості переробок на 40–60%, а час відновлення робочої ситуації значно скорочується, оскільки специфікація забезпечує необхідний контекст, без якого інакше знадобилися б години на аналіз коду. Ці цифри походять зі звітів практиків, а не з контрольованих досліджень, тому вимірюйте власні показники вихідної точки.
Зміна початкових намірів
Що це таке
Відхилення наміру — це поступова розбіжність, яка виникає між початковими вимогами бізнесу та поведінкою коду в умовах реальної експлуатації. Це не є новим явищем у роботі з допомогою ШІ та є однією з найстаріших проблем інженерії програмного забезпечення, проте агенти для програмування створюють небезпечний фактор прискорення цього процесу. Вони оптимізують код за критеріями правдоподібності та проходження тестів, а не відповідності вимогам бізнесу. Якщо попросити їх створити систему обробки платежів, вони напишуть код, який пройде всі тести та охопить усі вказані сценарії. Якщо специфікація є неповною чи застарілою, агент заповнює прогалини статистично ймовірними значеннями зі своїх даних навчання. Це підходить для загальних систем, але може бути катастрофічним для конкретних бізнес-правил. Найгірше відхилення — це те, яке помічають лише тоді, коли воно коштує клієнту грошей, призводить до аудиту відповідності чи інциденту в експлуатації, адже агенти дуже добре вміють створювати код, який виглядає правильним, хоча насправді має приховані помилки.
Захисти
- Жива специфікація. Перший захист — це специфікація, яка оновлюється в реальному часі під час прийняття рішень. Кожне відхилення від SPEC.md, незалежно від того, наскільки воно незначне чи обґрунтоване, відразу фіксується, тож файл завжди описує поточну поведінку, а не первісні наміри.
- Перевірка проти супротивника. Модель перевіряючого також виконує функцію виявлення відхилень. Порівняння результату зі специфікацією після кожного завдання дозволяє виявити відхилення на найменшій можливій глибині, ще до того, як вони накопичаться протягом кількох циклів реалізації.
- Відстеження охоплення специфікації. Більш складні системи відстежують частку вимог, які мають автоматизовані, перевірювані тести. Вимога без тесту може відхилятися непоміченою, а прагнення до повного охоплення є проявом розробки, керованої тестами, на рівні вимог.
Мінімальний AGENTS.md
Документ AGENTS.md, готовий до використання, може бути коротким. Як мінімум, він має містити опис проекту у одному абзаці, точні команди для збірки, тестування та перевірки коду, правила найменування та структури каталогів, списки «завжди», «спочатку запитайте» та «ніколи», посилання на документи SPEC.md та PLAN.md, а також правила керування бібліотекою. Адаптуйте кожну частину під ваші технології та вимоги організації.
Яке це дає вам
Розробка, заснована на специфікаціях, — це не тимчасовий тренд чи незначне покращення існуючих практик. Вона змінює сутність інженерної роботи. За допомогою агентів для кодування вузьким місцем у процесі створення продукту більше не є швидкість генерації синтаксису, а точність визначення намірів. Специфікація є кінцевим продуктом, код — це те, що її реалізує, а у процесі створення програмного забезпечення з використанням агентів специфікація є найважливішим результатом роботи інженера.
Пов’язана література
- Практичні нотатки: Я запускаю AI-агента для програмування локально, і його продуктивність майже вдвічі вища — Детальний огляд Практичних нотаток: Я запускаю AI-агента для програмування локально, і його продуктивність майже вдвічі вища: контракти, перевірки та шаблони коду для команд, які використовують цю модель.
- Інженерія агентів у п’яти шарах: від специфікацій та паралельних агентів до правил та нагляду — Карпаті описав перехід від традиційного програмування. Дізнайтеся про п’ять шарів інженерії агентів: специфікації, оркестрація, кодовані правила, людський огляд та можливість моніторингу, а також план на тиждень.