GitHub’un Spec Kit’i - Yüksek Kaliteli Yazılımı Daha Hızlı Geliştirmek

• Spec-Driven Development: Geleneksel geliştirmede yardımcı bir araç olan spec (şartname) kavramını çalıştırılabilir spec düzeyine çıkararak, spec’ten doğrudan çalışan bir implementasyon üretmeyi hedefleyen yaklaşım
  • Kod merkezli alışkanlığı dönüştürerek önce ne ve neden sorularını tanımlayıp, daha sonra nasıl kısmını somutlaştıran niyet odaklı geliştirmeyi vurgular
  • Temel fikir, spec aracılığıyla tutarlı çıktılar üretmek ve tekrar eden işleri otomatikleştirerek geliştiricinin ürün problemlerine odaklanmasını sağlamaktır
• Spec Kit, bu spec’leri çalıştırılabilir çıktılara dönüştürerek implementasyonu otomatikleştirmeye yardımcı olan bir araç setidir
• Kurulumdan sonra /specify ile ne/neden anlatılır, /plan ile stack/mimari tanımlanır, /tasks ile iş birimleri oluşturulur
• Amaç, organizasyonların fark yaratmayan ortak kodu yazmaktan çıkıp ürün senaryolarına odaklanmasına yardımcı olmak; spec odaklı yaklaşımla hem kaliteyi hem de hızı artırmayı amaçlayan deneysel bir çerçeve sunmaktır

Temel felsefe: Core philosophy

• Niyet odaklı geliştirme ile neyi öne çıkaran ve nasıl kısmını daha sonra somutlaştıran spec önce düşünce yapısı
• Guardrail’ler ve kurumsal ilkeler içeren zengin spec’ler yazılır; tek seferlik kod üretimi yerine çok aşamalı rafinasyon süreci izlenir
• Gelişmiş yapay zeka modellerinin yorumlama yeteneğine aktif biçimde dayanarak spec’i çalıştırılabilir sonuçlara dönüştürmeyi hedefler

Spec Kit ile spec odaklı süreç

• Spec Kit, spec’i mühendislik sürecinin merkezine yerleştirir; implementasyon, checklist ve iş kırılımını bunun üzerinden yönlendirir, geliştirici ise çoğunlukla yönlendirici rol üstlenir
  • Yazım işlerinin büyük kısmını coding agent üstlenir
• Süreç 4 aşamadan oluşur; her aşamada net kontrol noktaları vardır ve mevcut çalışma tamamen doğrulanmadan bir sonraki aşamaya geçilmez
• Specify aşaması: Yüksek seviyeli açıklama verildiğinde coding agent ayrıntılı bir spec üretir; bu, teknoloji stack’ine değil kullanıcı yolculuğuna, deneyime ve başarı metriklerine odaklanır
  • Kullanıcının kim olduğu, hangi problemin çözüldüğü, etkileşim biçimi ve önemli sonuçlar haritalanır
  • Bu, kullanıcıdan öğrenildikçe evrilen canlı bir artifact niteliği taşır
• Plan aşaması: İstenen stack, mimari ve kısıtlar verildiğinde coding agent kapsamlı bir teknik plan üretir
  • Şirketin standart teknolojileri, legacy sistem entegrasyonu, mevzuat uyumu ve performans hedefleri buna dahildir
  • Karşılaştırma için birden fazla plan varyasyonu istenebilir; iç dokümanlar sağlanırsa mimari kalıplar doğrudan entegre edilir
• Tasks aşaması: Spec ve plan temelinde coding agent işleri küçük, gözden geçirilebilir parçalara böler
  • Her görev bağımsız şekilde implementasyon ve test edilebilir; yapay zekanın görevleri doğrulayıp takip edebilmesi için tasarlanır
  • Örneğin “kimlik doğrulama kur” yerine “e-posta formatı doğrulaması yapan kullanıcı kayıt endpoint’i oluştur” gibi somuttur
• Implement aşaması: Coding agent görevleri tek tek ya da paralel işler, geliştirici ise odaklı değişiklikleri gözden geçirir
  • Spec neyin inşa edileceğini, plan bunun nasıl inşa edileceğini, tasks ise hangi işlerin yapılacağını gösterir
• Her aşamada geliştirici düşünüp rafine eder; spec’in niyeti yakalayıp yakalamadığını, planın gerçek kısıtları dikkate alıp almadığını, eksik veya edge case olup olmadığını denetleyen bir doğrulayıcı rolü üstlenir

