Azure Cosmos DB Spec Kit Eklentisi: Koddan Önce Tasarım

⏱️ 6 dk okuma📅 21 Eylül 2026

Yapay zeka destekli kodlama ajanları bir uygulamanın kodunun önemli bölümünü yazabiliyor, ama o kodun arkasındaki kararları gözden geçirmek hala geliştiricinin işi. Azure Cosmos DB tarafında bu kararlar partition key seçimini, erişim desenlerinin modellenmesini ve istemci yapılandırmasını kapsıyor; kod derlendikten çok sonra bile maliyeti, performansı ve dayanıklılığı belirleyen konular bunlar. Microsoft, GitHub Spec Kit için Azure Cosmos DB eklentisinin public preview sürümünü duyurdu. Spec Kit ekosistemindeki ilk veritabanı eklentisi bu; amacı Cosmos DB rehberliğini uygulama tasarımı aşamasına, yani kod üretilmeden önceki adıma taşımak.

Spec-driven development ne demek?

Spec-driven development (SDD) yaklaşımında gereksinimler, tasarım ve görevler uygulamadan önce netleşir. Ajan her aşamada okunabilir, düzeltilebilir ve onaylanabilir bir belge üretir. GitHub Spec Kit bu akış için açık bir çerçeve sunuyor, her aşamanın da kendi komutu var:

/specify: Ne inşa ettiğinizi ve neden inşa ettiğinizi bir spesifikasyonda toplar.
/plan: Spesifikasyonu mimariye ve veri modeline dönüştürür. Veritabanı kararlarının alındığı yer burasıdır.
/tasks: Planı sıralı ve doğrulanabilir iş birimlerine böler.
/implement: Plana sadık kalarak kodu görev görev üretir.

Planı incelerken önerilen partition key’in en yoğun sorgularınızı gerçekten karşılayıp karşılamadığını kontrol edebilirsiniz, bu yapının pratikteki faydası da burada. Orada bir değişiklik yapmak, veri katmanı yazıldıktan sonra her şeyi elden geçirmekten genellikle daha kolay. Planın ne zaman hazır olduğuna siz karar verirsiniz, sonra ajanın ürettiği kodu ve testleri gözden geçirirsiniz. Spec Kit bu akışa alana özgü komutlar ve hook’lar ekleyen eklentileri de destekliyor.

Genel amaçlıdan Cosmos DB farkındalığına

Spec Kit tasarımı gereği veritabanı bağımsız. Eklenti olmadan verdiği veritabanı önerileri, modelin mevcut bilgisine ve sizin sağladığınız bağlama kalıyor. Cosmos DB eklentisi ise partitioning, RU maliyetleri, point read’ler, indeksleme ve dayanıklı istemci yapılandırması konularında rehberlik ekliyor. Cosmos DB Agent Kit becerilerinin yerini almıyor; aynı bilgiyi Spec Kit komutları ve implementation hook’ları üzerinden erişilebilir kılıp onu tamamlıyor.

Eklentinin sunduğu başlıklar şöyle:

Kod üretim komutları: Point read, partition farkındalıklı ve parametreli sorgular, managed identity ile kimlik doğrulama, dayanıklı istemciler ve diğer Cosmos DB desenleri.
Veri modelleme rehberliği: Uygulamanın veriyi nasıl okuyup yazdığına bakarak container ve partition key seçimine yardımcı olur.
Uygulama öncesi danışman: before_implement hook’u ilgili desenleri seçer, bunlara ait en iyi uygulama kurallarını doğrudan implementation bağlamına dahil eder.
Uygulama sonrası inceleme: after_implement hook’u ajana üretilen kodu Cosmos DB rehberliğine karşı denetlemesini, tespit ettiği sorunları düzeltmesini ve tekrar kontrol etmesini söyler. Sonucu yine de sizin gözden geçirip test etmeniz gerekiyor.

Eklenti uyumlu Spec Kit ajanlarıyla çalışıyor; GitHub Copilot, Claude Code, Codex, Cursor ve Gemini CLI bunlar arasında. Diğer eklentilerle birlikte de kullanılabiliyor.

Takım standartlarını preset ile taşımak

Çoğu ekibin kendi adlandırma standartları, tercih ettiği SDK desenleri, güvenlik gereksinimleri ve inceleme adımları vardır. Spec Kit’in preset mekanizması, bu kuralları Cosmos DB eklentisini fork etmeden akışa eklemenizi sağlıyor. Preset ile şunları yapabilirsiniz:

Komut şablonlarını sarmalayıp veya geçersiz kılıp ekibinizin gereksinimlerini planlama ve uygulama aşamalarına dahil etmek.
Cosmos DB eklentisini başka eklentilerle birlikte kullanan ortak bir iş akışı tanımlamak.
Özelleştirmelerinizi eklentiden ayrı tutarak güncellemeleri fork bakımı yapmadan almak. Yine de alttaki komutlar değiştiğinde override’ların gözden geçirilmesi gerekiyor.

Örneğin bir platform ekibi, onaylı bölgeleri ve kimlik doğrulama gereksinimlerini planlama şablonuna ekleyen bir preset yayımlayabilir; preset’i kuran geliştiriciler komutu çalıştırdığında ilgili gereksinimler hazır gelir. Ama preset yalnızca ortak talimat sağlıyor, ekip politikalarına uyumu zorunlu kılmıyor. Üretilen belgeler ve kod yine sizin incelemenizi bekler.

