Koddan Claude Code özellik spesifikasyonları: basit bir iş akışı

Koddaki spesifikasyonların eşleşmesine neden ihtiyaç var

İ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ı spesifikasyon ve boşluklar listesi nedir

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:

• Kullanıcı tarafından görülen davranış (birine tıklayınca, gönderince, oturum açınca ne olur)
• Kurallar ve kısıtlamalar (zorunlu alanlar, limitler, hesaplamalar)
• Uç durumlar (boş durumlar, hatalar, yeniden denemeler, zaman aşımı)
• Yetkiler (kim görüntüleyebilir, oluşturabilir, düzenleyebilir, silebilir)
• Önemli çıktılar (gönderilen e-postalar, oluşturulan kayıtlar, durum değişiklikleri)

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:

• Fonksiyon ve sınıf isimleri, komponent ağaçları
• Mimari tartışmalar ve yeniden yazma planları

Boşluklar listesi ayrı olmalıdır. Yazarken bulduğunuz, uyumsuzluklar ve bilinmeyenlerin kısa bir listesidir.

• Bug: kod mevcut davranışı veya üzerinde anlaşılmış kuralı ihlal ediyorsa.
• Özellik isteği: yeni davranış isteniyorsa.
• Boşluk: doğru davranışın ne olması gerektiğini söyleyemiyorsunuz veya davranış ekranlar/roller arasında tutarsız.

Ö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.

Scope seçin ve basit bir spes formatı belirleyin

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:

• Gerçek kurallara ihtiyacınız varsa rotalardan ve handler'lardan başlayın.
• Gerçek deneyime ihtiyacınız varsa UI giriş noktalarından başlayın.
• Özellik karışıksa en üst seviyedeki sayfa/controller ile başlayın ve dışarı doğru çalışın.

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.

Spes şablonu (her kullanıcı akışı için tekrarlayın)

• Purpose: kullanıcının ne yapmaya çalıştığı
• Entry points: akışın başladığı yer (URL, menü, buton)
• Preconditions: auth, roller, gerekli veriler
• Main flow: düz dille 5–10 adım
• Data and side effects: oluşturulan/güncellenen kayıtlar, e-postalar, loglar
• Errors and edge cases: işler ters gittiğinde ne olur
• Open questions: netleştirmeniz gereken belirsiz davranışlar

Bu yapıyı tekrar tekrar kullanın, özellik spesleri okunabilir, karşılaştırılabilir ve güncellenmesi kolay olur.

Rotalardan ve handler'lardan davranış çıkarma

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.

Bileşenlerden ve UI akışlarından davranış çıkarma

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.

Bulguları okunabilir özellik speslerine dönüştürme

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:

• Unknown: e-posta bulunamadığında hangi mesaj görünmeli?
• Unknown: 0 öğeye izin verelim mi yoksa en az 1 mi zorunlu kılalım?
• Unknown: bu hata kullanıcıya mı gösterilmeli yoksa sadece loglanmalı mı?

Bu işaretler sessiz varsayımları hızlı takım sorularına dönüştürür.

Boşluklar listesini backlog'a dönüştürmeden oluşturun

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:

• Belirsiz davranış: uygulama bir şey yapıyor ama kural hiçbir yerde yazmıyor.
• Tutarsızlık: iki yerde aynı durum farklı davranıyor.
• Eksik kural: bir uç durum var ama kodda veya belgelerde karar görünmüyor.

Bir boşluk kaydederken üç parça ekleyin:

• Tip: bug (kod yanlış gibi) veya karar eksikliği
• Etki: kullanıcı karışıklığı, güvenlik riski, veri kaybı veya küçük
• Delil: nerede gördüğünüz ve gözlemlediğiniz şey (route/handler/component)

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.

Örnek: koddaki gerçek bir özelliği belgeleme

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:

• Promosyon kodları sunucu tarafında doğrulanır (süresi dolmuş, kullanım limiti, müşteri uygunluğu).
• Toplamlar promo uygulandıktan sonra yeniden hesaplanır, ancak önce stok yeniden kontrol edilir.
• Gönderi seçenekleri hedef, ağırlık ve herhangi bir öğenin "restricted" işaretlenip işaretlenmediğine bağlıdır.
• Onay, sepet yüklendiğinden beri satır öğesi stoğu değiştiyse başarısız olur.
• Vergi, gönderi seçildikten sonra hesaplanır (promo uygulanırken değil).

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.

Speki takım ile doğrulayın ve güncel tutun

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:

• Spek sahibi: spes değişikliklerini birleştiren kişi (genellikle feature owner veya teknik lider)
• Güncelleme tetikleyicisi: davranış değişikliği PR'ı ile veya her sürümde
• Hızlı kontrol: PR şablonuna "spec güncellendi mi?" onay kutusu ekleyin
• Depolama: koda yakın tutun ki kodla birlikte değişsin

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.

Yaygın hatalar ve tuzaklar

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:

• Doğrulama hataları ve kullanıcının gördüğü tam hata mesajları
• Çift gönderim işlemi (idempotency)
• Background işler (kuyruklar, cron job'lar) ve başarısız olurlarsa ne olur
• Eşzamanlılık sorunları (iki kullanıcı aynı kaydı değiştirdiğinde)
• Zaman bazlı davranışlar (zaman aşımı, süresi dolmalar, rate limitler)

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.

Paylaşmadan önce hızlı kontrol listesi

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ı.

Açıklık ve ortak anlayış

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:

• Tek sayfa testi: açılış kullanıcı hedefini, akışın nerede başladığını ve nerede bittiğini söylüyor mu?
• Roller ve erişim: ana roller ve her birinin ne yapıp yapamayacağı
• Sonuçlar: başarı ne görünür ve başarısızlıkta kullanıcı ne görür (mesajlar, yönlendirmeler, yeniden denemeler)
• Kenarlar ve limitler: boyut limitleri, rate limitler, zaman aşımı, doğrulama kuralları ve veri eksik olduğunda ne olur
• Dil: önce kullanıcıya görünen terimleri kullanın; kaçınılmaz jargon varsa bir kez tanımlayın

Yardımcı olan boşluklar, gürültü değil

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.

Bu hafta başlamak için sonraki adımlar

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.