Stores: Kendi Deposunda Planlama

Beta. Stores, referanslar, çalışma bağlamı ve çalışma kümeleri yeni özelliklerdir. Komut adları, bayraklar, dosya biçimleri ve JSON çıktısı sürümler arasında şekil değiştirebilir. Aşağıdaki tüm örnekler mevcut derleme üzerinde çalıştırılmıştır, ancak yükseltme yaptıktan sonra bu kılavuzu yeniden okuyun.

Bu çözümün ele aldığı sorun

OpenSpec normalde tek bir kod deposu içinde yaşar: kodunuzun yanında bir openspec/ klasörü, o depo için spesifikasyonları ve değişiklikleri barındırır.

Planlama tek bir depodan büyük hale geldiği anda bu yapı yetersiz kalmaya başlar:

• Çalışmanız birden fazla depoyu kapsıyor — bir özellik API sunucusunu, web uygulamasını ve ortak bir kütüphaneyi etkiliyor. Planın openspec/ klasörü kime ait olacak?
• Ekip, kod henüz var olmadan planlama yapıyor ya da bu depoda asla koda dönüşmeyecek şeyleri planlıyor.
• Gereksinimler bir ekip tarafından sahipleniliyor ve diğerleri tarafından tüketiliyor. Wiki sürümü sapıyor ve kodlama ajanınız zaten onu okuyamıyor.

Bir store, bunun cevabıdır: tüm işi planlama olan bağımsız bir depo. Zaten bildiğiniz aynı openspec/ yapısına sahiptir — spesifikasyonlar ve değişiklikler — ayrıca küçük bir kimlik dosyası içerir. Bir kez makinenize isimle kaydeder ve ardından her normal OpenSpec komutu her yerden içinde çalışabilir.

Yapı

            team-plans  (bir depo: kendi repolarında planlama)
            ├── .openspec-store/store.yaml     kimlik: "Ben team-plans'ım"
            └── openspec/
                ├── specs/      ne doğrudur
                └── changes/    ne hareket halindedir
                      ▲
                      │ her makinede adıyla kaydedilir;
                      │ herhangi bir repo gibi push/clone ile paylaşılır
        ┌─────────────┼─────────────┐
        │             │             │
    web-app       api-server     mobile-app
   (kod deposu)   (kod deposu)   (kod deposu)

Bu yapıyı basit tutan iki kural vardır:

1. Bir depo sadece bir git repodur. Kendiniz commit, push, pull ve review yaparsınız. OpenSpec asla kendi başına hiçbir şeyi clone, sync veya push etmez.
2. Mekanizma değil, beyanlar. Repolar, depolarla nasıl ilişkili olduklarını beyan edebilir (aşağıda gösterildiği gibi). Beyanlar, OpenSpec'in size söyleyebileceği şeyleri değiştirir — komutlarınızın nerede çalışacağını asla değiştirmez.

İlk deponuza beş dakika

İki komutla hiçlikten çalışan, depo kapsamındaki bir değişikliğe geçersiniz:

openspec store setup team-plans --path ~/openspec/team-plans

Depo hazır: team-plans
Konum: /Users/you/openspec/team-plans
OpenSpec kökü: hazır
Kayıt: kaydedildi

Sonraki adım: bu depo üzerinde normal OpenSpec komutlarını çalıştırın, örneğin:
  openspec new change <change-id> --store team-plans
Bu depoyu herhangi bir Git repo gibi commit ve push ederek paylaşın.

openspec new change add-login --store team-plans

Kullanılan OpenSpec kökü: team-plans (/Users/you/openspec/team-plans)
'add-login' değişikliği oluşturuldu: /Users/you/openspec/team-plans/openspec/changes/add-login/
Şema: spec-driven
Sonraki adım: openspec status --change add-login --store team-plans

Modelin tamamı bu. Buradan itibaren yaşam döngüsü bildiğiniz gibidir — status, instructions, validate, archive — her komutta --store team-plans bayrağıyla ve her yazdırılan ipucu bu bayrağı sizin için taşır. Using OpenSpec root: satırı her zaman komutun nerede çalıştığını söyler.

Hikâye: bir ekip, bir planlama deposu

