Урок 15.1. Обзор OpenSpec и установка

Зачем это нужно

В уроке 2.10 OpenSpec уже появлялся как один из инструментов на карте SDD-рынка: lightweight-подход с delta specs и удобной моделью для brownfield. Этот модуль - систематический разбор OpenSpec по официальной документации: установка, концепции, команды, повседневные workflow, командная работа и внутреннее устройство.

Прежде чем погружаться в детали, нужно решить две практические задачи:

• понять, что именно OpenSpec дает разработчику и его AI-агенту, чем он отличается от соседних подходов и когда его стоит брать;
• корректно установить CLI-инструмент и проверить, что он работает.

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

Основная идея

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

Философия проекта формулируется пятью принципами:

→ гибкий, а не жесткий (fluid not rigid)
→ итеративный, а не waterfall
→ простой, а не сложный
→ создан для brownfield, а не только для greenfield
→ масштабируется от личных проектов до enterprise

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

Какую проблему решает OpenSpec

Типичная ситуация при работе с coding-агентом:

Вы: «Добавь темную тему»
AI:  пишет код, добавляет зависимости, меняет стили в десяти файлах
Вы:  обнаруживаете, что тема переключается, но не сохраняется,
     а палитра не совпадает с дизайн-системой

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

Вы:    /opsx:propose add-dark-mode
AI:    Created openspec/changes/add-dark-mode/
       ✓ proposal.md — зачем делаем и что меняется
       ✓ specs/       — требования и сценарии
       ✓ design.md    — технический подход
       ✓ tasks.md     — чек-лист реализации

Спецификации - это обычный Markdown с требованиями и конкретными сценариями, без специального синтаксиса:

## 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

Такие спецификации пишет агент; вы проверяете план до того, как написан хоть один файл кода. Подробно формат требований разобран в уроке 15.10.

Два интерфейса: терминал и чат агента

С первого взгляда важно разделить две половины OpenSpec:

Терминал                    Чат coding-агента
─────────────────────       ─────────────────────────────
openspec init               /opsx:explore
openspec validate           /opsx:propose <change>
openspec update             /opsx:apply
openspec config             /opsx:archive

Установка, инициализация и валидация выполняются в терминале. Вся работа над изменением - исследование, предложение, реализация, архивация - происходит в чате AI-ассистента через слэш-команды. Это разделение сбивает с толку почти каждого нового пользователя минимум один раз, поэтому оно разобрано отдельно в уроке 15.4.

Карта документации - и как она ложится на модуль

Официальная документация организована по сценариям использования. Модуль 15 следует ей, но перестраивает материал в учебном порядке:

Если читать документацию самостоятельно, авторы рекомендуют начинать с Getting Started и How Commands Work. Если читать модуль - он идет в том же порядке, но с адаптацией под русскоязычного студента.

Версия на тридцать секунд

Полный жизненный цикл изменения в OpenSpec:

1. Установка     npm install -g @fission-ai/openspec@latest
2. Инициализация cd your-project && openspec init
3. Исследование  (в чате агента)  /opsx:explore            ← необязательно, но полезно
4. Предложение   (в чате агента)  /opsx:propose add-dark-mode
5. Реализация    (в чате агента)  /opsx:apply
6. Архивация     (в чате агента)  /opsx:archive

Шаги 1-2 происходят в терминале, остальное - в чате AI-ассистента. Это разделение - единственное, что стоит запомнить сразу. Пошаговый разбор первого изменения - в уроке 15.2.

Требования

Для работы OpenSpec нужен Node.js 20.19.0 или новее. Проверить версию:

node --version

Если Node отсутствует или старее, сначала обновите его. Homebrew на macOS и Linux устанавливает Node как зависимость автоматически.

Установка

Homebrew (macOS, Linux)

brew install openspec

npm

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

pnpm

pnpm add -g @fission-ai/openspec@latest

yarn

yarn global add @fission-ai/openspec@latest

