OpenSpec

Хранилища (бета) ​

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

OpenSpec обычно находится внутри одного репозитория: папка openspec/ рядом с кодом, который он планирует. Хранилище перемещает эту папку в отдельный репозиторий, и несколько репозиториев с кодом могут использовать его совместно.

После однократной настройки на каждой машине команды, такие как status, new change и archive, могут работать в хранилище из любого каталога.

         team-plans  (a store: OpenSpec in its own repo)
         ├── .openspec-store/store.yaml   the store's name
         └── openspec/
             ├── specs/
             └── changes/
                   ▲
                   │ set up once on each machine,
                   │ shared by pushing and cloning like any repo
     ┌─────────────┼─────────────┐
     │             │             │
 web-app       api-server     mobile-app
(code repo)   (code repo)    (code repo)

Вы делитесь хранилищем через git так же, как делитесь кодом: commit, push, pull и проверяйте его самостоятельно. Спецификации и изменения получают ветки и pull-реквесты так же, как и код.

Когда это нужно ​

Две распространённые причины использовать хранилище:

  • Фронтенд и бэкенд в отдельных репозиториях: одна функция затрагивает и то, и другое, и плану нужно единое место вместо двух половин.

          shop-plans  (store)
      └── openspec/changes/add-discounts/    one plan for the feature
                ▲
      ┌─────────┴─────────┐
      │                   │
  storefront             api
(frontend repo)     (backend repo)

  • Один продукт, несколько клиентских репозиториев: Android, iOS и веб поставляются из собственных репозиториев, но разделяют одно ожидаемое поведение. Спецификация описывает поведение, а не реализацию, поэтому одна спецификация обслуживает все три.

            product-specs  (store)
        └── openspec/specs/checkout/spec.md    the expected behavior
                  ▲
    ┌─────────────┼─────────────┐
    │             │             │
android-app    ios-app       web-app
(code repo)   (code repo)   (code repo)

Может быть несколько хранилищ, хотя мы рекомендуем держать их количество низким.

Настройка хранилища ​

Один человек создаёт хранилище, затем все остальные к нему присоединяются.

  1. Создайте хранилище (один человек, один раз на команду). Запустите openspec store setup и ответьте на запросы:

    bash
    # запускается из любого места; спрашивает, что создать и где
openspec store setup

    Оно задаёт три вопроса:

    • Имя хранилища: team-plans
    • Где должно находиться это хранилище?: предзаполнено ~/openspec/<name>, нажмите Enter, чтобы принять, или введите другой путь
    • Создать это хранилище?: показывает, что оно собирается создать, ответьте Yes

    Затем оно сообщает, что создало:

    yaml
    Store ready: team-plans
Location: ~/openspec/team-plans
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-plans
Share this store by committing and pushing it like any Git repo.

  2. Отправьте его на ваш git-хостинг. Сначала создайте пустой репозиторий team-plans на вашем хостинге. Настройка не добавляет git remote, поэтому подключите хранилище к этому репозиторию, а затем запушьте:

    bash
    # подключите хранилище к пустому репозиторию на вашем git-хостинге
cd ~/openspec/team-plans
git remote add origin git@github.com:acme/team-plans.git

# опубликуйте его
git push -u origin main

  3. Присоединитесь к хранилищу (каждый член команды, один раз на машину):

    bash
    # получите хранилище на свою машину
git clone git@github.com:acme/team-plans.git ~/openspec/team-plans

# сообщите OpenSpec, где оно находится
openspec store register ~/openspec/team-plans
    yaml
    Store registered: team-plans
Location: /Users/you/openspec/team-plans
OpenSpec root: ready
Registry: registered

    Регистрация сообщает вашей машине, где находится это хранилище. Имя хранилища уже закоммичено внутри него, в .openspec-store/store.yaml. Настройка зарегистрировала копию создателя, поэтому этот шаг нужен только клонированным копиям.

  4. Подтвердите, что всё работает, из любого каталога:

    bash
    # любая команда OpenSpec достигает хранилища по имени
openspec status --store team-plans
    yaml
    Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans

Типы настроек ​

У OpenSpec есть три типа настроек. Остальная часть этой страницы использует эти названия:

  • repo-local: OpenSpec внутри вашего репозитория, без хранилища. По умолчанию.
  • store-only: ваш репозиторий не хранит собственных спецификаций или изменений. Всё находится в хранилище.
  • store-optional: ваш проект имеет собственную папку openspec/ и также обращается к хранилищу, когда вы просите.

По умолчанию: OpenSpec внутри вашего репозитория (repo-local) ​

openspec init помещает папку openspec/ рядом с вашим кодом, и спецификации и изменения этого репозитория живут там. Хранилище не используется. Это настройка, которую описывает Настройка вашего проекта, и большинству проектов другая не нужна.

web-app  (репозиторий с кодом)
└── openspec/
    ├── specs/
    └── changes/

