Rotlar ve bileşenlerden gerçek uygulama davranışını çıkarıp canlı bir spesifikasyon ve boşluklar listesi oluşturarak Claude Code özellik spesifikasyonlarını koddan nasıl oluşturacağınızı öğrenin.
İnsanlar bir uygulamanın ne yaptığında farklılık yaşarlar çünkü farklı sürümlerini hatırlarlar. Destek son öfkeli ticket'ı hatırlar. Satış demo yolunu hatırlar. Mühendisler özelliğin ne yapması gerektiğini hatırlar. Üç kişiye sorduğunuzda üç emin cevap alırsınız ve hiçbiri mevcut yapıyla uyuşmaz.
Zamanla kod tek güncel kalan kaynak olur. Dokümanlar sürüklenir, ticket'lar kapanır ve hızlı düzeltmeler yığılır. Bir rota yeni bir doğrulama kuralı alır. Bir UI toggle varsayılanı değiştirir. Bir handler farklı hatalar dönmeye başlar. Hiç kimse spesifikasyonu güncellemez çünkü opsiyonelmiş gibi gelir ve her değişiklik belgelenmeyecek kadar küçük görünür.
Bu öngörülebilir sorunlar yaratır. Takımlar farkında olmadıkları uç durumları bozan değişiklikler gönderir. QA sadece mutlu yolu test eder ve handler'larda gömülü kuralları kaçırır. Yeni ekip üyeleri gerçek kısıtlamaları anlamadan davranışı UI'dan kopyalar. Paydaşlar ise üzerinde anlaşılmış davranışa işaret etmek yerine görüşleri tartışır.
İyi sonuç mükemmel bir doküman değildir. Ortak netliktir. Herkes şu soruları tahmin etmeden cevaplayabilmeli: “X yaparsam ne olur?” ve “Sistem neyi garanti ediyor?” Böylece daha az sürpriz, daha kısa inceleme döngüleri ve “Bekle, zaten yapıyor” anları azalır çünkü ekip aynı gerçeğe bakıyordur.
Bir spesifikasyon kodla eşleştiğinde değişiklikleri planlamak güvenli hale gelir. Göndermeden önce neyin kararlı, neyin tesadüfi ve neyin eksik olduğunu görebilirsiniz.
Canlı bir spes, uygulamanın bugün gerçekte ne yaptığını kısa ve düzenlenebilir şekilde anlatan bir belgedir. Tek seferlik bir doküman değildir. Davranış değiştiğinde o da değişir, böylece ekip güvenebilir.
Koddank yazılan özellik spesifikasyonlarından (örneğin Claude Code kullanarak) bahsedildiğinde amaç basittir: rotalardan, handler'lardan ve ekranlardan gerçek davranışı okuyun, sonra bunu düz dille yazın.
Yararlı bir canlı spes, kullanıcının görebildiklerine ve sistemin neyi taahhüt ettiğine odaklanır. Şunları kapsamalıdır:
Ne kaplamamalıdır: kodun nasıl organize edildiği. Dosya isimlerini ve refactor planlarını söylemeye başlarsanız uygulama detaylarına kayıyorsunuz. Kaçının:
Boşluklar listesi ayrı olmalıdır. Yazarken bulduğunuz, uyumsuzluklar ve bilinmeyenlerin kısa bir listesidir.
Örnek: bir rota 10MB üzerindeki dosyaları reddediyor ama UI 25MB diyor. Bu, ekip hangi kuralın gerçek olduğuna karar verene kadar bir boşluktur.
Küçük başlayın. Tüm uygulamayı belgeleye çalışırsanız güvenilmeyen not yığını elde edersiniz. Kullanıcıların bir cümleyle tanımlayabileceği bir dilim seçin: “takıma davet et”, “ödeme”, “parola sıfırlama” gibi. İyi kapsamlar tek bir özellik alanı, bir modül veya giriş noktasından sonuca kadar bir kullanıcı yoludur.
Gerçekliği nerede gördüğünüze göre giriş noktanızı seçin:
Kodu okumadan önce birkaç girdi toplayın ki uyumsuzluklar çabuk fark edilsin: mevcut API dokümanları, eski ürün notları, destek ticket'ları ve insanların şikayet ettiği “bilinen ağrılar”. Bunlar kodun yerini almaz ama hata durumları, uç durumlar ve izinler gibi eksik durumları fark etmenize yardım eder.
Spes formatını sıkıcı ve tutarlı tutun. Her spes aynı şekilde okunduğunda ekip daha hızlı hizalanır.
Bu yapıyı tekrar tekrar kullanın, özellik spesleri okunabilir, karşılaştırılabilir ve güncellenmesi kolay olur.
Sunucu giriş noktalarıyla başlayın. Rotalar ve handler'lar “uygulama ne yapıyor”u somut olarak gösterir: kim çağırabilir, ne göndermeliler, ne alırlar ve sistemde ne değişir.
Kapsamdaki rotaları listeleyin ve her birini bir kullanıcı niyetiyle eşleyin. "POST /api/orders" yazmayın. "Sipariş ver" veya "Taslak kaydet" yazın. Niyetini dümdüz kelimelerle adlandıramıyorsanız, bu zaten bir spes boşluğudur.
Her handler'ı okurken, girdileri ve doğrulama kurallarını kullanıcıya yönelik gereksinimler olarak yakalayın. Zorunlu alanları, izin verilen formatları ve gerçek hataya neden olan kuralları dahil edin. Örnek: “Email geçerli olmalı”, “Miktar en az 1 olmalı”, “Başlangıç tarihi geçmişte olamaz.”
Yetki ve rol kontrollerini de aynı şekilde not edin. "middleware: requireAdmin" yerine belgeleyin: "Sadece adminler herhangi bir siparişi iptal edebilir. Normal kullanıcılar yalnızca 10 dakika içinde kendi siparişlerini iptal edebilir." Kod ownership, feature flag veya tenant sınırlarını kontrol ediyorsa bunları da ekleyin.
Sonra çıktıları ve sonuçları not edin. Başarı ne döner (oluşturulan ID, güncellenmiş obje)? Yaygın hatalar nasıl görünür (401 oturum yok, 403 izin yok, 404 bulunamadı, 409 çakışma, 422 doğrulama hatası)?
Son olarak, yan etkileri kaydedin çünkü bunlar davranışın parçasıdır: oluşturulan/güncellenen kayıtlar, gönderilen e-postalar veya bildirimler, yayınlanan event'ler, kuyruğa alınan background işler ve başka akışları tetikleyen herhangi bir şey. Bu ayrıntılar, ekipler daha sonra speke güvendiğinde sürprizleri önler.
Rotalar uygulamanın ne yapabileceğini söyler. Bileşenler kullanıcının gerçekten ne yaşadığını söyler. UI'yı bir sözleşmenin parçası olarak ele alın: ne gösteriliyor, ne engelleniyor ve işler ters gittiğinde ne oluyor.
Özellik için giriş ekranlarını bulun. Sayfa komponenti, layout wrapper ve fetching, izinler ve navigasyonu kontrol eden birkaç “karar” komponenti arayın. Gerçek davranış genellikle orada yaşar.
Komponentleri okurken kullanıcıların hissedebileceği kuralları yakalayın: hangi eylemler devre dışı bırakılır, zorunlu adımlar, koşullu alanlar, yükleniyor durumları ve hataların nasıl gösterildiği (alan altı inline hata vs toast, otomatik yeniden deneme, “tekrar deneyin” butonları). Ayrıca stale veri gösterme, iyimser güncelleme veya “son kaydedildi” zaman damgası gibi durum ve cache davranışlarını not edin.
Kullanıcılara sessizce davranışı değiştiren gizli akışlara dikkat edin. Feature flag'ler, deney bucket'ları ve sadece adminlere açık kapılar için arama yapın. Otomatik yönlendirmeleri de not edin: oturumu olmayanları sign-in sayfasına gönderme veya erişimi olmayanları upgrade ekranına yönlendirme gibi.
Somut bir örnek: “E-posta Değiştir” ekranında Save butonu e-posta geçerli olana kadar devre dışı kalır, istek sırasında spinner gösterilir, başarı bir onay banner'ı tetikler ve backend doğrulama hataları input altına render edilir. Kod newEmailFlow gibi bir flag gösteriyorsa, her iki varyantı ve aralarındaki farkları not edin.
Her UI akışını kısa adımlar olarak yazın (kullanıcı ne yapıyor, UI karşılık olarak ne yapıyor) ve koşulları ve hataları etkilenen adımın yanına koyun. Bu, spesin okunabilirliğini korur ve boşlukları bulmayı kolaylaştırır.
Rota ve komponentlerden alınan ham notlar faydalıdır ama tartışılması zor olabilir. Gözlemlediklerinizi bir PM, tasarımcı, QA ve mühendisin okuyup üzerinde anlaşabileceği bir speke yeniden yazın.
Pratik bir kalıp, her rota veya ekran için bir kullanıcı hikayesidir. Küçük ve spesifik tutun. Örnek: “Giriş yapmış bir kullanıcı parolasını sıfırlayabilir, böylece erişimini geri kazanır.” Kod rol bazlı farklı davranış gösteriyorsa (admin vs kullanıcı), bunu ayak notlarda saklamak yerine ayrı hikayelere bölün.
Sonra kabul kriterlerini gerçek kod yollarını yansıtacak şekilde yazın, ideal ürün değil. Handler token eksikse 401 döndürüyorsa bu bir kriterdir. UI submit butonunu alan geçerli olana kadar devre dışı bırakıyorsa bu bir kriterdir.
Veri kurallarını düz dilde dahil edin; özellikle sürprizlere yol açanları: limitler, sıralama, benzersizlik, zorunlu alanlar. “Kullanıcı adları benzersiz olmalıdır (kaydetmede kontrol edilir)” ifadesi “unique index” demekten daha açıktır.
Uç durumlar genellikle güzel bir doküman ile faydalı bir doküman arasındaki farktır. Boş durumları, null değerleri, yeniden denemeleri, zaman aşımlarını ve API çağrısı başarısız olduğunda kullanıcıların ne gördüğünü belirtin.
Bilinmeyenlerle karşılaştığınızda tahmin etmek yerine işaretleyin:
Bu işaretler sessiz varsayımları hızlı takım sorularına dönüştürür.
Boşluklar listesi ikinci bir Jira olmamalıdır. Kod ile niyet edilen davranışın uyuşmadığı veya kimsenin “doğru”yu açıkça açıklayamadığı yerlerin kısa, delile dayalı kaydıdır. İyi yapıldığında uzlaşma aracı olur, planlama kavgası değil.
Boşluk sayılacakları konusunda katı olun:
Bir boşluk kaydederken üç parça ekleyin:
Delil listeyi görüşlerden uzak tutar. Örnek: “POST /checkout/apply-coupon süresi geçmiş kuponları kabul ediyor ama CouponBanner.tsx UI'da onları engelliyor. Etki: gelir kaybı ve kullanıcı karışıklığı. Tip: bug veya karar eksikliği (niyet doğrulanmalı).”
Kısa tutun. İlk tur için sert bir limit koyun, örn. 10 madde. 40 sorun bulduysanız bunları kalıplara (doğrulama tutarsızlıkları, yetki kontrolleri, boş durumlar) göre gruplayın ve sadece en iyi örnekleri bırakın.
Boşluk listesinde tarihler ve planlama eklemekten kaçının. Sahiplik gerekiyorsa hafif tutun: kimin karar vermesi gerektiğini (ürün) veya kimin davranışı doğrulayabileceğini (mühendislik) not edin; gerçek planlamayı backlog'a taşıyın.
Küçük, yüksek trafik bir kapsam seçin: promosyon kodları ve gönderi seçenekleri olan checkout. Amaç tüm ürünü yeniden yazmak değil, uygulamanın bugün ne yaptığını yakalamaktır.
Backend rotalarla başlayın. Kurallar genellikle ilk olarak orada görünür. POST /checkout/apply-promo, GET /checkout/shipping-options, POST /checkout/confirm gibi rotalar bulabilirsiniz.
Bu handler'lardan davranışı düz dille yazın:
Sonra UI bileşenlerini kontrol edin. Bir PromoCodeInput başarılı yanıt sonrası toplamların yenilendiğini ve hataların input altına inline gösterildiğini gösterebilir. Bir ShippingOptions bileşeni ilk yüklemede en ucuz seçeneği otomatik seçebilir ve kullanıcı değiştirdiğinde tam fiyat dökümünü tetikleyebilir.
Şimdi okunabilir bir spes ve küçük bir boşluklar listesine sahipsiniz. Örnek: hata mesajları promo route ve UI arasında farklı ("Invalid code" vs "Not eligible") ve kimse açık bir vergi yuvarlama kuralına işaret edemiyor (satır başına mı yoksa sipariş toplamına mı).
Planlamada ekip önce gerçekliği kabul eder, sonra neyi değiştireceklerine karar verir. Görüşleri tartışmak yerine belgelenmiş davranışları gözden geçirir, düzeltilecek bir uyumsuzluğu seçer ve geri kalanını "mevcut bilinen davranış" olarak tutar.
Spek, ekip gerçeğe uyduğunu kabul ederse yardımcı olur. Bir mühendis ve bir ürün kişisiyle kısa bir okuma yapın. Sıkı tutun: kullanıcıların ne yapabildiği ve sistemin ne yaptığı üzerine 20–30 dakikalık odaklanmış bir gözden geçirme.
Okuma sırasında ifadeleri evet/hayır sorularına çevirin. “Bir kullanıcı bu route'a geldiğinde her zaman 403 döner mi?” “Bu boş durum kasıtlı mı?” Bu, kastedilen davranış ile zamanla eklenmiş kazara davranışı ayırır.
Düzenlemeye başlamadan önce kelime dağarcığında anlaşın. UI’daki kelimeleri kullanın (buton etiketleri, sayfa başlıkları, hata mesajları). İç isimleri sadece mühendislerin kodu bulmasını kolaylaştıracaksa ekleyin (rota isimleri, komponent isimleri). Bu, product’ın “Workspace” derken spesin “Org” demesi gibi uyuşmazlıkları önler.
Güncel tutmak için sahiplik ve ritmi açık yapın:
Koder.ai gibi bir araç kullanıyorsanız snapshot'lar ve rollback, özellikle büyük bir refactor sonrası "önce" ve "sonra" davranışlarını karşılaştırmanıza yardımcı olur.
Speke güveni kaybettirmenin en hızlı yolu, sahip olmak istediğiniz ürünü değil elinizdeki ürünü tanımlamaktır. Sert bir kural koyun: her ifade kodda veya gerçek bir ekranda gösterebileceğiniz bir şeyle desteklenmelidir.
Bir diğer tuzak kodun yapısını belgeye kopyalamaktır. "Controller -> Service -> Repository" gibi bir spes değil, klasör haritasıdır. Kullanıcı taraflı terimlerle yazın: hangi eylem tetikliyor, kullanıcı ne görüyor, ne kaydediliyor ve hatalar nasıl gözüküyor.
Yetkiler genelde sona bırakılır ve sonra her şey bozulur. Erişim kurallarını erken ekleyin, hatta dağınıksa da. Hangi rollerin görüntüleyebildiğini, oluşturabildiğini, düzenleyebildiğini, silebildiğini, dışa aktarabildiğini veya onaylayabildiğini ve kuralın nerede uygulandığını (sadece UI, sadece API veya her ikisi) belirtin.
Mutlu yolları atlamayın. Gerçek davranış yeniden denemelerde, kısmi başarısızlıklarda ve sürelere bağlı kurallarda saklıdır (süre dolmaları, cooldown, günlük limitler). Bunları birinci sınıf davranışlar gibi ele alın.
Hızlıca boşlukları ortaya çıkarmak için kontrol edin:
Son olarak, boşluklar listenizi hareketli tutun. Her boşluk şu etiketlerden birine sahip olmalı: "unknown, needs decision," "bug, fix," veya "missing feature, plan." Etiketlenmezse liste donar ve spes "canlı" olmaktan çıkar.
Açıklık, kapsam ve uygulanabilirlik için hızlı bir geçiş yapın. Yazmayan bir kişi bile özelliğin bugün ne yaptığını ve hangi noktaların belirsiz olduğunu anlamalı.
Spec'i yeni bir ekip üyesi gibi okuyun. Bir dakikada özelliği özetleyebiliyorlarsa iyi gidiyorsunuz. "Nereden başlıyor?" veya "mutlu yol nedir?" soruları geliyorsa açılışı sıkılaştırın.
Kontrol edin:
Her boşluk spesifik ve test edilebilir olmalı. "Hata işleme belirsiz" demek yerine: "Ödeme sağlayıcı 402 döndürürse UI genel bir toast gösteriyor; istenen mesaj ve yeniden deneme davranışı doğrulanmalı." Tek bir sonraki eylem ekleyin (ürün sor, test ekle, logları incele) ve kimin cevap vermesi gerektiğini not edin.
Bir özellik alanı seçin ve 60 dakika ile zaman kutusu yapın. Küçük ama gerçek bir şey seçin (giriş, ödeme, arama, bir admin ekranı). Kapsam için bir cümle yazın: ne dahil, ne hariç.
İş akışını baştan sona bir kez çalıştırın: ana rotaları/handler'ları gözden geçirin, ana UI akışını izleyin ve gözlemlenebilir davranışları (girdiler, çıktılar, doğrulama, hata durumları) not edin. Takılırsanız soruyu bir boşluk olarak kaydedin ve devam edin.
Bitirdiğinizde, takımın yorum yapabileceği yerde speki paylaşın ve bir kural koyun: gönderilen herhangi bir davranış değişikliği aynı teslimat penceresinde speği güncellemeyi gerektirsin, beş satır bile olsa.
Boşlukları backlog'tan ayrı tutun. Onları "bilinmeyen davranış," "tutarsız davranış" ve "test eksikliği" olarak gruplandırın ve hangi maddelerin şimdi önemli olduğunu haftalık kısa bir gözden geçirmede kararlaştırın.
Tasarım ve yineleme yavaş geliyorsa, sohbet tabanlı bir oluşturucu (ör. Koder.ai) ilk versiyonu hızlıca çıkarmanıza yardımcı olabilir. Özelliği tanımlayın, önemli snippet'leri veya rota isimlerini yapıştırın, ifadeyi sohbette rafine edin ve gerektiğinde kaynağı dışa aktarın. Amaç hız ve ortak netliktir, daha büyük bir süreç değil.
Küçük, kullanıcı tarafından görülebilen bir dilimle başlayın (örneğin “parolayı sıfırla” veya “takım daveti”). Kuralları ve sonuçları yakalamak için rotaları/handler'ları okuyun, sonra kullanıcıların gerçekte ne gördüğünü yakalamak için UI akışını inceleyin (devre dışı bırakılan durumlar, hatalar, yönlendirmeler). Tutarlı bir şablon kullanarak yazın ve bilinmeyenleri ayrı bir boşluklar listesi olarak kaydedin.
Varsayılan: mevcut kod davranışını gerçek kaynak olarak kabul edin ve onu belgeleyin.
Davranış kazara veya tutarsız görünüyorsa, spekte “düzeltilmiş” bir yorum yapmayın—delil (nerede gördüğünüz ve nasıl davrandığı) ekleyerek bunu bir boşluk olarak işaretleyin, sonra kodu veya speki güncelleme kararı alın.
Sıkıcı ve tekrarlanabilir tutun. Pratik bir şablon:
Bu, spesifikasyonları okunabilir kılar ve tutarsızlıkları bulmayı kolaylaştırır.
Kuralları kullanıcı gözüyle yazın, kod notları olarak değil.
Örnekler:
Hangi durumun hataya yol açtığını ve kullanıcı bununla karşılaştığında ne gördüğünü belirtin.
Gözlemlenebilir olana odaklanın:
Yan etkiler diğer özellikleri ve destek/operasyon beklentilerini etkilediği için önemlidir.
UI bir şeyi engelliyor ama API izin veriyorsa (veya tersi), kararı verilene kadar bunu bir boşluk olarak kaydedin.
Kaydedin:
Sonra bir kural belirleyin ve kod ile speki her ikisini de güncelleyin.
Boşluklar listesini küçük ve delile dayalı tutun. Her madde şunları içermeli:
Zamanlama veya planlama yerine, kimin kararı verebileceğini veya kimin doğrulayacağını not edin.
Açıkça belgeleyin, tahmin etmeyin.
Şunları dahil edin:
Bunlar genellikle sürprizlerin ve hataların kaynağıdır.
Kısa tutun: bir mühendis ve bir product kişisiyle 20–30 dakikalık bir okuma yeterli olabilir.
İfadeleri evet/hayır sorularına çevirin (ör. “Bu route’a erişildiğinde her zaman 403 dönüyor mu?”). UI’daki görünür metinleri (buton etiketleri, sayfa başlıkları, hata mesajları) kullanarak terimleri hizalayın.
Speki koda yakın tutun ve güncellemeleri gönderim sürecinin bir parçası yapın.
Pratik varsayımlar:
Amaç: büyük bir yeniden yazım değil, küçük ve sık düzenlemeler.
