Быстрый старт в OpenSpec: установка, рабочий процесс и распространённые ошибки

Спецификации как дельты, а не 40-страничный PRD.

Содержимое страницы

OpenSpec — это бесплатный CLI-инструмент с открытым исходным кодом от Fission AI, который позволяет вам и вашему ИИ-агенту по кодированию согласовать изменения в простом формате Markdown до написания любого кода, без ритуалов, связанных с этапами, характерных для более тяжелых фреймворков, управляемых спецификациями.

Большинство команд, пытающихся внедрить подход разработки по спецификации (Spec-Driven Development), застревают на одном и том же компромиссе: достаточно процессов, чтобы агент не начал угадывать, но не так много шаблонов, чтобы исправление бага в 50 строк требовало составления предложения. Ответ OpenSpec состоит в том, чтобы полностью проигнорировать инстинкт «сначала задокументировать всю систему» и писать спецификации только для того, на что изменение действительно влияет, используя дельты ADDED, MODIFIED и REMOVED вместо полного переписывания каждый раз.

OpenSpec spec-driven development workflow with an AI coding assistant

Именно этот дизайн, ориентированный на изменения, объясняет, почему OpenSpec часто упоминается рядом с GitHub Spec Kit, Kiro и Superpowers в сравнении категорий инструментов SDD — это обычно выбор, когда команда хочет ревьюабельные спецификации без 800-страничной фазы планирования. Это руководство охватывает установку CLI, рабочий процесс из четырех команд, который вы используете ежедневно, как выглядит изменение на диске, а также вопросы и жалобы, которые чаще всего возникают на Reddit и в трекере задач самого OpenSpec.

Что такое OpenSpec?

OpenSpec описывает свою философию в четырех строках: текучая, а не жесткая; итеративная, а не водопадная; простая, а не сложная; созданная для brownfield (существующих кодовых баз), а не только для greenfield (новых проектов). На практике это означает, что нет зафиксированных этапов — вы можете редактировать предложение, спецификацию или список задач в любой точке изменения, а не заставлять себя проходить этапы «спецификация, затем планирование, затем реализация» в строгом порядке, как описано в нейтральном к инструментам рабочем процессе SDD.

Изменение в OpenSpec порождает до четырех артефактов в Markdown в своей собственной папке:

Артефакт Назначение
proposal.md Зачем существует изменение и что оно меняет, простым языком
specs/ Дельта-требования и сценарии — тестированная спецификация для этого изменения
design.md Необязательный технический подход для изменений, которым он нужен
tasks.md Чек-лист реализации, по которому работает агент

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

Установка OpenSpec

OpenSpec — это CLI на Node.js, поэтому на вашем компьютере нужна Node 20.19.0 или новее.

node --version

Установите CLI глобально через npm, затем проверьте, что он появился в вашем PATH:

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

Также поддерживаются установки через Deno, pnpm, yarn, bun и nix, если это лучше подходит вашей настройке, чем npm. После установки инициализируйте его внутри проекта:

cd your-project
openspec init

openspec init спрашивает, какими ИИ-инструментами вы пользуетесь, и пишет соответствующие файлы навыков и команд — OpenSpec поддерживает более 30 ассистентов, включая Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro и OpenCode. Для CI или скриптов настройки пропустите выборщик полностью:

openspec init --tools claude,cursor   # настроить конкретные инструменты
openspec init --tools all             # все поддерживаемые инструменты
openspec init --tools none            # только структура openspec/, без файлов инструментов

После этого перезапустите свою IDE, чтобы она подхватила новые написанные навыки и команды. Если вы хотели бы, чтобы ваш ассистент выполнил всю установку за вас, OpenSpec поставляется с промптом настройки, который можно вставить в Claude Code или другого агента, который выполнит установку, запустит openspec init и сообщит, что было настроено.

Основной рабочий процесс: Explore, Propose, Apply, Archive

Вот та вещь, которая сбивает с толку почти всех в первый день: команды openspec запускаются в вашем терминале, но команды /opsx: запускаются в чат-окне вашего ИИ-ассистента. Нет отдельного «интерактивного режима», в который нужно войти — ввод slash-команды в чате и есть способ начать.

