Spec-Driven Development: Milyarlarca Sterlinlik Ödeme Trafiğinden Dersler

SDD, kodu yazmadan önce sistemin davranışını makinece okunabilir ve insanca anlaşılır bir şartnamede tanımlama yaklaşımıdır. GitHub'ın Eylül 2025'te duyurduğu açık kaynak Spec Kit aracı bu akışı spec, plan, görev ve uygulama adımlarına ayırıyor, Claude Code, Copilot, Gemini CLI gibi birçok ajanla çalışıyor ve Ağustos 2026'da 1.0 sürümüne ulaştı.

Çoğu üründe belirsiz bir spec, yanlış renkte bir buton ya da eksik bir filtre üretir. Ödemede ise aynı belirsizlik çift çekime, kaybolan iadeye ya da mutabakatta açıklanamayan bir farka dönüşür. Örneğin 'ödeme başarısız olursa kullanıcıya hata göster' cümlesi, ağ zaman aşımında ödemenin aslında bankada gerçekleşmiş olabileceği durumu kapsamaz.

Bu yüzden ödeme spec'i üç şeyi açıkça yazmalıdır: her durum ve geçiş, her dış çağrının tekrar edildiğinde ne olacağı ve paranın her hareketinin hangi hesaplara yazılacağı. Bu üçü yoksa, AI ajanı boşlukları makul ama yanlış varsayımlarla doldurur.

Son 12 ayda SDD, deneysel bir akıştan araç ekosistemine dönüştü. GitHub Spec Kit Ağustos 2026'da 1.0 sürümüne ulaştı ve artık onlarca Agent entegrasyonu, eklenti ve preset kataloğuyla geliyor; Amazon'un Spec odaklı IDE'si Kiro da ilk yılını geride bırakıp Eylül 2026'da workflow özelliğini ekledi. Eleştiri de olgunlaştı: Thoughtworks'ten Birgitta Böckeler, Ekim 2025'te bu araçların küçük işler için fazla ağır olduğunu, çok sayıda markdown dosyası ürettiğini ve Agent'ların Spec'i her zaman izlemediğini yazdı. Pratik sonuç, SDD'nin her iş için değil, ödeme gibi yüksek riskli modüller için seçici kullanılması.

Sözleşme tarafında OpenAPI 3.2 Eylül 2025'te, 3.2.1 Eylül 2026'da yayımlandı; Arazzo 1.1 Mayıs 2026'da AsyncAPI desteği getirdi. Idempotency-Key başlığı için IETF taslağı ise RFC olmadan süresi dolmuş durumda; yani standart davranış hâlâ sağlayıcı dokümanlarında. SWIFT yapılandırılmış adres geçişini erteledi. Ödemenin kendisinde ise yeni bir aktör var: AP2 ve ACP ile Agent'lar kullanıcı adına ödeme başlatıyor, bu da Spec'e imzalı yetki ve limit kurallarını ekliyor.

Bir ödeme tek bir 'başarılı' ya da 'başarısız' alanıyla temsil edilemez. Tipik bir yaşam döngüsünde oluşturuldu, yetkilendirme bekliyor, yetkilendirildi, tahsil edildi, kısmen iade edildi, iade edildi, ters ibraz edildi gibi durumlar ve aralarındaki izinli geçişler vardır.

Spec'te bu durum makinesini bir tablo ya da diyagram olarak yazmak, iki tür hatayı baştan engeller. Birincisi imkânsız geçişler: iade edilmiş bir ödemenin tekrar tahsil edilmesi gibi. İkincisi belirsiz durumlar: sağlayıcıdan yanıt gelmediğinde ödemeyi 'bilinmiyor' durumuna alıp bir mutabakat işine bırakmak, onu 'başarısız' sayıp kullanıcıya tekrar denetmekten çok daha güvenlidir.

Somut bir kural: her geçiş için tetikleyici olay, ön koşul ve yan etki yazılmalı. Veritabanında da durum alanı serbest metin değil, izinli değerlerle sınırlı bir enum olmalı ve geçişler tek bir fonksiyondan yapılmalı. AI ajanına bu tabloyu verdiğinde, yazdığı kodun her dalını tabloyla karşılaştırabilirsin.

Ağ güvenilmezdir. Mobil uygulama ödeme isteğini gönderir, bağlantı kopar, kullanıcı tekrar dener. Sunucu iki isteği ayırt edemezse müşteri iki kez ödeme yapar. Idempotency, aynı işlemin birden fazla kez çalıştırılmasının tek seferle aynı sonucu vermesidir ve ödeme API'lerinde genelde istemcinin ürettiği bir anahtarla sağlanır.

Stripe'ın dokümantasyonu iyi bir referans: anahtar 255 karaktere kadar olabilir, V4 UUID gibi yüksek entropili bir değer önerilir ve API v1'de anahtarlar en az 24 saat sonra temizlenebilir. Aynı anahtarla farklı parametreler gönderilirse istek hata verir; bu, yanlışlıkla başka bir işlemi aynı anahtarla eşleştirmeyi önler.

Spec'te yazılması gerekenler: hangi uç noktalar anahtar ister, anahtar ne kadar saklanır, aynı anahtarla eşzamanlı iki istek gelirse ne olur, ilk istek 500 ile bittiyse tekrar ne döner. Bu soruların cevabı kodda kalırsa her servis farklı davranır.