Agentic workflow içinde Spec Kit nasıl kullanılır

• Spec Kit, GitHub Copilot, Claude Code, Gemini CLI gibi coding agent’larla çalışır; basit bir komut dizisiyle agent’ı yönlendirip artifact’ler üretir
  • Bu yaklaşım, muğlak prompt’ları net niyetlere dönüştürerek güvenilir icra sağlar
• Proje başlatıldıktan sonra /specify komutuyla yüksek seviyeli prompt verildiğinde coding agent projenin tüm spec’ini üretir ve projenin “ne” ve “neden”ine odaklanır
• /plan komutuyla yüksek seviyeli teknik yön verildiğinde coding agent mimariye ve kısıtlara saygı duyan ayrıntılı plan oluşturur
• /tasks komutuyla spec ve plan çalıştırılabilir görev listesine ayrıştırılır; coding agent da buna göre proje gereksinimlerini uygular

Geliştirme aşamaları: Development phases

• 0-to-1 (greenfield) aşaması: Yüksek seviyeli gereksinimlerden yola çıkarak spec oluşturma → plan yapma → production-grade uygulama üretme akışını destekler
• Yaratıcı keşif aşaması: Farklı stack/mimari ve UX pattern’lerini paralel implementasyon ile deneme sürecini öne çıkarır
• Kademeli iyileştirme (brownfield) aşaması: özellik ekleme, legacy modernizasyonu ve süreç uyarlamasını yinelemeli biçimde sürdüren evrimsel geliştirme yaklaşımı

Bu yaklaşımın iyi çalıştığı 3 senaryo

• Greenfield (zero-to-one): Yeni projeye başlarken hemen kod yazmak yerine önce spec ve plan hazırlanır; böylece yapay zekanın niyet edilen şeyi inşa etmesi sağlanır ve genel kalıplara dayalı sıradan çözümler yerine özelleştirilmiş sonuçlar elde edilir
• Mevcut sistemde özellik geliştirme (N-to-N+1): Karmaşık bir codebase’e özellik eklerken spec, yeni özelliğin mevcut sistemle etkileşimini netleştirir; plan ise mimari kısıtları kodlayarak sisteme doğal biçimde oturan kod üretilmesini sağlar
  • Bu, sürekli geliştirmeyi daha hızlı ve daha güvenli hale getirir; gelişmiş context engineering teknikleri gerekebilir
• Legacy modernizasyonu: Legacy sistemi yeniden kurarken özgün niyet kaybolmuşsa, Spec Kit süreci temel iş mantığını modern spec’e taşır ve yeni bir mimari planlayarak yapay zekanın teknik borç olmadan yeniden inşa etmesini sağlar

Önkoşullar

• Linux/macOS veya Windows üzerinde WSL2 gerekir
• Yapay zeka agent’ı olarak Claude Code, GitHub Copilot, Gemini CLI, Cursor seçeneklerinden biri seçilir

[edunga1]

Copilot Workspace'ı hatırlatıyor.

[cocofather]

Doğal dil tabanlı yapay zeka programlamasının temeli olacak gibi görünüyor.

[tested]

GitHub’un Spec Kit’inin avantajları GitHub Copilot’ta da kullanılabiliyor.
GitHub tarafından yapıldığı için elbette denebilir ama diğer araçların çoğu Claude tabanlıydı.

[skageektp]

Kiro IDE'yi hatırlatıyor.

[kandk]

İlginçmiş. Mantıklı da geliyor.

[xguru]

Yazının ortasındaki SDD ayrıntılı tanıtım bağlantısındaki içerik oldukça iyi. Aşağıda bunu yapay zeka ile özetledim.

Spesifikasyon Odaklı Geliştirme (Specification-Driven Development, SDD)

Gücün Tersine Dönüşü

• Kodu merkeze alıp PRD ve tasarım belgelerini yardımcı unsur olarak kullanan akışı tersine çevirerek, spesifikasyonun asıl kaynak ve kodun da belirli bir dil ya da framework üzerinde gerçekleştirilen bir ifade biçimi olduğunu savunuyor
  • Spesifikasyon ile implementasyon arasındaki kalıcı boşluğun belge takviyesi ya da süreç sıkılaştırmasıyla giderilmesinin zor olduğuna dair bir tespit sunuyor
  • Çalıştırılabilir spesifikasyonlar ve uygulama planı kodu üretirse bu boşluk ortadan kalkar ve geriye yalnızca dönüşüm kalır
