OpenSpec

Sklepy (beta) ​

Planuj zmiany obejmujące wiele repozytoriów: jeden sklep, wiele repozytoriów.

OpenSpec normalnie znajduje się w jednym repozytorium: w folderze openspec/ obok kodu, który planuje. Sklep przenosi ten folder do własnego repozytorium, a kilka repozytoriów kodu może z niego korzystać.

Po jednorazowym ustawieniu na każdym komputerze, polecenia takie jak status, new change, i archive mogą działać w sklepie z dowolnego katalogu.

         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)

You share a store with git, the same way you share code: commit, push, pull, and review it yourself. Specs and changes get branches and pull requests the same way code does.

Kiedy potrzebujesz jednego ​

Dwa najczęstsze powody, aby używać sklepu:

  • Frontend i backend w osobnych repozytoriach: jedna funkcja dotyka obu, a plan potrzebuje jednego domu zamiast dwóch części.
        shop-plans  (store)
        └── openspec/changes/add-discounts/    one plan for the feature
                  ▲
        ┌─────────┴─────────┐
        │                   │
    storefront             api
  (frontend repo)     (backend repo)
  • Jeden produkt, kilka repozytoriów klientów: Android, iOS i web są wydawane z własnych repozytoriów, ale dzielą jedną oczekiwaną zachowanie. Spec opisuje zachowanie, a nie implementację, więc jeden spec służy wszystkim trzem.
          product-specs  (store)
          └── openspec/specs/checkout/spec.md    the expected behavior
                    ▲
      ┌─────────────┼─────────────┐
      │             │             │
  android-app    ios-app       web-app
  (code repo)   (code repo)   (code repo)

Możesz mieć więcej niż jeden sklep, chociaż zalecamy utrzymywanie niskiej liczby.

Konfiguracja store ​

Jedna osoba tworzy store, następnie wszyscy inni dołączają do niego.

  1. Utwórz store (jedna osoba, raz na zespół). Uruchom openspec store setup i odpowiedz na pytania:

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

    Zadaje trzy pytania:

    • Nazwa store: team-plans
    • Gzie powinien znajdować się ten store?: wypełnione domyślnie ~/openspec/<name>, naciśnij Enter, aby zaakceptować, lub wpisz inną ścieżkę
    • Uworzyć ten store?: pokazuje, co zostanie utworzone, odpowiedz Yes

    Następnie zgłasza, co utworzył:

    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. Przypisz do hosta git. Najpierw utwórz pusty repozytorium team-plans na swoim hostie. Konfiguracja nie dodaje zdalnego repozytorium git, więc połącz store z tym repozytorium, a następnie push:

    bash
    # 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. Dołącz do store (każdy kolega z团队u, raz na maszynę):

    bash
    # 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
    yaml
    Store registered: team-plans
Location: /Users/you/openspec/team-plans
OpenSpec root: ready
Registry: registered

    Rejestracja mówi maszynie, gdzie znajduje się ten store. Nazwa store'a jest już zapisana w .openspec-store/store.yaml. Konfiguracja zarejestrowała kopię tworzącego, więc tylko sklonowane kopie potrzebują tego kroku.

  4. Potwierdź, że działa, z dowolnego katalogu:

    bash
    # any OpenSpec command reaches the store by name
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

Rodzaje konfiguracji ​

OpenSpec ma trzy konfiguracje. Reszta tej strony korzysta z tych nazw:

  • repo-local: OpenSpec w twoim repozytorium, bez store. Domyślny.
  • store-only: twoje repozytorium nie przechowuje własnych speców ani zmian. Wszystko znajduje się w store.
  • store-optional: Twój projekt ma własny folder openspec/ i również sięga po store, gdy tylko poprosisz.

Domyślny: OpenSpec w twoim repozytorium (repo-local) ​

openspec init tworzy folder openspec/ obok twojego kodu, a specy i zmiany tego repozytorium vivą tam. Nie jest używany żaden store. To jest konfiguracja, której uczy Ustaw projekt, i大多数 projektów nigdy nie potrzebuje innej.

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

OpenSpec poza twoim repozytorium, w store (store-only) ​

Repozytorium nie przechowuje własnych speców ani zmian. Wszystko, co planuje, znajduje się w store, a jedna linia w konfiguracji repozytorium łączy je.

Często, gdy jeden zespół bud wszystie repozytoria i plany w jednym miejscu. Przykład powyżej mają tę samą postać.

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 w twoim repozytorium i w store (store-optional) ​

