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

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

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

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

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

Рабочий процесс разработки на основе спецификаций в OpenSpec с ИИ-ассистентом по коду

Именно этот дизайн, ориентированный на конкретные изменения, объясняет, почему OpenSpec так часто упоминается рядом с GitHub Spec Kit, Kiro и Superpowers в сравнении категорий инструментов SDD — это обычно выбор тех команд, которые хотят иметь проверяемые спецификации без восьмисотстраничной фазы планирования. В этом руководстве рассматриваются установка 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, чтобы она подхватила newly созданные навыки и команды. Если вы предпочитаете, чтобы ассистент выполнил всю установку за вас, OpenSpec предоставляет готовый промпт для настройки, который можно вставить в Claude Code или другого агента. Он выполнит установку, запустит openspec init и сообщит, что было настроено.

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

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

flowchart LR A["/opsx:explore (необязательно)"] --> 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 и позвольте агенту сформировать из него сфокусированную дельту; механическая одноразовая конвертация сорокастраничного PRD обычно приводит к созданию спецификации, которой никто не будет доверять через шесть месяцев. Для команд, которые хотят иметь направляемый первый запуск с рассказом, вместо прыжка сразу в реальное изменение, расширенная команда /opsx:onboard сканирует кодовую базу в поисках небольших, безопасных улучшений и проходит через полный цикл на их примере.

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

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

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

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

«Как мне остановить агента от повторного предложения того, что мы уже отклонили?» У /opsx:archive нет специального статуса для отклоненного изменения, поэтому ничто не говорит будущему предложению, что идея уже была исследована и отвергнута. Смотрите Отклоненные предложения в OpenSpec: конвенция памяти решений для паттерна decision.md и правила конфигурации, которое заставляет агента искать в архиве перед новым предложением.

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

Хороший выбор:

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

Менее подходящий выбор:

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

Заключение

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

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

Подписаться

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