Skip to content

OPSX'e Geçiş ​

Bu kılavuz, eski OpenSpec iş akışından OPSX'e geçişinizi kolaylaştırmak için hazırlanmıştır. Geçiş süreci sorunsuz olacak şekilde tasarlanmıştır—mevcut çalışmalarınız korunur ve yeni sistem daha fazla esneklik sunar.

Ne Değişiyor? ​

OPSX, eski aşama-kilitli iş akışını akışkan, eylem tabanlı bir yaklaşımla değiştirir. İşte temel değişiklik:

ÖzellikEskiOPSX
Komutlar/openspec:proposal, /openspec:apply, /openspec:archiveVarsayılan: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (genişletilmiş iş akışı komutları isteğe bağlı)
İş AkışıTüm çıktıları bir anda oluşturArtımlı olarak veya hepsini birden oluştur—seçim sizin
Geri DönüşSakar aşama kapılarıDoğal—herhangi bir çıktıyı istediğiniz zaman güncelleyin
ÖzelleştirmeSabit yapıŞema tabanlı, tamamen özelleştirilebilir
Yapılandırmaİşaretçilerle CLAUDE.md + project.mdopenspec/config.yaml içinde temiz yapılandırma

Felsefe değişikliği: İş doğrusal değildir. OPSX bunun böyle olduğunu iddia etmeyi bırakır.


Başlamadan Önce ​

Mevcut Çalışmalarınız Güvenli ​

Göç süreci, koruma odaklı olarak tasarlanmıştır:

  • openspec/changes/ içindeki aktif değişiklikler — Tamamen korunur. OPSX komutlarıyla devam edebilirsiniz.
  • Arşivlenmiş değişiklikler — Dokunulmaz. Geçmişiniz olduğu gibi kalır.
  • openspec/specs/ içindeki ana spesifikasyonlar — Dokunulmaz. Bunlar doğruluk kaynağınızdır.
  • CLAUDE.md, AGENTS.md vb. dosyalarındaki içerikleriniz — Korunur. Sadece OpenSpec işaretçi blokları kaldırılır; yazdığınız her şey kalır.

Ne Kaldırılır ​

Sadece değiştirilen OpenSpec yönetimli dosyalar:

NeNeden
Eski slash komut dizinleri/dosyalarıYeni beceri sistemi tarafından değiştirildi
openspec/AGENTS.mdArtık geçerli olmayan iş akışı tetikleyicisi
CLAUDE.md, AGENTS.md vb. dosyalardaki OpenSpec işaretçileriArtık gerekli değil