• Yapay zeka, karmaşık spesifikasyonların yorumlanmasını ve uygulama planlarının oluşturulmasını mümkün kılar; ancak yapısız üretim kaosa yol açtığı için SDD, kaliteyi kesin yapı ve koruyucu sınırlar ile güvence altına alır
• Bakım, spesifikasyonun evrimleşmesi eylemidir; geliştirme niyeti doğal dil, tasarım varlıkları ve temel ilkelerle ifade edilir, kod ise son mil konumundadır
• Hata ayıklamada yanlış kodu düzeltmekten çok spesifikasyonun ve uygulama planının düzeltilmesi öncelik kazanır; refactoring ise açıklığın yeniden yapılandırılması olarak yeniden tanımlanır

Pratikte SDD İş Akışı

• Fikir, yapay zeka ile konuşmalı etkileşim üzerinden PRD'ye dönüştürülerek rafine edilir; yapay zeka soruları, edge case'leri ve kabul kriterlerini somutlaştırır
  • Gereksinim ve tasarımı sürekli bir etkinliğe dönüştürerek ekip düzeyinde branch tabanlı spesifikasyon çalışması, inceleme ve sürümlemeyi destekler
• Araştırma ajanı, kütüphane uyumluluğu, performans, güvenlik ve kurumsal kısıtları (DB standardı, kimlik doğrulama, dağıtım politikası) araştırır ve bunları otomatik olarak spesifikasyona yansıtır
• PRD'den uygulama planı üretilerek gereksinimler ile teknik kararlar izlenebilir biçimde eşleştirilir; yapay zeka da çelişkileri, belirsizlikleri ve eksikleri sürekli doğrular
• Spesifikasyon ve plan yeterince olgunlaştığında kod üretimi başlar; ilk aşamada ise keşif amaçlı üretim ile uygulanabilirlik doğrulanır
  • Alan kavramları veri modeli, kullanıcı hikâyeleri API endpoint'leri, kabul senaryoları ise testler hâline dönüştürülür
• Operasyon aşamasındaki metrikler ve incident'lar, spesifikasyonu güncelleyerek bir sonraki yeniden üretime yansıtılır; performans darboğazları işlevsel olmayan gereksinimler, güvenlik açıkları ise genel kısıtlar seviyesine yükseltilir

SDD Neden Şimdi Önemli?

• Yapay zeka yetenek eşiği: Doğal dildeki spesifikasyonlardan güvenilir biçimde çalışan kod üretmek mümkün hâle geldi; implementasyon çevirisinin mekanik kısmının otomasyonu, keşfi ve yaratıcılığı artırmayı destekliyor
• Karmaşıklığın patlaması: Çok sayıda servis, framework ve bağımlılık nedeniyle niyet-implementasyon uyumunu korumak zorlaştı; bu yüzden SDD'nin spesifikasyon güdümlü hizalamasına ihtiyaç var
• Değişimin hızlanması: Sık pivot yaşanan durumlarda SDD, değişiklikleri belge-tasarım-kod arasında elle yaymak yerine sistematik yeniden üretimle ele alır
  • Örnek olarak what-if simülasyonları ve paralel implementasyonu mümkün kılarak karar alma çevikliği sağlar

Temel İlkeler

• Spesifikasyon = ortak dil: Spesifikasyon birinci sınıf çıktıdır, kod belirli bir stack'in ifadesidir ve bakım da spesifikasyonun evrimi eylemidir
• Çalıştırılabilir spesifikasyon: Doğru, eksiksiz ve yoruma kapalı seviyedeki spesifikasyonlarla çalışan sistem üretilir
• Sürekli rafinasyon: Tek seferlik bir kapı yerine sürekli tutarlılık doğrulaması yapılır
• Araştırma temelli bağlam: Performans, güvenlik ve kurumsal kısıtlar sürekli toplanarak spesifikasyona eklenir
• İki yönlü geri bildirim: Operasyondaki gerçeklik, spesifikasyon güncellemesinin girdisi olur
• Keşif için dallanma: Aynı spesifikasyondan performans, bakım yapılabilirlik, UX, maliyet gibi optimizasyon hedeflerine göre birden çok implementasyon üretilmesi desteklenir

