SSS

En sık sorulan sorulara hızlı yanıtlar. Sorunuz gerçekten "bir şey bozuk" sorusuysa, Sorun Giderme sayfası daha uygun. Bir terimin tanımını görmek istiyorsanız, Terimler Sözlüğü sayfasına bakın.

Temeller

OpenSpec nedir, tek cümleyle?

Herhangi bir kod yazılmadan önce, sizin ve yapay zekâ kodlama asistanınızın ne inşa edileceği konusunda yazılı olarak anlaşmasını sağlayan hafif bir katmandır.

Neden buna ihtiyacım olsun?

Çünkü yapay zekâ asistanları yanlış olduklarında bile kendinden emindir. Gereksinimler yalnızca bir sohbet dizisinde kaldığında, yapay zekâ boşlukları tahminlerle doldurur ve siz bunu kod zaten var olduktan sonra fark edersiniz. OpenSpec anlaşmayı daha öncesine taşır, hataların düzeltilmesinin ucuz olduğu noktaya. Tam gerekçesi için Genel Bakış: Temel Kavramlar sayfasına bakın.

Her şey için kullanmak zorunda mıyım?

Hayır. Anlaşmanın önemli olduğu yerlerde kullanın, bu da çoğu basit olmayan iş için geçerlidir. Tek karakterlik bir yazım hatası düzeltmesinde bu tören muhtemelen değmez, ve bu gayet normaldir.

Büyük mevcut bir kod tabanında kullanabilir miyim, yoksa sadece yeni projeler için mi?

Mevcut kod tabanları asıl odak noktasıdır. OpenSpec mevcut projeler için tasarlanmıştır: tüm uygulamanızı baştan belgelemek zorunda değilsiniz. Yalnızca her değişikliğin dokunduğu yerler için spesifikasyon yazarsınız ve spesifikasyonlarınız zamanla gerçekten yaptığınız işin etrafında şekillenir. Özel bir rehber vardır: Mevcut Bir Projede OpenSpec Kullanımı.

Tek bir yapay zekâ aracına bağlı mı?

Hayır. OpenSpec, Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex ve daha fazlası dahil 30+ asistanla çalışır. Tam liste ve araç başına detaylar Desteklenen Araçlar sayfasındadır.

Komutlar

/opsx:propose komutunu nereye yazıyorum?

Yapay zekâ asistanınızın sohbetine, terminalinize değil. Bu en sık karıştırılan nokta olduğu için kendi sayfasına sahip: Komutlar Nasıl Çalışır. Kısa versiyonu: openspec ... terminalde çalışır, /opsx:... sohbette çalışır.

"Etkileşimli modu" nasıl başlatırım?

Başlatılacak ayrı bir mod yok. Yapay zekâ asistanınızı normal şekilde açıp sohbetine bir slash komutu yazarsınız. Slash komutu, OpenSpec'e "girmenin" yoludur. (Gerçekten etkileşimli tek terminal özelliği openspec viewdur, spesifikasyonları ve değişiklikleri gözden geçirmek için bir panel.) Tam açıklama Komutlar Nasıl Çalışır sayfasındadır.

Bir slash komutu yazdım ama hiçbir şey olmadı. Neden?

En olası durum, terminalde yazdınız ama yapay zekâ sohbetinde yazmadınız, aracınızın tanımadığı bir yazım kullandınız ya da komutlar henüz yüklenmedi. Dosyalar eksikse — ya da aracı hiç kurmadıysanız — openspec init çalıştırın; openspec update yalnızca zaten var olan dosyaları yeniler. Ardından asistanınızı yeniden başlatın ve "Başlangıç" altında yazdırılan biçimi kullanın — bkz. Nasıl Çağrılır. Sorun Giderme sayfasında tam kontrol listesi vardır.

Neden bir araçta sözdizimi /opsx:propose, diğerinde /opsx-propose?

Her yapay zekâ aracı özel komutları biraz farklı şekilde sunar ve OpenSpec, aracınızın yazdığı dosyayı yüklediği şekilde yazar. opsx-propose.md adlı bir komut dosyası /opsx-propose olarak yazılır; commands/opsx/ altında dosyalanan bir komut ise /opsx:propose olarak yazılır. Komut yerine beceri kullanan araçlar beceri adını kullanır — Codex $openspec-propose, Kimi Code /skill:openspec-propose gerektirir. openspec init "Başlangıç" satırı, seçtiğiniz araçlar için doğru biçimi zaten yazdırır; tam tablo Nasıl Çağrılır sayfasındadır.

Beceri ile komut arasındaki fark nedir?

Her ikisi de OpenSpec'in asistanınızın iş akışını çalıştırabilmesi için yazdığı dosyalardır. Beceriler (.../skills/openspec-*/SKILL.md) daha yeni araçlar arası standarttır; komutlar (.../commands/opsx-*) eski araç başına slash dosyalarıdır. Seçim yapmanıza gerek yok. Sadece slash komutunu yazarsınız ve OpenSpec, aracınızın kullandığı olanı yükler.

