Разработка на основе спецификаций

Вы наблюдали это: просите AI агента “добавить фотошеринг в приложение”, и он что-то строит. Код компилируется. Тесты проходят. Но архитектура не соответствует тому, что бы вы выбрали. Модель данных делает предположения, которые вы бы никогда не сделали. И вот вы три дня в фиче, которая нуждается в переписывании.

Это ловушка vibe coding. Агент не сломан — он делает именно то, что вы просили. Проблема в том, что вы просили код, когда должны были сначала попросить ясность.

Разработка на основе спецификаций (SDD) переворачивает сценарий. Вместо прыжка напрямую к реализации, вы определяете чего хотите в спецификации, которая становится источником истины. Спецификация — это не документация, написанная после факта — это исполняемый контракт, определяющий что будет построено.

Проблема code-first

Когда вы промптите AI-агента без чётких спецификаций, вы просите его читать ваши мысли. А языковые модели исключительны в завершении паттернов, а не в чтении мыслей.

Что происходит с расплывчатыми промптами:

• Агент делает разумные предположения — некоторые будут неверными.
• Требования проявляются инкрементально, запирая вас в ранних решениях.
• Кодовая база становится de-facto спецификацией.
• Ключевые решения застревают в Slack-тreads или в головах людей.
• Крупные переписывания требуют огромных усилий, потому что код по своей сути связывающий.

Вы обнаруживаете проблемы глубоко в реализации, когда они дороги в исправлении. Агент построил то, что вы сказали, а не то, что вы имели в виду.

Что SDD из себя представляет

Будем честны о том, чем SDD не является:

• Не waterfall-планирование: Вы не пишете исчерпывающую документацию перед касанием кода.
• Не бюрократия: Это не должно вас замедлять; это должно предотвращать дорогую доработку.
• Не предсказание будущего: Вы захватываете текущее понимание, которое эволюционирует.

SDD — это делание технических решений явными, ревьюуемыми и эволюционирующими. Это version control для вашего мышления.

Ключевой инсайт: Спецификации становятся живыми документами, которые развиваются вместе с кодом. Они являются активными инструментами, которые помогают вам продумывать edge cases, координировать команды и включать мульти-вариантные реализации.

Когда ваша спецификация превращается в работающий код автоматически, намерение становится источником истины — а не сам код.

Рабочий процесс SDD

SDD разбивает разработку на отдельные фазы. Каждая фаза имеет определённое назначение и производит артефакты, которые питают следующую фазу.

Фаза 0: Конституция (опционально, но рекомендуется)

Перед любой итерацией установите правила игры. Каковы ваши некогда-negotiable принципы?

Что входит в конституцию:

• Подходы и стандарты тестирования
• Политики безопасности и правила соответствия
• Ограничения дизайн-системы
• Конвенции tech stack (CLI-first, API-first и т.д.)
• Инженерные практики
• Требования к интеграции

Это становится ограждениями, которые направляют всю разработку. Агент знает что запрещено ещё до того как напишет первую строку кода.

Фаза 1: Спецификация

Определите “что” и “почему”: проблему, пользователей, scope и критерии успеха.

Фокус на:

• Формулировка проблемы
• Персоны пользователей и когорты
• Ключевые пользовательские потоки и опыт
• Метрики успеха
• Ограничения (производительность, приватность, безопасность)
• Что явно вне scope

Избегайте: Деталей технической реализации, выбора стека, архитектуры (это приходит позже).

Пример промпта спецификации:

Build a trip planner that generates day-by-day itineraries for multi-city trips.

Problem: help travelers plan multi-city trips with realistic timing, budget guidance
Users: casual travelers, travel bloggers, small tour operators
Key flows: create trips, add cities, auto-generate itinerary, adjust by preferences
Non-functional: P95 itinerary generation under 4 seconds for 7-day trips
Out of scope: airline booking, hotel payments

Выход — структурированный SPEC.md, который захватывает требования. Агент может пометить секции как [NEEDS CLARIFICATION] — разрешите их перед продвижением.

Фаза 2: План

Переведите продуктовую спецификацию в техническую реализацию. Теперь вы определяете “как”.

Фокус на:

• Выбор tech stack
• Архитектура и дизайн-паттерны
• Границы интеграции
• Контракты данных и схемы
• Цели производительности
• Подход к безопасности
• Идентифицированные риски

Пример промпта планирования:

Stack: FastAPI + Postgres + Redis; Next.js front end; mobile via Expo.
Architecture: API-first, backend service + vector store for place of interest (POI) embeddings.
AI: routing agent for POIs, scheduler for packing days, critic for validation.
Performance: target end-to-end plan in under 4 seconds at P95.
Security: redact PII in logs, encrypt at rest.

Выход — PLAN.md с технической архитектурой. Ключевая выгода: вы можете генерировать несколько вариантов плана для сравнения разных подходов перед коммитом.

Фаза 3: Задачи

Разбейте на спецификацию и план на управляемые, тестируемые, упорядоченные рабочие элементы.

