OpenSpec

Сховища (beta) ​

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

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 так само, як ділитеся кодом: комітите, пушите, пулите та переглядаєте його самостійно. Специфікації та зміни отримують гілки та pull requests так само, як і код.

Коли це потрібно ​

Дві поширені причини використовувати сховище:

  • Фронтенд і бекенд в окремих репозиторіях: одна функція зачіпає обидва, і плану потрібен єдиний дім замість двох половин.

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

  • Один продукт, кілька клієнтських репозиторіїв: Android, iOS та web випускаються зі своїх репозиторіїв, але поділяють одну очікувану поведінку. Специфікація описує поведінку, а не реалізацію, тому одна специфікація обслуговує всі три.

            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 на вашій машині. Запасний варіант, коли нічого з переліченого вище не застосовується.

Якщо жоден із цих варіантів не застосовується, а у вас є зареєстровані сховища, команда завершиться помилкою та перелічить їх. Коли id одного зі сховищ збігається з назвою вашого репозиторію в його 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 із кореня репозиторію коду, щоб установити файли інтеграції з AI-інструментами, не повертаючи планування назад у цей репозиторій:

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.

Робота в сховищі ​

Робочі процеси не змінюються — ані для вас, ані для вашого агента. Propose, apply та archive виконуються так, як і завжди. Єдина відмінність — у тому, де створюються артефакти, і наведений вище розділ саме це й описує.

Створіть зміну зсередини репозиторію 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
  • Куди вона потрапила: у репозиторій сховища, а не поруч із вашим кодом.
  • Поширення: зміна існує лише у вашій локальній копії (checkout), доки ви не закомітите й не запушите репозиторій сховища. Учасники команди побачать її після 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 (beta).

Як читати specs з іншого store ​

Вашому репозиторії можна зберігати власну папку openspec/, а вашому агенту все ще дозволати читати specs іншого store. Означте цей store у розділі references: у openspec/config.yaml вашого репозиторію:

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

Ці references доступні лише для читання. Ваша робота залишається в вашому репозиторії, а саме references змінює лише те, що вашому агенту сказано.

Коли workflow створює артефакт, його інструкції отримують індекс specs іншого store, кожен із якою містить один рядок підсумку та точну команду для отримання:

xml
<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 клонування store, для машин, у яких ще немає цього store:

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

Після вказання URL openspec doctor перетворює відсутній store на вставну виправлення:

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

Обмеження бета-версії ​

  • Форма може змінюватися: назви команд, флагів та форматів файлів можуть змінюватися між релізами. Після оновлення перечитайте цю сторінку.
  • Синхронізація, за замовчуванням, не передбачена: OpenSpec ніколи не клонує, не витягує, не надсилає. Застарілий checkout показує застарілі specs, доки ви не викликаєте pull, а references читаються з того, що є на диску.
  • Один checkout на одну назву store: реєстрація другого каталогу під назву, яка вже зареєстрована, не вдалася, з підказкою спочатку виконати openspec store unregister.