OpenSpec

Mağazalar (beta) ​

Depoları kapsayan plan değişiklikleri: tek mağaza, birçok depo.

OpenSpec normalde tek bir deponun içinde yaşar: planladığı kodun yanındaki bir openspec/ klasörü. Bir mağaza bu klasörü kendi deposuna taşır ve birçok kod deposu bunu paylaşabilir.

Her makinede bir kez yapılan kurulumdan sonra status, new change ve archive gibi komutlar mağazada herhangi bir dizinden çalışabilir.

         team-plans  (bir mağaza: OpenSpec kendi deposunda)
         ├── .openspec-store/store.yaml   mağazanın adı
         └── openspec/
             ├── specs/
             └── changes/
                   ▲
                   │ her makinede bir kez kurulur,
                   │ herhangi bir depo gibi itme ve klonlama ile paylaşılır
     ┌─────────────┼─────────────┐
     │             │             │
 web-app       api-server     mobile-app
(kod deposu)   (kod deposu)    (kod deposu)

Bir mağazayı git ile paylaşırsınız, tıpkı kodu paylaştığınız gibi: kendiniz commit, push, pull ve review yaparsınız. Spec'ler ve change'ler de tıpkı kod gibi branch'ler ve pull request'ler alır.

Bir mağazaya ne zaman ihtiyacınız olur ​

Bir mağaza kullanmak için iki yaygın neden:

  • Frontend ve backend ayrı depolarda: bir özellik her ikisini de etkiler ve planın iki yarım yerine tek bir eve ihtiyacı vardır.

          shop-plans  (mağaza)
      └── openspec/changes/add-discounts/    özellik için tek plan
                ▲
      ┌─────────┴─────────┐
      │                   │
  storefront             api
(frontend deposu)     (backend deposu)

  • Tek ürün, birçok istemci deposu: Android, iOS ve web kendi depolarından yayınlanır ancak tek bir beklenen davranışı paylaşır. Bir spec davranışı tanımlar, uygulamayı değil; bu nedenle tek bir spec üçüne de hizmet eder.

            product-specs  (mağaza)
        └── openspec/specs/checkout/spec.md    beklenen davranış
                  ▲
    ┌─────────────┼─────────────┐
    │             │             │
android-app    ios-app       web-app
(kod deposu)   (kod deposu)   (kod deposu)

Birden fazla mağazanız olabilir, ancak sayıyı düşük tutmanızı öneririz.

Mağaza kurulumu ​

Bir kişi mağazayı oluşturur, ardından diğer herkes katılır.

  1. Mağazayı oluşturun (bir kişi, ekip başına bir kez). openspec store setup komutunu çalıştırın ve istemleri yanıtlayın:

    bash
    # herhangi bir dizinden çalıştırın; ne oluşturacağını ve nereye oluşturacağını sorar
openspec store setup

    Üç soru sorar:

    • Mağaza adı: team-plans
    • Bu mağaza nerede bulunmalı?: ~/openspec/<name> ile önceden doldurulmuş, kabul etmek için Enter'a basın veya başka bir yol yazın
    • Bu mağaza oluşturulsun mu?: ne oluşturacağını gösterir, Yes yanıtını verin

    Ardından oluşturduklarını bildirir:

    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 sunucunuza gönderin. Önce sunucunuzda boş bir team-plans deposu oluşturun. Kurulum bir git remote eklemez, bu yüzden mağazayı bu depoya bağlayın, ardından gönderin:

    bash
    # mağazayı git sunucunuzdaki boş depoya bağlayın
cd ~/openspec/team-plans
git remote add origin git@github.com:acme/team-plans.git

# yayınlayın
git push -u origin main

  3. Mağazaya katılın (her takım arkadaşı, makine başına bir kez):

    bash
    # mağazayı makinenize alın
git clone git@github.com:acme/team-plans.git ~/openspec/team-plans

# OpenSpec'e nerede olduğunu söyleyin
openspec store register ~/openspec/team-plans
    yaml
    Store registered: team-plans