Каждая задача включает:

• Чёткое описание
• Критерии приёмки
• Зависимости
• Ссылки на секции спецификации
• Требования к тестам

Пример разбивки на задачи:

• Контракт API для генерации маршрута со схемами
• Промпты агента и ограждения
• Загрузчики данных для POI-метаданных
• Кеширование и обработка rate-limit
• Фронтенд-потоки: создание поездки, редактирование предпочтений, просмотр маршрута
• Наблюдаемость: тайминги, отслеживание стоимости, таксономия ошибок

По умолчанию элементы, связанные с тестами, включены и упорядочены перед реализацией — структура TDD встроена.

Фаза 4: Реализация

Выполняйте задачи маленькими срезами, оставаясь в рамках ограничений.

Ключевая практика: Держите агентов указывающими обратно на SPEC.md и PLAN.md для каждого изменения. Работайте из спецификации, плана или файла задач, а не из ad-hoc промптов. Выполняйте маленькими, ревьюуемыми частями.

Пример среза реализации:

• Реализовать POST /itinerary с валидацией схемы
• Добавить промпт агента-планировщика с учётом ограничений
• Кешировать lookups и transit matrices
• Верифицировать против критериев приёмки

Каждый срез должен решать конкретный кусочек головоломки.

Фаза 5: Тестирование

Тестирование — это не отдельная фаза — оно интегрировано повсюду. Тесты привязываются напрямую к требованиям для трассируемости.

Типы тестов:

• Контрактные тесты: Валидация запрос/ответ API
• Проперти-тесты: Верификация ограничений (например, ни один день не превышает 10km пешком)
• Перформанс-тесты: P95 латентность ниже цели
• Тесты безопасности: Редaktion PII, верификация шифрования

Трасса от “что было обещано” к “что было доставлено” становится аудируемой.

Фаза 6: Поддержка

Требования меняются. SDD элегантно это обрабатывает:

1. Сначала обновите спецификацию
2. Регенерируйте план
3. Обновите задачи
4. Позвольте агентам рефакторить в рамках
5. Расширьте тесты для новых правил
6. Ведите changelog ревизий спецификации

Пример запроса на изменение:

Add "family mode" that favors kid-friendly POIs and shorter walking segments.

Process:
- Update SPEC.md constraints
- Re-run planning
- Regenerate affected tasks
- Adjust prompts
- Extend tests for new rules
- Document why trade-offs were made

Человеческое ревью необходимо перед принятием регенерированных планов.

GitHub Spec Kit

Spec Kit от GitHub — это open-source инструментарий, который переводит SDD в операционное состояние для множества AI-кодинг агентов.

Что он предоставляет

• Specify CLI: Инструмент на Python, который бутстрапит проекты для SDD
• Шаблонысты: Структурированные форматы для спецификаций, планов, задач и конституции
• Слэш-команды: Промпты AI-агентов для структурированного рабочего процесса разработки
• Вспомогательные скрипты: Автоматизация для поддержания каркаса SDD

Установка

# Постоянная установка (рекомендуется)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Инициализировать проект
specify init <PROJECT_NAME>

# Или в текущей директории
specify init . --ai claude

Поддерживаемые агенты

Spec Kit работает с большинством современных AI-кодинг агентов:

Агент	Поддержка
Claude Code	✅
GitHub Copilot	✅
Cursor	✅
Gemini CLI	✅
Windsurf	✅
Kilo Code	✅
Roo Code	✅
Codex CLI	✅
opencode	✅

Шаблоны разработаны для работы между агентами без настроек.

Структура проекта

After running specify init, you’ll see:

├───.github (or agent-specific folder)
│   └───prompts
│       plan.prompt.md
│       specify.prompt.md
│       tasks.prompt.md
│
└───.specify
    ├───memory
    │   constitution.md
    │
    ├───scripts
    │   └───bash (or powershell)
    │       check-task-prerequisites.sh
    │       create-new-feature.sh
    │       setup-plan.sh
    │
    └───templates
        plan-template.md
        spec-template.md
        tasks-template.md

Когда SDD работает

Идеальные сценарии

Greenfield разработка (0-to-1): Starting new projects from scratch. Небольшая предварительная работа гарантирует что AI строит реальное намерение, а не generic решения на основе common паттернов.

Работа над фичами в существующих системах (N-to-N+1): Самая мощная область применения. Добавление фичей в complex, существующие кодовые базы. Принуждает к ясности how new фичи взаимодействуют с существующими системами. Новый код ощущается native, не прикрученным.

Модернизация легаси: Перестройка legacy systems где оригинальное намерение потеряно времени. Захватите essential business logic в современной спецификации, спроектируйте свежую архитектуру, и позвольте AI перестроить без унаследованного долга.

Complex системы со многими contributors: Microservice архитектуры, multi-repo фронтенды, AI-powered бэкенды. Каждая граница становится явной, enabling contract testing.

