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

Обычно 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 — точно так же, как и для работы с кодом: вы сами выполняете коммиты, отправку (push), получение (pull) и ревью. Для спецификаций и изменений создаются ветки и пул-реквесты так же, как и для кода.

Когда нужно хранилищеCopy Anchor Link

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

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

  Copy Text

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

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

  Copy Text

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

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

Настройка хранилищаCopy Anchor Link

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

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

   Copy Text

   # run from anywhere; it asks what to create and where
   openspec store setup

   Будет задано три вопроса:

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

   Затем команда выведет отчёт о созданных ресурсах:

   Copy Text

   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), поэтому привяжите хранилище к этому репозиторию и отправьте изменения:

   Copy Text

   # connect the store to the empty repo on your git host
   cd ~/openspec/team-plans
   git remote add origin git@github.com:acme/team-plans.git
   
   # publish it
   git push -u origin main

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

   Copy Text

   # get the store onto your machine
   git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
   
   # tell OpenSpec where it lives
   openspec store register ~/openspec/team-plans

   Copy Text

   Store registered: team-plans
   Location: /Users/you/openspec/team-plans
   OpenSpec root: ready
   Registry: registered

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

4. Проверьте результат из любой директории:

   Copy Text

   # any OpenSpec command reaches the store by name
   openspec status --store team-plans

   Copy Text

   Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
   No active changes. Create one with: openspec new change <name> --store team-plans

Типы конфигурацийCopy Anchor Link

В OpenSpec предусмотрено три типа конфигурации. Далее на странице используются следующие обозначения:

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

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

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

web-app  (code repo)
└── openspec/
    ├── specs/
    └── changes/

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

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

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

team-plans  (store)
└── openspec/
    ├── specs/       the repo's specs live here
    └── changes/     its changes too
          ▲
          │ store: team-plans   (the connecting line)
web-app  (code repo)
└── openspec/
    └── config.yaml    nothing else

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

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

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

team-plans  (store)
└── openspec/          the shared specs and changes
          ▲
          │ only when you pass --store team-plans
web-app  (code repo)
└── openspec/          this repo's own
    ├── config.yaml
    ├── specs/
    └── changes/

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

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

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

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

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

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

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

Строка store: (проекты в режиме store-only)Copy Anchor Link

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

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

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

# inside web-app, connected
openspec status

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 остановится с ошибкой и выведет список зарегистрированных хранилищ.
• Зафиксируйте изменение в git: коллеги, клонировавшие ваш проект, тоже получат эту настройку. Им всё равно потребуется зарегистрировать хранилище на своей машине (шаг 3 в разделе «Настройка хранилища»), иначе OpenSpec выдаст ошибку с просьбой выполнить регистрацию.
• Рядом с реальными папками: если в вашем проекте также присутствуют папки specs/ или changes/, OpenSpec будет использовать их, а эту строку проигнорирует с предупреждением.

Установка интеграций в репозитории режима store-onlyCopy Anchor Link

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

# inside web-app, at the repository root
openspec init --tools claude

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

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

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

Параметр defaultStore на вашей машинеCopy Anchor Link

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

# use team-plans whenever nothing else names a store
openspec config set defaultStore team-plans

# undo it
openspec config unset defaultStore

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

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

Чтобы перевести репозиторий из локального режима (repo-local) в режим работы только с хранилищем (store-only):

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

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

Работа в хранилищеCopy Anchor Link

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

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

# inside web-app; the store: line routes this to team-plans
openspec new change add-login

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 проверит вашу конфигурацию без внесения изменений и выведет способ исправления для каждой найденной проблемы:

# check the current root and its stores
openspec doctor

Doctor

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

References
  (none declared)

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

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

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

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

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

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

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

<referenced_stores>
<!-- Read-only upstream context. Fetch what you need; cite what you use. -->
Store team-plans (/Users/you/openspec/team-plans):
  - payments: Rules for charging and refunding customers.
  Fetch: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

В ссылке также можно указать URL для клонирования хранилища — это пригодится на машинах, где оно ещё не развёрнуто:

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

Если URL объявлен, при отсутствии хранилища команда openspec doctor сформирует готовую для вставки в терминал команду исправления:

# output wrapped to fit
References
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: Referenced store 'design-system' is not registered on this machine.
    Fix: 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

Ограничения бета-версииCopy Anchor Link

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