Bir ekip, spesifikasyonlarını ve değişikliklerini team-plans içinde tutar; onları kod depolarına dağıtmaz.

Birinci gün (kuran kişi):

openspec store setup team-plans --path ~/openspec/team-plans \
  --remote git@github.com:acme/team-plans.git
git -C ~/openspec/team-plans push -u origin main

--remote parametresi, clone URL'sini deponun kendi kimlik dosyasına (.openspec-store/store.yaml) kaydeder, ilk commit'te. Bundan sonraki her clone, nereden geldiğini bilerek doğar; böylece sağlık kontrolleri ve hata mesajları, henüz sahip olmayan ekip arkadaşları için eksiksiz, yapıştırılabilir bir düzeltme yazdırabilir.

Her ekip arkadaşı (her makinede bir kez):

git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
openspec store register ~/openspec/team-plans

Bundan sonra herkes aynı planlama deposu üzerinde adıyla çalışır:

openspec status --store team-plans --change add-login
openspec show add-login --store team-plans

İş paylaşımı git'tir, bilinçli olarak. Oluşturduğunuz bir değişiklik, commit ve push edene kadar yalnızca sizin checkout'unuzda var olur — kodla aynı şekilde. Planlar, bir depo sıradan bir repo olduğu için branch, pull request ve review'u bedava alır.

Ekip kod depolarını bağlama. Planlaması tamamen dışsallaştırılmış bir kod deposu, openspec/config.yaml içinde tam olarak bir satıra ihtiyaç duyar:

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

Artık web-app içinde çalıştırılan her OpenSpec komutu, hiç bayrak olmadan team-plans üzerinde çalışır:

cd ~/src/web-app
openspec status --change add-login

Kullanılan OpenSpec kökü: team-plans (/Users/you/openspec/team-plans)
...

İşaretçi bir yedek çözümdür, asla bir geçersiz kılma değildir: açık bir --store her zaman kazanır ve repo kendi gerçek planlama klasörlerini büyütürse, onlar kazanır (eski işaretçiyi kaldırma uyarısıyla birlikte).

Makinenizdeki her repo için tek bir varsayılan. Tüm planlaması aynı depoya yapılan birçok kod deposu arasında çalışıyorsanız, her repoya store: satırı eklemek yerine bunu bir kez, küresel olarak ayarlayın:

openspec config set defaultStore team-plans

Artık bir planlama kökünün dışında çalıştırılan ve ne --store ne de proje işaretçisi içermeyen herhangi bir komut team-plans olarak çözümlenir. Öncelik listesinin en altında yer alır, bu yüzden --store, yerel bir kök ve proje store: işaretçisi hâlâ kazanır. Kök pankartı ve JSON root bloğu, depo id'si ile birlikte source: "global_default" raporlar, böylece makine genelinde bir varsayılanı bir repoya ait işaretçiden her zaman ayırt edebilirsiniz. openspec config unset defaultStore ile temizleyin. Id kayıtlı değilse, komutlar hata verir ve kaydetmenizi veya eski varsayılanı temizlemenizi söyler.

Örnek: bir özellik, iki bileşen deposu

Varsayalım add-checkout-promo hem checkout-api hem de checkout-web'i değiştiriyor. Ekip tek bir ortak ürün sözleşmesi istiyor, ancak her kod deposu kendi uygulama görevlerine, branch'ine ve review'una hâlâ ihtiyaç duyuyor.

İki katman kullanın:

1. Ortak davranışı team-plans içinde tutun.
2. Uygulama planlarını her bileşen deposunda tutun ve depoyu salt okunur üst akış bağlamı olarak referanslayın.

Önce ortak sözleşmeyi depoda planlayın:

openspec new change add-checkout-promo --store team-plans
openspec status --change add-checkout-promo --store team-plans

Öneri ve spesifikasyonlar, bileşenler arasındaki sınırda davranışı tanımlamalı — örneğin, servisin döndürdüğü promosyon alanları ve ön yüzün uygun olmayan bir checkout'u nasıl ele aldığı. Bu değişikliği depo repoda herhangi bir başka branch ve pull request gibi review edin.