OpenSpec вне вашего репозитория, в хранилище (store-only) ​

Репозиторий не хранит собственных спецификаций или изменений. Всё, что он планирует, находится в хранилище, и одна строка в конфиге репозитория связывает их.

Обычно, когда одна команда создаёт все репозитории и планы в одном месте. Все примеры выше имеют такую форму.

team-plans  (хранилище)
└── openspec/
    ├── specs/       спецификации репозитория живут здесь
    └── changes/     его изменения тоже
          ▲
          │ store: team-plans   (связывающая строка)
web-app  (репозиторий с кодом)
└── openspec/
    └── config.yaml    больше ничего

OpenSpec в вашем репозитории и в хранилище (store-optional) ​

Репозиторий остаётся repo-local для собственной работы, пока хранилище содержит общие спецификации и изменения. Внутри репозитория OpenSpec использует папку openspec/ вашего проекта и обращается к хранилищу только при передаче --store.

Обычно, когда репозиторий использовал OpenSpec до появления хранилища, или когда в основном независимый репозиторий лишь изредка касается общей работы.

team-plans  (хранилище)
└── openspec/          общие спецификации и изменения
          ▲
          │ только при передаче --store team-plans
web-app  (репозиторий с кодом)
└── openspec/          собственные файлы этого репозитория
    ├── config.yaml
    ├── specs/
    └── changes/

Репозиторий может начать как repo-local и позже переместить свои спецификации и изменения в хранилище. Перемещение спецификаций и изменений репозитория в хранилище показывает, как это сделать.

Где создаются артефакты при использовании хранилищ ​

При использовании хранилища OpenSpec также должен решить, где создаются артефакты. Это зависит от вашей настройки:

  • store-only (ваш проект пишет только в хранилище): каждый артефакт создаётся в хранилище. Строка store: ниже фиксирует это.
  • store-optional (ваш проект имеет собственную папку openspec/ и также использует хранилище): артефакты создаются в вашем проекте, если только вы не укажете хранилище в запросе или не передадите --store для этого изменения. Затем ваш агент проносит этот флаг через остальной рабочий процесс.

OpenSpec записывает артефакты в одно из двух мест: в папку openspec/ вашего проекта или в папку хранилища. Он выбирает в следующем порядке, и первый подходящий вариант побеждает:

  1. --store <id> в команде. Всегда побеждает, из любого каталога.
  2. Папка openspec/ вашего проекта. Если в вашем проекте есть собственные папки specs/ или changes/, OpenSpec использует их.
  3. Строка store: в вашем проекте. Так store-only проект фиксирует своё хранилище.
  4. defaultStore на вашей машине. Запасной вариант, когда ни одно из вышеперечисленного не применимо.

Если ни одно из этих условий не применимо и у вас есть зарегистрированные хранилища, команда завершается ошибкой и перечисляет их. Когда идентификатор одного хранилища совпадает с именем вашего репозитория в его remote origin, ошибка называет это хранилище и строку store:, которая его выбирает. OpenSpec никогда не выбирает хранилище по имени самостоятельно, потому что репозитории в разных организациях могут иметь одинаковое имя.

Когда OpenSpec выбирает хранилище, он выводит Using OpenSpec root: ... перед выводом команды.

Строка store: (проекты store-only) ​

Добавьте одну строку в openspec/config.yaml вашего проекта:

yaml
# web-app/openspec/config.yaml
store: team-plans

Всё, что вы или ваш агент запускаете внутри вашего проекта, теперь использует хранилище, без необходимости вводить флаг:

bash
# внутри web-app, подключено
openspec status
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans
  • Без строки: выполните обычную команду в store-only проекте, и OpenSpec остановится с ошибкой, перечисляющей ваши зарегистрированные хранилища.
  • Закоммитьте её: коллеги, клонирующие ваш проект, тоже получат эту строку. Им всё равно нужно зарегистрировать хранилище на своей машине (шаг 3 из Настройки хранилища), иначе OpenSpec выдаст ошибку и попросит зарегистрировать его.
  • Рядом с реальными папками: если в вашем проекте также есть папки specs/ или changes/, OpenSpec использует их и игнорирует строку, с предупреждением.

Установка интеграций в store-only репозитории ​

Запустите init из корня репозитория с кодом, чтобы установить файлы интеграции с ИИ-инструментами, не возвращая планирование в этот репозиторий:

bash
# внутри web-app, в корне репозитория
openspec init --tools claude
  • Файлы интеграции: записываются в репозиторий с кодом.
  • openspec/config.yaml: сохраняется байт в байт, включая строку store:.
  • openspec/specs/ и openspec/changes/: не создаются в репозитории с кодом.

OpenSpec отказывается выполнять эту команду из подкаталога репозитория с кодом. Запускайте её из корня репозитория.

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

