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:
| Özellik | Eski | OPSX |
|---|---|---|
| Komutlar | /openspec:proposal, /openspec:apply, /openspec:archive | Varsayı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ştur | Artı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ştirme | Sabit yapı | Şema tabanlı, tamamen özelleştirilebilir |
| Yapılandırma | İşaretçilerle CLAUDE.md + project.md | openspec/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:
| Ne | Neden |
|---|---|
| Eski slash komut dizinleri/dosyaları | Yeni beceri sistemi tarafından değiştirildi |
openspec/AGENTS.md | Artık geçerli olmayan iş akışı tetikleyicisi |
CLAUDE.md, AGENTS.md vb. dosyalardaki OpenSpec işaretçileri | Artı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/skillsyolu altındaki OpenSpec yönetimliSKILL.mddosyaları yalnızca yer değiştirmeler mevcut olduktan sonra uzlaştırılır; özel dosyalar ve farklı kopyalar yerinde kalır. İşaretlenmemiş bir.agentsağ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çinopenspec initilecodexseçeneğini açıkça seçin. Eski prompt temizliği hâlâ yalnızca$CODEX_HOME/promptsveya~/.codex/promptsiç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:
- İçeriğini gözden geçirin
- Faydalı bağlamı
openspec/config.yamldosyasına taşıyın (aşağıdaki yönergelere bakın) - 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
coreprofili kullanır (propose,explore,apply,update,sync,archive). - Göç edilen kurulumlar, gerekli olduğunda
customprofili 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:
openspec initInit 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:
- Eski slash komut dizinleri kaldırılır
- OpenSpec işaretçileri
CLAUDE.md,AGENTS.mdvb. dosyalardan soyulur (içeriğiniz kalır) openspec/AGENTS.mdsilinir- Yeni beceriler
.claude/skills/dizinine kurulur - Varsayılan şema ile
openspec/config.yamloluş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:
openspec updateUpdate 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:
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)
# 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 specificationsSonra (config.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 flowsTemel Farklar
| project.md | config.yaml |
|---|---|
| Serbest biçimli markdown | Yapılandırılmış YAML |
| Tek bir metin bloğu | Ayrı bağlam ve artefakt başına kurallar |
| Ne zaman kullanıldığı belirsiz | Bağlam TÜM artefaktlarda görünür; kurallar yalnızca eşleşen artefaktlarda görünür |
| Şema seçimi yok | Açı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ı
config.yaml oluşturun (init tarafından henüz oluşturulmadıysa):
yamlschema: spec-drivenBağlamınızı ekleyin (kısa tutun—bu her isteğe gider):
yamlcontext: | Your project background goes here. Focus on what the AI genuinely needs to know.Artefakt başına kurallar ekleyin (isteğe bağlı):
yamlrules: proposal: - Your proposal-specific guidance specs: - Your spec-writing rulesproject.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):
| Komut | Amaç |
|---|---|
/opsx:propose | Bir değişiklik oluşturur ve planlama artefaktlarını tek adımda üretir |
/opsx:explore | Yapılandırmasız fikirleri tartışır |
/opsx:apply | tasks.md'den görevleri uygular |
/opsx:update | Bir değişikliğin planlama artefaktlarını revize eder ve tutarlı tutar |
/opsx:sync | Delta spesifikasyonları ana spesifikasyonlara birleştirir |
/opsx:archive | Değişikliği sonlandırır ve arşivler |
Genişletilmiş iş akışı (özel seçim):
| Komut | Amaç |
|---|---|
/opsx:new | Yeni bir değişiklik iskeleti başlatır |
/opsx:continue | Sonraki artefaktı oluşturur (tek seferde bir tane) |
/opsx:ff | Hızlandırma—planlama artefaktlarını bir anda oluşturur |
/opsx:verify | Uygulamanın spesifikasyonlarla uyumlu olduğunu doğrular |
/opsx:bulk-archive | Birden fazla değişikliği bir anda arşivler |
/opsx:onboard | Rehberli 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
| Eski | OPSX 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:continueBağı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:exploreBir 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.mdOPSX, 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-featureOPSX 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-featureZaten var olanlara dayanarak neyin oluşturulmaya hazır olduğunu gösterir.
Durumu görüntülemeniz mi gerekiyor?
openspec status --change add-my-featureYeni Yapılandırma Sistemi
config.yaml Yapısı
# 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:
- CLI bayrağı:
--schema <name>(en yüksek öncelik) - Değişiklik meta verisi: Değişiklik dizinindeki
.openspec.yaml - Proje yapılandırması:
openspec/config.yaml - Varsayılan:
spec-driven
Mevcut Şemalar
| Şema | Yapıtlar | En Uygun Olduğu Yer |
|---|---|---|
spec-driven | proposal → specs → design → tasks | Çoğu proje |
Tüm mevcut şemaları listele:
openspec schemasÖzel Şemalar
Kendi iş akışınızı oluşturun:
openspec schema init my-workflowVeya mevcut bir tanesini çatallayın:
openspec schema fork spec-driven my-workflowAyrı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:
openspec init --forceGeç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:
openspec schemas --jsonYapılandırma uygulanmıyor
- Dosyanın
openspec/config.yamlkonumunda olduğundan emin olun (.ymldeğil) - YAML sözdizimini doğrulayın
- 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 korunduKaldırılanlar
.claude/commands/openspec/— yerini.claude/skills/aldıopenspec/AGENTS.md— kullanımdan kaldırıldıopenspec/project.md—config.yamldosyasına taşıyın, ardından silinCLAUDE.md,AGENTS.mdvb. dosyalardaki OpenSpec işaret blokları
Komut Hızlı Başvurusu
/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şturYardım Alma
- Discord: discord.gg/YctCnvvshC
- GitHub Sorunları: github.com/Fission-AI/OpenSpec/issues
- Dokümantasyon: Tam OPSX başvurusu için docs/opsx.md