İyi Spesifikasyonlar Yazmak

Bir spesifikasyonu nadiren boş bir sayfadan yazarsınız. Değişikliği düz bir dille tanımlar, /opsx:propose gereksinimleri ve senaryoları taslak olarak oluşturur, sonra onları iyi hale getirirsiniz. Bu sayfa, işte o son kısımla ilgilidir — "iyi"nin ne olduğu ve yapay zekayı buna nasıl yönlendireceğiniz.

Değişiklik İnceleme sayfasının tamamlayıcısıdır: inceleme, taslaktaki zayıf noktaları yakalamak, yazmak ise güçlü olanın nelerden oluştuğunu bilmektir.

Spesifikasyon davranıştır, kod değil

Bir spesifikasyon, sisteminizin ne yaptığını, kodun nasıl inşa edildiğini değil, herkesin kontrol edebileceği terimlerle söyler. Gereksinimler (davranış ifadeleri) ve senaryolar (onları kanıtlayan somut örnekler) ile oluşur.

### Gereksinim: Oturum Zaman Aşımı
Sistem, 30 dakikalık eylemsizlik sonrasında bir oturumu sona erdirmelidir (SHALL).

#### Senaryo: Boşta kalma zaman aşımı
- GIVEN kimliği doğrulanmış bir oturum
- WHEN hiçbir etkinlik olmaksızın 30 dakika geçer
- THEN oturum geçersiz kılınır ve kullanıcının yeniden kimlik doğrulaması gerekir

Nasıl kısmını — kuyruğu, kütüphaneyi, tablo şemasını — design.mdye ya da koda bırakın. Davranış ve implementasyon tek bir gereksinimde karıştığında, gereksinim test edilebilirliğini yitirir ve kod değiştiği anda güncelliğini kaybetmeye başlar.

İyi bir gereksinimi ne oluşturur

İyi bir gereksinim, başka birine test etmesi için verebileceğiniz kadar yalın biçimde ifade edilmiş tek bir davranıştır.

• Tek ifade, tek SHALL/MUST. Eğer bir gereksinim üç tane "ve ayrıca" maddesi içeriyorsa, aslında üç gereksinimdir. Onları ayırın.

• Gözlemlenebilir. Kodun dışından biri, gereksinimin geçerli olup olmadığını anlayabilmelidir. "Sistem, yükleme 10 MB'ı aştığında bir hata bandı gösterir" gözlemlenebilirdir. "Sistem büyük yüklemeleri zarifçe ele alır" değildir.

• Doğru kuvvette. OpenSpec, RFC 2119 anahtar kelimelerini kullanır ve bunlar farklı anlamlara gelir:

  Anahtar Kelime	Anlamı
  MUST / SHALL	Kesin bir gereklilik. Pazarlık konusu olmaz.
  SHOULD	Güçlü bir öneri, gerekçeli bir istisnaya açık.
  MAY	Gerçekten isteğe bağlı.

  Varsayılan olarak MUST/SHALL'a yönelin. SHOULD'u yalnızca gerçekten "yapmamak için iyi bir sebep olmadıkça" anlamında kullandığınızda tercih edin.

Gereksinim için test: Kodu hiç görmemiş bir testçi, geçip geçmediğini anlayabilir mi? Anlayamıyorsa, netleştirilmeye ihtiyacı vardır.

İyi bir senaryoyu ne oluşturur

Senaryolar, gereksinimin kendini kanıtladığı yerdir. Her biri, otomatik bir teste dönüşebilecek somut bir GIVEN / WHEN / THEN'dir.

• Gereksinimini çalıştırır. Gereksinimi başka kelimelerle yeniden ifade eden bir senaryo hiçbir şeyi test etmez. Belirli bir durumu ve belirli bir sonucu gösteren bir örnek haline getirin.
• Sadece mutlu yolu değil, önemli olan durumları kapsayın. Geçerli giriş kolaydır. Boş girdi, süresi dolmuş token, ikinci tıklama, ters giden şey — hataların yaşadığı yerler ve bir senaryonun en çok değer kattığı durumlar buralardır.
• Başlıkta durumu adlandırın. "Senaryo: Süresi dolmuş token reddedilir" bir gözden geçirene neyin kapsandığını anında söyler; "Senaryo: Test 2" söylemez.

Faydalı bir alışkanlık: onaylamadan önce, Kırıldığını görmekten en çok üzüleceğim durum nedir? diye sorun — ve bir senaryonun o durumu adlandırdığından emin olun.

Doğru delta türünü seçin

Bir değişiklik, spesifikasyonlara yaptığı düzenlemeleri üç bölüm türüyle tanımlar. Doğru olanı kullanmak, arşivlenmiş spesifikasyonlarınızı dürüst tutar:

• ## ADDED Requirements — daha önce var olmayan, yepyeni davranışlar.
• ## MODIFIED Requirements — zaten var olan ve değişen davranışlar. Tam yeni sürümü ekleyin; neyin değiştiğine dair kısa bir not, gözden geçirene yardımcı olur.
• ## REMOVED Requirements — kaldırılan davranışlar, nedenini belirten bir satırla birlikte.

