OpenSpec

Sözlük ​

Her OpenSpec terimi tek bir yerde, düz bir dille tanımlanmıştır. Bir kez göz atın, kalan belgeler çok daha hızlı okunur.

Terimler konu bazında gruplandırılmış, her grup içinde alfabetik sıralanmıştır.

Temel isimler ​

Spec. Sisteminizin bir kısmının nasıl davrandığını açıklayan bir belgedir. Spec'ler openspec/specs/ dizininde bulunur, alan bazında organize edilir ve gereksinimler ile senaryolardan oluşur. Spec, "bu yazılım ne yapıyor?" sorusunun üzerinde uzlaşılmış cevabıdır. Bkz. Concepts.

Source of truth. Bütünüyle openspec/specs/ dizini. Sisteminizin güncel, üzerinde uzlaşılmış davranışını barındırır. Değişiklikler bu dizine düzenleme önerir; arşivleme bunları uygular.

Change. openspec/changes/<name>/ altında bir klasör olarak paketlenmiş tek bir iş birimi. Bir change, o işle ilgili her şeyi barındırır: önerisi, tasarımı, görevleri ve getirdiği spec düzenlemeleri. Bir change, bir özellik veya düzeltme.

Artifact. Bir change içindeki bir belge. Standart artifact'ler öneri, delta spec'ler, tasarım ve görevlerdir. Bağımlılık sırasına göre oluşturulurlar ve birbirine besleme sağlarlar.

Delta spec. Bir change içinde yalnızca neyin değiştiğini ADDED, MODIFIED ve REMOVED bölümleri kullanarak açıklayan, tüm spec'i yeniden ifade etmeyen bir spec. OpenSpec'in mevcut sistemleri temiz bir şekilde düzenlemesini sağlayan şey budur. Bkz. Concepts.

Domain. Spec'ler için mantıksal bir gruplandırma, örneğin auth/, payments/ veya ui/. Sisteminizi nasıl düşündüğünüze uygun domain'ler seçersiniz.

Bir spec'in içinde ​

Requirement. Sistemin sahip olması gereken tek bir davranış, genellikle RFC 2119 anahtar sözcüğüyle yazılır: "The system SHALL expire sessions after 30 minutes." Gereksinimler neyi belirtir, nasılını değil.

Scenario. Bir gereksinimin somut, test edilebilir bir örneği, tipik olarak Given/When/Then biçiminde. Senaryolar bir gereksinimi doğrulanabilir kılar: birinden otomatik bir test yazabilirsiniz.

RFC 2119 keywords. Bir gereksinimin ne kadar katı olduğunu standartlaştırılmış anlamıyla taşıyan MUST, SHALL, SHOULD ve MAY kelimeleri. MUST ve SHALL mutlak anlam taşır. SHOULD istisnaya yer bırakarak öneri niteliğindedir. MAY isteğe bağlıdır. İsim, bunları tanımlayan internet standartları belgesinden gelir.

Artifact'ler ​

Proposal (proposal.md). Bir change'in nedeni ve neyi: niyeti, kapsamı ve yüksek düzey yaklaşımı. Oluşturacağınız ilk artifact.

Design (design.md). Nasıllığı: teknik yaklaşım, mimari kararlar ve dokunmayı planladığınız dosyalar. Basit değişiklikler için isteğe bağlıdır.

Tasks (tasks.md). Onay kutuları içeren uygulama kontrol listesi. AI, /opsx:apply sırasında bunu işler ve ilerledikçe maddeleri işaretler.

Yaşam döngüsü ​

Archive. Bir change'i tamamlama eylemi. Delta spec'leri ana spec'lere birleştirilir ve change klasörü openspec/changes/archive/YYYY-MM-DD-<name>/ dizinine taşınır. Arşivlemeden sonra spec'leriniz yeni gerçekliği tanımlar. Bkz. Concepts.

Sync. Bir change'in delta spec'lerini change'i arşivlemeden ana spec'lere birleştirme. Genellikle otomatik yapılır (arşivleme bunu önerir), ancak uzun süren değişiklikler için /opsx:sync olarak ayrı kullanılabilir. Bkz. Commands.

İş akışı ve komutlar ​

OPSX. Akışkan eylemler etrafında şekillenen, katı aşamalardan uzak mevcut standart OpenSpec iş akışı. Slash komutlarının tümü /opsx: ile başlar. Bkz. OPSX Workflow.

Slash command. AI asistanınızın sohbetine yazdığınız bir komut, örneğin /opsx:propose. Slash komutları iş akışını yönlendirir. Terminal komutları değildir. Bkz. How Commands Work.