flowchart LR A["/opsx:explore (optional)"] --> B["/opsx:propose change-name"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specs merged| E["openspec/specs/"]
  • /opsx:explore — это партнер для мышления без рисков. Он читает релевантную часть вашей кодовой базы, раскладывает варианты и формирует план до того, как что-либо будет записано на диск — стоит выработать эту привычку именно потому, что она останавливает ретивого агента от уверенного построения неправильной вещи.
  • /opsx:propose <name> создает openspec/changes/<name>/ и чертит предложение, дельта-спецификации, необязательный дизайн и список задач за один шаг. Вы ревьюите план здесь, до начала реализации.
  • /opsx:apply работает по списку задач, отмечая пункты по мере продвижения. Поскольку прогресс находится в файлах, а не только в истории чата, вы можете очистить окно контекста или начать новую сессию и продолжить ровно там, где остановился /opsx:apply.
  • /opsx:archive архивирует завершённое изменение в openspec/changes/archive/YYYY-MM-DD-<name>/ и сливает его дельта-спецификации в каноническое дерево openspec/specs/.

Профиль по умолчанию core устанавливает ровно эти четыре команды, плюс update и sync. Расширенный профиль добавляет new, continue, ff, verify, bulk-archive и onboard для команд, которые хотят создавать артефакты по одному, а не все сразу — переключитесь на него с помощью openspec config profile, затем выполните openspec update.

Каждый инструмент по-разному написывает одну и ту же команду в зависимости от того, как он загружает пользовательские инструкции: /opsx:propose в Claude Code, /opsx-propose в Cursor и GitHub Copilot, @opsx-propose в Amazon Q или $openspec-propose в Codex. openspec init выводит точную форму для выбранных вами инструментов, поэтому самое быстрое исправление проблемы «при вводе команды ничего не произошло» — это обычно перечитать выведенный подсказку, а не гадать.

Как изменение выглядит на диске

Папка изменения под openspec/changes/add-dark-mode/ обычно содержит предложение, дельта-спецификацию и список задач, подобные этому:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Формат дельт ADDED/MODIFIED/REMOVED — это механизм, который позволяет OpenSpec избегать переписывания всего файла спецификации для изменения одного поля. Именно поэтому OpenSpec явно ориентирован на brownfield (существующие проекты), а не на greenfield (новые): вы никогда не документируете все ваше приложение до получения ценности, вы просто документируете срез, на который влияет каждое реальное изменение, и openspec/specs/ заполняется естественно в течение месяцев обычной работы.

Полезные CLI-команды для проверки этого состояния, не покидая терминала:

openspec list                 # активные изменения
openspec show add-dark-mode   # просмотр артефактов изменения
openspec validate --all       # проверка форматирования спецификаций по всему проекту
openspec view                 # интерактивная панель управления

Коммитьте всю папку openspec/ в git. Активные изменения и архив предназначены для того, чтобы стать устойчивой, версионируемой записью того, что делает ваша система и почему она изменилась, — не черновиком, который вы удаляете после слияния.

Внедрение OpenSpec на существующей кодовой базе

Самое распространенное беспокойство от команд, оценивающих OpenSpec на реальном проекте, — это какая-то версия вопроса: «моему приложению 80 000 строк, мне нужно сначала описать все это спецификацией?» Нет. Собственное руководство OpenSpec по этому вопросу предельно ясно: выберите что-то маленькое и реальное, что вы и так собирались строить на этой неделе, запустите /opsx:explore на области, которую вы собираетесь трогать, чтобы агент сначала маппил, как вещи на самом деле работают, затем /opsx:propose изменение, ограниченное только этим срезом.

Если у вас уже есть PRD, документы SRS или дизайн-доки, лежащие в Notion или Confluence, относитесь к ним как к исходному материалу для исследования, а не к чему-то, что нужно массово конвертировать в спецификации. Вставьте релевантный раздел в сессию /opsx:explore и позвольте агенту сформировать сфокусированную дельту из него; одноразовая механическая конвертация 40-страничного PRD, как правило, порождает спецификацию, которой никто не будет доверять через шесть месяцев. Для команд, которые хотят руководящий, нарративный первый прогон, а не прыжок сразу в реальное изменение, расширенная команда /opsx:onboard сканирует вашу кодовую базу на предмет небольшого, безопасного улучшения и проходит по полному циклу на нем.

Частые вопросы и проблемы

Это проблемы, которые постоянно возникают в Discord OpenSpec, issue-трекерах GitHub и на Reddit в сабредитах вроде r/cursor, r/RooCode и r/opencodeCLI.

«Я ввел slash-команду, и ничего не произошло». Почти всегда одно из следующего: вы ввели ее в терминале вместо чата ассистента, ваша IDE не перезапускалась с тех пор, как был запущен openspec init, или версия CLI настолько стара, что openspec update сообщает, что все актуально, не записывая более новые файлы рабочего процесса. Запустите openspec update, перезапустите IDE и убедитесь, что папки навыков существуют (.claude/skills/openspec-* для Claude Code или эквивалент для вашего инструмента из списка поддерживаемых).

«ИИ генерирует гораздо больше спецификации, чем мне нужно». Это самая цитируемая жалоба в длинных обзорах: агент может превратить фичу на 30 минут в спецификацию на 800 строк. OpenSpec ограничивает поле context:,注入емое в каждый запрос, 50 КБ специально, чтобы принудить дисциплину, но сами дельта-спецификации не имеют жесткого лимита, поэтому сокращение сгенерированных спецификаций до того, что действительно является несущей конструкцией, — это привычка, которую вам нужно поддерживать самостоятельно, а не то, что инструмент принудительно обеспечивает за вас.

«Два изменения задели одно и то же требование, и одно молча выбросило сценарий другого». Это реальный, задокументированный крайний случай: архивация применяет дельту MODIFIED как замену всего блока с ключом по имени требования, поэтому, если два изменения в процессе оба модифицируют одно и то же требование, архивация второго когда-то переписывала сценарии первого без предупреждения. Текущие версии добавляют проверку дрейфа, которая прерывает архивацию и говорит вам сначала обновить спецификацию изменения — но всё еще стоит знать, что режим сбоя существует, если вы запускаете несколько изменений в одной области параллельно.

«Какую ИИ-модель мне на самом деле стоит использовать с ним?». Собственные документация OpenSpec рекомендуют модели с высоким уровнем рассуждений как для планирования, так и для реализации — модели класса Opus и Codex упоминаются специально — и очистку окна контекста перед реализацией, поскольку чистый контекст порождает измеримо лучшие результаты, чем долгая, накопленная сессия.

«Чем это отличается от Spec Kit, Kiro, Superpowers или BMAD?». Это самый частый вопрос на Reddit, и честный ответ — «вес процесса». Собственный README OpenSpec формулирует сравнение прямо: Spec Kit тщательный, но тяжелее, с большим количеством Markdown и жесткими шлюзами фаз; Kiro мощный, но запирает вас в IDE AWS и моделях Claude; OpenSpec обменивает часть этой начальной структуры на возможность свободно итерировать и работать с тем ассистентом, который у вас уже открыт. Для полного разбора против Spec Kit, Kiro, навыков Claude Code, BMAD-METHOD и Superpowers, см. выделенное сравнение инструментов SDD.

«ИИ действительно следует спецификации, которую только что написал?». Не всегда, и это задокументированная проблема в целом для инструментов SDD, не уникальная для OpenSpec — большое окно контекста не означает, что агент обращает одинаковое внимание на каждую его часть. Команда /opsx:verify существует специально, чтобы ловить сгенерированный код, который противоречит его собственной спецификации, и ее стоит запускать на любом нетривиальном коде, а не слепо доверять реализации.

«Нужно ли мне это для исправления в одну строку?». Нет. Собственный FAQ OpenSpec говорит об этом: используйте там, где согласие важно, что является большинством нетривиальной, многофайловой работы, и пропускайте для исправления опечатки или одноразового прототипа, который вы удалите через неделю.

Когда OpenSpec подходит, а когда нет

Хорошее соответствие:

  • Brownfield кодовые базы, где вы хотите ревьюабельные спецификации без документирования всей системы заранее.
  • Соло-разработчики и небольшие команды, которые хотят более легкий церемониал, чем Spec Kit, но все же получают письменный план перед кодом.
  • Работа, охватывающая несколько файлов, изменение схемы или что-либо, для чего джуниор-инженер разумно попросил бы короткий дизайн-док.
  • Команды, ужеcommitted к ревью планов в pull requests — дельта-спецификации диффуются чисто, поскольку они описывают только то, что изменилось.

Более слабое соответствие:

  • Одиночные баг-фиксы и одноразовые прототипы, где шаг ревью предложения стоит больше, чем приносит.
  • Команды, которым нужна более тяжелая, более предписывающая структура Spec Kit или опыт, нативный для AWS и интегрированный с IDE, как Kiro — см. рамку принятия решений в сравнении инструментов, чтобы понять, где выигрывает каждый инструмент.
  • Межрепозиторные фичи сегодня, если вы не готовы попробовать бета-фичу stores в OpenSpec, которая переносит планирование в собственное общий репозиторий, чтобы несколько кодовых баз и агентов могли читать один и тот же план.
  • Все, кто еще решает, заслуживает ли данная фича спецификации вообще — сначала прочитайте Разработка по спецификации vs Vibe Coding, поскольку OpenSpec помогает только после того, как вы уже решили, что структура стоит накладных расходов.

Заключение

Ставка OpenSpec состоит в том, что большая часть боли Spec-Driven Development исходит от церемониала, а не от самой идеи согласования плана перед существованием кода. Дельты вместо полного переписывания, отсутствие зафиксированных фаз и brownfield-first рабочий процесс делают его заметно легче для внедрения на кодовой базе, которую вы не создавали с нуля. Компромиссы тоже реальны — разрастание спецификаций — настоящий риск без дисциплины, обработка конфликтов вокруг одновременных изменений одного требования все еще созревает, и экосистема моложе, чем собственный инструментарий GitHub. Установите его на один реальный проект, прогоните небольшое изменение через explore-propose-apply-archive от начала до конца и решите тогда, оправдывает ли более легкий церемониал свои затраты на вашей реальной рабочей нагрузке.

Полезные ссылки

Подписаться

Получайте новые материалы про системы, инфраструктуру и AI engineering.