Planlama hangi bağlamı görür?

Bir depo seçmek OpenSpec kökünü değiştirir; o depoyu kullanan her kod deposunu keşfetmez veya okumaz. Depo talimatları, depodaki artefaktları ve yapılandırılmış bağlamı görür. Bileşen kodunu yalnızca bu klasörler ajan veya editöre de erişilebilir olduğunda ve ajan onları okuduğunda görür.

Bir çalışma seti, planlama deposunu ve her iki kod deposunu birlikte açmanın pratik bir yoludur:

openspec workset create checkout-promo \
  --member ~/openspec/team-plans \
  --member ~/src/checkout-api \
  --member ~/src/checkout-web \
  --tool code
openspec workset open checkout-promo

Bu, klasörleri tek bir IDE çalışma alanında görünür kılar. Kaynak bağlamını depona kopyalamaz, etkilenen depoları seçmez veya ajanlara onları düzenleme izinini vermez. Kalıcı çapraz bileşen gerçeklerini ortak spesifikasyonlarda tutun; bir planlayıcının tesadüfen incelediği kaynağı hatırlamasına güvenmeyin.

Her depoda uygulama nasıl başlar?

Açık bir --store veya daha yakın bir openspec/ kökü uygulanmadığında, store: team-plans işaretçisi komutları o depoya yönlendirir. Tek bir depo görev listesini apply'nin çağrıldığı dizine göre bölmek gibi bir şey yapmaz. OpenSpec şu anda görevleri depolara yönlendirmez.

Her bileşen bağımsız kapsamlı bir apply/review döngüsüne ihtiyaç duyduğunda, ona yerel bir OpenSpec kökü verin ve merkezi depoyu işaret etmek yerine referanslayın:

# checkout-api/openspec/config.yaml (ve benzer şekilde checkout-web'de)
schema: spec-driven
references:
  - team-plans

Ortak sözleşme onaylandıktan ve deponun ana spesifikasyonlarında erişilebilir hale geldikten sonra, bileşenin kısmı için küçük bir yerel değişiklik oluşturun:

cd ~/src/checkout-api
openspec new change implement-checkout-promo-api

cd ~/src/checkout-web
openspec new change implement-checkout-promo-ui

Her repodaki talimatların referans dizini, depo spesifikasyonunun özetini ve tam openspec show ... --store team-plans alma komutunu sağlar. Her yerel öneri o ortak sözleşmeyi alıntılar ve görevleri yalnızca o bileşendeki işi tanımlar. Ardından her repoda ayrı ayrı /opsx:apply çalıştırın; kök çözümleme, artefaktları ve uygulama düzenlemelerini o repo kapsamına sınırlar. Servis ve ön yüz değişiklikleri artık bağımsız olarak test edilebilir, review edilebilir, birleştirilebilir ve arşivlenebilir.

Uygulama, ortak depo değişikliği hâlâ aktifken başlamak zorundaysa, onu açıkça openspec show add-checkout-promo --store team-plans ile alın; referans dizimleri kanonik depo spesifikasyonlarını listeler, aktif depo değişikliklerini değil. Depo branch'ini ve bileşen branch'lerini pull request açıklamalarında bağlı tutun, böylece gözden geçirenler her uygulamanın sözleşmenin hangi sürümünü takip ettiğini görebilsin.

Hikâye: ekip sınırlarını aşan gereksinimler

Bir platform ekibi gereksinimlerin sahibidir. Ürün ekipleri kendi depolarında, kendi tasarımlarıyla bunların üzerine inşa eder. Bir referans, hiç kimsenin işini taşımadan bu ilişkiyi tanımlar.

   platform-reqs (depo)                 api-server (kod deposu)
   platform ekibine ait                bir ürün ekibine ait
   ┌──────────────────────────┐          ┌──────────────────────────┐
   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
   │   payments/spec.md       │ okur     │   references:            │
   │   auth/spec.md           │          │     - platform-reqs      │
   │                          │          │ openspec/specs/          │
   │ openspec/changes/        │          │   (kendi tasarımları)    │
   │   platform işi           │          │ openspec/changes/        │
   │                          │          │   (kendi işleri)         │
   │                          │          └──────────────────────────┘
   └──────────────────────────┘

