Sorun Giderme

Somut sorunlar için somut çözümler. Her giriş bir belirtiyi adlandırır, olası nedeni bir cümleyle açıklar ve çözümü sunar. Sorununuz burada yoksa SSS yardımcı olabilir ve Discord kesinlikle yardımcı olacaktır.

Kurulum ve yapılandırma

openspec: command not found

CLI kurulu değil ya da kabuğunuz onu bulamıyor. Küresel olarak kurun ve kontrol edin:

npm install -g @fission-ai/openspec@latest
openspec --version

Kuruldu ama hâlâ bulunamıyorsa, küresel npm bin dizininiz muhtemelen PATH üzerinde değil. Küresel paketlerin nerede olduğunu görmek için npm prefix -g çalıştırın: macOS ve Linux'ta binary'ler o dizinin bin/ altındadır, Windows'ta ise doğrudan o dizin içindedir. O yolun PATH üzerinde olduğundan emin olun. (npm bin -g npm 9'da kaldırıldı.)

EY destekli kurulumu kullandıysanız, bu beklenen devir noktasıdır: o istem, asistanınıza PATH değişikliğini göstermesini söyler, kabuk başlangıç dosyalarınızı kendisi düzenlemesini değil.

"Requires Node.js 20.19.0 or higher"

OpenSpec, Node 20.19.0+ üzerinde çalışır. Sürümünüzü kontrol edin ve gerekirse yükseltin:

node --version

OpenSpec'i bun ile kuruyorsanız, OpenSpec'in yine de Node üzerinde çalıştığını unutmayın; bu nedenle PATH üzerinde Node 20.19.0+ bulunmalıdır. Kurulum bölümüne bakın.

openspec init AI aracımı yapılandırmadı

Init hangi araçların kurulacağını sorar. Aracınızı atladıysanız veya başka bir araç eklemek istiyorsanız, tekrar çalıştırın ya da etkileşimsiz biçimi kullanın:

openspec init --tools claude,cursor

Araç kimliklerinin tam listesi Desteklenen Araçlar sayfasındadır. Her şey için --tools all, araç kurulumunu atlamak için --tools none kullanın.

Komutlar görünmüyor

/opsx:propose (veya aracınızın karşılığı) görünmüyorsa ya da hiçbir şey yapmıyorsa, bu listeyi sırayla kontrol edin. En hızlı kontrol edileceklerden başlayarak sıralanmıştır.

1. Yanlış yerde olabilirsiniz. Slash komutları AI asistanınızın sohbetine yazılır, terminalinize değil. /opsx:propose'u kabuğunuza yazdıysanız sorun budur. Komutlar Nasıl Çalışır bölümüne bakın.

2. Dosyaları yeniden oluşturun. Proje kök dizininden:

   openspec update

   Bu, yapılandırdığınız her araç için beceri ve komut dosyalarını yeniden yazar.

   Talimat dosyaları kurulu CLI'dan gelir, bu nedenle eski bir CLI her şeyin güncel olduğunu bildirir ama asla yeni iş akışlarını yazmaz. openspec update artık bunu kontrol eder ve yükseltme teklif eder — görürseniz teklifi kabul edin.

3. Asistanınızı yeniden başlatın. Çoğu araç, becerileri ve komutları başlangıçta tarar. Yeni bir pencere genellikle işi görür.

4. Dosyaların var olduğunu doğrulayın. Claude Code için .claude/skills/ dizininin openspec-* klasörlerini içerdiğinden emin olun. Diğer araçlar kendi dizinlerini kullanır; tümü Desteklenen Araçlar sayfasında listelenmiştir.

5. Bu projeyi başlattığınızı kontrol edin. Beceriler proje bazlı yazılır. Bir repo klonladıysanız veya klasör değiştirdiyseniz, orada openspec init (veya openspec update) çalıştırın.

6. Aracınızın komut dosyalarını desteklediğini doğrulayın. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent ve ortak .agents hedefi için üretilmiş opsx-* komut dosyaları oluşturulmaz; bunlar beceri tabanlı çağrıları kullanır, bu nedenle /opsx onlar için asla otomatik tamamlanmaz. Codex'te $openspec-propose, Kimi Code'da /skill:openspec-propose, diğerlerinde /openspec-propose yazın. Ortak .agents hedefi satıcıdan bağımsızdır, bu nedenle /openspec-propose ortak biçimdir ama garanti edilmiş değildir — asistanınız buna yanıt vermiyorsa, beceriyi nasıl çağırdığına dair kendi dokümantasyonuna bakın. Amazon Q komut dosyaları alır ama onları slash menüsüne değil, istem kitaplığına yükler — orada /opsx değil @opsx-propose yazın. Her aracın biçimi Nasıl Çağrılır bölümünde listelenmiştir.

