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 вместе с кодом, что позволяет отслеживать эволюцию архитектурных решений через историю коммитов.