Spec-Driven Development (SDD)(Розробка на основі інженерних специфікацій)

1. Огляд концепції та системна проблема

Найпоширеніша помилка розробників-початківців у вайбкодингу — підхід «Prompt-and-Pray» (написати розмитий запит у чат і сподіватися, що модель вгадає архітектуру). Коли запит звучить як «Зроби білінг через Stripe для передплатників», модель самостійно обирає випадкові схеми бази даних, використовує застарілі бібліотеки, ігнорує вебхуки, забуває про ідемпотентність і не враховує крайові випадки скасування платежу. Коли інженер просить полагодити баг, модель починає гарячково латати дірки, остаточно перетворюючи кодову базу на спагеті-код (AI Slop).

Spec-Driven Development (SDD, розробка на основі специфікацій) — це інженерна дисципліна, що відокремлює етап системного проектування від етапу кодогенерації. Перед тим як торкатися кодової бази, створюється формалізований документ специфікації (spec.md або RFC.md). Цей документ стає єдиним джерелом правди (Single Source of Truth) і контрактом, проти якого агент виконує та верифікує кожен наступний крок.

2. Архітектурна таксономія та ментальна модель

Архітектурний каркас SDD будується на чіткій ієрархії артефактів проектування:

┌─────────────────────────────────────────────────────────────┐
│             SPEC-DRIVEN DEVELOPMENT ARTIFACT HIERARCHY      │
├─────────────────────────────────────────────────────────────┤
│ 1. Product Context: Проблема користувача та бізнес-мета     │
├─────────────────────────────────────────────────────────────┤
│ 2. Technical Contracts:                                     │
│    • Схеми даних (Drizzle / Prisma schemas, SQL DDL)        │
│    • API Contracts (Zod Schemas, OpenAPI, TypeScript types) │
│    • Invariants & Security Rules (Idempotency, RBAC, Auth)  │
├─────────────────────────────────────────────────────────────┤
│ 3. Atomic Task Checklist (DAG):                             │
│    • Step 1 ➔ Step 2 ➔ Step 3 (Строгий порядок залежностей) │
├─────────────────────────────────────────────────────────────┤
│ 4. Verification Predicates: Машинні критерії готовності     │
└─────────────────────────────────────────────────────────────┘

1. Технічні контракти (Interface-First):
   • Опис взаємодії систем ще до реалізації внутрішньої логіки. Визначаються структури запитів/відповідей, схеми валідації та стан помилок.
2. Атомарний граф завдань (Task Decomposition DAG):
   • Задача розбивається на послідовність дрібних, незалежно перевірюваних підзадач. Кожна підзадача повинна модифікувати не більше 1–3 файлів.
3. Машино-верифіковні критерії (Acceptance Predicates):
   • Замість суб'єктивного «перевір, що все працює», специфікація містить конкретні команди перевірки: «pnpm test auth.test.ts проходить успішно, покриття гілок > 90%».
4. Статус-трекер життєвого циклу (Lifecycle Tracker):
   • Специфікація містить інтерактивні чек-бокси ([ ] ➔ [x]), які агент оновлює після виконання та верифікації кожного кроку.

3. Технічний пайплайн та внутрішня механіка

Життєвий цикл розробки за методологією SDD:

1. Інтерв'ювання та синтез специфікації (Interview Phase): Інженер формулює завдання. Модель ставить уточнюючі запитання щодо нетривіальних деталей: яка поведінка очікується при розриві мережі, як обробляти дублікати, які ліміти рейт-лімітингу.
2. Фіксація специфікації в репозиторії: Створюється артефакт (наприклад, .specs/004-billing-integration.md), який додається до системи контролю версій Git.
3. Людський аудит та затвердження (Spec Approval): Інженер вичитує запропоновані схеми даних і контракти. Якщо архітектурне рішення містить недоліки, вони виправляються на рівні тексту специфікації за 2 хвилини, уникаючи годин переписування коду.
4. Покрокове делегування агенту (Step-by-Step Execution): Агент викликається для реалізації конкретного кроку зі специфікації:
   • Агент читає контекст специфікації.
   • Пише тести відповідно до контрактів (TDD).
   • Реалізує функціонал.
   • Запускає тести та фіксує виконання підзадачі.
5. Фінальна верифікація та архівація: Коли всі пункти специфікації відзначені як виконані, проводиться наскрізний аудит, а специфікація залишається в репозиторії як жива документація фічі.

4. Практичні інженерні сценарії в продакшені

01. Розробка критичного платіжного модуля з ідемпотентністю

Перед написанням коду інтеграції платіжного шлюзу інженер створює специфікацію:

• Фіксує структуру таблиці idempotency_keys із полями key, response_payload, status, expires_at.
• Описує точний алгоритм поведінки при отриманні повторного вебхука зі схожим transaction_id.
• Агент імплементує модуль суворо за специфікацією; жоден граничний випадок не втрачається.

02. Паралельна робота бекенд- та фронтенд-агентів

Команда створює новий дашборд аналітики:

• Спершу в специфікації описуються схеми Zod та інтерфейси TypeScript для всіх графіків і метрик.
• Фронтенд-агент використовує ці схеми для верстки компонентів із моковими даними.
• Бекенд-агент одночасно реалізує реальні SQL-запити та роути API під той самий контракт.
• Інтеграція проходить без жодного конфлікту несумісності типів.

03. Безпечна масштабна міграція легасі-модуля

Заміна старої самописної авторизації на Better Auth:

• Специфікація описує збереження зворотної сумісності сесій у Redis та покроковий план міграції парольних хешів з bcrypt на Argon2id.
• Агент розбиває міграцію на 7 ізольованих етапів, кожен із яких тестується окремо.

5. Підводні камені, типові помилки та безпека

• Параліч надлишкового проектування (Over-Engineering Paralysis): Написання 20-сторінкової специфікації для дрібного виправлення відступів або зміни кольору кнопки — безглузда витрата часу. Застосовуйте SDD для задач, що зачіпають більше ніж 2 модулі або містять критичну бізнес-логіку.
• Розсинхронізація коду та специфікації (Spec Rot): Якщо під час розробки виникає потреба змінити схему, інженери часто виправляють код напряму, забуваючи оновити spec.md. Це збиває з пантелику наступних агентів, які знову читатимуть застарілу специфікацію.
• Використання розмитих формулювань: Фрази на кшталт «система має працювати швидко» або «забезпечити надійність» є катастрофічними для ШІ. Специфікація повинна оперувати конкретними значеннями: «час відповіді p99 < 150ms», «повертати HTTP 429 при перевищенні 100 rpm».
• Ігнорування версіонування специфікацій: Файли специфікацій повинні бути частиною репозиторію Git разом із кодом, що дозволяє відстежувати еволюцію архітектурних рішень через історію комітів.