Spec-Driven Development: от хаотичного AI-кодинга к инженерному процессу

Короткая версия

Spec-Driven Development, или SDD, — это способ работать с AI-ассистентами не через бесконечный чат и «vibe coding», а через явные спецификации: требования, сценарии, дизайн и список задач. Сначала договориться с агентом, что именно должно измениться, потом дать ему писать код, проверяя результат не на вкус, а относительно согласованных артефактов.

OpenSpec — один из самых практичных инструментов для такого процесса. Это не новая IDE и не облачный сервис, а легкий open-source слой поверх существующего проекта и любимого AI-инструмента: Claude Code, Cursor, Codex, GitHub Copilot, OpenCode, Windsurf, Gemini CLI, Kiro и многих других. Он создает в репозитории папку openspec/, где живут текущие спецификации системы и отдельные папки изменений.

Главная формула OpenSpec:

идея → proposal → delta specs → design → tasks → implementation → sync/archive

В стандартном быстром профиле это выглядит так:

/opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive

Почему SDD стал важен именно сейчас

AI-кодинг резко снизил стоимость написания кода, но не снизил стоимость непонимания. Если задача описана расплывчато, агент быстро создаст много кода, который выглядит убедительно, но расходится с реальными требованиями. Чем больше проект, тем сильнее проблема:

• требования остаются в истории чата и теряются между сессиями;
• агент забывает контекст, потому что контекстное окно не бесконечно;
• разные изменения пересекаются и конфликтуют;
• ревью превращается в чтение diff, хотя ошибка часто была не в коде, а в исходном намерении;
• команда не понимает, почему было принято то или иное решение.

SDD переносит центр тяжести с «напиши код» на «сначала зафиксируй намерение». Это особенно полезно для агентной разработки, где один и тот же человек может за день запускать несколько независимых AI-задач.

GitHub Spec Kit формулирует более радикальную версию подхода: спецификация становится первичным артефактом, а код — выражением этой спецификации. В их тексте SDD описан как инверсия привычной модели, где «code is truth»: теперь спецификации не обслуживают код, а код обслуживает спецификации.

Kiro, со своей стороны, продвигает похожую идею как «engineering rigor for agentic development»: запрос на естественном языке превращается в требования и acceptance criteria, затем в архитектурный дизайн, затем в дискретные задачи, связанные с требованиями.

OpenSpec занимает более легкую и прагматичную позицию: он не пытается заменить всю среду разработки, а дает переносимый формат и команды, которые работают с существующими агентами.

Что такое OpenSpec

OpenSpec — AI-native система для spec-driven development. Репозиторий: https://github.com/Fission-AI/OpenSpec. Пакет npm: @fission-ai/openspec, текущая изученная версия — 1.4.1. Проект написан на TypeScript, распространяется под MIT.

Философия из документации OpenSpec:

fluid not rigid         — без жестких фазовых ворот
iterative not waterfall — уточняем по мере работы
easy not complex        — минимальная церемония
brownfield-first        — рассчитано на существующие кодовые базы

Это важное отличие от тяжеловесных процессов. OpenSpec не говорит: «сначала полностью закончи ТЗ, потом дизайн, потом код». Он говорит: «создай достаточно хорошее описание, начни работать, а когда узнаешь больше — обнови артефакты».

Как OpenSpec организует проект

После openspec init в проекте появляется структура:

openspec/
├── specs/              # источник истины: как система работает сейчас
│   └── <domain>/
│       └── spec.md
├── changes/            # предлагаемые изменения: одна папка на изменение
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # delta specs: что меняется
│           └── <domain>/
│               └── spec.md
└── config.yaml         # опциональный проектный контекст и правила

Две главные сущности:

• openspec/specs/ — текущее описание поведения системы. Это «что правда сейчас».
• openspec/changes/ — рабочие изменения. Каждая фича, багфикс или рефакторинг живет отдельно, пока не будет завершен и заархивирован.

Такой формат дает несколько преимуществ:

1. Можно вести несколько изменений параллельно.
2. Можно ревьюить не только код, но и намерение.
3. Можно понять историю решения: proposal, design, tasks и spec delta остаются в архиве.
4. Можно восстановить контекст в новой AI-сессии без пересказа всей истории.