Değişikliklerle çalışma

"Change not found"

Komut hangi değişikliği kastettiğinizi anlayamadı. Açıkça adlandırın ya da mevcut olanları kontrol edin:

openspec list                    # aktif değişiklikleri gör
/opsx:apply add-dark-mode        # sohbetinde değişikliği adlandır

Ayrıca doğru proje dizininde olduğunuzdan emin olun.

"No artifacts ready"

Her artefakt ya zaten oluşturulmuş ya da bir bağımlılık üzerinde bekliyor. Ne engellediğini görün:

openspec status --change <name>

Sonra eksik bağımlılığı önce oluşturun. Sırayı unutmayın: öneri, spesifikasyonları ve tasarımı etkinleştirir; spesifikasyonlar ve tasarım birlikte görevleri etkinleştirir.

openspec validate uyarılar veya hatalar bildiriyor

Doğrulama, spesifikasyonlarınızı ve değişikliklerinizi yapısal sorunlar açısından kontrol eder. Mesajı okuyun: dosyayı ve sorunu adlandırır.

openspec validate <name>           # tek bir öğeyi doğrula
openspec validate --all            # her şeyi doğrula
openspec validate --all --strict   # daha sıkı kontroller, CI için uygun
openspec validate --archived       # arşivlenmiş değişikliklerde kontrol edilmemiş görev varsa hata ver

Yaygın nedenler eksik zorunlu bir bölüm (örneğin senaryosu olmayan bir spesifikasyon) veya biçimsiz bir delta başlığıdır. Dosyayı düzeltin ve yeniden çalıştırın. CLI referansı çıktı biçimini belgelemektedir.

Bir mesaj kendi notunu hak ediyor:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

MODIFIED gereksinimi tüm gereksinim bloğunu değiştirir, bu nedenle değişikliği hayatta kalan her senaryoyu taşımalıdır, yalnızca düzenlediklerinizi değil. Adlandırılan senaryoları openspec/specs/<capability-path>/spec.md dosyasından delta'ya geri kopyalayın, yoldaki alan dizinlerini koruyarak. Bu genellikle birinin aynı gereksinime senaryo eklediği eski bir değişikliğin üzerinde ortaya çıkar — arşivleme her halükârda o değişikliği reddeder ve doğrulama artık bunu uygulamadan önce söyler.

AI eksik veya yanlış artefaktlar oluşturdu

AI'nin yeterli bağlamı yoktu. Birkaç kaldıraç yardımcı olur:

• openspec/config.yaml dosyasına proje bağlamı ekleyin, böylece yığınız ve kurallarınız her isteğe enjekte edilir. Özelleştirme bölümüne bakın.
• Yalnızca belirli artefaktlara uygulanan yönlendirme için artefakt başına rules: ekleyin.
• Öneri sunarken daha ayrıntılı bir açıklama verin.
• /opsx:ff ile hepsini birden yapmak yerine, genişletilmiş /opsx:continue ile birer birer artefakt oluşturun ve her birini inceleyin.

Arşivleme bitmiyor veya eksik görevler hakkında uyarı veriyor

Arşivleme eksik görevler nedeniyle engel olmaz ama uyarı verir, çünkü arşivleme genellikle işin bittiği anlamına gelir. Görevler bilinçli olarak kaldıysa (kısmi bir değişiklik dosyalıyorsanız), devam edin. Aksi halde önce görevleri tamamlayın. Arşivleme ayrıca henüz senkronize etmediyseniz delta spesifikasyonlarınızı ana spesifikasyonlara senkronize etmeyi teklif eder; bir nedeniniz yoksa evet deyin.

"User force closed the prompt with 0 null"

Bir şey, soruya yanıt verilemeyecek bir yerde openspec archive çalıştırdı — bir araçtan çağıran bir AI ajanı, bir CI işi veya stdin kapalı herhangi bir kabuk. Arşivleme en fazla üç onay sorar ve yanıtlanamayan bir soru eskiden o ham mesajla başarısız olurdu.

Önceden yanıt vermek için --yes geçin:

openspec archive <change-name> --yes