High-stakes фичи: Платёжные потоки, healthcare диагностика, safety-critical автоматизация. Кодируйте перформанс, безопасность и пороги надёжности.

Долгосрочные проекты: Когда проект переживёт founding team, SDD сохраняет дизайн-намерение как институциональную память.

Когда пропустить

Быстрые прототипы: SDD может быть overkill. Облегчите процесс — короткая спецификация, простой план, ручные заметки.

Дизайн-эксперименты: Полная структура SDD замедляет momentum когда вы исследуете.

Одноразовые операции: Иногда вам нужны immediate результаты без итерации.

Простые, well-understood проблемы: Overhead не оправдан для тривиальных задач.

Почему это работает

Ключевая проблема с расплывчатым промптингом в том, что языковые модели исключительны в паттерн-комплишн, а не в чтении мыслей.

Расплывчатый промпт: “add photo sharing to my app”

Это заставляет модель гадать о тысячах незаявленных требований. Она делает разумные предположения — но некоторые будут неверными. Вы обнаруживаете проблемы глубоко в реализации, когда они дороги в исправлении.

С чёткой спецификацией + техническим планом + сфокусированными задачами = ясность AI

Теперь, вместо угадывания, AI:

• Знает что строить: From specification
• Знает как строить: From plan
• Знает последовательность: From tasks
• Знает ограничения: From constitution

Подход работает across different stacks porque fundamental challenge is the same: translating intent into working code. Your specification captures intent clearly. Your plan translates intent to technical decisions. And tasks break the work down into implementable pieces. AI just handles the actual coding.

Распространённые ловушки

Over-specifying too early

Проблема: Пытаться capture every pixel before building.

Решение: Спеки должны эволюционировать с пониманием. Стремитесь к just-enough structure для test automation и AI generation, и итерируйте as you validate assumptions.

Letting specs drift

Проблема: Изменения проникают в продакшн без обновления спецификации.

Решение: Относитесь к документу как к передовой вашего журнала изменений. Сначала обновите спецификацию, затем мержите код. Это сохраняет трассируемость для аудитов.

No clear ownership

Проблема: “Кто-то другой исправит это позже” синдром.

Решение: Назначьте “spec steward” (роль которая ротируется) чтобы гарантировать что merge requests включают обновления спецификации. Они должныn’t flag inconsistencies early.

Focusing on what instead of why

Проблема: Future teammates lack context for confident changes.

Решение: Capture rationale as well as requirements. Include business drivers (“сократить время checkout до менее 2 секунд”) и документируйте смягчённые риски (“соответствовать SOC 2 audit log mandates”).

Treating as static document

Проблема: Спецификация становится устаревшим артефактом.

Решение: Держите вашу спецификацию как живой документ который эволюционирует вместе с кодом. Обновляйте во время фазы поддержки и ведите changelog ревизий.

Enterprise преимущества

Централизованные требования: Политики безопасности, правила соответствия, ограничения дизайн-системы, потребности интеграции — всё это должно жить в спецификации и плане, где AI может реально это использовать. Не в чьей-то голове, закопанное в wiki which nobody reads, или разбросанное across Slack conversations.

Аудируемость: Со спецификацией commit прилинкованной к каждому релизу, у вас есть доказуемая цепочка от требования к реализации, to satisfy auditors demanding due diligence.

Общий словарь: Один глоссарий пользовательских потоков, метрик и состояний ошибок. С no dueling definitions of “session”, “tenant”, or “SLA”, у вас меньше трения в кросс-функциональной работе.

Ускоренный онбординг: New hires skim change-tracked спецификации. Они могут видеть как требования эволюционировали и reach productive coding за days, not weeks.

Безопасная параллельная разработка: С интерфейсами замороженными в контракте и mock servers сгенерированными из спецификации, вы можете surface integration issues early, before staging.

Сдвиг в мышлении

Традиционная разработка: код — источник истины.

Разработка на основе спецификаций: намерение — источник истины.

Вы перестаёте спрашивать “Как мне написать идеальный промпт?” и начинаете спрашивать “Как мне capture intent clearly enough that AI может его выполнить?”

Работа агента — переводить намерение в работающий код. Ваша работа — делать это намерение явным, ревьюуемым и эволюционирующим.

Ресурсы

Официальные

• ПРОБОВАТЬ: GitHub - github/spec-kit — Официальный репозиторий (62k+ звёзд, MIT лицензия)
• ЧИТАТЬ: Spec-driven development with AI - GitHub Blog — Официальный анонс и обзор

Туториалы

• ЧИТАТЬ: Spec-Driven Development Tutorial using GitHub Spec Kit — Реальный туториал с примерами
• ЧИТАТЬ: Diving Into Spec-Driven Development With GitHub Spec Kit — Microsoft Developer Blog

Мейнтейнеры

• Den Delimarsky (@localden)
• John Lam (@jflam)

---

Используете SDD в продакшене? Поделитесь своим опытом—что сработало, что нет и что вы узнали.