İş Akışı

Ne inşa edeceğimden emin değilsem nereden başlamalıyım?

/opsx:explore ile. Bu, herhangi bir değişiklik veya kod var olmadan önce kod tabanınızı okuyan, seçenekleri ortaya koyan ve belirsiz bir problemi somut bir plana dönüştüren riski olmayan bir düşünce ortağıdır. Varsayılan profilde olduğu için her zaman kullanılabilir. Plan netleştiğinde /opsx:propose'a devreder. Bu, en iyi edinilecek alışkanlıktır çünkü hevesli bir yapay zekânın yanlış şeyi güvenle inşa etmesini engeller. Bkz. Önce Keşfet.

En basit akış nedir?

/opsx:explore (isteğe bağlı)   ardından   /opsx:propose <ne istediğiniz>   ardından   /opsx:apply   ardından   /opsx:archive

Düşünmek için keşfet, planı taslaklamak için öner, inşa etmek için uygula, arşivlemek için dosyala. Tam olarak ne istediğinizi zaten biliyorsanız keşfet adımını atlayın.

/opsx:propose ile /opsx:new arasındaki fark nedir?

/opsx:propose varsayılan tek adımlı komuttur: değişikliği oluşturur ve tüm planlama artefaktlarını aynı anda taslaklar. /opsx:new genişletilmiş komut setinin bir parçasıdır ve yalnızca boş bir değişiklik iskeleti oluşturur, artefaktları /opsx:continue ile tek tek (ya da /opsx:ff ile hepsini birden) oluşturmanızı bırakır. Adım adım kontrol istemedikçe propose kullanın. Bkz. Komutlar.

core ve genişletilmiş profiller nedir?

Bir profil, hangi slash komutlarının yükleneceğini belirler. Core (varsayılan) size propose, explore, apply, update, sync, archive verir. Genişletilmiş set new, continue, ff, verify, bulk-archive ve onboard ekler, daha ince kontrol için. openspec config profile ile değiştirin, ardından openspec update ile uygulayın.

/opsx:sync çalıştırmam gerekiyor mu?

Genellikle hayır. Sync, bir değişikliğin delta spesifikasyonlarını ana spesifikasyonlarınıza birleştirir ve /opsx:archive bunu sizin için yapmayı teklif eder. Yalnızca arşivlemeden önce spesifikasyonların birleştirilmesini istediğinizde manuel olarak çalıştırın, örneğin uzun süreli bir değişiklikte. Bkz. Komutlar.

Başladıktan sonra bir öneri, spesifikasyon veya görevi nasıl düzenlerim?

Dosyayı düzenleyin. Her artefakt openspec/changes/<name>/ altında düz Markdown'dır ve kilitli bir aşama ya da özel düzenleme modu yoktur. Elle değiştirin ya da yapay zekânızı revize etmesini isteyin ("tasarımı kuyruk kullanacak şekilde güncelle"), ardından devam edin. Yapay zekâ her zaman mevcut dosya içeriğinden çalışır. Tam rehber: Bir Değişikliği Düzenleme ve İterasyon.

Bir kısmını uyguladıktan sonra plana geri dönüp değiştirebilir miyim?

Evet, her zaman. İş akışı akışkandır, bu yüzden gözden geçirme ve düzenleme kilitli kaldığınız aşamalar değildir. Artefaktı düzenleyin, ardından devam edin. Kodun hâlâ plana uyup uymadığını yapılandırılmış olarak kontrol etmek istiyorsanız /opsx:verify çalıştırın. Bkz. Bir Değişikliği Düzenleme ve İterasyon.

Kodu elle düzenledim. Spesifikasyonla nasıl uyumlu hale getiririm?

Arşivlemeden önce ikisini senkronize edin, çünkü arşivleme spesifikasyonlarınızı gerçek kaynağı yapar. Eğer kod artık doğruysa, gönderdiğiniz şeyle eşleşecek şekilde delta spesifikasyonu güncelleyin; eğer spesifikasyon doğruysa, kod uyana kadar inşa etmeye devam edin. /opsx:verify uyumsuzlukları ortaya çıkarır. Bkz. Bir Değişikliği Düzenleme ve İterasyon.

Mevcut bir değişikliği ne zaman güncellemeliyim, ne zaman yenisini başlatmalıyım?

Aynı işin rafine edilmiş hâliyse güncelleyin. Niyet köklü biçimde değiştiyse ya da kapsam farklı işlere patladıysa sıfırdan başlayın. İş Akışları sayfasında karar akış şeması ve örnekler vardır.

Oturumum bağlamı dolarsa ya da gereksinimler uygulama sırasında değişirse ne olur?