Ölçüm sonuçları: ne kanıtlandı, ne kanıtlanmadı

Microsoft hem üretilen kodun Cosmos DB en iyi uygulamalarına uyumunu hem de uçtan uca uygulama geliştirme sonuçlarını değerlendirmiş.

En iyi uygulama kontrolleri. Eklentinin rehberliği olan ve olmayan durumlar farklı modeller, diller ve karmaşıklık seviyeleri üzerinde karşılaştırılmış. Kontroller arasında istemci uygulama adı yapılandırması, ID ve partition key ile point read, 404 yanıtının “kayıp öğe” olarak ele alınması, parametreli ve partition kapsamlı sorgular, ETag kullanımı, transactional batch, anahtarsız kimlik doğrulama ve partition key tasarımı var.

Rehberlik uygulandığında ortalama başarı oranı 0,10, yani yaklaşık 10 puan artmış, 24 test kombinasyonunun 19’unda iyileşme görülmüş. Sonuçlar koşular arasında da daha tutarlı çıkmış. En büyük kazanç istemci uygulama adının ayarlanmasında; başarı oranında +0,79. Tek tek en iyi uygulama komutlarının testlerinde +0,14 ile +0,37 aralığında kazanım ölçülmüş, rehberliğe zaten uyan modellerde iyileşme payı doğal olarak daha az olmuş. Danışmanın komut önerileri de ayarlanmış, precision değeri 0,57’den 0,68’e çıkmış. Bu testler rehberliğin sağlanmasının kontrol edilen en iyi uygulamalara uyumu artırdığını gösteriyor, her komutun her uygulamada doğru kod ürettiğini kanıtlamıyor.

Uçtan uca uygulama testleri. Ajanlar tüm akışı otonom biçimde yürüttüğünde önerilen Cosmos DB komutlarını sıklıkla atlamış, veri katmanını bu rehberlik olmadan yazmışlar. v0.2.0 sürümündeki değişiklikler de bu bulgudan doğmuş: danışman artık ilgili kuralları doğrudan implementation bağlamına ekliyor, hem danışman hem inceleme hook’ları zorunlu (non-optional) olarak yapılandırılıyor, inceleme adımı da ajana düzeltmeleri uygulayıp kodu yeniden kontrol etmesini söylüyor.

Güncellenen eklenti, kullanılabilir sonuç veren iki model için önceki sürüme göre ortalamada mütevazı bir artış kaydetmiş, ama belirsizlik payı “hiç iyileşme yok” ihtimalini de dışarıda bırakmıyor. Aynı otonom testlerde eklenti, yalnızca Spec Kit kullanımıyla kabaca aynı seviyede kalmış, Spec Kit’siz çalışan ajanın ise altında sonuç vermiş. Üçüncü bir model ajan çalışma zamanı hataları nedeniyle kullanılabilir skor üretememiş. Bu testler, her aşamada insan incelemesinin etkisini ölçmüyor. Şu ana kadarki en net ölçülmüş fayda, rehberlik sağlandığında en iyi uygulamalara uyumun artması. Metodoloji, sonuçlar ve sınırlamalar için efficacy notu yayımlanmış durumda.

Diğer Cosmos DB araçlarıyla ilişkisi

Spec Kit eklentisi, kodlama ajanlarına yönelik mevcut Cosmos DB araçlarının üzerine uygulama planlama ve uygulama rehberliği ekliyor:

Araçlar ve MCP entegrasyonları: VS Code için Azure Cosmos DB eklentisi ve Azure Cosmos DB Shell içindeki opsiyonel MCP modu, ajanların verdiğiniz izinler çerçevesinde veriyi keşfetmesini ve sorgulamasını sağlıyor.
Agent Kit becerileri: Günlük kodlama görevleri için Cosmos DB bilgisi sunuyor.
Spec Kit eklentisi: Spesifikasyon, plan, uygulama görevleri ve kod incelemesinden oluşan akışa Cosmos DB komutları ve hook’ları ekliyor.

Bunları birlikte kullanabilir ya da işinize uyanı seçebilirsiniz. Eklenti özellikle, uygulama tasarımını kodlama akışının bir parçası olarak belgelemek ve gözden geçirmek istediğiniz projeler için tasarlanmış.

Nasıl denenir?

Eklenti public preview aşamasında, kurulumu da tek satır. Spec Kit’in specify CLI’ını kullanan bir projede:

specify extension add cosmosdb --from https://github.com/AzureCosmosDB/spec-kit-cosmosdb/archive/refs/tags/v0.2.0.zip

Ardından Spec Kit akışını (/specify, /plan, /tasks, /implement) yürütürken önerilen veri modelini ve üretilen kodu adım adım inceleyebilirsiniz. Komut adları ve davranışları preview süresince değişebilir; bu yüzden eklentiyi iyi bildiğiniz bir iş yükü üzerinde denemek, eksik rehberlik, hatalı öneri veya düzeltme gerektiren kod örneklerini de kullandığınız ajan ve model bilgisiyle birlikte issue olarak açmak öneriliyor.

Kaynaklar ve İleri Okuma

Bu yazı yapay zeka (büyük dil modelleri) ile hazırlanmış, insan editör tarafından incelenmiştir. İçerik üretim sürecimiz.

Aşkın KILIÇYazar

20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.

AZ-305AZ-104AZ-500AZ-400DP-203AI-102