Ürün ekibi, neye dayandığını beyan eder kendi deposunun openspec/config.yaml dosyasında:

references:
  - platform-reqs

Referanslar salt okunur bağlamdır. Repo kendi openspec/ kökünü korur; iş orada kalır. Ne değişir: o repodaki openspec instructions artık referans verilen deponun spesifikasyonlarının dizinini içerir — her biri tek satırlık bir özet ve tam alma komutuyla birlikte (openspec show <spec-id> --type spec --store platform-reqs). api-server içinde çalışan bir ajan, üst akış ödeme gereksinimlerini bulabilir, onları alıntileyebilir ve düşük seviyeli tasarımını repodaki kendi kökünde yazabilir — hiç kimsenin bağlamı yapıştırmasına gerek kalmadan.

Bir referans, kendi clone kaynağını taşıyabilir, böylece henüz depoya sahip olmayan ekip arkadaşları bir çıkmaz yerine eksiksiz bir düzeltme alır:

references:
  - { id: platform-reqs, remote: "git@github.com:acme/platform-reqs.git" }

Plan ve kodu birlikte açmak istediğinizde, bir çalışma seti oluşturun. Bu kişisel ve açıktır: her kişi, makinesinde gerçekten çalıştığı klasörleri seçer. Bu yerel checkout yollarıyla ilgili hiçbir şey ortak planlama deposuna commit edilmez.

openspec workset create platform \
  --member ~/openspec/platform-reqs \
  --member ~/src/api-server \
  --member ~/src/web-app

Her zaman sorabileceğiniz iki soru

"Kurulumum sağlıklı mı?" — openspec doctor mevcut kökü ve referans verdiği depoları salt okunur olarak kontrol eder, her bulgu için yapıştırılabilir bir düzeltmeyle birlikte:

Doctor

Root
  Location: /Users/you/src/api-server
  OpenSpec root: ok

References
  - platform-reqs: ok (/Users/you/openspec/platform-reqs)
  - 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

"Neyle çalışıyorum?" — openspec context, çalışma setini OpenSpec beyanlarından derler: kök ve referans verdiği depolar.

Working context for api-server (/Users/you/src/api-server)

OpenSpec root
  api-server  /Users/you/src/api-server

Referenced stores
  platform-reqs  /Users/you/openspec/platform-reqs
    Fetch: openspec show <spec-id> --type spec --store platform-reqs

Her ikisi de ajanlar için --json destekler. openspec context --code-workspace <path> ek olarak, tüm seti içeren bir VS Code çalışma alanı dosyası yazar — bu komutun gerçekleştirdiği tek yazma işlemi budur.

Worksets: birlikte çalıştığınız klasörleri yeniden açın

Yukarıdakilerin tümünden bağımsız olarak: çoğu kişi her oturumda aynı birkaç klasörü birlikte açar — planlama deposu ve iki veya üç kod deposu. Workset, tam olarak bunun kişisel, adlandırılmış bir görünümüdür ve tercih ettiğiniz araçta tek komutla yeniden açılır.

  workset "platform"                 openspec workset open platform
  ├── team-plans   ~/openspec/team-plans         │
  ├── api-server   ~/src/api-server              ▼
  └── web-app      ~/src/web-app       all three open in your tool

openspec workset create platform \
  --member ~/openspec/team-plans --member ~/src/api-server \
  --tool code
openspec workset list

platform  (opens in VS Code)
  team-plans  /Users/you/openspec/team-plans
  api-server  /Users/you/src/api-server

openspec workset open platform komutu, kaydedilen aracı başlatır: editörler (VS Code, Cursor) tüm üyeleri tek pencerede açar ve döner. İlk üye birincildir. Aracı istediğiniz zaman --tool <id> ile geçersiz kılabilirsiniz.

Workset'ler bilinçli olarak paylaşılan durum değildir. Makinenizde yaşarlar, asla commit edilmezler ve iş hakkında hiçbir iddiada bulunmazlar — yalnızca birlikte açık tutmayı tercih ettiklerinizi kaydederler. Birini kaldırmak üye klasörlere asla dokunmaz. Yeni araçlar yapılandırma, kod değildir: çalışma alanı dosyası veya klasör başına bağlama bayrakları ile başlatılabilecek her şey, global yapılandırmadaki openers anahtarı altına eklenebilir (openspec config edit).

