Spec-driven geliştirme

Ajana "sepete kupon kodu ekle" deyip beklemek hızlı başlar ama çoğu zaman yanlış yerde biter. Model söylemediğiniz her kararı kendi tahminiyle verir. GitHub ekibi sorunu şöyle özetliyor: ajanlara arama motoru gibi davranıyoruz, oysa onlar her şeyi harfi harfine alan bir eş programcı gibidir.¹

Spec-driven geliştirme, kodu yazdırmadan önce ne yapılacağını bir dosyaya yazmak ve ajanı o dosyaya göre çalıştırmaktır.¹² Spec hem sizin hem ajanın başvurduğu ortak kaynak olur.

Plan ile spec'in farkı

Agentic kodlama dersindeki plan modu da kodlamadan önce düşündürür. Fark, planın konuşmanın içinde kalmasıdır. Spec ise repoda duran bir dosyadır: commit edilir, incelenir ve yeni bir oturumda tekrar okunur.

Spec'in ne kadar yaşayacağı da bir tercihtir. Yalnızca o iş için yazılıp unutulan spec'e spec-first, özellikle birlikte güncellenen spec'e spec-anchored denir. Bugünkü araçların çoğu ilkini destekliyor.²

Akış: spec, plan, görevler, uygulama

Araçlar farklı isimler kullansa da akış aynıdır:¹²

1. Spec: Ne yapılacak ve neden. Kullanıcı ne görür, ne zaman "bitti" deriz. Teknoloji yok.

2. Plan: Nasıl yapılacak. Hangi dosyalar, hangi bileşenler, hangi kısıtlar.

3. Görevler: Planı tek tek test edilebilen küçük parçalara bölmek.

4. Uygulama: Ajan görevleri sırayla yapar, siz her adımda küçük bir diff incelersiniz.

Her adımın sonunda durup dosyayı okursunuz. Yanlışı spec'te düzeltmek, koddan düzeltmekten ucuzdur.

Spec'i boş sayfadan yazmanıza gerek yok. Prompt ve context engineering dersindeki gibi ajandan size soru sormasını isteyin, cevaplardan spec'i o yazsın.³ Addy Osmani da kısa bir hedefle başlayıp ayrıntıyı ajana genişletmeyi, kod yazılmadan önce taslağı okumayı öneriyor.⁴

İyi bir spec'te ne olur

Claude Code dokümanına göre en işe yarayan spec kendi başına yeterlidir: ilgili dosyaları ve arayüzleri adıyla yazar, kapsam dışını açıkça söyler ve özelliğin çalıştığını kanıtlayan uçtan uca bir kontrolle biter.³ Kupon özelliği için kısa bir örnek:

# Cart coupon

## Goal
Kullanıcı sepette kupon kodu girip indirim alabilsin.

## Acceptance criteria
- `SALE10` girildiğinde ara toplamdan %10 düşülür.
- Geçersiz kodda input altında "Kupon geçersiz" yazar, toplam değişmez.
- Aynı anda tek kupon uygulanır; yenisi eskisinin yerine geçer.

## Files
- `src/features/cart/components/CouponForm.tsx` (new)
- `src/features/cart/lib/applyCoupon.ts` (new)
- `src/features/cart/components/CartSummary.tsx`

## Out of scope
- Kupon yönetim paneli, kullanıcı başına kupon limiti.

## Boundaries
- Always: mevcut `Button` ve `Input` bileşenlerini kullan.
- Ask first: yeni paket eklemeden önce sor.
- Never: `CartSummary` dışındaki fiyat hesaplarına dokunma.

## Verification
`pnpm test applyCoupon` geçer. Playwright: `SALE10` ile toplam 1.000 TL'den 900 TL'ye düşer.

Son iki bölüm Addy Osmani'nin önerisinden geliyor: ajanın sınırlarını her zaman, önce sor ve asla diye üç katmanda yazmak.⁴ Komutlar, klasör yapısı ve kod stili gibi her özellikte aynı kalan bilgiler ise spec'e değil AGENTS.md'ye gider.

Görevlere bölmek ve uygulamak

Spec onaylanınca ajandan bir görev listesi isteyin. Her görev tek başına test edilebilmeli:¹

- [ ] 1. `applyCoupon` fonksiyonu ve birim testleri
- [ ] 2. `CouponForm` bileşeni, hata mesajı dahil
- [ ] 3. `CartSummary`'ye indirim satırı
- [ ] 4. Playwright ile uçtan uca senaryo

Uygulamayı yeni bir oturumda başlatın. Temiz bağlam yalnızca spec'e ve göreve odaklanır.³ Uzun bir talimat listesinde model her maddeye daha az uyar. Bu yüzden her göreve spec'in yalnızca ilgili bölümünü verin.⁴

Görev bitince ajandan çıktıyı spec'le karşılaştırmasını ve karşılanmayan kriterleri listelemesini isteyin.⁴ Testler geçiyor ve liste boşsa görevi işaretleyip commit edin.

Spec'i güncel tutmak

İş sırasında bir karar değişirse (örneğin kupon artık kargo ücretine de uygulanıyorsa) önce spec'i güncelleyin, sonra kodu. Spec'i kodla birlikte versiyon kontrolünde tutun.⁴ Böylece altı ay sonra bu özelliğe dokunan biri (ya da bir ajan) neden böyle çalıştığını dosyadan okur.

Ne zaman gerekmez?

Spec bir araçtır, tören değil. martinfowler.com'daki bir incelemede yazar, küçük bir hata düzeltmesi için aracın 4 kullanıcı hikâyesi ve 16 kabul kriteri ürettiğini anlatıyor. Ayrıca ajanın spec'teki notları yer yer görmezden geldiğini ve tekrarlı Markdown dosyalarını incelemenin koddan daha yorucu olduğunu yazıyor.²

Araç şart değil. Bir SPEC.md, bir görev listesi ve plan modu aynı akışı kurar.

Kendin dene

• Sepete kupon özelliği için ajandan sizi sorgulamasını isteyin ve cevaplardan SPEC.md yazdırın. Kapsam dışı bölümü var mı?

• Spec'teki bir kabul kriterini belirsiz yazın ("kupon düzgün çalışsın"). Ajanın yazdığı testler neyi kontrol ediyor?

• Görev listesini çıkarıp yalnızca ilk görevi yeni bir oturumda uygulatın. Diff kaç dosyaya dokunuyor?

• Görev bitince ajandan "spec'te karşılanmayan kriterleri listele" isteyin. Liste boş mu?

Detaylı öğrenmek için

• Yazı: Addy Osmani, "How to write a good spec for AI agents"; spec'in altı bölümü, modüler prompt'lar ve kendi kendini doğrulama.⁴

• Yazı: martinfowler.com, "Understanding Spec-Driven-Development"; Kiro, Spec Kit ve Tessl'in eleştirel karşılaştırması.²

• Resmi doküman: Claude Code "Best practices"; ajanın sizi sorgulaması ve spec'i yeni oturumda uygulatmak.³