Arşivleme sırasında, EKLENEN ana spesifikasyona eklenir, DEĞİŞTİRİLEN eski sürümün yerini alır ve KALDIRILAN da ondan çıkarılır. Bir yeteneğin son gereksinimini kaldırırsanız onu emekli edersiniz: içinde hiçbir şey olmayan bir spek bırakmak yerine, arşiv openspec/specs/<yetenek>/spec.md dosyasını siler. Bu, dosya kaldıran tek arşiv adımı olduğu için, açıkça istenmesi gerekir — değişikliğin .openspec.yaml dosyasına, halihazırda ihtiyacı olan schema:'nın yanına retire_capabilities: true ekleyin. Bu olmadan arşiv iptal edilir ve size söyler. Emeklilik, dosyanın tamamını sildiği için, spesifikasyon başlığı, ## Purpose ve gereksinim blokları dışında herhangi bir şey içeriyorken de reddedilir — örneğin bir ## Notes bölümü, bir gereksinimin altındaki bir yorum. İptal mesajı, o satırları adlandırır; onları ## Purpose'a ya da bir gereksinime taşıyın ya da spek'i elle silin. Çağrıcının checkout'undaki bir spek için, arşiv çıktısı, commit edilmiş bir dosyayı geri getiren git checkout komutunu da belirtir; seçilmiş depolar, checkout kapsamında kurtarma rehberliği alır. Gerçek bir değişikliği ADDED olarak işaretlerseniz, birbiriyle yarışan iki gereksinim elde edersiniz; yeni davranışı MODIFIED olarak tanımlarsanız, yerine koyacak hiçbir şey olmaz. Emin değilseniz, mevcut spek'i açın ve gereksinimin zaten orada olup olmadığına bakın.

Bilmeniz gereken bir bölüm daha var. Delta'nız henüz mevcut olmayan bir yetenek oluşturduğunda, onu ## Purpose ile açın — yeteneğin ne için olduğuna dair bir-iki cümle. Arşiv, oluşturduğu ana spek'in Amacı olarak bunu kullanır; atlarsanız, elle doldurmanız için bir TBD yer tutucusu kalır. Mevcut bir spek'in zaten bir Amacı vardır, bu nedenle delta'nınki orada yok sayılır — birini değiştirmek için doğrudan openspec/specs/<yetenek-yolu>/spec.md dosyasını düzenleyin. Burada <yetenek-yolu>, specs/'e göreli dizindir; düz bir projede user-auth ya da alana göre düzenlenmiş bir projede identity/user-auth gibi.

Değişikliği doğru boyutlandırın

En sık yapılan yazım hatası, kötü ifade edilmiş bir gereksinim değil — bir değişikliğin üç değişiklik olmaya çalışmasıdır.

İyi bir değişikliğin, bir cümleyle söyleyebileceğiniz tek bir amacı vardır. "Bir karanlık mod düğmesi ekle." "Giriş ucunu hız-sınırla." "Oturumları çerezlerden taşı." Değişikliği anlatmak çok sayıda "ve ayrıca" gerektiriyorsa, bu onu bölme sinyalidir.

Bir değişikliğin çok büyük olduğunun işaretleri:

• Teklifin kapsamı, ilişkisiz özellikler listesi gibi okunur.
• Gözden geçirmek bir öğleden sonrayı alır, bu yüzden kimse yapmaz.
• İki kişi çakışmadan üzerinde çalışamaz.
• Görevlerin yarısı kendi başına yayınlanabilir.

Daha küçük değişikliklerin gözden geçirilmesi daha kolaydır, tek bir odaklanmış oturumda inşa edilmesi daha kolaydır ve altı ay sonra arşivden başka bir şey kalmadığında muhakeme etmesi daha kolaydır. Aynı anda birkaç değişiklik yürütebilirsiniz — bkz. Düzenleme ve yineleme ve İş Akışları.

Tam tersi de olur: bir satırlık bir yazım hatası düzeltmesi, üç gereksinim ve bir tasarım dokümanı gerektirmez. Merasimi, konunun önemine göre ayarlayın.

Yapay zekayı iyi bir taslağa nasıl yönlendirirsiniz

/opsx:propose ilk taslağı yaptığı için, geri aldığınız kalite, verdiğiniz şeyin kalitesini takip eder. Gereksinimleri elle yazmanız gerekmez — yapay zekayı iyi hedeflemeniz gerekir:

• Amacı ve sınırı belirtin. "İlk yüklemede işletim sistemi ayarını takip eden bir karanlık mod düğmesi ekle — mevcut tema API'sine dokunma." Kapsam dışı kısmı, kapsam içi kısmı kadar önemlidir.
• Önemsediğiniz durumları adlandırın. "Temayı daha önce elle seçmiş bir kullanıcı için bir senaryo olduğundan emin ol." Yapay zeka işaret ettiğiniz şeyi kapsar.
• Sonra düzenleyin. Düz Markdown'dur. Belirsiz bir SHALL'ı sıkılaştırın, hiçbir şeyi test etmeyen bir senaryoyu silin, kaçırdığı durumu ekleyin — ya da yapay zekadan isteyin: "zaman aşımı gereksinimi belirsiz, onu 30 dakikaya sabitleyin."

Taslak, keskinleştir, tekrarla. Birkaç tur bunu yapmak, güveneceğiniz bir spesifikasyon üretir ki bütün mesele de budur.

Hızlı bir kontrol listesi

• Her gereksinim, bir SHALL/MUST ile tek bir gözlemlenebilir davranıştır.
• Gereksinimlere hiçbir implementasyon detayı yerleştirilmemiştir.
• Her gereksinimin, onu gerçekten çalıştıran en az bir senaryosu vardır.
• Önemli uç ve hata durumlarının senaryoları vardır, sadece mutlu yolun değil.
• Deltalar, mevcut spek'e kıyasla ADDED / MODIFIED / REMOVED'ı doğru kullanır.
• Tüm değişikliğin, bir cümleyle ifade edebileceğiniz tek bir amacı vardır.

Sıradaki adım

• Değişiklik İnceleme — gözden kaçanı yakalayan iki dakikalık geçiş.
• Kavramlar — spesifikasyonların, değişikliklerin ve deltaların arkasındaki daha derin model.
• Örnekler ve Tarifler — baştan sona gerçek değişiklikler.