Uygulama Yaklaşımları

• Bugün uygulanabilir kısımda asıl önemli olan, mevcut araçları bir araya getirmek ve disiplini korumaktır; bu da şu unsurlarla mümkündür
  • Spesifikasyonun yinelemeli rafinasyonu için yapay zeka asistanı
  • Teknik bağlam toplamak için araştırma ajanı
  • Spesifikasyondan implementasyona dönüşüm için kod üretim araçları
  • Spesifikasyon öncelikli iş akışına uygun sürüm kontrolü
  • Spesifikasyon belgeleri üzerinde yapay zeka tutarlılık analizi temelli kontrol
• Ortak ilke, spesifikasyonu tek doğruluk kaynağı olarak konumlandırmak ve kodu da spesifikasyonun talep ettiği çıktı olarak ele almaktır

Komutlarla SDD'yi Akıcı Hâle Getirmek

• /specify: Özellik açıklamasını yapılandırılmış bir spesifikasyona dönüştürür; otomatik numaralandırma, branch oluşturma ve şablon tabanlı dizin kurulumunu otomatikleştirir
• /plan: Spesifikasyon analizi → anayasa uyumluluğu incelemesi → teknik çeviri → veri modeli, API sözleşmesi, test senaryoları dokümantasyonu → quickstart doğrulaması üretir
• /tasks: plan.md ve ilgili tasarımı okuyarak uygulanabilir görev listesi üretir; paralel yapılabilecek görevleri işaretler ve güvenli paralel gruplandırma sağlar
• Örnek: sohbet özelliği
  • Geleneksel yaklaşımda yaklaşık 12 saatlik dokümantasyon işini, spesifikasyon, plan ve görev otomasyonuyla yaklaşık 15 dakikalık kurulum düzeyine indiren bir akış örneği sunuluyor
  • Çıktılar arasında spesifikasyon, uygulama planı ve gerekçeleri, API sözleşmesi ve veri modeli, quickstart senaryosu, tasks.md bulunuyor ve bunlar branch içinde sürüm kontrolüne alınıyor

Yapılandırılmış Otomasyonun Gücü

• Eksik öğeleri önleme: Şablonlar, işlevsel olmayan gereksinimler ve hata işleme dâhil olmak üzere kapsamı genişletir
• Karar izlenebilirliği: Tüm teknik seçimler somut gereksinimlerle ilişkilendirilir
• Yaşayan belge: Spesifikasyon kodu ürettiği için senkronizasyonu korumak kolaylaşır
• Hızlı yineleme: Gereksinim değiştiğinde planı yeniden üreterek dakika ya da saat ölçeğinde yanıt vermek mümkün olur

Şablon Tabanlı Kalite