Repozytorium pozostaje repo-local dla własnej pracy, podczas gdy store przechowuje współdzielone specy i zmiany. Wewnątrz repozytorium OpenSpec używ twojego projektu openspec/ folderu i sięga po store tylko, gdy podasz --store.

Często, gdy repozytorium używa OpenSpec przed istnieniem store, lub gdy niemal niezależne repozytorium tylko okazjonalnie dotyka shared work.

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/

Repozytorium może zacząć jako repo-local, a następnie przenieść swoje specy i zmiany do store. Przenieś specy i zmiany repozytorium do store pokazuje, jak.

Gdzie są tworzone artefakty przy użyciu store ​

Korzystając ze store, OpenSpec również musi zdecydować, gdzie zostaną utworzone artefakty. To zależy od twojej konfiguracji:

  • store-only (twój projekt tylko zapisuje w store): każdy artefakt jest tworzony w store. Linia store: poniżej rejestruje to.
  • store-optional (twój projekt ma własny folder openspec/ i również korzysta ze store): artefakty są tworzone w twoim projekcie, chyba że nazwiesz store w żądaniu lub podasz --store dla tej zmiany. Twój agent następnie przenosi flagę przez reszę przepływu pracy.

OpenSpec zapisuje artefakty w jednym z dwóch miejsc: folder openspec/ twojego projektu lub store. Wybiera w tej kolejności, i pierwsza opcja, która ma zastosowanie, wygrywa:

  1. --store <id> w poleceniu. Zawsze wygrywa, z dowolnego katalogu.
  2. Folder openspec/ twojego projektu. Jeśli projekt ma własny folder specs/ lub changes/, OpenSpec ich używa.
  3. Linia store: w twoim projekcie. Jak projekt store-only rejestruje swojego store.
  4. defaultStore na twojej maszynie. Awarii, gdy żadna z powyższych opcji nie ma zastosowania.

Jeśli żadna z tych opcji nie ma zastosowania i masz zarejestrowane store, polecenie się niepowodzeniem i je wymienia. Gdy id jednego store'a pasuje do nazwy twojego repozytorium w jego zdalnym origin, błąd podaje ten store i linię store: go wybierający. OpenSpec nigdy nie wybiera store'a po nazwie na własną rkę, ponieważ repozytoria w różnych organizacjach mogą mieć tę samą nazwę.

Gdy OpenSpec wybiera store, drukuje Using OpenSpec root: ... przed wynikiem polecenia.

Linia store: (projekty store-only) ​

Dodaj jedną linię do openspec/config.yaml twojego projektu:

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

Wszystko, co ty lub twój agent uruchomisz wewnątrz twojego projektu, teraz korzysta ze store, bez konieczności wpisywania flagi:

bash
# inside web-app, connected
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
  • Bez linii: uruchom zwyczajne polecenie w projekcie store-only i OpenSpec zatrzymuje się z błądem wymieniającym twoje zarejestrowane store.
  • Zcommituj to: koledzy, who clone twojego projektu, również otrzymają tę linię. Nadal potrzebują store'a zarejestrowanego na ich maszynie (krok 3 Konfiguracja store), w przeciwnym razie OpenSpec błęduje i mówi, aby go zarejestrowali.
  • Obok prawdziwych folderów: jeśli projekt również ma foldery specs/ lub changes/, OpenSpec ich używa i ignoruje linię, z ostrzeżeniem.

instaluj integracje w repozytorium store-only ​

Uruchom init z katalogu głównego repozytorium kodu, aby zainstalować pliki integracji narzędzi AI, bez przenoszenia planowania z powrotem do tego repozytorium:

bash
# inside web-app, at the repository root
openspec init --tools claude
  • Pliki integracji: zapisane w repozytorium kodu.
  • openspec/config.yaml: zachowany bajt po bajcie, włącznie z linią store:.
  • openspec/specs/ i openspec/changes/: nie są tworzone w repozytorium kodu.

OpenSpec odmuży tego polecenia z podkatalogu repozytorium kodu. Uruchamiaj go z katalogu głównego repozytorium.

OpenSpec również odmuży --language tutaj, ponieważ języki należy do konfiguracji zewnętrznego store. Uruchom init w katalogu głównego store lub edytuj tę konfigurację bezpośrednio.

defaultStore na twojej maszynie ​

Ustaw raz, jeśli każdy projekt, w którym pracujesz, używ tego samego store. OpenSpec powraca do niego, gdy nie znajdzie flagi, lokalnego folderu openspec/ ani linii store:

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