Explore (/opsx:explore). Düşünme ortağı komutu. Kod tabanınızı okur, seçenekleri karşılaştırır ve bulanık bir fikri somut bir plana dönüştürür; hiçbir artifact oluşturmaz ve kod yazmaz. Bir sorununuz ama henüz planınız yoksa önerilen başlangıç noktasıdır. Bkz. Explore First.

CLI. Terminalinizde çalıştırdığınız openspec programı. Projeleri kurar, değişiklikleri listeler ve doğrular, paneli açar ve arşivler. OpenSpec'in terminal tarafı. Bkz. CLI.

Skill. AI asistanınızın otomatik algılayıp takip ettiği talimat klasörü (.../skills/openspec-*/SKILL.md). Skills, OpenSpec iş akışını asistanınıza sunmak için ortaya çıkan araçlar arası standarttır.

Command file. Araç başına slash komut dosyası (.../commands/opsx-*). Daha eski dağıtım mekanizması, skills ile birlikte hâlâ desteklenmektedir. Bunlara doğrudan nadiren dokunursunuz.

Profile. Projenizde kurulu slash komut seti. Core (varsayılan) propose, explore, apply, update, sync, archive içerir. Genişletilmiş set new, continue, ff, verify, bulk-archive, onboard ekler. openspec config profile ile değiştirilir.

Delivery. OpenSpec'in araçlarınız için skills, command file veya her ikisini kurup kurmayacağı. Küresel olarak yapılandırılır ve openspec update ile uygulanır.

Özelleştirme ​

Schema. Bir iş akışının hangi artifact'lere sahip olduğunu ve bunların birbirine nasıl bağımlı olduğunu tanımlayan yapı. Yerleşik varsayılan spec-driven'dır (proposal → specs → design → tasks). Çatalını alabilir veya kendiniz yazabilirsiniz. Bkz. Customization.

Template. Bir schema içinde, AI'ın belirli bir artifact için ürettiğini şekillendiren Markdown dosyası. Bir template'i düzenlemek, yeniden derleme gerektirmeden AI çıktısını anında değiştirir.

Project config (openspec/config.yaml). Proje bazlı ayarlar: varsayılan schema, her planlama isteğine enjekte edilen context: ve artifact başına rules:. OpenSpec'e yığınınızı ve konvansiyonlarınızı öğretmenin en kolay yolu. Bkz. Customization.

Context injection. Proje arka planını config.yaml'in context: alanına koymak, böylece AI'ın ürettiği her artifact'e otomatik olarak eklenir. AI'ın ayrı bir dosya okumasını ummaktan daha güvenilirdir.

Dependency graph. Artifact requires: ilişkileri tarafından oluşturulan yönlü graf. Bir DAG'dır (yönlü döngüsüz graf: oklar yalnızca ileriye işaret eder, asla döngü oluşturmaz) ve OpenSpec bunu sıradaki oluşturabileceğiniz şeyi bilmek için kullanır.

Enablers, not gates. Artifact bağımlılıklarının sıradaki mümkün olanı gösterdiğini, zorunlu olanı değil gösterdiğini ifade eden ilke. Herhangi bir artifact'e istediğiniz zaman geri dönüp düzenleme yapabilirsiniz. Bkz. Core Concepts at a Glance.

Depolar arası koordinasyon (beta) ​

Bu terimler yalnızca planlamanız birden fazla depoyu kapsıyorsa geçerlidir. Beta aşamasındadır. Çoğu kullanıcı bunları görmezden gelebilir. Bkz. Stores User Guide.

Store. Tek işi planlama olan bağımsız bir depo. Zaten bildiğiniz openspec/ yapısına sahiptir (specs ve changes) ve küçük bir kimlik dosyası içerir. Makinenizde bir kez adıyla kaydeder, ardından herhangi bir OpenSpec komutu her yerden içinde çalışabilir.

Reference. Bir kod deposunun openspec/config.yaml dosyasında, o depoyu besleyen bir store'ın beyanı. Referanslar salt okunurdur: depo kendi kökünü korur ve openspec instructions, referans verilen store'ın spec'lerinin indeksini ve her biri için tam olarak nasıl alınacağını gösteren komutu ekler.

Working context. openspec context'in mevcut depo için derlediği şey: OpenSpec kökü ve referans verdiği her store, her biri nasıl alınacağını göstererek. "Ne üzerinde çalışıyorum?" sorusunun cevabı.

Workset. Birlikte açtığınız kişisel, makineye özgü klasör seti (çalıştığınız kod depoları yanında bir store). openspec workset create ile açıkça oluşturulur; o yerel yollar hakkında hiçbir şey paylaşılan planlama deposuna commit edilmez.

Ayrıca bkz. ​