• Uygulama ayrıntılarının erken sızmasını önleme: WHAT/WHY odaklı, HOW'u dışarıda bırakan kurallarla soyutlama seviyesinin korunması teşvik edilir
• Belirsizlik işaretlemeyi zorunlu kılma: [NEEDS CLARIFICATION] işareti ile tahmini yasaklama ve açık soru sorma teşvik edilir
• Kontrol listesi tabanlı öz denetim: Tamlık, açıklık ve ölçülebilir kabul kriterleri kontrol edilerek kalite kapısı oluşturulur
• Anayasa kapısı: Basitlik kapısı (≤3 proje), anti-abstraction kapısı (framework'ü doğrudan kullanma), entegrasyon öncelikli kapı (sözleşme ve sözleşme testlerini önceleme) gibi ön aşama (-1) kontrolleri uygulanır
• Katmanlı ayrıntı yönetimi: Aşırı kod ve ayrıntı, implementation-details/ altına ayrılarak okunabilirlik korunur
• Test önceliği: Sözleşme → entegrasyon → E2E → birim sırasındaki dosya üretimi ve test önceliği kurallarıyla doğrulanabilirlik sağlanır
• Varsayım ve tahmini özellikleri bastırma: Tahmine dayalı özellik yasağı ve aşama bazlı ön koşulların açıkça belirtilmesiyle kapsam yönetimi güçlendirilir

Anayasal Temel

• memory/constitution.md içindeki değişmez ilkelerle, tüm implementasyonların tutarlı, sade ve yüksek kaliteli kalmasını sağlayan bir geliştirme anayasası benimsenir
  • Article I: Library-First — Her özellik bağımsız bir kütüphane olarak başlar ve modülerlik sağlar
  • Article II: CLI Mandate — Her kütüphane, metin girdi/çıktısı ve JSON destekleyen bir CLI arayüzü sunarak gözlemlenebilirliği ve test kolaylığını güvence altına alır
  • Article III: Test-First — Test onayı ve başarısızlık (red) doğrulanmadan implementasyon yasaktır; önce davranışı tanımlama ilkesi uygulanır
  • Articles VII & VIII: Basitlik ve anti-abstraction — Proje sayısını en aza indirme ve framework'lere doğrudan güvenme ile aşırı mühendislik engellenir
  • Article IX: Integration-First Testing — Gerçek ortama yakın testler tercih edilir ve sözleşme testleri implementasyondan önce zorunlu tutulur
• Şablonlardaki Phase -1 kapısı, anayasa uyumluluğunu kontrol listesi hâline getirir; istisnalar ise Complexity Tracking içinde açık gerekçeyle kaydedilir
• Değişiklik prosedürü sayesinde ilkelerin uygulanma biçimi evrilebilir, ancak çekirdek felsefe korunur

Dönüşüm

• Hedef, geliştiricilerin yerini almak değil; mekanik çeviriyi otomatikleştirerek insan yeteneklerini güçlendirmek ve niyet-implementasyon uyumunu korumaktır
• SDD, spesifikasyonun kodu üretmesini sağlayarak spesifikasyon, araştırma ve kodun sıkı bir geri bildirim döngüsü içinde birlikte evrildiği sürekli dönüşümü hayata geçirir

[amoplan]

Bunu hangi yapay zekayla özetlediniz?

[xguru]

Bunu GPT-5 ile yaptım. Özetleme amacıyla benim düzenlediğim oldukça uzun bir prompt kullanıyorum.

[heycalmdown]

Bu konsepte oldukça katıldığım için hafta sonu yeni bir projede biraz test ettim, ama düşündüğüm kadar iyi çalışmıyor. Hâlâ çok fazla iyileştirmeye ihtiyaç var gibi görünüyor. Öncelikle kabaca çalışma şekli, daha önce birçok kez tanıtıldığı gibi, şöyle: spesifikasyon yazımı → spec yazımı → görev yazımı → uygulama

Sorun ise şu:

• constitution.md dosyası "nasıl geliştireceğiz" konusundaki temel rehber ama "bu uygulama sonunda ne olacak" bilgisini içermiyor
• spec.md, tek bir özelliği açıklayan bir doküman
• "bu uygulama nedir" sorusuna cevap veren bir ana doküman yok
• GitHub'da yürüyen tartışmaları okuyunca, spec zincirinin eninde sonunda source of truth olacağı söyleniyor gibi görünüyor. Biraz kuşkulandırıyor ama kabaca anlayabildim.
• /specify ve /tasaks komutlarıyla çok sayıda doküman çıktı olarak üretiliyor (istediğim sonuç buydu), ama bu yüzden sanırım context çok hızlı tüketiliyor (Claude Code kullanıyorum)
• Bir kez implementasyona girince, bir süre Spec Kit'ten uzaklaşılıyor ve her zamanki gibi Claude Code ile sohbet ederek implementasyon tamamlanıyor
• Tüm context tüketilip compaction yapıldığında ya da yeni bir oturum başlatıldığında, Spec Kit'in oluşturduğu dokümanların varlığı unutuluyor
• tasks.md içinde tanımlı işleri ilerletirken, başta düzgün yapılmış şeylerin üzerine yazılabildiği ve bug düzeltme sürecinde yeni özellikler de yapılabildiği için tasks.md ile giderek bağ kopuyor. tasks.md'yi kalıcı olarak saklamanın anlamını bilmiyorum.

Şimdilik vardığım sonuçlar şöyle:

• İlk düşünülen şeyden farklı bir sonuç çıksa bile, önce spec'i tamamlayıp ardından yeni bir spec oluşturarak yavaş yavaş düzeltmek gerekiyor
• İlk spec kaçınılmaz olarak büyüyecek, bu yüzden uygulamanın işlevlerini hiç açıklamadan sadece boilerplate oluşturmak daha iyi olabilir
• PoC seviyesinde bir şey yaparken Spec Kit kullanmamak daha iyi olabilir