Главные артефакты OpenSpec

proposal.md

Отвечает на вопросы «зачем» и «что меняется». Хороший proposal фиксирует:

• намерение;
• проблему или пользовательскую потребность;
• scope;
• что не входит в scope;
• общий подход;
• риски и rollback, если это важно.

Пример:

# Proposal: Add Dark Mode

## Intent
Users need a dark mode option to reduce eye strain during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context for state management.

Delta specs

Delta specs — ключевая идея OpenSpec. Вместо переписывания всей документации изменение описывает, что именно добавляется, меняется или удаляется.

Формат:

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

## REMOVED Requirements

### Requirement: Remember Me
Deprecated in favor of 2FA.

Применение дельт — sync:

• ADDED добавляется в основной spec;
• MODIFIED заменяет существующее требование;
• REMOVED удаляет требование.

Архивация — archive — затем переносит папку изменения в openspec/changes/archive/ (предложив сперва запустить sync, если ещё не).

design.md

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

tasks.md

Чеклист реализации. Он превращает дизайн в конкретные шаги:

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page

Для AI-агента это особенно ценно: он получает не просто большой запрос, а последовательность проверяемых действий.

Команды OpenSpec

OpenSpec ставит slash-команды в поддерживаемые AI-инструменты. В базовом профиле core доступны:

• /opsx:propose — создать изменение и все планировочные артефакты;
• /opsx:explore — исследовать проблему до формального изменения;
• /opsx:apply — реализовать tasks;
• /opsx:sync — применить delta specs к основным specs;
• /opsx:archive — завершить изменение и перенести его в архив.

Расширенный профиль добавляет:

• /opsx:new — создать только каркас изменения;
• /opsx:continue — создавать следующий артефакт по одному;
• /opsx:ff — быстро создать все планировочные артефакты;
• /opsx:verify — проверить реализацию против proposal/specs/design/tasks;
• /opsx:bulk-archive — архивировать несколько завершенных изменений;
• /opsx:onboard — пошаговый walkthrough.

Типовые сценарии работы

Быстрая фича

Когда задача понятна:

/opsx:propose add-dark-mode
/opsx:apply
/opsx:sync
/opsx:archive

Подходит для небольших и средних задач: добавить настройку, починить баг, изменить интеграцию, обновить UI.

Неясная задача

Когда непонятно, что именно делать:

/opsx:explore

Агент сначала исследует кодовую базу, находит варианты, задает уточнения или предлагает подходы. Когда решение созрело:

/opsx:propose optimize-product-list-fetching

Сложная задача с контролем по шагам

В расширенном профиле:

/opsx:new rewrite-auth-flow
/opsx:continue   # proposal
/opsx:continue   # specs
/opsx:continue   # design
/opsx:continue   # tasks
/opsx:apply
/opsx:verify
/opsx:archive

Так лучше работать с архитектурными изменениями, платежами, auth, миграциями данных и всем, где ошибка стоит дорого.

Параллельные изменения

OpenSpec позволяет держать несколько папок в openspec/changes/:

openspec/changes/add-dark-mode/
openspec/changes/fix-login-redirect/
openspec/changes/optimize-product-query/

Это удобно, когда срочный баг прерывает работу над фичей. После завершения багфикса можно вернуться к прежнему change ID.

Чем OpenSpec отличается от plan mode в AI-редакторе

Plan mode полезен, но обычно живет внутри текущей сессии или конкретного инструмента. OpenSpec дает более устойчивый слой:

• планы лежат в репозитории;
• их можно ревьюить в pull request;
• они переживают смену агента и сессии;
• они связаны с требованиями и сценариями;
• изменение можно архивировать и встроить в основную спецификацию.

Иначе говоря, plan mode — это поведение ассистента, OpenSpec — это проектный артефакт.

Чем OpenSpec отличается от GitHub Spec Kit и Kiro

OpenSpec

Сильные стороны:

• легкий слой поверх существующих инструментов;
• работает с большим списком AI-ассистентов;
• не требует API-ключей или MCP;
• хорошо подходит для brownfield-проектов;
• delta specs удобны для небольших и средних изменений;
• TypeScript/npm установка проста для web-разработчиков.