Location: /Users/you/openspec/team-plans
OpenSpec root: ready
Registry: registered

    Kayıt işlemi makinenize bu mağazanın nerede olduğunu söyler. Mağazanın adı zaten .openspec-store/store.yaml içinde kayıtlıdır. Kurulum oluşturanın kopyasını kaydetti, bu yüzden yalnızca klonlanmış kopyaların bu adıma ihtiyacı vardır.

  4. Çalıştığını doğrulayın, herhangi bir dizinden:

    bash
    # herhangi bir OpenSpec komutu mağazaya isme göre ulaşır
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

Kurulum türleri ​

OpenSpec'in üç kurulumu vardır. Bu sayfanın geri kalanı bu isimleri kullanır:

  • repo-local: OpenSpec deponuzun içinde, mağaza yok. Varsayılan.
  • store-only: deponuzun kendi spec veya değişikliği yok. Her şey mağazada bulunur.
  • store-optional: projenizin kendi openspec/ klasörü var ve ayrıca istediğinizde bir mağazaya erişir.

Varsayılan: OpenSpec deponuzun içinde (repo-local) ​

openspec init, kodunuzun yanına bir openspec/ klasörü koyar ve o deponun spec'leri ve değişiklikleri orada bulunur. Mağaza devreye girmez. Bu, Projenizi kurun sayfasının öğrettiği kurulumdur ve çoğu proje başka bir kurulum gerektirmez.

web-app  (kod deposu)
└── openspec/
    ├── specs/
    └── changes/

OpenSpec deponuzun dışında, bir mağazada (store-only) ​

Depo kendi spec'lerini veya değişikliklerini saklamaz. Planladığı her şey mağazada bulunur ve deponun yapılandırmasındaki tek bir satır ikisini birbirine bağlar.

Bir ekibin tüm depoları ve planları tek bir yerde oluşturması durumunda yaygındır. Yukarıdaki örneklerin tamamı bu yapıya sahiptir.

team-plans  (mağaza)
└── openspec/
    ├── specs/       deponun spec'leri burada bulunur
    └── changes/     değişiklikleri de
          ▲
          │ store: team-plans   (bağlayan satır)
web-app  (kod deposu)
└── openspec/
    └── config.yaml    başka bir şey yok

OpenSpec hem deponuzda hem de bir mağazada (store-optional) ​

Depo kendi işleri için repo-local kalır, mağaza ise paylaşılan spec'leri ve değişiklikleri barındırır. Depo içinde OpenSpec, projenizin openspec/ klasörünü kullanır ve yalnızca --store parametresini geçtiğinizde mağazaya erişir.

Bir deponun mağaza mevcut olmadan önce OpenSpec kullandığında veya büyük ölçüde bağımsız bir deponun yalnızca ara sıra paylaşılan işlere dokunduğu durumlarda yaygındır.

team-plans  (mağaza)
└── openspec/          paylaşılan spec'ler ve değişiklikler
          ▲
          │ yalnızca --store team-plans geçtiğinizde
web-app  (kod deposu)
└── openspec/          bu deponun kendi
    ├── config.yaml
    ├── specs/
    └── changes/

Bir depo repo-local olarak başlayabilir ve spec'lerini ile değişikliklerini daha sonra mağazaya taşıyabilir. Bir deponun spec'lerini ve değişikliklerini mağazaya taşıma bunun nasıl yapılacağını gösterir.

Mağaza kullanırken yapıtların nerede oluşturulacağı ​

Mağaza kullandığınızda, OpenSpec'in yapıtların nerede oluşturulacağına da karar vermesi gerekir. Bu, kurulumunuza bağlıdır:

  • store-only (projeniz yalnızca mağazaya yazar): her yapıt mağazada oluşturulur. Aşağıdaki store: satırı bunu kaydeder.
  • store-optional (projenizin kendi openspec/ klasörü var ve ayrıca mağaza kullanıyorsunuz): yapıtlar, isteğinizde mağazayı belirtmediğinizçe veya o değişiklik için --store geçmediğinizçe projenizde oluşturulur. Aracınız daha sonra bu bayrağı iş akışının geri kalanında taşır.