Yarn 2 и новее (Berry) убрали команду global. На этих версиях ставьте OpenSpec через npm, pnpm или bun: глобальному CLI не обязательно разделять пакетный менеджер вашего проекта.

deno

Deno иногда не разбирает тег @latest; в этом случае укажите версию явно, например @^1.3.1:

deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@latest

Если подкоманды запускают внешние программы (например, config edit, feedback или workspace open), может понадобиться scoped-флаг --allow-run=<program>.

bun

Bun умеет ставить глобальные пакеты, но сам OpenSpec исполняется на Node.js: Node.js 20.19.0+ должен быть доступен в PATH.

bun add -g @fission-ai/openspec@latest

Nix

Запустить без установки:

nix run github:Fission-AI/OpenSpec -- init

Или установить в профиль:

nix profile install github:Fission-AI/OpenSpec

Или добавить в окружение разработки в flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    openspec.url = "github:Fission-AI/OpenSpec";
  };

  outputs = { nixpkgs, openspec, ... }: {
    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
      buildInputs = [ openspec.packages.x86_64-linux.default ];
    };
  };
}

Установка через AI-ассистента

Если не хочется делать установку вручную, документация предлагает готовый промпт: вставьте его в любой ассистент, умеющий выполнять shell-команды - Claude Code, Codex, Cursor, Gemini CLI, Copilot и остальные поддерживаемые инструменты. Промпт устанавливает CLI, инициализирует проект и отчитывается о том, что реально произошло.

Ручные шаги из разделов выше остаются источником истины - промпт просто выполняет их за вас. Перевод промпта с сохранением команд:

Установи OpenSpec в этот проект и настрой его для меня. Выполняй шаги
по порядку и останавливайся там, где шаг велит остановиться.

1. RUNTIME. Выполни `node --version`. OpenSpec требует Node.js 20.19.0
   или новее. Если Node отсутствует или старый - скажи об этом и
   остановись: не устанавливай Node, не переключай версии, не
   переконфигурируй мой менеджер версий.

2. INSTALL. Используй пакетный менеджер, который уже есть в моем PATH,
   предпочтение npm:
     npm install -g @fission-ai/openspec@latest
     pnpm add -g @fission-ai/openspec@latest
     bun add -g @fission-ai/openspec@latest
     yarn global add @fission-ai/openspec@latest   (только Yarn 1.x)
   Не выбирай менеджер по lockfile проекта: глобальная установка не
   связана с зависимостями репозитория. Если нет ни одного из четырех -
   остановись и скажи мне, не импровизируй. (Если у меня Nix, укажи на
   раздел Nix в документации по установке OpenSpec.)
   Покажи мне точную команду и дай подтвердить перед запуском: это
   установка софта вне проекта, и я могу хотеть другой менеджер.
   Остановись и спроси снова, если установке нужны sudo или права
   администратора, она падает с ошибкой прав или сообщает, что
   глобальный bin-каталог отсутствует. Никогда не редактируй мои
   shell-файлы (.bashrc, .zshrc, .profile, fish, PowerShell profile) и
   не запускай команды настройки, которые правят их за меня, - покажи
   изменение, пусть его сделаю я.

3. PATH. Выполни `openspec --version`. Если команда не найдена, возможно,
   она просто недоступна в текущем shell: скажи, куда пакетный менеджер
   ее установил и как добавить каталог в PATH для моего shell и ОС, затем
   остановись до моего подтверждения. Если напечатана версия старее
   установленной - более ранняя копия перекрывает ее в PATH: сообщи обе
   версии вместо продолжения. Если я использую менеджер версий - скажи
   об этом, вместо того чтобы обходить его правкой PATH: с nvm или fnm
   CLI привязан к версии Node, активной при установке; с asdf или volta
   может потребоваться перегенерация shim.

