Yapay zekâyla kod yazmak, açık konuşayım, insanı başta biraz sarhoş ediyor. Bir iki komut veriyorsun. Ekranın altından bir sürü kod akıyor. Sonra bir bakıyorsun ki proje ortada ama neden öyle yapıldığına dair tek satır açıklama yok. İşin aslı şu ki, sorun kodun kendisi değil — asıl eksik kalan şey niyet. Ben de son iki yılda, özellikle 2024 baharında İstanbul’da üzerinde çalıştığım küçük bir SaaS prototipinde bunu net gördüm: Kod vardı, hız vardı, hatta demo da çıkmıştı,. Biri gelip “neden böyle yaptık?” deyince odada hafif bir sessizlik oluyordu, herkes birbirine bakıyordu, kimse tam cevap veremiyordu. Evet. Aynen öyle.
Küçük bir detay: Holger Leichsenring’in anlattığı yaklaşım tam burada devreye giriyor: önce spesifikasyon, sonra ajanlar, en son kod. Yani “hadi yaz bakalım” demek yerine önce ne yapılacağını, hangi sınırlarla yapılacağını. Neden o yoldan gidildiğini netleştiriyorsun. Bu bana bayağı tanıdık geldi. 2023’te Ankara’da bir ekip toplantısında benzer bir karmaşa yaşamıştık — herkes AI araçlarını sevmişti ama üç hafta sonra aynı modül için üç farklı yorum ortaya çıkmıştı. Klasik. Specification-first çalışma işte bu dağınıklığı biraz toparlıyor, en azından bende öyle işe yaradı.
Neden AI ile Kod Yazarken Yol Haritası Şart?
Bak şimdi, klasik geliştirici alışkanlığı nedir? Önce çözümü düşünürsün. Sonra kodu yazarsın. En son da dokümantasyonu “bir ara eklerim” diye erteleyip unutursun. Yapay zekâ gelince bu akış iyice ters yüz oldu, çünkü model sana saniyeler içinde çözüm üretiyor ama o çözümün arkasındaki mantığı taşımıyor. Yani hani hızlıca yemek söylersin de gelen tabakta ne olduğunu tam anlayamazsın ya — biraz öyle bir his.
Benim editör masasında en çok dikkatimi çeken şey şu oldu: İyi yapılandırılmış projelerde AI gerçekten iş görüyor. Klasör düzeni temizse, isimler tutarlıysa, sınırlar belliyse, Claude veya Codex gibi araçlar fena olmayan sonuç veriyor (ki bu çoğu kişinin gözünden kaçıyor). Ama proje zaten dağınıksa? İşte orada işler çorba oluyor, hem de hızla. Aynı şeyi geçen ay İzmir’de freelance çalışan bir arkadaşım da söyledi; “temiz repo’da hızlanıyorum. Yamalı bohça projede model beni daha da yoruyor” dedi. Katılıyorum, yüzde yüz katılıyorum.
Specification-first yaklaşımın güzelliği tam burada ortaya çıkıyor (bizzat test ettim). Modeli direkt koda salmak yerine önce hedefleri veriyorsun: kullanıcı senaryosu, kabul kriterleri, teknik kısıtlar, güvenlik notları… Böylece AI artık sadece üretici değil, daha kontrollü bir yardımcı haline geliyor. Kâğıt üstünde süper duruyor tabii. Ben de ilk başta “göreceğiz” diyordum ama denedikçe mantığı oturdu, itiraf edeyim.
Koddan önce düşünceyi kilitlemek
Bir projede kararların yarısı görünmezdir. Neden PostgreSQL seçildi? Neden event-driven mimariye geçilmedi? Neden bu endpoint senkron kaldı? Bunlar sonradan unutuluyor. Altı ay sonra kimse hatırlamıyor, soran da yok aslında — ta ki bir şeyler bozulana kadar. Spesifikasyon katmanı tam burada devreye giriyor; kararları sadece saklamıyor, tekrar kullanılabilir hale de getiriyor.
Bu arada küçük startup ile enterprise arasındaki fark gerçekten büyük. Küçük ekipte hız baskısı var, (belki yanılıyorum ama) herkes “çabuk bitirelim” diyor. Kurumsal tarafta ise onay süreçleri uzadıkça uzuyor — bazen fazla bile uzuyor, bu ayrı bir dert. Spec-first yaklaşım aslında ikisine de uyuyor: startup için kaos azaltıcı bir fren gibi çalışıyor, enterprise içinse izlenebilirlik sağlayan sağlam bir iskelet oluyor. İlginç değil mi?
Çok konuştum, örnekle göstereyim.
Dokümantasyon Sadece API İçin Değil
Ne yalan söyleyeyim, Dürüst olayım, yıllarca dokümantasyon deyince akla Swagger sayfası ya da README gelirdi. Onlar önemli tabii. Ama yetmiyorlar. Çünkü API dokümanı sana ne yaptığını söyler; neden yaptığını değil (eh, fena değil). Aradaki fark bazen gece ile gündüz kadar büyük oluyor, ciddiye alın bunu.
Kendi deneyimimde en işe yarayan şey şu oldu: Resmî arayüzler için kısa ama net doküman yazıyorum; problemli alanlarda ise karar notu bırakıyorum. Mesela Mart 2024’te Bursa’da incelediğim mesaj tabanlı bir backend’de tek satırlık açıklamanın bile saatler kazandırdığını gördüm — özellikle retry mantığında bu çok netti. Ama gereksiz her metoda yorum koymak? O resmen gürültü üretmek. Dengeyi bulmak lazım.
Spesifikasyonun gücü kodu açıklamasında değil; kararları görünür kılmasında yatıyor.
İşin güzel tarafı şu: Bu yaklaşım teknik borcu tek başına bitirmiyor, hayır. Ama onu görünür yapıyor. Görünür olan şey yönetilebilir olur ya — hani masanın üstündeki kabloyu toparlamak gibi düşünün. Masanın altında kalan düğüm gün gelir ayağa dolanır. Daha fazla bilgi için PDF Dünyasında Bir Nefes: Ücretsiz ve Limitsiz Araçlar yazımıza bakabilirsiniz.
| Aşama | Klasik Akış | Specification-First Akışı |
|---|---|---|
| Başlangıç | Kod yazılır | Sorun ve hedef tanımlanır |
| Ara kontrol | Kod review sırasında yakalanır | Kabul kriterleriyle erken doğrulanır |
| Ajan kullanımı | Sınırsız üretim eğilimi vardır | Sınırlar önceden çizilir |
| Sürdürülebilirlik | Zayıf olabilir | Daha yüksek izlenebilirlik sağlar |
| Ekip hafızası | Kişilere bağlı kalır | Dokümana dayanır |
Ajanlarla Çalışırken Neler Bozuluyor?
Lafı gevelemeden söyleyeyim: AI ajanları bazen fazla hevesli davranıyor. “Bunu yapayım mı?” diye sormadan beş dosya değiştirip geliyorlar ve sen ekran karşısında öylece kalıyorsun. Şunu da ekleyeyim hemen — sorun modelin kötü olması değil. Sorun sınırların belirsiz olması. Butterfly CSS: 2026’da Dikkat Çeken Hafif Bir Seçenek yazımızda bu konuya da değinmiştik.
Evet, doğru duydunuz.
Araya gireyim: Bende bunun canlı örneği Nisan 2025’te oldu, evet baya yakın tarih. Bir yan projede agent’e küçük bir refactor görevi verdim; basit sandığım iş büyüdü çünkü model aynı anda hem naming’i düzeltmeye hem test eklemeye hem de klasör yapısını baştan kurmaya kalktı. Sonuç? Kod satırı arttı, zihinsel yük de arttı. O an anladım ki ajana görev vermek bambaşka şey, onu yönetmek bambaşka şey. Çok farklı beceriler bunlar. Bu konuyla ilgili Apple’ın Akıllı Gözlük Planı: Dört Çerçeve, Tek Hedef yazımıza da göz atmanızı tavsiye ederim.
Neden spec dosyası ajana dizgin oluyor?
Eğer elinde açık kabul kriterleri varsa model daha az sapıtıyor, bunu rahatlıkla söyleyebilirim. Mesela şöyle maddeler: Daha fazla bilgi için LoanLink’i Kurarken Öğrendiğim 7 Kritik Full-Stack Ders yazımıza bakabilirsiniz. Bu konuyla ilgili Oppo Pad 5 Pro Sızdı: Ekran, Güç ve Batarya Netleşiyor yazımıza da göz atmanızı tavsiye ederim.
- Kullanıcı girişi boşsa hata dönecek.
- Sadece X rolündeki kullanıcı bu endpoint’i çağırabilecek.
- Tüm değişiklikler mevcut testleri kırmayacak.
- Migrasyon geri alınabilir olacak.
Böyle maddeler kulağa sıkıcı geliyor, biliyorum. Ama pratikte hayat kurtarıyorlar. Çünkü AI’ya “iyi niyetli tahmin” alanını daraltıyorsun. Dur aslında — burada önemli olan tahmin alanını sıfırlamak değil; yanlış yönde aşırı özgürlüğü kısmak. İnce ama önemli bir ayrım bu.
Küçük Takımda Başka, Büyük Organizasyonda Başka Çalışıyor
Aynı yöntem her yerde aynı etkiyi vermiyor. Maalesef.
Küçük startup’ta spec-first yaklaşımı genelde hafif tutulmalı. Aksi halde takım daha işe başlamadan evrak işi hissine kapılıyor, motivasyon düşüyor, sonra kimse belgeye bakmıyor. Ben olsam iki sayfalık canlı spesifikasyonla başlarım; kabul kriterleri, risk notları ve birkaç örnek yeterli. Fazlası bazen gereksiz ağırlık yapar — arabaya gereksiz bagaj doldurmak gibi, hız keser.
Büyük organizasyonda ise tablo değişiyor. Burada denetim, güvenlik ve uyumluluk devreye giriyor. Kurumsal tarafta çalışan arkadaşlardan duyduğum kadarıyla spec-first modeli özellikle AI destekli geliştirmede audit izi bırakmak için baya işe yarıyor; kim neyi niye değiştirdi sorusu havada kalmıyor. Siz hiç denediniz mi? Hatta bazı ekiplerde ADR ile birleşince güzel bir omurga oluşuyor, sağlam bir şey çıkıyor ortaya.
Evet, doğru duydunuz.
Nerede avantaj sağlıyor?
- Daha az yanlış anlaşılma
- Daha iyi code review
- Daha kolay onboarding
- Daha düşük tekrar işçilik
- Daha net güvenlik kontrolü
Bunun yanında kusursuz falan değil tabii. Bazen spesifikasyon fazlalığı hız kesiyor, bazen de ekip “zaten biliyoruz” diye belgeyi güncellemeyi unutuyor. İşte orası hayal kırıklığı yaratıyor. Kâğıt üstünde disiplin güzel duruyor, ama gerçek hayatta insanlar aceleci. Bu ne anlama geliyor? İnsan faktörü dediğimiz şey tam olarak bu zaten.
Peki Pratikte Nasıl Uygulanır?
Ben olsam süreci üç parçaya bölerdim: Önce problemin kısa özeti, sonra kabul kriterleri, en sonda teknik notlar. Çok uzun roman yazmaya gerek yok (inanın bana). Aşağıdaki basit iskelet çoğu ekip için yeterli olur:
# Feature Spec
## Problem
Kullanıcı kayıt sırasında e-posta doğrulaması bekliyor.
## Acceptance Criteria
- Kullanıcı kayıt sonrası doğrulama linki alacak.
- Link 15 dakika içinde geçersiz olacak.
- Doğrulanmamış hesap giriş yapamayacak.
## Notes
- Retry politikası tanımlanacak.
- Loglarda kişisel veri tutulmayacak.
- Test senaryoları ayrıca listelenecek.
Böyle başladığında modelin işi kolaylaşıyor, insanın işi de. Çünkü artık “bir şeyler yap” demiyorsun; “şu sınırlar içinde bunu hallet” diyorsun. Aradaki fark büyük. Çok büyük hatta.
Nerede Tutar, Nerede Zorlanır?
E tabi her yöntem gibi bunun da zayıf tarafları var. En belirgini şu: başlangıç maliyeti yükseliyor. En çok da tek kişilik projelerde insan bazen “ya ben bunu direkt yazar geçerim” diyor. Haklılık payı var, yok demeyeceğim. Basit script’lerde ekstra süreç gerçekten gereksiz olabiliyor.
Araya gireyim: Ama orta ölçekten itibaren resim değişiyor. Bilhassa ödeme akışı, kimlik doğrulama, veri (söylemesi ayıp) dönüşümü, çoklu servis entegrasyonu gibi alanlarda spec-first yaklaşımı ciddi rahatlatıyor — bunu deneyimle söylüyorum. Geçen yıl Kasım ayında Eskişehir’de gördüğüm bir fintech demosunda bunu net hissettim: Koddan çok karar metni konuşulduğu için tartışmalar daha kısa sürdü, toplantılar daha verimli geçti.
Bence iyi olduğu yerler:
- Ajanların saçmalamasını sınırlamak isteyen ekipler
- Sık değişen ürünlerde ortak hafızayı korumak isteyenler
- Tasarımı testle birlikte yürütmek isteyen takımlar
- Denetim izi isteyen kurumsal yapılar
Bence beklediğim kadar iyi olmadığı yer ise aşırı küçük işler. Tek dosyalık otomasyonlarda büyük çoğunluk bu süreç biraz gösterişli kaçabiliyor. Yani her problemi Ferrari ile çözmeye çalışmak gibi bir şey. Neyse, uzatmayayım.
Sıkça Sorulan Sorular
Specification-first development nedir?
Kısaca,koddan önce niyetin,kuralların ve kabul kriterlerinin yazılmasıdır. Böylece AI ya da insan geliştirici,neyi neden yaptığına dair net bir çerçeve görür.
Bu yöntem küçük ekiplerde işe yarar mı？
Evet,ama hafif tutulursa daha iyi olur. Uzun prosedürlere dönüşürse hız kaybettirir;iki sayfalık canlı spesifikasyon çoğu zaman yeterlidir.
Ajan tabanlı kodlama için neden önemli?
Çünkü ajanlara sınır çizmezseniz onlar geniş alanda dolaşıyor. Spec dosyası görev kapsamını daraltıp sapmaları azaltıyor.
ADR ile birlikte kullanılabilir mi?
Evet,hatta bence çok iyi gider. ADR karar geçmişini,spec ise özellik bazlı niyeti tutar. İkisi birlikte daha güçlüdür.
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.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