OpenSpec yapıtları iki yerden birine yazar: projenizin openspec/ klasörüne veya mağazanınkine. Şu sırayla seçer ve uygulanan ilk seçenek kazanır:

  1. Komutta --store <id>. Her zaman kazanır, herhangi bir dizinden.
  2. Projenizin openspec/ klasörü. Projenizde kendi specs/ veya changes/ klasörleriniz varsa, OpenSpec bunları kullanır.
  3. Projenizdeki store: satırı. Store-only projenin mağazasını kaydetme şekli.
  4. Makinenizdeki defaultStore. Yukarıdakilerin hiçbiri uygulanmadığında son çare.

Bunlardan hiçbiri uygulanmazsa ve kayıtlı mağazalarınız varsa, komut başarısız olur ve bunları listeler. Bir mağazanın kimliği deponuzun origin uzak adresindeki adıyla eşleştiğinde, hata o mağazayı ve onu seçen store: satırını belirtir. OpenSpec asla kendi başına bir mağazayı ada göre seçmez, çünkü farklı organizasyonlardaki depolar aynı adı paylaşabilir.

OpenSpec bir mağaza seçtiğinde, komut çıktısından önce Using OpenSpec root: ... yazdırır.

store: satırı (store-only projeler) ​

Projenizin openspec/config.yaml dosyasına bir satır ekleyin:

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

Projeniz içinde sizin veya aracınızın çalıştırdığı her şey artık yazılacak bir bayrak olmadan mağazayı kullanır:

bash
# web-app içinde, bağlı
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
  • Satır olmadan: store-only projede düz bir komut çalıştırın ve OpenSpec kayıtlı mağazalarınızı listeleyen bir hata ile durur.
  • Commit edin: deponuzu klonlayan takım arkadaşlarınız da bu satırı alır. Yine de makinelerinde mağazayı kaydetmeleri gerekir (Mağaza kurulumunun 3. adımı), yoksa OpenSpec hata verir ve onlara kaydetmelerini söyler.
  • Gerçek klasörlerin yanında: projenizde ayrıca specs/ veya changes/ klasörleri varsa, OpenSpec bunları kullanır ve bir uyarıyla satırı yok sayar.

Store-only depoda entegrasyonlar kurun ​

Planlamayı o deponun içine geri taşımadan AI aracı entegrasyon dosyalarını kurmak için kod deponun kök dizininden init çalıştırın:

bash
# web-app içinde, depo kök dizininde
openspec init --tools claude
  • Entegrasyon dosyaları: kod deposuna yazılır.
  • openspec/config.yaml: store: satırı dahil byte-byte korunur.
  • openspec/specs/ ve openspec/changes/: kod deposunda oluşturulmaz.

OpenSpec kod deponun bir alt dizininden bu komutu reddeder. Depo kök dizininden çalıştırın.

OpenSpec ayrıca --language parametresini burada reddeder çünkü dil bilgisi harici mağazanın yapılandırmasına aittir. Init'i mağaza kök dizininde çalıştırın veya doğrudan o yapılandırmayı düzenleyin.

Makinenizdeki defaultStore ​

Çalıştığınız her projenin aynı mağazayı kullandığı durumda bir kez ayarlayın. OpenSpec bir bayrak, yerel openspec/ klasörü ve store: satırı bulamadığında buna geri döner:

bash
# başka hiçbir şey mağaza belirtmediğinde team-plans kullanın
openspec config set defaultStore team-plans

# geri alın
openspec config unset defaultStore

Yerel kalan komutlar. init, update, templates, schemas ve openspec schema alt komutları yalnızca geçerli dizinde etkili olur ve --store almaz.

Bir deponun spec'lerini ve değişikliklerini mağazaya taşıma ​