0.1 artı 0.2'nin kayan noktalı sayılarla tam olarak 0.3 etmemesi, ödeme sistemlerinde teorik bir merak değildir. Para ya en küçük birim cinsinden tamsayı olarak (kuruş, peni) ya da sabit hassasiyetli bir decimal tipiyle tutulmalı ve her tutar bir para birimi koduyla birlikte taşınmalıdır. Japon yeni gibi bazı para birimlerinin ondalık basamağı yoktur; spec bunu ISO 4217'ye göre tanımlamalı.

Çift taraflı kayıt (double-entry), her para hareketinin en az bir borç ve bir alacak kaydı olarak yazılması ve toplamların her zaman sıfırlanması kuralıdır. Örneğin 100 liralık bir satışta müşteri alacak hesabı, komisyon gelir hesabı ve satıcı borç hesabı aynı işlemde güncellenir.

Spec'te bu kural bir değişmez (invariant) olarak yazılırsa test edilebilir hâle gelir: 'her işlemde kayıtların toplamı sıfırdır.' Yuvarlama kuralı da açıkça yazılmalı; komisyonu üç satıcıya bölerken kalan kuruşun kime gideceği spec'te yoksa, AI ajanı bir tercih yapar ve bu tercih sonra mutabakatta karşına çıkar.

Ödeme sistemleri nadiren yalnızdır: banka, kart ağı, dolandırıcılık servisi ve muhasebe sistemiyle konuşur. Her entegrasyon bir sözleşmedir. REST uç noktaları için OpenAPI (güncel sürüm Eylül 2026 tarihli 3.2.1), olay akışları için AsyncAPI, bankalar arası mesajlaşma için ISO 20022 bu sözleşmeleri makinece okunabilir kılan standartlardır.

ISO 20022 iyi bir örnek: SWIFT, sınır ötesi ödeme talimatlarında eski MT formatıyla birlikte yaşam dönemini 22 Kasım 2025'te bitirdi ve bu mesajlar artık yalnızca ISO 20022 formatında iletiliyor. SWIFT'e göre ödeme talimatlarının yüzde 98'den fazlası artık ISO 20022 ile gönderiliyor. Zengin, yapılandırılmış alanlar uyum kontrolünü kolaylaştırıyor ama alan uzunlukları ve zorunluluklar konusunda hata payı bırakmıyor. Bir sonraki adım olan ve Kasım 2026'ya planlanan yapılandırılmamış adres kaldırımını ise SWIFT, Ağustos 2026'da topluluk talebiyle erteledi; yeni takvimi en geç Aralık 2026'da açıklayacak. Ders: Spec'te dış sözleşmenin tarihini sabit kabul etme, sürümünü ve geçerlilik tarihini ayrı bir alan olarak tut.

Spec'i tek doğru kaynak yapmak için sözleşmeden kod üretimi, istek ve yanıt doğrulaması ve tüketici güdümlü sözleşme testleri kullanılır. Anti-pattern: OpenAPI dosyasını koddan sonradan üretmek. Bu durumda spec, sistemin olması gereken davranışını değil, o anki hâlini belgeler ve hiçbir hatayı yakalamaz.

Örnek tabanlı testler 'şu girdide şu çıktı' der. Ödemede asıl riskler beklenmedik kombinasyonlardadır: kısmi iade sonrası ters ibraz, farklı para birimlerinde bölünmüş ödeme, aynı anda gelen iki webhook. Özellik tabanlı test (property-based testing), spec'teki değişmezleri rastgele üretilen binlerce senaryoya karşı sınar. Örneğin 'iade toplamı hiçbir zaman tahsil edilen tutarı aşamaz' bir özelliktir; araç bunu bozan en küçük girdiyi bulmaya çalışır.

İkinci savunma hattı mutabakattır (reconciliation): kendi kayıtlarını banka ya da sağlayıcı raporuyla düzenli karşılaştırmak. Spec, mutabakatın ne sıklıkla yapılacağını, hangi farkın otomatik düzeltileceğini ve hangisinin insana gideceğini tanımlamalı.

AI ajanı burada güçlü bir yardımcı: spec'teki değişmezlerden test iskeleti üretebilir. Ama testin neyi kanıtladığını kontrol etmek insan işi; ajanın yazdığı bir testin her zaman geçmesi, onun bir şey test etmediği anlamına gelebilir.

Spec Kit benzeri akışlarda ajan önce spec'i okur, bir teknik plan çıkarır, bunu görevlere böler ve uygular. Bu akışın ödemede çalışması için spec'in kod kadar ciddiye alınması gerekir: sürüm kontrolünde durmalı, PR ile değişmeli ve her değişiklik ilgili test ve sözleşme güncellemesini tetiklemeli.

Tipik bir hata zinciri şöyle işler: bir ürün yöneticisi kısmi iadeyi ister, geliştirici ajanla kodu yazdırır, spec güncellenmez. Altı ay sonra başka bir ajan spec'e bakarak bir rapor yazar ve kısmi iadeyi bilmediği için toplamları yanlış hesaplar. Spec ile kodun ayrışması, ajanlar çoğaldıkça hızlanan bir risk.

Pratik kurallar: spec'te her kural için bir kimlik numarası tut ve testlerde bu numaraya atıf yap. CI'da spec'i değiştirmeden ödeme modülüne dokunan PR'ları işaretle. Ajanın spec'te olmayan bir davranış eklemesi gerekiyorsa, önce spec'i değiştiren ayrı bir PR açmasını iste.