defaultStore на вашей машине ​

Установите его один раз, если каждый проект, в котором вы работаете, использует одно и то же хранилище. OpenSpec использует его как запасной вариант, когда не находит ни флага, ни локальной папки openspec/, ни строки store::

bash
# используйте team-plans, когда ничто другое не называет хранилище
openspec config set defaultStore team-plans

# отмените это
openspec config unset defaultStore

Команды, которые остаются локальными. init, update, templates, schemas и подкоманды openspec schema действуют только на текущий каталог и не принимают --store.

Перемещение спецификаций и изменений репозитория в хранилище ​

Чтобы перевести репозиторий из repo-local в store-only:

  1. Переместите всё из openspec/specs/ и openspec/changes/ репозитория в те же папки в хранилище.
  2. Удалите теперь пустые папки, чтобы папка openspec/ репозитория содержала только config.yaml.
  3. Добавьте строку store: в этот config.yaml.

openspec status внутри репозитория теперь начинается с Using OpenSpec root: team-plans.

Работа в хранилище ​

Рабочие процессы не меняются ни для вас, ни для вашего агента. Предложение, применение и архивирование работают как всегда. Единственное отличие — где создаются артефакты, и раздел выше это описывает.

Создайте изменение изнутри store-only репозитория, и оно окажется в хранилище:

bash
# внутри web-app; строка store: направляет это в team-plans
openspec new change add-login
yaml
Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
Created change 'add-login' at /Users/you/openspec/team-plans/openspec/changes/add-login/
Schema: spec-driven
Next: openspec status --change add-login --store team-plans
  • Куда оно попало: в репозиторий хранилища, а не рядом с вашим кодом.
  • Как поделиться: изменение существует только в вашем клоне, пока вы не закоммитите и не запуштите репозиторий хранилища. Коллеги увидят его после pull. То же самое касается каждого артефакта, который записывают рабочие процессы.
  • Пути в документации: везде, где документация показывает путь openspec/, в настройке с хранилищем эта папка принадлежит хранилищу.

Когда артефакты создаются там, где вы не ожидали, openspec doctor проверяет вашу настройку, ничего не меняя, и выводит исправление для каждой находки:

bash
# проверьте текущий корень и его хранилища
openspec doctor
yaml
Doctor

Root
  Location: /Users/you/openspec/team-plans
  OpenSpec root: ok
  Store: team-plans (metadata ok)

References
  (none declared)

openspec context перечисляет корень и хранилища, с которыми работает ваш текущий каталог, когда вам нужна та же картина без проверок.

Чтобы открыть хранилище и репозиторий в одном окне редактора, чтобы ваш агент мог читать оба, см. Worksets (бета).

Чтение спецификаций из другого хранилища ​

Ваш репозиторий может иметь собственную папку openspec/ и при этом позволить вашему агенту читать спецификации из другого хранилища. Объявите такое хранилище в секции references: в файле openspec/config.yaml репозитория:

yaml
# api-server/openspec/config.yaml
references:
  - team-plans

Ссылки являются доступными только для чтения. Ваша работа остаётся в вашем репозитории, а ссылка лишь изменяет то, что сообщается вашему агенту.

Когда рабочий процесс создаёт артефакт, его инструкции получают индекс спецификаций из указанного хранилища, каждая с однострочным описанием и точной командой для их получения:

xml
<referenced_stores>
<!-- Контекст из внешнего хранилища только для чтения. Получайте то, что нужно; указывайте то, что используете. -->
Хранилище team-plans (/Users/you/openspec/team-plans):
  - payments: Правила для выставления счетов и возврата средств клиентам.
  Получить: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

Ссылка также может содержать URL клонирования хранилища для машин, где оно ещё не добавлено:

yaml
references:
  - team-plans
  - { id: design-system, remote: "git@github.com:acme/design-system.git" }

При наличии указанного URL команда openspec doctor превратит отсутствующее хранилище в готовое решение для исправления:

yaml
# вывод обрезан для подгонки
Ссылки
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: Указанное хранилище 'design-system' не зарегистрировано на этой машине.
    Исправление: git clone -- git@github.com:acme/design-system.git '/Users/you/openspec/design-system' &&
         openspec store register '/Users/you/openspec/design-system' --id design-system

Ограничения бета-версии ​

  • Форма может меняться: названия команд, флаги и форматы файлов могут измениться между релизами. Перечитайте эту страницу после обновления.
  • Без синхронизации, намеренно: OpenSpec никогда не клонирует, не подтягивает и не отправляет изменения. Устаревшая рабочая копия показывает устаревшие спецификации до тех пор, пока вы не выполните подтягивание, а ссылки читаются из того, что находится на диске.
  • Одна рабочая копия на имя хранилища: регистрация второй папки под уже зарегистрированным именем завершится ошибкой с подсказкой сначала выполнить openspec store unregister.