İşte spesifikasyonların değerini kanıtladığı yer. Plan dosyalarda yaşadığı için (yalnızca sohbet geçmişinde değil), bağlamınızı temizleyebilir, taze bir yapay zekâ oturumu başlatabilir ve /opsx:apply ile devam edebilirsiniz; artefaktları okur ve ilk işaretlenmemiş görevden devam eder. Gereksinimler değişirse, artefaktları yeni gerçeklikle eşleşecek şekilde düzenleyin ve devam edin. Temiz bir bağlam penceresi ayrıca daha iyi sonuçlar üretir; uygulamadan önce temizleyin.

openspec/ klasörünü git'e commit etmeli miyim?

Evet. Spesifikasyonlarınız, aktif değişiklikleriniz ve arşiviniz projenin geçmişinin bir parçasıdır. Diğer kaynaklar gibi commit edin. Arşiv özellikle sisteminizin neden bu şekilde çalıştığının kalıcı bir kaydı haline gelir.

Spesifikasyonlar ve değişiklikler

Spesifikasyonda ne olur, tasarımda ne?

Spesifikasyon gözlemlenebilir davranışı açıklar: sistemin ne yaptığını, girdilerini, çıktılarını ve hata koşullarını. Tasarım nasıl inşa edileceğini açıklar: teknik yaklaşım, mimari kararlar, dosya değişiklikleri. Uygulama dışarıdan görünen davranışı değiştirmeden değişebiliyorsa, bu tasarıma ait, spesifikasyona değil. Kavramlar daha derinlemesine ele alır.

Delta spesifikasyon nedir?

Tüm spesifikasyonu yeniden ifade etmek yerine, yalnızca değişenleri ADDED, MODIFIED ve REMOVED bölümleriyle açıklayan bir spesifikasyondur. OpenSpec'in mevcut sistemlerdeki düzenlemeleri temiz biçimde ele almasının yoludur. Bkz. Kavramlar.

Arşivlenen değişiklikler nereye gider?

openspec/changes/archive/YYYY-MM-DD-<name>/ dizinine, tüm değişiklik artefaktları korunarak. Değişiklik aktif listenizden çıkar. retire_capabilities: true açıkça bildiren bir değişiklik, o yeteneğin son gereksinimini kaldırdığında ana yetenek spesifikasyonunu da silebilir.

Yapılandırma ve özelleştirme

Yapay zekâya teknoloji yığmamı nasıl anlatırım?

openspec/config.yaml dosyasına context: altına koyun. Bu metin her planlama isteğine enjekte edilir, böylece yapay zekâ her zaman yığmanızı ve kurallarınızı bilir. Bkz. Özelleştirme.

İngilizce dışında başka bir dilde spesifikasyon üretebilir miyim?

Evet. Yapılandırmanızın context: kısmına bir dil talimatı ekleyin. Çok Dilli sayfasında birkaç dil için kopyala-yapıştır parçaları vardır.

İş akışının kendisini değiştirebilir miyim?

Evet, özel şemalarla. Bir şema hangi artefaktların var olduğunu ve bunların birbirine nasıl bağımlı olduğunu tanımlar. Varsayılanı openspec schema fork spec-driven my-workflow ile çatallayın, ardından düzenleyin. Bkz. Özelleştirme.

Modeller, gizlilik ve yükseltmeler

Hangi yapay zekâ modelini kullanmalıyım?

OpenSpec, yüksek akıl yürütme modelleriyle en iyi sonucu verir. README, hem planlama hem uygulama için Codex 5.5 ve Opus 4.7 gibi modelleri önerir. Ayrıca bağlam pencerenizi temiz tutun: en iyi sonuçlar için uygulamadan önce temizleyin.

OpenSpec veri toplar mı?

Anonim kullanım istatistikleri toplar: yalnızca komut adları ve sürüm. Argüman, yol, içerik veya kişisel veri yok ve CI ortamında otomatik olarak kapalıdır. export OPENSPEC_TELEMETRY=0 veya export DO_NOT_TRACK=1 ile devre dışı bırakabilirsiniz.

Nasıl yükseltirim?

İki adım. Paketi yükseltin (npm install -g @fission-ai/openspec@latest), ardından her projede openspec update çalıştırarak üretilen becerileri ve komutları yenileyin.

OpenSpec'i nasıl kaldırırım?

Kaldırma komutu yoktur, çünkü yalnızca küresel bir paket ve projenizdeki dosyalardır. Paketi kaldırın (npm uninstall -g @fission-ai/openspec), isteğe bağlı olarak openspec/ dizinini ve üretilen araç dosyalarını silin. Adım adım, neyin güvenli şekilde tutulabileceği dahil, Kurulum: Kaldırma sayfasındadır.

Yardım alma

Sorularımı nereye sorarım veya hataları nereye bildiririm?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Terminalinizden: openspec feedback "mesajınız" sizin için bir GitHub issue açar.

Bu belgeler yanlış ya da kafa karıştırıcı. Ne yapmalıyım?

Bize söyleyin ya da düzeltin. Belgeleme PR'ları hoş karşılanır ve değerlidir. Bir issue açın ya da pull request gönderin.