4. INITIALIZE. Спроси, какими AI-инструментами я пользуюсь, и сопоставь
   каждый с id из `openspec init --help` (Copilot - `github-copilot`,
   Zoo Code - `roocode`). `--tools` принимает список через запятую -
   назови все. `openspec init --tools <ids>` автоматически удаляет
   остатки старых версий OpenSpec, не спрашивая, - включая файлы
   промптов `opsx-*.md` в домашнем каталоге (Codex держит их в
   ~/.codex/prompts). Перед запуском поищи их: каталоги
   `.../commands/openspec/`, маркерные блоки OpenSpec в CLAUDE.md или
   AGENTS.md, промпты `opsx-*.md` в домашнем каталоге. Перечисли
   найденное и дождись моего согласия; если ничего нет - скажи и
   продолжай без вопросов. Существующий каталог `openspec/` - не
   проблема: init его обновит и не тронет мои specs и changes.
   Подтверди, что мы в правильном каталоге: init создает `openspec/`
   там, где запущен, включая вложенный пакет монорепозитория.
   Затем выполни: openspec init --tools <ids>

5. REPORT. Не предполагай, что должно существовать, - расскажи, что
   реально напечатал init: сколько skills и/или команд создано и где,
   строку конфигурационного файла, пометку "Setup required" и что
   перезапустить или перезагрузить. Некоторые инструменты работают
   только через skills и корректно не создают ни одного файла команд:
   отсутствие команд само по себе не ошибка. Если init сообщил, что
   ничего не сгенерировано, передай предложенное им исправление вместо
   повторной попытки. В конце расскажи, как вызывать OpenSpec в моем
   инструменте, и возьми точное написание из созданных файлов, а не из
   строки summary: пунктуация различается по инструментам (/opsx:propose
   в одних, /opsx-propose в других, @opsx-propose в Amazon Q), а
   инструменты с skills вместо команд вызываются по имени skill
   (/openspec-propose, $openspec-propose в Codex или
   /skill:openspec-propose в Kimi Code).

Промпт не содержит ничего vendor-специфичного: это обычные инструкции плюс те же команды из этой страницы. Он работает на macOS, Linux и Windows и намеренно останавливается вместо импровизации, когда шаг требует вашего разрешения. Ассистент должен уметь выполнять shell-команды - несколько IDE-интеграций этого не умеют.

Инженерный вывод курса: сам промпт - образец безопасного делегирования привилегированных действий агенту. Ассистенту явно запрещено редактировать shell-файлы, устанавливать Node и импровизировать менеджеры пакетов; в точках риска он обязан остановиться и спросить. Этот же принцип стоит переносить в собственные setup-промпты.

Проверка установки

openspec --version

Команда должна напечатать установленную версию CLI. Если команда не найдена - глобальный bin-каталог пакетного менеджера не попал в PATH (типовые причины и решения - в уроке 15.15).

Обновление

Обновите пакет, затем обновите сгенерированные файлы в каждом проекте:

npm install -g @fission-ai/openspec@latest   # или эквивалент pnpm/yarn/bun
openspec update                              # внутри каждого проекта

openspec update перегенерирует файлы skills и команд для настроенных инструментов, чтобы слэш-команды соответствовали установленной версии CLI. Команда также проверяет, не опубликована ли более новая версия, и предлагает обновиться: именно обновление открывает доступ к новым workflow.

Удаление

Команды openspec uninstall нет: OpenSpec - это глобальный пакет плюс файлы в проекте. Удаление - три ручных шага, ни один не трогает исходный код.

1. Удалить глобальный пакет:

npm uninstall -g @fission-ai/openspec   # или: pnpm rm -g / yarn global remove / bun rm -g

2. Удалить OpenSpec из проекта (необязательно). Если specs и changes больше не нужны, удалите каталог openspec/:

rm -rf openspec/

Подумайте перед этим: openspec/specs/ и openspec/changes/archive/ - запись о том, как система устроена и почему она менялась. Если история может пригодиться, оставьте каталог (или храните его в git) даже после удаления CLI.