Araçlara göre eski komut konumları (örnekler—sizin aracınız farklı olabilir):

  • Claude Code: .claude/commands/openspec/
  • Cursor: .cursor/commands/openspec-*.md
  • Devin Desktop, formerly Windsurf: .windsurf/workflows/openspec-*.md
  • Cline: .clinerules/workflows/openspec-*.md
  • Roo: .roo/commands/openspec-*.md
  • GitHub Copilot: .github/prompts/openspec-*.prompt.md (sadece IDE eklentileri; Copilot CLI'de desteklenmez)
  • Codex: OpenSpec artık kanonik .agents/skills/openspec-* yolunu kullanır. Eski .codex/skills yolu altındaki OpenSpec yönetimli SKILL.md dosyaları yalnızca yer değiştirmeler mevcut olduktan sonra uzlaştırılır; özel dosyalar ve farklı kopyalar yerinde kalır. İşaretlenmemiş bir .agents ağacı zaten OpenSpec becerileri içeriyorsa, OpenSpec eski dizinden tahmin etmeye çalışmak yerine mevcut Codex ($openspec-*) veya genel (/openspec-*) gösterimini korur. Sahipliği değiştirmek için openspec init ile codex seçeneğini açıkça seçin. Eski prompt temizliği hâlâ yalnızca $CODEX_HOME/prompts veya ~/.codex/prompts içindeki OpenSpec'in izin verilen dosya adlarını hedefler.
  • Ve diğerleri (Augment, Continue, Amazon Q vb.)

Göç, yapılandırdığınız araçları tespit eder ve eski dosyalarını temizler.

Kaldırılacaklar listesi uzun görünebilir, ancak bunların hepsi OpenSpec'in başlangıçta oluşturduğu dosyalardır. Kendi içerikleriniz asla silinmez.

Dikkatinizi Gerektirenler ​

Bir dosya manuel göç gerektirir:

openspec/project.md — Bu dosya otomatik olarak silinmez çünkü yazdığınız proje bağlamı içerebilir. Şunları yapmanız gerekecek:

  1. İçeriğini gözden geçirin
  2. Faydalı bağlamı openspec/config.yaml dosyasına taşıyın (aşağıdaki yönergelere bakın)
  3. Hazır olduğunuzda dosyayı silin

Bu değişikliği neden yaptık:

Eski project.md pasifti—ajanlar okuyabilir, okumayabilir, okuduklarını unutabilirlerdi. Güvenilirliğin tutarsız olduğunu tespit ettik.

Yeni config.yaml bağlamı her OpenSpec planlama isteğine aktif olarak enjekte edilir. Bu, proje kurallarınızın, teknoloji yığını ve kurallarınızın yapay zekâ artefakt oluştururken her zaman hazır olduğu anlamına gelir. Daha yüksek güvenilirlik.

Maliyet:

Bağlam her isteğe enjekte edildiği için, kısa tutmak isteyeceksiniz. Gerçekten önemli olanlara odaklanın:

  • Teknoloji yığını ve ana kurallar
  • Yapay zekânın bilmesi gereken açık olmayan kısıtlamalar
  • Önceden sıkça göz ardı edilen kurallar

Mükemmel yapmaya çalışmayın. Burada en iyi neyin işe yaradığını hâlâ öğreniyoruz ve bağlam enjeksiyonunun nasıl çalıştığını deneylerimize göre geliştireceğiz.


Göçü Çalıştırma ​

Hem openspec init hem de openspec update eski dosyaları tespit eder ve sizi aynı temizlik sürecinden geçirir. Durumunuza uygun olanı kullanın:

  • Yeni kurulumlar varsayılan olarak core profili kullanır (propose, explore, apply, update, sync, archive).
  • Göç edilen kurulumlar, gerekli olduğunda custom profili yazarak daha önce kurulu iş akışlarınızı korur.

openspec init Kullanımı ​

Yeni araçlar eklemek veya hangi araçların yapılandırılacağını yeniden yapılandırmak istiyorsanız bunu çalıştırın:

bash
openspec init

Init komutu eski dosyaları tespit eder ve sizi temizlik sürecinden geçirir:

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

Evet dediğinizde ne olur:

  1. Eski slash komut dizinleri kaldırılır
  2. OpenSpec işaretçileri CLAUDE.md, AGENTS.md vb. dosyalardan soyulur (içeriğiniz kalır)
  3. openspec/AGENTS.md silinir
  4. Yeni beceriler .claude/skills/ dizinine kurulur
  5. Varsayılan şema ile openspec/config.yaml oluşturulur

openspec update Kullanımı ​

Sadece göç yapmak ve mevcut araçlarınızı son sürüme güncellemek istiyorsanız bunu çalıştırın:

bash
openspec update

Update komutu da eski artefaktları tespit eder ve temizler, ardından oluşturulan becerileri/komutları mevcut profilinize ve teslimat ayarlarınıza uygun şekilde yeniler.

Etkileşimsiz / CI Ortamları ​

Betiklenmiş göçler için:

bash
openspec init --force --tools claude

--force bayrağı soruları atlar ve temizliği otomatik olarak kabul eder.

Bu, küresel Codex prompt dizinindeki OpenSpec yönetimli Codex prompt dosyalarının temizliğini de içerir. Temizlik yalnızca OpenSpec'in izin verilen eski Codex prompt dosya adlarını hedefler, bunları yalnızca yer değiştirmeler .agents/skills/openspec-* becerileri mevcut olduktan sonra kaldırır ve diğer tüm dosyaları korur.


project.md'den config.yaml'e Göç ​

Eski openspec/project.md, proje bağlamı için serbest biçimli bir markdown dosyasıydı. Yeni openspec/config.yaml yapılandırılmıştır ve—kritik olarak—her planlama isteğine enjekte edilir, böylece yapay zekâ çalışırken kurallarınız her zaman hazır olur.

Önce (project.md) ​

markdown
# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

Sonra (config.yaml) ​

yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

Temel Farklar ​

project.mdconfig.yaml
Serbest biçimli markdownYapılandırılmış YAML
Tek bir metin bloğuAyrı bağlam ve artefakt başına kurallar
Ne zaman kullanıldığı belirsizBağlam TÜM artefaktlarda görünür; kurallar yalnızca eşleşen artefaktlarda görünür
Şema seçimi yokAçık schema: alanı varsayılan iş akışını belirler

Ne Tutulmalı, Ne Bırakılmalı ​

Göç sırasında seçici olun. Kendinize sorun: "Yapay zekâ bunu her planlama isteği için mi ihtiyaç duyuyor?"

context: için uygun adaylar

  • Teknoloji yığını (diller, çerçeveler, veritabanları)
  • Ana mimari kalıplar (monorepo, microservices vb.)
  • Açık olmayan kısıtlamalar ("X kütüphanesini kullanamıyoruz çünkü...")
  • Sıkça göz ardı edilen kritik kurallar

Bunun yerine rules: bölümüne taşıyın

  • Artefakt özel biçimlendirme ("spesifikasyonlarda Given/When/Then kullanın")
  • İnceleme kriterleri ("öneriler geri alma planı içermelidir")
  • Bunlar yalnızca eşleşen artefakt için görünür, böylece diğer istekler daha hafif kalır

Tamamen dışarıda bırakın

  • Yapay zekânın zaten bildiği genel en iyi uygulamalar
  • Özetlenebilecek ayrıntılı açıklamalar
  • Mevcut işi etkilemeyen tarihsel bağlam

Göç Adımları ​

  1. config.yaml oluşturun (init tarafından henüz oluşturulmadıysa):

    yaml
    schema: spec-driven
  2. Bağlamınızı ekleyin (kısa tutun—bu her isteğe gider):

    yaml
    context: |
      Your project background goes here.
      Focus on what the AI genuinely needs to know.
  3. Artefakt başına kurallar ekleyin (isteğe bağlı):

    yaml
    rules:
      proposal:
        - Your proposal-specific guidance
      specs:
        - Your spec-writing rules
  4. project.md dosyasını tüm faydalı içerikleri taşıdıktan sonra silin.

Aşırı düşünmeyin. Temellerle başlayın ve iterasyon yapın. Yapay zekânın önemli bir şeyi kaçırdığını fark ederseniz ekleyin. Bağlam şişkin hissediyorsa budayın. Bu yaşayan bir belgedir.

Yardım Gerekli mi? Bu İfadeni Kullanın ​

project.md'nizi nasıl özetleyeceğinizi bilmiyorsanız, yapay zekâ asistanınıza sorun:

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

Yapay zekâ, neyin temel olduğunu ve neyin budanabileceğini belirlemenize yardımcı olacaktır.


Yeni Komutlar ​

Komut kullanılabilirliği profile bağlıdır:

Varsayılan (core profili):

KomutAmaç
/opsx:proposeBir değişiklik oluşturur ve planlama artefaktlarını tek adımda üretir
/opsx:exploreYapılandırmasız fikirleri tartışır
/opsx:applytasks.md'den görevleri uygular
/opsx:updateBir değişikliğin planlama artefaktlarını revize eder ve tutarlı tutar
/opsx:syncDelta spesifikasyonları ana spesifikasyonlara birleştirir
/opsx:archiveDeğişikliği sonlandırır ve arşivler

Genişletilmiş iş akışı (özel seçim):

KomutAmaç
/opsx:newYeni bir değişiklik iskeleti başlatır
/opsx:continueSonraki artefaktı oluşturur (tek seferde bir tane)
/opsx:ffHızlandırma—planlama artefaktlarını bir anda oluşturur
/opsx:verifyUygulamanın spesifikasyonlarla uyumlu olduğunu doğrular
/opsx:bulk-archiveBirden fazla değişikliği bir anda arşivler
/opsx:onboardRehberli uçtan uca başlangıç iş akışı

Genişletilmiş komutları openspec config profile ile etkinleştirin, ardından openspec update çalıştırın.

Eski Komutlardan Eşleme ​

EskiOPSX Karşılığı
/openspec:proposal/opsx:propose (varsayılan) veya /opsx:new ardından /opsx:ff (genişletilmiş)
/openspec:apply/opsx:apply
/openspec:archive/opsx:archive

Yeni Yetenekler ​

Bu yetenekler genişletilmiş iş akışı komut setinin bir parçasıdır.

İnce artefakt oluşturma:

/opsx:continue

Bağımlılıklara göre tek seferde bir artefakt oluşturur. Her adımı gözden geçirmek istediğinizde bunu kullanın.

Keşif modu:

/opsx:explore

Bir değişikliğe karar vermeden önce fikirleri bir ortakla tartışın.


Yeni Mimarı Anlamak ​

Kilitli Fazlardan Akışkana ​

Eski iş akışı doğrusal ilerlemeyi zorunlu kılıyordu:

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

Uygulama aşamasındayken tasarımın yanlış olduğunu fark ettiniz mi?
Çok geç. Faz kapıları geriye dönmenize kolayca izin vermez.

OPSX, fazlar yerine eylemler kullanır:

         ┌───────────────────────────────────────────────┐
         │           EYLEMLER (fazlar değil)             │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                  herhangi bir sırada          │
         └───────────────────────────────────────────────┘

Bağımlılık Grafiği ​

Yapıtlar (artifact'lar) yönlendirilmiş bir grafik oluşturur. Bağımlılıklar kapı değil, kolaylaştırıcılardır:

                        proposal
                       (kök düğüm)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (gerektirir:                 (gerektirir:
         proposal)                    proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (gerektirir:
                     specs, design)

/opsx:continue komutunu çalıştırdığınızda, neyin hazır olduğunu kontrol eder ve bir sonraki yapıtı önerir. Ayrıca herhangi bir sırada birden fazla hazır yapıt oluşturabilirsiniz.

Beceriler ve Komutlar ​

Eski sistem, araca özgü komut dosyaları kullanıyordu:

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

OPSX, gelişmekte olan beceriler (skills) standardını kullanır:

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Beceriler, birden fazla yapay zeka kodlama aracı tarafından tanınır ve daha zengin meta veriler sağlar.

Codex, OPSX'te yalnızca becerileri destekler. OpenSpec artık Codex özel istem dosyaları üretmez; bunun yerine oluşturulan .agents/skills/openspec-* dizinlerini kullanın.


Devam Eden Değişiklikleri Sürdürme ​

Devam eden değişiklikleriniz OPSX komutlarıyla sorunsuz çalışır.

Eski iş akışından aktif bir değişikliğiniz mi var?

/opsx:apply add-my-feature

OPSX mevcut yapıtları okur ve kaldığınız yerden devam eder.

Mevcut bir değişikliğe daha fazla yapıt eklemek mi istiyorsunuz?

/opsx:continue add-my-feature

Zaten var olanlara dayanarak neyin oluşturulmaya hazır olduğunu gösterir.

Durumu görüntülemeniz mi gerekiyor?

bash
openspec status --change add-my-feature

Yeni Yapılandırma Sistemi ​

config.yaml Yapısı ​

yaml
# Zorunlu: Yeni değişiklikler için varsayılan şema
schema: spec-driven

# İsteğe bağlı: Proje bağlamı (en fazla 50KB)
# TÜM yapıt talimatlarına eklenir
context: |
  Proje geçmişiniz, teknoloji yığınınız,
  kurallarınız ve kısıtlarınız.

# İsteğe bağlı: Yapıt başına kurallar
# Yalnızca eşleşen yapıtlara eklenir
rules:
  proposal:
    - Geri alma planı ekleyin
  specs:
    - Given/When/Then biçimini kullanın
  design:
    - Yedek stratejileri belgeleyin
  tasks:
    - En fazla 2 saatlik parçalara bölün

Şema Çözümleme ​

Hangi şemanın kullanılacağını belirlerken OPSX şu sırayla kontrol eder:

  1. CLI bayrağı: --schema <name> (en yüksek öncelik)
  2. Değişiklik meta verisi: Değişiklik dizinindeki .openspec.yaml
  3. Proje yapılandırması: openspec/config.yaml
  4. Varsayılan: spec-driven

Mevcut Şemalar ​

ŞemaYapıtlarEn Uygun Olduğu Yer
spec-drivenproposal → specs → design → tasksÇoğu proje

Tüm mevcut şemaları listele:

bash
openspec schemas

Özel Şemalar ​

Kendi iş akışınızı oluşturun:

bash
openspec schema init my-workflow

Veya mevcut bir tanesini çatallayın:

bash
openspec schema fork spec-driven my-workflow

Ayrıntılar için Özelleştirme bölümüne bakın.


Sorun Giderme ​

"Etkileşimli olmayan modda eski dosyalar algılandı" ​

Bir CI veya etkileşimli olmayan ortamda çalışıyorsunuz. Şunu kullanın:

bash
openspec init --force

Geçişten sonra komutlar görünmüyor ​

IDE'nizi yeniden başlatın. Beceriler başlangıçta algılanır.

"Kurallarda bilinmeyen yapıt kimliği" ​

rules: anahtarlarınızın şemanızın yapıt kimlikleriyle eşleştiğini kontrol edin:

  • spec-driven: proposal, specs, design, tasks

Geçerli yapıt kimliklerini görmek için şunu çalıştırın:

bash
openspec schemas --json

Yapılandırma uygulanmıyor ​

  1. Dosyanın openspec/config.yaml konumunda olduğundan emin olun (.yml değil)
  2. YAML sözdizimini doğrulayın
  3. Yapılandırma değişiklikleri anında geçerli olur—yeniden başlatma gerekmez

project.md taşınmadı ​

Sistem, project.md dosyasını bilinçli olarak korur çünkü özel içeriğinizi barındırabilir. Manuel olarak inceleyin, yararlı kısımları config.yaml dosyasına taşıyın ve ardından silin.

Ne temizleneceğini görmek mi istiyorsunuz? ​

init komutunu çalıştırın ve temizlik istemini reddedin—hiçbir değişiklik yapılmadan tüm algılama özetini görürsünüz.


Hızlı Başvuru ​

Geçiş Sonrası Dosyalar ​

project/
├── openspec/
│   ├── specs/                    # Değişmedi
│   ├── changes/                  # Değişmedi
│   │   └── archive/              # Değişmedi
│   └── config.yaml               # YENİ: Proje yapılandırması
├── .claude/
│   └── skills/                   # YENİ: OPSX becerileri
│       ├── openspec-propose/     # varsayılan çekirdek profili
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # genişletilmiş profil new/continue/ff vb. ekler
├── CLAUDE.md                     # OpenSpec işaretleri kaldırıldı, içeriğiniz korundu
└── AGENTS.md                     # OpenSpec işaretleri kaldırıldı, içeriğiniz korundu

Kaldırılanlar ​

  • .claude/commands/openspec/ — yerini .claude/skills/ aldı
  • openspec/AGENTS.md — kullanımdan kaldırıldı
  • openspec/project.md — config.yaml dosyasına taşıyın, ardından silin
  • CLAUDE.md, AGENTS.md vb. dosyalardaki OpenSpec işaret blokları

Komut Hızlı Başvurusu ​

text
/opsx:propose      Hızlı başlangıç (varsayılan çekirdek profili)
/opsx:apply        Görevleri uygula
/opsx:archive      Bitir ve arşivle

# Genişletilmiş iş akışı (etkinleştirilmişse):
/opsx:new          Değişikliği iskelet olarak oluştur
/opsx:continue     Sonraki yapıtı oluştur
/opsx:ff           Planlama yapıtlarını oluştur

Yardım Alma ​