Zaten geçiyorsanız bayrakları koruyun — --skip-specs ve --no-validate arşivlemenin ne yaptığını değiştirir, bu nedenle çıplak --yes yeniden çalıştırması aynı komut değildir. Güncel sürümler bayrağı sizin için adlandırır ve yapıştırabileceğiniz bir Fix: satırı basar. Bir listeden seçim yapmak istediyseniz, değişiklik adını açıkça geçin: seçici de bir yanıt gerektirir.

Bunun yerine arşivlemeyi çıktısı bir dosyaya yönlendirilmiş veya bir araç tarafından yakalanmış olarak çalıştırdıysanız ve gerçekten bir yanıt boruladınız (printf 'y\n' | openspec archive …), eski sürümler istemi çizerken terminal kaçış kodlarını o yakalamaya yazardı — bazı ortamlarda dosyayı ciddi şekilde şişirecek kadar. Güncel sürümler stdout bir terminal değilse onay istemlerini düz metin olarak okur ve argümansız openspec archive (aksi halde etkileşimli bir değişiklik seçicisi çizecekti) yerine bir menü çizmek yerine değişiklik adını önceden geçmenizi ister. Her halükârda yönlendirilmiş ve ajan çalıştırmaları temiz kalır; --yes (bir değişiklik adı ile) geçmek istemleri tamamen atlar.

Yapılandırma

config.yaml dosyam uygulanmıyor

Üç yaygın şüpheli:

1. Yanlış dosya adı. openspec/config.yaml olmalı, .yml değil.
2. Geçersiz YAML. Herhangi bir YAML doğrulayıcıdan geçirin; CLI ayrıca satır numaralarıyla sözdizimi hatalarını bildirir.
3. Yeniden başlatma beklediniz. Gerekli değil. Yapılandırma değişiklikleri anında geçerli olur.

"Unknown artifact ID in rules: X"

rules: altındaki bir anahtar, şemanızdaki hiçbir artefaktla eşleşmiyor. Varsayılan spec-driven şeması için geçerli kimlikler proposal, specs, design, tasks'tır. Herhangi bir şema için kimlikleri görmek:

openspec schemas --json

"Context too large"

context: alanı her isteğe enjekte edildiği için bilinçli olarak 50KB ile sınırlıdır. Özetleyin veya uzun belgeleri yapıştırmak yerine bağlantı verin. Daha az bağlam aynı zamanda daha iyi ve daha hızlı sonuçlar üretir.

"Schema not found"

Bağvunduğunuz şema adı mevcut değil. Mevcut olanları listeleyin ve yazımı kontrol edin:

openspec schemas                    # mevcut şemaları listele
openspec schema which <name>        # bir şemanın nereden çözümlendiğini gör
openspec schema init <name>         # özel bir şema oluştur

Özelleştirme bölümüne bakın.

Eski iş akışından geçiş

"Legacy files detected in non-interactive mode"

CI'da veya etkileşimsiz bir kabukta olduğunuz ve OpenSpec temizlenecek eski dosyalar buldu ama size soru soramıyor. Otomatik olarak onaylayın:

openspec init --force

Codex için OpenSpec, $CODEX_HOME/prompts veya ~/.codex/prompts dizinlerinde eski yönetilen istem dosyaları tespit edebilir. Bu temizlik yalnızca OpenSpec'in izin listesindeki eski Codex istem dosya adlarıyla sınırlıdır ve etkileşimsiz openspec init yalnızca yerine geçen .agents/skills/openspec-* becerilerinin mevcut olduğu dosyaları kaldırır. Etkileşimsiz openspec update, --force geçmediğiniz sürece tüm eski temizliği dokunmadan bırakır.

Geçişten sonra komutlar görünmedi

IDE'nizi yeniden başlatın. Beceriler başlangıçta tespit edilir. Hâlâ görünmüyorsa openspec update çalıştırın ve Desteklenen Araçlar sayfasındaki dosya konumlarını kontrol edin.

Eski project.md dosyam taşınmadı

Bu bilinçli bir karardır. OpenSpec, project.md dosyasını otomatik olarak asla silmez çünkü yazdığınız bağlamı barındırıyor olabilir. Faydalı kısımları config.yaml'in context: bölümüne taşıyın, ardından kendiniz silin. Geçiş Kılavuzu bunu adım adım anlatır, AI'ınıza damıtma işini yaptırabileceğiniz bir istem de dahil.

Hâlâ takıldınız mı?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Terminalinizden: openspec feedback "what went wrong" sizin için bir sorun açar.

Bir sorun bildirdiğinizde OpenSpec sürümünüzü (openspec --version), Node sürümünüzü (node --version), AI aracınızı ve tam komutu ile çıktıyı ekleyin. Yardım çok daha hızlı olur.