3. Удалить сгенерированные файлы AI-инструментов (необязательно). OpenSpec записывает файлы skills и команд в каталоги инструментов: .claude/skills/openspec-*/, .cursor/commands/opsx-* и так далее. Удалите skills openspec-* и команды opsx-* для настроенных инструментов; точные пути перечислены в уроке 15.13. Маркерные блоки OpenSpec в CLAUDE.md или AGENTS.md удалите вручную - остальное содержимое этих файлов ваше.

Что стоит знать сразу

Несколько фактов из README, которые пригодятся до глубокого разбора:

• Модели. OpenSpec лучше всего работает с моделями с высоким уровнем рассуждения; документация рекомендует Codex 5.5 и Opus 4.7 и для планирования, и для реализации.
• Гигиена контекста. OpenSpec выигрывает от чистого контекстного окна: очищайте контекст перед началом реализации и поддерживайте гигиену контекста в течение сессии.
• Сравнение с альтернативами. Против GitHub Spec Kit OpenSpec легче и свободнее в итерациях; против Kiro - не привязывает к конкретной IDE и моделям; против работы без спецификаций - добавляет предсказуемость без церемоний. Подробное сравнение - в уроке 2.10.
• Stores (beta). Для команд, где фича расползается на несколько репозиториев, OpenSpec предлагает Stores - планирование в отдельном репозитории. Разбор - в уроке 15.12.
• Телеметрия. CLI собирает анонимную статистику использования: только имена команд и версию, без аргументов, путей и PII; в CI отключается автоматически. Опция отключения: openspec config set telemetry.enabled false или переменная OPENSPEC_TELEMETRY=0.

Практика

1. Проверьте версию Node.js: node --version. Если версия ниже 20.19.0 - обновите.
2. Установите OpenSpec удобным способом (npm install -g @fission-ai/openspec@latest или brew install openspec).
3. Выполните openspec --version и убедитесь, что команда доступна в PATH.
4. В любом тестовом проекте выполните openspec init и посмотрите, какие каталоги и файлы появились. Пока не углубляйтесь в них - их назначение разобрано в уроке 15.2.

Краткое резюме

• OpenSpec добавляет легкий слой спецификаций поверх репозитория: агент готовит proposal, delta specs, design и tasks, вы проверяете план до написания кода.
• Два интерфейса: CLI (openspec init, validate, update) в терминале и слэш-команды (/opsx:explore, /opsx:propose, /opsx:apply, /opsx:archive) в чате AI-агента.
• Требование - Node.js 20.19.0+; установка через Homebrew, npm, pnpm, yarn, deno, bun или Nix.
• Готовый setup-промпт делегирует установку AI-ассистенту с явными запретами и точками остановки.
• openspec update внутри проекта синхронизирует сгенерированные файлы команд с версией CLI; удаление - ручное: глобальный пакет, каталог openspec/, файлы инструментов.

Вопросы для самопроверки

1. Почему требования, живущие только в истории чата, приводят к непредсказуемым результатам агента?
2. Какие шаги жизненного цикла изменения выполняются в терминале, а какие - в чате AI-агента?
3. Чем установка через Yarn 1.x отличается от Yarn 2+ и что делать владельцам Berry?
4. Зачем после обновления глобального пакета запускать openspec update в каждом проекте?
5. Почему setup-промпт запрещает ассистенту редактировать shell-файлы и устанавливать Node, и в каких точках он обязан останавливаться?
6. Что теряет проект при удалении каталога openspec/, даже если сам CLI уже не нужен?

Что дальше

Урок 15.2 проводит первое изменение от идеи до архивации: openspec init, полный цикл /opsx:explore → /opsx:propose → /opsx:apply → /opsx:archive на минимальном примере.

Источники

• https://github.com/Fission-AI/OpenSpec/blob/main/README.md
• https://github.com/Fission-AI/OpenSpec/blob/main/docs/README.md
• https://github.com/Fission-AI/OpenSpec/blob/main/docs/installation.md