--- title: "Spec-Driven Development: от хаотичного AI-кодинга к инженерному процессу" canonical: https://maxtokens.ai/ru/posts/openspec-spec-driven-development/ date: 2026-06-13 tags: [agents, infra] description: "Зачем нужны спецификации, как устроен OpenSpec, чем он отличается от Spec Kit и Kiro и как внедрить SDD в существующий проект." --- ## Короткая версия 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 ``` Жизненный цикл изменения в OpenSpec: идея → proposal, delta specs, design, tasks → implementation → sync → 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/ # источник истины: как система работает сейчас │ └── / │ └── spec.md ├── changes/ # предлагаемые изменения: одна папка на изменение │ └── / │ ├── proposal.md │ ├── design.md │ ├── tasks.md │ └── specs/ # delta specs: что меняется │ └── / │ └── 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`, если ещё не). Delta specs применяет к основному spec sync: ADDED дописывает, MODIFIED заменяет, REMOVED удаляет; archive затем переносит папку изменения ### `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 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: ## 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//`. 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:](https://github.com/Fission-AI/OpenSpec) - [OpenSpec сайт:](https://openspec.dev/) - 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`:](https://github.com/github/spec-kit) - [Kiro home/docs: https://kiro.dev/ и](https://aws.amazon.com/documentation-overview/kiro/) Локальная проверка репозитория 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.