Komutlar nerede çalışacağını nasıl belirler

Her normal komut kökünü aynı şekilde, şu sırayla çözümler:

1. --store <id>          you said so explicitly        → that store
2. nearest openspec/     a real planning root here     → this repo
   (walking up from cwd)
3. store: pointer        config.yaml declares a store  → that store
4. defaultStore          global config sets a machine  → that store
                         default
5. none of the above     stores registered on this     → error with a
                         machine?                        selection hint
                         no stores registered?         → the current
                                                          directory
                                                          (classic behavior)

Using OpenSpec root: satırı (ve --json çıktısındaki root bloğu) hangi durumda olduğunuzu söyler.

Bilinen kısıtlamalar

• Beta şekli. Bu sayfadaki her şey sürümler arasında değişebilir — adlar, bayraklar, dosya biçimleri, JSON anahtarları.
• Makine başına store id'si başına bir checkout. Aynı id altında ikinci bir checkout kaydederken önce store unregister yapmanız gerektiğine dair bir ipucuyla başarısız olur.
• Asla senkronizasyon yok — tasarım gereği. OpenSpec asla klonlama, çekme veya itme yapmaz. Eski bir checkout, siz çekene kadar eski spesifikasyonları gösterir; referanslar diskte ne varsa canlı olarak indekslenir.
• Boş planlama klasörleri yok olabilir. Yeni bir store'da henuz Git'te openspec/changes/, openspec/specs/ veya openspec/changes/archive/ bulunmayabilir. Bu, beta sırasında kabul edilir; bu klasörler normal komutlar onlar için dosya oluşturduğunda belirir.
• Pointer depolar pointer olarak kalır. openspec/config.yaml dosyasında store: <id> bildiren yalnızca yapılandırma içeren bir depo, store checkout olarak kaydedilecek bir şey değil, dışsallaştırılmış planlama olarak ele alınır. O depoyu bilinçli olarak yerel bir store köküne dönüştürmek istiyorsanız önce store: satırını kaldırın.
• Bazı komutlar yerinde kalır. templates ve terk edilen isim biçimleri (openspec change show, ...) yalnızca geçerli dizinde çalışır — --store yok. schemas, kanonik kök seçim önceliğini izler ve başarılı JSON dizi biçimini değiştirmeden --store <id> kabul eder.
• Makine başına durum makine başınadır. Store kayıt defteri ve workset'ler yerel ayarlardır. Makinenizin düzeniyle ilgili hiçbir şey paylaşılan planlamaya commit edilmez.
• Workset'ler için iki başlatma stili. Çalışma alanı dosyası veya klasör başına bağlama bayrakları ile başlatılamayan bir araç opener olarak eklenemez.
• Agent JSON'da bilinen bir büyük/küçük harf ayrımı var (store ailesi anahtarları snake_case, workflow ailesi camelCase). Agent sözleşmesinde belgelenmiştir; birleştirilmesi sürüm numaralı bir sürüme ertelenmiştir.

Şeyler nerede yaşar

Ne	Nerede	Paylaşılan mı?
Bir store'un planlaması	<store>/openspec/ (specs, changes)	Evet — commit edin ve ittirin
Bir store'un kimliği	<store>/.openspec-store/store.yaml	Evet — store ile birlikte commit edilir
Store kayıt defteri	<data dir>/openspec/stores/registry.yaml	Hayır — yalnızca bu makine
Workset'ler	<data dir>/openspec/worksets/	Hayır — yalnızca bu makine

<data dir>, macOS ve Linux'ta ~/.local/share/openspec (veya ayarlandığında $XDG_DATA_HOME/openspec), Windows'ta ise %LOCALAPPDATA%\openspec'tır.

Referans

Bu sayfadaki her komut için kesin bayraklar ve JSON biçimleri: CLI referansı (Stores, Doctor, Working context, Personal worksets) ve agent sözleşmesi.