"Bana bir uygulama yaz" demek kolay; onu üretime taşımak başka bir şey. Vibe coding küçük prototiplerde harika sonuç verirken, kod tabanı büyüdükçe mimari sapma, bağlam kaybı ve tekrar eden hatalar ortaya çıkıyor — spec-driven development nedir sorusu tam da bu noktada anlam kazanıyor. Bu yazıda vibe coding'in nerede kırıldığını, spec-driven development'ın (SDD) ne olduğunu ve ikisini ne zaman birlikte kullanman gerektiğini adım adım anlatıyorum.
💡 Pro Tip: Spec yazmayı "ekstra iş" değil, agent'a verdiğin talimatın sözleşmesi olarak düşün — spec ne kadar net olursa, gözden geçirmen gereken kod o kadar az olur.
İçindekiler
- Vibe coding neden ölçekte kırılıyor
- Spec-driven development tam olarak nedir
- Spec → plan → task → kod döngüsü
- Küçük işte spec yazmanın maliyeti — ne zaman gerekmez
- CLAUDE.md / kural dosyaları ile SDD akışını kurmak
- Spec'i canlı tutmak: kod değişince spec de değişmeli
- Hibrit model — keşifte vibe, teslimde spec
- SSS
- Spec-driven development nedir?
- Vibe coding ile spec-driven development arasındaki fark nedir?
- Hangi projelerde spec-driven development kullanılmalı?
- Spec yazmak vibe coding'i yavaşlatır mı?
- Spec dosyasını nerede tutmalıyım?
- Güncelleme (Eylül 2026)
- Sonuç
- Kaynaklar
Vibe coding neden ölçekte kırılıyor
Terimin kendisi Şubat 2025'te OpenAI'nin kurucularından ve eski Tesla AI lideri Andrej Karpathy tarafından ortaya atıldı. Karpathy, AI ile sohbet eder gibi konuşup gerisini modele bırakma pratiğini tarif ediyordu; kısa sürede "kodu tam anlamadan, sonuçlara ve takip prompt'larına güvenerek" çalışma biçimi olarak yaygınlaştı.
GitHub'ın Spec Kit lansman yazısı, kırılma noktasını net tarif ediyor: "Bazen kod derlenmiyor. Bazen problemin bir kısmını çözüyor ama asıl niyeti kaçırıyor. Yığın veya mimari seçmeyeceğin bir şey olabiliyor." Yazıya göre sorun agent'ın kodlama yeteneği değil, bizim yaklaşımımız: "Coding agent'ları arama motoru gibi kullanıyoruz, oysa onlara daha çok her şeyi harfi harfine alan çift-programlama ortakları gibi davranmamız gerekiyor."
Bu, hızlı prototipte sorun değil. GitHub'ın kendi ifadesiyle bu "vibe-coding" yaklaşımı "hızlı prototipler için harika olabilir, ama ciddi, kritik-görev uygulamaları inşa ederken veya mevcut kod tabanlarıyla çalışırken daha az güvenilir." Kod tabanı büyüdükçe, agent'a verdiğin doğal dil talimatı belirsizleştikçe, her yeni prompt bir öncekinin varsayımlarını unutuyor — mimari tutarlılık kayboluyor.
Geliştirici Simon Willison'ın erken dönemde dile getirdiği ve Wikipedia'nın "vibe coding" maddesinde aktarılan uyarı da aynı noktaya işaret ediyor: "Production bir kod tabanına vibe coding ile ilerlemek açıkça risklidir. Yazılım mühendisi olarak yaptığımız işin çoğu, mevcut sistemleri evrilmekten ibarettir; burada altta yatan kodun kalitesi ve anlaşılabilirliği kritik önem taşır." Bu cümle, vibe coding'in neden "yeni bir şey yazmak" ile "mevcut bir sistemi büyütmek" arasında farklı davrandığını özetliyor — spec-driven development'ın asıl değer ürettiği yer de ikinci senaryo.
Spec-driven development tam olarak nedir
GitHub, Spec Kit'i duyururken spesifikasyonları yeniden tanımlıyor: "Statik dokümanlar olarak değil, projeyle birlikte evrilen canlı, çalıştırılabilir artifact'lar olarak." Spec'ler paylaşılan doğruluk kaynağı hâline geliyor: "Bir şey mantıklı gelmediğinde spec'e dönersin; proje karmaşıklaştığında onu inceltirsin; görevler çok büyük hissettirdiğinde onları parçalara ayırırsın."
Spec-driven development'ı "vibe coding'in karşıtı" olarak görmek yanıltıcı — daha çok onun disiplinli hâli. Merriam-Webster'ın Mart 2025'te "slang & trending" listesine aldığı tanıma göre vibe coding'de "geliştirici kodun nasıl veya neden çalıştığını anlamak zorunda değildir ve genellikle belirli sayıda bug ve aksaklığın var olacağını kabul etmesi gerekir." SDD tam olarak bu kabulü ortadan kaldırmayı hedefliyor: kod yazılmadan önce ne inşa edildiğinin, neden inşa edildiğinin ve kabul kriterlerinin yazılı hâle gelmesi.
Thoughtworks'ün Kasım 2025 Technology Radar'ı (Vol. 33) konuyu şöyle çerçeveliyor: "Spec-driven development, AI-destekli kodlama iş akışları için yükselen bir yaklaşım... genellikle yapılandırılmış bir fonksiyonel spesifikasyonla başlayıp, onu daha küçük parçalara, çözümlere ve görevlere ayıran çok adımlı bir süreçle devam eden iş akışlarını ifade eder." Aynı rapor üç farklı yorumu karşılaştırıyor; Spec Kit satırındaki faz adlarını GitHub'ın kendi lansman yazısından tamamlıyorum:
Araç | Yaklaşım | Aşamalar |
|---|---|---|
Amazon Kiro | Kullanıcıyı üç aşamadan geçirir | Requirements → Design → Tasks |
GitHub Spec Kit | Benzer süreci "daha zengin orkestrasyon, yapılandırılabilir prompt'lar" ile genişletir | Specify → Plan → Tasks → Implement + "anayasa" (değişmez ilkeler) |
Tessl Framework | Spesifikasyonun kendisini asıl bakımı yapılan artifact hâline getirir (Eylül 2025 itibarıyla özel beta) | Spec-merkezli, koddan bağımsız bakım |
Üçü de aynı temel fikri paylaşıyor — spesifikasyonu koddan önce ve koddan ayrı bir artifact olarak ele almak — ama "ne kadar katı" sorusuna farklı cevap veriyorlar. Spec Kit'in "anayasa" kavramı özellikle dikkat çekici: bu, projenin asla ihlal edilmemesi gereken ilkelerini (örneğin "her API endpoint testli olmalı") ayrı bir dosyada tutup her plan ve task adımında referans olarak kullanmak anlamına geliyor.
Spec → plan → task → kod döngüsü
GitHub'ın Spec Kit'i dört net kontrol noktalı bir süreç izliyor: "Dört fazda, net kontrol noktalarıyla çalışır... mevcut görev tam olarak doğrulanmadan bir sonrakine geçmezsin." Yayınlanan sıra şöyle:
- Specify — üst düzey hedefini agent'a doğal dilde anlatırsın; agent bunu yapılandırılmış bir spesifikasyona dönüştürür.
- Plan — spesifikasyon, teknik bir plana (mimari kararlar, veri modeli, arayüz sınırları) dönüşür.
- Tasks — plan, küçük ve doğrulanabilir görevlere bölünür.
- Implement — agent görevleri tek tek uygular; sen her adımda gözden geçirirsin.
Bu döngünün pratikteki en büyük farkı gözden geçirme biçiminde. GitHub'ın ifadesiyle: "Bin satırlık kod dökümlerini incelemek yerine, sen — geliştirici — belirli problemleri çözen odaklı değişiklikleri gözden geçirirsin." Yani spec, agent'ın ürettiği diff'i küçük ve izlenebilir parçalara bölen bir filtre görevi görüyor.
Kendi spec dosyanı yazarken aşağıdaki gibi minimal bir iskelet işe yarar — amaç, agent'a "ne", "neden" ve "ne zaman bitti" sorularını baştan cevaplamak:
markdown
1# Spec: Kullanıcı bildirim tercihleri2 3## Problem4 5Kullanıcılar hangi bildirim türünü alacağını seçemiyor.6 7## Kabul kriterleri8 9- Kullanıcı e-posta/push/hiçbiri arasında seçim yapabilir10- Tercih değişikliği anında kaydedilir11- Varsayılan: tüm bildirimler açık12 13## Kapsam dışı14 15- Bildirim sıklığı ayarı (sonraki iterasyon)Küçük işte spec yazmanın maliyeti — ne zaman gerekmez
Spec yazmak ücretsiz değil. Thoughtworks'ün Kasım 2025 Technology Radar'ı, SDD'yi bilinçli olarak temkinli bir halkaya — "Assess" (dene ama henüz genel kabul önerme) — yerleştirdi ve şu notu düştü: "Bu alanı büyüleyici buluyoruz, ancak iş akışları hâlâ karmaşık ve fikir sahibi (opinionated). Bu araçlar görev boyutuna ve türüne göre çok farklı davranıyor; bazıları incelemesi zor uzun spec dosyaları üretiyor."
Bu, "her işte spec yaz" demek değil. Ben genelde şu ayrımı kullanırım: tek dosyalık bir bug fix, bir buton rengi değişikliği veya izole bir yardımcı fonksiyon için spec yazmak, çözdüğü sorundan daha pahalıya mal oluyor — orada doğrudan "vibe" ile ilerlemek daha rasyonel. Spec'in değeri, iş büyüdükçe, birden fazla dosyayı/servisi etkiledikçe ve "kabul kriteri" belirsizleştikçe artıyor.
Pratikte spec gerektirmeyen işler genelde şu ortak özelliği taşır: kapsamı tek oturuşta gözden geçirilebilir, geri alması ucuz ve mimari kararı yok. Spec gerektiren işler ise: birden fazla katmanı (API + DB + UI) etkiliyor, "kabul edildi" tanımı tartışmalı, ya da agent'ın önceki denemede yanlış varsayımla ilerlediği bir alan.
Kabaca şu tabloyla karar verebilirsin:
Durum | Spec gerekli mi | Neden |
|---|---|---|
Tek dosyalık bug fix | Hayır | Kapsam tek oturuşta gözden geçirilir |
Yeni buton/stil değişikliği | Hayır | Geri alması ucuz, mimari etkisi yok |
Çok-katmanlı yeni özellik (API+DB+UI) | Evet | Kabul kriteri katmanlar arası tutarlı olmalı |
Mevcut kod tabanına entegrasyon | Evet | Agent mevcut varsayımları bilmiyor |
Hızlı prototip / kanıt-amaçlı demo | Hayır | GitHub'ın kendi ifadesiyle "hızlı prototipler için harika" |
Kritik-görev / production akışı | Evet | Aynı kaynağa göre "daha az güvenilir" olduğu alan |
CLAUDE.md / kural dosyaları ile SDD akışını kurmak
Spec-driven araçların ortak noktası, agent'a tek seferlik değil kalıcı bir bağlam vermesi. GitHub'ın Spec Kit'i bunu Claude Code, GitHub Copilot ve Gemini CLI dahil birden fazla ajanla çalışacak şekilde tasarladı — yani spec dosyaları, tek bir aracın değil, projenin ortak sözleşmesi.
Claude Code'da bu mekanizma zaten var: proje kökündeki CLAUDE.md dosyası, her oturumda otomatik yüklenir ve agent'a projenin kurallarını, dizin yapısını ve "yapma" listesini anlatır. SDD ile CLAUDE.md'yi birlikte kullanmanın en pratik yolu, ikisini farklı katmanlarda tutmak: CLAUDE.md kalıcı proje kurallarını (tech stack, deploy akışı, yasaklar) taşırken, spec dosyası o anki işin kabul kriterlerini taşır.
markdown
1# CLAUDE.md (proje-geneli kural dosyası — kalıcı)2 3- Tech stack: Next.js + Prisma, testler Vitest4- Yeni özellik önce spec.md ile başlar, sonra plan+tasks5- Kritik akışlarda (ödeme/auth) spec zorunlu; küçük fix'te opsiyonelBu ayrım, agent'ın her seferinde "bu proje nasıl çalışıyor" sorusunu yeniden sormasını engelliyor; spec dosyası ise "bu iş ne zaman bitti" sorusunu cevaplıyor.
Bir spec dosyasının kod incelemesinde nasıl kontrol noktası olarak kullanılacağını kısa bir örnekle göstereyim — kabul kriterlerini bash içinde yorum satırı olarak tutup, gözden geçirirken tek tek işaretleyebilirsin:
bash
1# review-checklist.sh — spec.md'deki kabul kriterlerini PR'a karşı işaretle2# [ ] Kullanıcı e-posta/push/hiçbiri arasında seçim yapabiliyor mu?3# [ ] Tercih değişikliği anında kaydediliyor mu?4# [ ] Varsayılan tüm bildirimler açık mı?5# Her satır agent'ın ürettiği diff'te karşılığını bulmadan PR onaylanmazSpec'i canlı tutmak: kod değişince spec de değişmeli
GitHub'ın Spec Kit yazısındaki en kritik cümlelerden biri şu: spec'ler "statik dokümanlar değil, projeyle birlikte evrilen canlı, çalıştırılabilir artifact'lar." Bu, geleneksel PRD'lerin düştüğü tuzağın tam tersi — yazılıp bir kere onaylandıktan sonra rafa kaldırılan, koddan giderek kopan bir doküman değil.
Pratikte bu şu anlama geliyor: "Bir şey mantıklı gelmediğinde spec'e dönersin; proje karmaşıklaştığında onu inceltirsin; görevler çok büyük hissettirdiğinde onları parçalara ayırırsın." Yani spec tek yönlü bir girdi değil, geri besleme döngüsünün parçası. Agent bir varsayımla çakışan bir kod yazdığında, önce spec'i düzeltirsin, sonra kodu yeniden ürettirirsin — kodu elle yamayıp spec'i eski hâliyle bırakmazsın.
Bunu disipline etmenin en basit yolu: spec dosyasını kodla aynı pull request'te tutmak. Spec değişmeden kod değişiyorsa, o PR'da bir tutarsızlık var demektir — review sırasında ilk bakılacak yer de burası.
Hibrit model — keşifte vibe, teslimde spec
GitHub'ın kendi çerçevesi burada da yol gösterici: "Bu 'vibe-coding' yaklaşımı hızlı prototipler için harika olabilir, ama ciddi, kritik-görev uygulamaları inşa ederken veya mevcut kod tabanlarıyla çalışırken daha az güvenilir." Bu tek cümle aslında hibrit modelin tarifi — hangi aşamada hangi modun kullanılacağını söylüyor.
Pratikte üç aşamalı bir akış işe yarıyor:
- Keşif (vibe): "Bu nasıl görünür, bu API nasıl davranır" sorularını hızlıca cevaplamak için agent'a doğrudan doğal dille prompt at, kodu çalıştır, at, tekrar dene. Amaç öğrenmek, üretmek değil.
- Karar (spec): Keşifte netleşen yaklaşımı spec.md'ye yaz — kabul kriterleri, kapsam dışı, mimari kısıtlar.
- Teslim (implement): Spec'e göre agent'tan küçük, gözden geçirilebilir diff'ler iste; her diff'i spec'e karşı doğrula.
Bu üç aşama arasında geçiş maliyeti düşük tutulduğu sürece hibrit model, "ya hep vibe ya hep spec" ikileminden kurtarıyor.
Somut bir örnek üzerinden gidelim: diyelim ki mevcut bir e-ticaret uygulamasına "favori ürünler" özelliği ekleyeceksin. Keşif aşamasında agent'a "kullanıcı bir ürünü favoriye eklediğinde arayüz nasıl tepki vermeli" diye sorup birkaç hızlı prototip ürettirebilirsin — hangisi kullanıcı deneyimi açısından daha iyi hissettiriyor, bunu görmek istiyorsun, üretim kodu yazmıyorsun. Karar aşamasında bu keşiften çıkan yaklaşımı ("favori butonu optimistic update yapacak, backend hatası durumunda geri alınacak") spec'e yazarsın. Teslim aşamasında ise agent'tan bu spec'e göre önce veri modelini, sonra API endpoint'ini, sonra arayüz bileşenini ayrı diff'ler hâlinde ister ve her birini spec'teki kabul kriterine karşı kontrol edersin. Keşif aşamasında üretilen kodun hiçbiri doğrudan teslim aşamasına kopyalanmaz — yalnızca öğrenilen karar taşınır.
ALTIN İPUCU
Bu yazının en değerli bilgisi
Bu ipucu, yazının en önemli çıkarımını içeriyor.
Easter Egg
Gizli bir bilgi buldun!
Bu bölümde gizli bir bilgi var. Keşfetmek ister misin?
Okuyucu Ödülü
Bir sonraki özelliği agent'a yazdırmadan önce kullanabileceğin, spec-driven geçişin ilk on dakikasını kapsayan hızlı bir kontrol listesi hazırladım. Amaç, spec yazmayı bir formaliteye değil, gerçek bir karar anına dönüştürmek — her madde tek başına iki dakikada cevaplanabilir olacak şekilde seçildi.
SSS
Spec-driven development nedir?
Spec-driven development, AI-destekli kodlama iş akışlarında yükselen bir yaklaşımdır; genellikle yapılandırılmış bir fonksiyonel spesifikasyonla başlayıp bunu daha küçük parçalara, çözümlere ve görevlere ayıran çok adımlı bir süreçle devam eder (Thoughtworks Technology Radar Vol. 33 tanımı). GitHub'ın Spec Kit'inde bu süreç Specify → Plan → Tasks → Implement dört fazına karşılık gelir.
Vibe coding ile spec-driven development arasındaki fark nedir?
Vibe coding'de geliştirici hedefi doğal dille tarif eder ve kodun nasıl çalıştığını derinlemesine anlamadan sonuçlara güvenir; Merriam-Webster'ın tanımıyla "belirli sayıda bug ve aksaklığın var olacağını kabul etmesi gerekir." Spec-driven development ise kodu yazmadan önce kabul kriterlerini, kapsamı ve mimari kısıtları yazılı hâle getirir; GitHub'ın ifadesiyle gözden geçirme "bin satırlık kod dökümleri" yerine "odaklı değişiklikler" üzerinden yapılır.
Hangi projelerde spec-driven development kullanılmalı?
Thoughtworks'e göre araçlar "görev boyutuna ve türüne göre çok farklı davranıyor." Pratikte birden fazla katmanı etkileyen, mevcut kod tabanına entegre olan veya kabul kriteri tartışmalı işlerde spec değerli; GitHub'ın tarifiyle "ciddi, kritik-görev uygulamaları" bu kategoriye giriyor.
Spec yazmak vibe coding'i yavaşlatır mı?
Kısa vadede evet, çünkü kodlamaya başlamadan önce düşünme adımı ekler. Ancak Thoughtworks'ün temkinli notu da gösteriyor ki bu bir ödünleşim: "iş akışları hâlâ karmaşık ve fikir sahibi." Küçük, tek dosyalık işlerde bu maliyet karşılığını vermez — spec'i yalnız kapsamı büyük ve geri alması pahalı işlerde kullanmak, toplam hızı düşürmek yerine artırır.
Spec dosyasını nerede tutmalıyım?
Kodla aynı depoda, ilgili pull request ile birlikte. Böylece spec ile kod arasındaki tutarsızlık review sırasında hemen görülür; CLAUDE.md gibi proje-geneli kural dosyaları kalıcı kuralları taşırken, spec dosyası o anki işin kabul kriterlerini taşır.
Güncelleme (Eylül 2026)
Bu yazının gövdesi 18 Kasım 2025 itibarıyla geçerli bilgilerle yazıldı. O tarihten bu yana hem vibe coding'in riskleri hem de spec-driven araçların kapsamı somut biçimde genişledi.
Kanıtlar ağırlaştı. Aralık 2025'te CodeRabbit'in 470 açık kaynak GitHub pull request'i üzerinde yaptığı analiz, üretken AI ile birlikte yazılan kodun insan yazımı koda kıyasla yaklaşık 1,7 kat daha fazla "major" sorun içerdiğini ortaya koydu; yanlış yapılandırmalar %75 daha sık, güvenlik açıkları ise 2,74 kat daha yüksek çıktı. Aynı dönemde Orchids adlı bir vibe coding platformunda güvenlik araştırmacısı Etizaz Mohsin tarafından keşfedilen bir açık, Şubat 2026'da BBC News'e gösterildi.
Vibe coding ana akıma iyice yerleşti. Ocak 2026'da Linus Torvalds'ın, hobi projesi bir ses efekti üretici için görselleştirme aracını Google Antigravity ile "vibe-coding" yöntemiyle yazdığı ortaya çıktı; Torvalds bunu projenin README dosyasında sınırlı Python bilgisine bağladı.
Spec Kit tek akıştan çoklu giriş noktasına genişledi. Bugün (23 Eylül 2026) itibarıyla projenin güncel README'si artık yalnız "spec ile inşa et" değil, "bug fix" ve "fikir değerlendirmesi" gibi bağımsız giriş noktalarını da tanımlıyor ("Build with a spec, fix a bug, or assess an idea"). Yıldız sayısı aynı tarihte 139k'ye ulaştı; Kasım 2025'te Thoughtworks Radar'da karşılaştırılan Amazon Kiro'nun herkese açık geri bildirim deposu ise 4,3k yıldızda — bu depo ürünün kendi kaynak kodu deposu değil.
Bu üç gelişme birlikte okunduğunda tablo net: vibe coding'in ölçek sorunları veri ile daha somut hâle geldi, spec-driven araçlar ise yalnız "yeni özellik yaz" senaryosunun ötesine (bug fix, fikir değerlendirmesi) genişleyerek disiplinli akışı daha geniş bir iş yelpazesine taşıdı.
Sonuç
Vibe coding ile spec-driven development bir rekabet değil, aynı iş akışının iki farklı aşaması. Keşifte hız için vibe'a güvenip, teslimde kabul kriterlerini yazılı hâle getirerek spec'e geçmek, agent'ın gücünden vazgeçmeden mimari sapmayı önlüyor. Eğer Claude Code kullanıyorsan bu ayrımı kurmanın en doğal yolu, kalıcı kuralları CLAUDE.md dosyasında tutup, o anki işin kabul kriterlerini ayrı bir spec dosyasında taşımak.
Bir sonraki adım olarak, agent'a büyük bir özelliği tek seferde yazdırmadan önce işi nasıl planladığını Claude Code Plan Mode ile deneyebilir, birden fazla agent'ı paralel çalıştırman gerekiyorsa Multi-Agent Teams rehberine bakabilirsin. Vibe coding ile başlayıp production'a taşırken karşılaşacağın tuzakları Vibe Coding MVP'sini Production'a Taşıma Rehberi ve Vibe Coding Güvenlik Kontrol Listesi ayrıntılı biçimde ele alıyor. Spec-driven akışta agent'ın ürettiği kodu nasıl test ettireceğini merak ediyorsan AI Destekli Unit Test Üretimi rehberi de bu yazının doğal devamı.
Kaynaklar
- Spec-driven development with AI: Get started with a new open source toolkit — GitHub'ın resmi Spec Kit lansman yazısı; dört fazlı Specify/Plan/Tasks/Implement sürecini ve "canlı, çalıştırılabilir artifact" tanımını içeriyor.
- Spec-driven development — Thoughtworks Technology Radar Vol. 33 — Kasım 2025 tarihli, SDD'yi "Assess" halkasına yerleştiren, Kiro/Spec Kit/Tessl karşılaştırmasını içeren birincil kaynak.
- Vibe coding — Wikipedia — Karpathy'nin Şubat 2025 kökeni, CodeRabbit Aralık 2025 analizi ve Torvalds Ocak 2026 örneği dahil güncel olay örgüsü.
- 'Vibe coding' named word of the year by Collins Dictionary — BBC News, 6 Kasım 2025; terimin Karpathy tarafından Şubat 2025'te ortaya atıldığının teyidi ve Collins Word of the Year duyurusu.
- github/spec-kit — GitHub deposu — Spec Kit'in güncel (Eylül 2026) README'si, "build with a spec, fix a bug, or assess an idea" genişlemesinin kanıtı.
- kirodotdev/Kiro — GitHub deposu — Amazon Kiro'nun herkese açık geri bildirim deposu; 23 Eylül 2026 itibarıyla 4,3k yıldız (GitHub API: 4.330), "Güncelleme" bölümündeki Kiro rakamının kaynağı.
- Spec Kit — GitHub stars badge (shields.io) — 23 Eylül 2026 itibarıyla canlı yıldız sayısı ölçümü (139k), "Güncelleme" bölümündeki rakamın kaynağı.