# undo it
openspec config unset defaultStore

Polecenia, które pozostają lokalne. init, update, templates, schemas oraz podpolecenia openspec schema działają tylko na bieżącym katalogu i nie przyjmują --store.

Przenieś specy i zmiany repozytorium do store ​

Aby zabrać repozytorium z repo-local do store-only:

  1. Przenieś wszystko z openspec/specs/ i openspec/changes/ repozytorium do tych samych folderów w store.
  2. Usuń teraz puste foldery, tak aby folder openspec/ repozytorium zawierał tylko config.yaml.
  3. Dodaj linię store: do tego config.yaml.

openspec status wewnątrz repozyterium teraz zaczyna od Using OpenSpec root: team-plans.

Praca w store ​

Przepływy pracy się nie zmieniają, dla ciebie lub twojego agenta. Propozycja, zastosowanie i archiwizacja działają tak jak zawsze. Jedyna różnica to, gdzie są tworzone artefakty, a sekcja powyżej opisuje to.

Utwórz zmianę wewnątrz repozyterium store-only i trafia do store:

bash
# inside web-app; the store: line routes this to 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
  • Gdzie trafiło: do repozyterium store, nie obok twojego kodu.
  • Udostępnianie: zmiana istnieje tylko w twoim checkout, dopóki nie zcommitujesz i nie pushujesz repozyterium store. Koledzy widzą ją po pociągnięciu. To samo dotyczy każdego artefaktu, który przepływy pracy zapisują.
  • Ścieżki w dokumentacji: gdziekolwiek dokumentacja pokazuje ścieżkę openspec/, w konfiguracji store ten folder należy do store.

Gdy artefakty są tworzone w miejscu, którego nie oczekiwałeś, openspec doctor sprawdza twoją konfigurację bez zmiany czegokolwiek i drukuje poprawkę dla każdego znalezienia:

bash
# check the current root and its stores
openspec doctor
yaml
Doctor

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

References
  (none declared)

openspec context wymienia root i store, z których działa bieżący katalog, gdy chcesz ten sam obraz bez sprawdzeń.

Aby otwierać store i repozyterium w jednym oknie edytora, tak aby agent mógł oboje przeczytać, zobacz Worksets (beta).

Odczyt specyfikacji z innego magazynu ​

Twoje repozytorium może zachować własny katalog openspec/, a jednocześnie pozwalać agentowi czytać specyfikacje z innego magazynu. Zadeklaruj ten magazyn w sekcji references: w pliku openspec/config.yaml repozytorium:

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

Odwołania są tylko do odczytu. Twoja praca pozostaje w Twoim repozytorium, a odwołanie zmienia jedynie to, co jest przekazywane agentowi.

Gdy workflow tworzy artefakt, jego instrukcje otrzymują indeks specyfikacji magazynu referencyjnego — każda z nich z jednolinijkowym podsumowaniem i dokładnym poleceniem pobrania:

xml
<referenced_stores>
<!-- Kontekst nadrzędny tylko do odczytu. Pobieraj to, czego potrzebujesz; cytuj to, czego używasz. -->
Magazyn team-plans (/Users/you/openspec/team-plans):
  - payments: Zasady pobierania opłat i zwracania środków klientom.
  Pobierz: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

Odwołanie może również zawierać adres URL do klonowania magazynu — dla maszyn, które jeszcze tego magazynu nie mają:

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

Gdy adres URL jest zadeklarowany, openspec doctor zamienia brakujący magazyn w gotową do wklejenia poprawkę:

yaml
# dane wyjściowe zawinięte, aby pasowały
Odwołania
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: Magazyn referencyjny 'design-system' nie jest zarejestrowany na tej maszynie.
    Poprawka: 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

Ograniczenia wersji beta ​

  • Struktura może się zmienić: nazwy poleceń, flagi i formaty plików mogą zmieniać się między wydaniami. Przeczytaj tę stronę ponownie po aktualizacji.
  • Brak synchronizacji — celowo: OpenSpec nigdy nie klonuje, nie wykonuje pull ani push. Nieaktualna kopia robocza pokazuje nieaktualne specyfikacje, dopóki nie wykonasz pull, a odwołania są czytane z tego, co znajduje się na dysku.
  • Jedna kopia robocza na nazwę magazynu: zarejestrowanie drugiego katalogu pod już zarejestrowaną nazwą kończy się niepowodzeniem, z podpowiedzią, aby najpierw uruchomić openspec store unregister.