Bir deponuzu repo-local'dan store-only'a geçirmek için:

  1. Deponun openspec/specs/ ve openspec/changes/ klasörlerindeki her şeyi mağazadaki aynı klasörlere taşıyın.
  2. Artık boş olan klasörleri silin, böylece deponun openspec/ klasörü yalnızca config.yaml içerir.
  3. Bu config.yaml dosyasına store: satırını ekleyin.

Depo içinde openspec status artık Using OpenSpec root: team-plans ile başlar.

Mağazada çalışma ​

İş akışları sizin veya aracınız için değişmez. Propose, apply ve archive her zamanki gibi çalışır. Tek fark yapıtların nerede oluşturulacağıdır ve yukarıdaki bölüm bunu kapsar.

Store-only deponun içinden bir değişiklik oluşturun ve mağazaya düşer:

bash
# web-app içinde; store: satırı bunu team-plans'e yönlendirir
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
  • Nereye gittiği: kodunuzun yanına değil, mağaza deposuna.
  • Paylaşma: değişiklik, mağaza deponuzu commit edip gönderme ana kadar yalnızca sizin çalışma kopyanızda bulunur. Takım arkadaşları pull yaptıklarında görürler. İş akışlarının yazdığı her yapıt için aynısı geçerlidir.
  • Belgelerdeki yollar: belgelerde bir openspec/ yolu gösterildiğinde, mağaza kurulumunda bu klasör mağazanınkindir.

Yapıtlar beklenmedik bir yerde oluşturulduğunda, openspec doctor kurulumunuzu hiçbir şeyi değiştirmeden kontrol eder ve her bulgu için bir düzeltme yazdırır:

bash
# geçerli kökü ve mağazalarını kontrol edin
openspec doctor
yaml
Doctor

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

References
  (none declared)

openspec context, kontroller olmadan aynı tabloyu istediğinizde geçerli dizinizin çalıştığı kökü ve mağazaları listeler.

Mağazayı ve bir depoyu tek bir editör penceresinde açmak için, böylece aracınız her ikisini de okuyabilir, bkz. Worksets (beta).

Spec'leri başka bir store'dan oku ​

Repo'nuz kendi openspec/ klasörünü saklayabilir ve aynı zamanda agent'ınızın başka bir store'un spec'lerini okumasına izin verebilir. Bu store'u repo'nuzun openspec/config.yaml dosyasında references: altında bildirin:

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

Referanslar salt okunurdur. Çalışmalarınız repo'nuzda kalır ve referans yalnızca agent'ınıza söylenenleri değiştirir.

Bir iş akışı bir artifact oluşturduğunda, talimatları referans gösterilen store'un spec'lerinin bir dizinini alır; her biri tek satırlık bir özet ve almak için tam komut içerir:

xml
<referenced_stores>
<!-- Salt okunur üst kaynak bağlamı. İhtiyacınız olanı alın; kullandığınızı belirtin. -->
Store team-plans (/Users/you/openspec/team-plans):
  - payments: Müşterileri ücretlendirme ve iade etme kuralları.
  Fetch: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

Bir referans ayrıca store'un clone URL'sini de taşıyabilir, henüz bu store'a sahip olmayan makineler için:

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

URL bildirildiğinde, openspec doctor eksik bir store'u yapıştırılabilir bir çözüme dönüştürür:

yaml
# sığması için çıktı sarıldı
Referanslar
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: 'design-system' adlı referans store bu makinede kayıtlı değil.
    Çözüm: 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

Beta sınırları ​

  • Şekil değişebilir: komut adları, bayraklar ve dosya formatları sürümler arasında değişebilir. Yükselttikten sonra bu sayfayı tekrar okuyun.
  • Tasarım gereği senkronizasyon yok: OpenSpec asla clone, pull veya push yapmaz. Güncel olmayan bir checkout, siz pull yapana kadar güncel olmayan spec'leri gösterir ve referanslar diskte ne varsa ondan okunur.
  • Store adı başına bir checkout: zaten kayıtlı olan bir adın altında ikinci bir klasör kayıt etmek başarısız olur ve önce openspec store unregister çalıştırmanız için bir ipucu verilir.