Компромиссы:

• качество артефактов зависит от модели и дисциплины команды;
• нужно привыкнуть обновлять specs, а не только код;
• часть workflow полагается на корректную интеграцию с конкретным AI-инструментом.

GitHub Spec Kit

Spec Kit делает акцент на более полном spec-driven цикле: constitution, specify, plan, tasks, implement. Его философия более радикальна: спецификация — основной драйвер, код — выход из спецификации и плана. Это мощно, но может быть тяжелее по процессу.

Kiro

Kiro — это agentic IDE/CLI с встроенным spec-driven workflow. Он превращает prompt в requirements, design и tasks внутри собственной среды. Это удобно, если команда готова работать в Kiro, но менее универсально, чем OpenSpec, который рассчитан на разные агенты и редакторы.

Установка OpenSpec

Требования: Node.js 20.19.0+.

Установка через npm:

npm install -g @fission-ai/openspec@latest

Инициализация в проекте:

cd your-project
openspec init

Проверка:

openspec --version
openspec list
openspec validate --all

Для scripted setup:

openspec init --tools claude,cursor
openspec init --tools all
openspec init --tools none
openspec init --profile core

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

OpenSpec поддерживает установку skills и/или command files для большого списка инструментов, среди них:

• Claude Code;
• Cursor;
• Codex;
• GitHub Copilot;
• OpenCode;
• Windsurf;
• Gemini CLI;
• Kiro;
• Cline;
• RooCode;
• Kilo Code;
• Amazon Q;
• Qwen Code;
• Continue;
• Antigravity;
• и другие.

То есть OpenSpec не заставляет команду мигрировать в один редактор. Он дает общий формат работы, а команда выбирает агента.

Настройка openspec/config.yaml

Пример:

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

Что это дает:

• context подмешивается во все инструкции;
• rules применяются к конкретным артефактам;
• агент лучше держит проектные соглашения;
• меньше нужно повторять в каждом prompt.

Практический гайд: как внедрить SDD в существующий проект

Шаг 1. Установить OpenSpec

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

Выберите инструменты, которыми реально пользуется команда. Не обязательно ставить все.

Шаг 2. Добавить проектный контекст

Создайте или отредактируйте openspec/config.yaml:

schema: spec-driven
context: |
  Stack: Next.js, TypeScript, PostgreSQL
  Tests: Vitest for units, Playwright for e2e
  API: REST, JSON, zod validation
  Deployment: Railway
rules:
  specs:
    - Every changed behavior needs at least one scenario
  design:
    - Mention migrations and rollback when data changes
  tasks:
    - Include tests and verification commands

Шаг 3. Начать с небольшой задачи

Не начинайте с переписывания всей архитектуры. Возьмите маленькое изменение:

/opsx:propose add-empty-state-to-dashboard

Проверьте созданные файлы:

openspec/changes/add-empty-state-to-dashboard/proposal.md
openspec/changes/add-empty-state-to-dashboard/specs/.../spec.md
openspec/changes/add-empty-state-to-dashboard/design.md
openspec/changes/add-empty-state-to-dashboard/tasks.md

Шаг 4. Отредактировать артефакты до кода

Не соглашайтесь автоматически. Проверьте:

• верно ли понята задача;
• нет ли лишнего scope;
• есть ли acceptance scenarios;
• реалистичен ли design;
• tasks достаточно конкретны;
• есть ли проверка и тесты.

Шаг 5. Реализовать

/opsx:apply

Во время работы можно уточнять:

обнови design.md: мы не будем добавлять новую таблицу, используем существующую settings
продолжай apply

Шаг 6. Проверить

Если доступен расширенный workflow:

/opsx:verify

И вручную:

openspec validate <change-name>
npm test
npm run lint

Шаг 7. Синхронизировать и архивировать

/opsx:sync
/opsx:archive

После этого основная спецификация обновлена, а change хранится в архиве.

Как писать хорошие specs

Хорошая спецификация описывает поведение, а не реализацию.

Плохо:

### Requirement: Use Redis
The system SHALL use Redis for sessions.

Лучше:

### Requirement: Session persistence
The system SHALL preserve authenticated sessions across application restarts.

#### Scenario: Restart does not log out active user
- GIVEN a user has an active session
- WHEN the application process restarts
- THEN the user remains authenticated
- AND the session expiration time is preserved

Redis может быть частью design, но requirement должен объяснять, чего хочет система.

Когда SDD особенно полезен

• AI coding в большом brownfield-проекте;
• несколько агентов или несколько разработчиков работают параллельно;
• требования часто уточняются;
• нужна трассировка от бизнес-решения до кода;
• важны тесты и acceptance criteria;
• есть риск, что агент «сделает красиво, но не то»;
• нужно возвращаться к задаче через несколько дней или в другой сессии.

Когда SDD может быть лишним

• одноразовый скрипт на 20 строк;
• эксперимент, который точно будет выброшен;
• чисто механическая правка без behavioral change;
• задача, где скорость важнее аудита и воспроизводимости.

Даже тогда можно использовать мини-версию: короткий proposal + tasks без полноценной спецификации.

Типичные ошибки

Ошибка 1. Генерировать specs и сразу кодить

OpenSpec полезен только если человек реально ревьюит артефакты. Иначе это просто лишние markdown-файлы.

Ошибка 2. Писать requirements как технические задачи

Requirement должен описывать поведение. Технические решения — в design.

Ошибка 3. Смешивать несколько изменений

add-dark-mode-and-refactor-auth — плохой change. Лучше два отдельных изменения.

Ошибка 4. Не архивировать изменения

Если changes копятся и не попадают в specs/, источник истины устаревает.

Ошибка 5. Не обновлять artifacts после открытия новых фактов

Если во время реализации выяснилось, что дизайн неправильный, надо обновить design/spec/tasks, а не просто «договориться в чате».

Мини-шаблон change для команды

# Proposal: <change-name>

## Intent
Why are we doing this?

## Scope
- What changes
- What is explicitly out of scope

## Requirements
- User-visible behavior
- Acceptance scenarios

## Design notes
- Architecture
- Data changes
- Risks
- Rollback

## Tasks
- [ ] Implementation
- [ ] Tests
- [ ] Docs if needed
- [ ] Verification command

Рекомендованный командный процесс

Для команды из 2–10 разработчиков:

1. Любая нетривиальная фича начинается с /opsx:propose.
2. PR должен включать openspec/changes/<change>/.
3. Reviewer сначала смотрит proposal/specs/design/tasks, потом diff.
4. Перед merge запускается /opsx:verify или ручной эквивалент.
5. После merge change архивируется, specs обновляются.
6. Раз в неделю команда чистит зависшие changes.

Вывод

Spec-Driven Development — это ответ на новую проблему AI-разработки: код стало легко генерировать, но намерение, требования и проверяемость не стали автоматически лучше. OpenSpec дает легкий, переносимый способ удерживать эти вещи в репозитории.

Главная ценность OpenSpec не в markdown-файлах сами по себе. Ценность в том, что агент начинает работать против явного контракта: proposal объясняет намерение, specs фиксируют поведение, design показывает технический путь, tasks задают порядок реализации, archive превращает изменение в историю системы.

Если использовать OpenSpec дисциплинированно, он превращает AI coding из потока импровизаций в управляемый инженерный процесс — без тяжелого waterfall и без привязки к одной IDE.

Источники и что было проверено

• OpenSpec GitHub:
• OpenSpec сайт:
• OpenSpec docs в репозитории: README.md, docs/getting-started.md, docs/concepts.md, docs/workflows.md, docs/opsx.md, docs/commands.md, docs/installation.md, docs/supported-tools.md.
• npm package metadata: @fission-ai/openspec@1.4.1.
• GitHub Spec Kit README и spec-driven.md:
• Kiro home/docs: https://kiro.dev/ и

Локальная проверка репозитория OpenSpec:

• клонирован Fission-AI/OpenSpec, commit 1b06fdd;
• файлов в git: 842;
• TypeScript-файлов: 272, примерно 67k строк;
• Markdown-файлов: 517, примерно 52k строк;
• npm run build успешно завершился;
• npm test успешно завершился: 89 test files passed, 1661 tests passed.