AI Serisi Mülakat 16: İyi bir spec kodlama nasıl olmalıdır?

Bir iyi Spec Coding (Spesifikasyon Odaklı Programlama), temel olarak "belirsiz fikirleri" "kesin, doğrulanabilir, çalıştırılabilir sözleşmelere" dönüştürmektir. Bu sadece bir belge yazmak değil, insanlar ve AI (veya insanlar arasında) arasında belirsiz olmayan bir iletişim dili oluşturmaktır. Aşağıda, iyi bir spec'in neye benzediğini spec içerik yapısı, yazma ilkeleri, AI ile işbirliği süreci ve kalite doğrulama olmak üzere dört boyuttan anlatacağım.

1. Spesifikasyon Belgesinin Standart Yapısı (İşlev Modülü Örneği ile)

Bölüm	Zorunlu İçerik	Örnek
1. Amaç ve Kapsam	Bir cümlede ne yapıldığını açıklayın, ne yapılmadığını belirtin	"Kullanıcı kaydı API'sini uygulayın, e-posta doğrulamasını içermez"
2. Girdi/Çıktı Sözleşmesi	Veri yapısı, türü, zorunlu/isteğe bağlı alanlar, örnek değerler	`POST /register` istek gövdesi `{email: string, password: string}`, yanıt `201` veya `400` hata kodu ile
3. Davranış ve Mantık	İş kuralları, sınır koşulları, durum geçişleri	"Şifre uzunluğu 8-20 karakter, en az bir rakam içermeli; e-posta zaten varsa `409` döndür"
4. Hata Yönetimi	Tüm olası istisna senaryoları ve karşılık gelen hata kodları/mesajları	"Veritabanı bağlantı hatası → `503` döndür, yığını açıklama"
5. İşlevsel Olmayan Gereksinimler	Performans (yanıt süresi < 200ms), güvenlik (parametreli sorgular), günlük, gözlemlenebilirlik	"Tüm SQL'ler önceden derlenmeli; `email` kaydedilmeli, `password` kaydedilmemeli"
6. Test Durumları (Kritik)	En az 3 tipik girdi + 2 sınır/istisna girdi, beklenen çıktıyı verin	Aşağıdaki tabloya bakın
7. Bağımlılıklar ve Kısıtlamalar	Hangi kütüphane, sürüm, ortam değişkenleri kullanılıyor	"Python 3.10+, FastAPI, ortam değişkeni `DB_URL`"

Test Durumları Örneği (spec içinde gömülü)

Senaryo	Girdi	Beklenen Çıktı
Normal kayıt	email: `a@b.com`, pwd: `Pass1234`	`201`, `user_id` döndür
Şifre çok kısa	pwd: `Ab1`	`400`, hata kodu `WEAK_PASSWORD`
E-posta zaten var	Aynı email	`409`, hata kodu `EMAIL_EXISTS`

İyi bir Spec önce test durumlarını yazmalıdır, çünkü AI bunlara dayanarak doğrudan birim testleri oluşturabilir ve tamamlandıktan sonra otomatik olarak doğrulayabilir.

2. Spec Yazmanın Temel İlkeleri (SMART Varyantı)

İlke	Açıklama	Ters Örnek
Kesin (Precise)	Kesin sayılar, türler, boolean koşullar kullanın; 'mümkün olduğunca', 'genellikle' gibi ifadelerden kaçının	❌ "Şifre yeterince güvenli olmalı" → ✅ "Şifre en az 8 karakter, büyük harf, küçük harf ve rakam içermeli"
Doğrulanabilir (Verifiable)	Her gereksinim otomatik test veya manuel kontrol ile geçti/kaldı olarak belirlenebilmeli	❌ "Kod zarif olmalı" → ✅ "Fonksiyon döngüsel karmaşıklığı ≤ 10, tekrarlanan kod bloğu yok"
Belirsiz Olmayan (Unambiguous)	Aynı terim tüm belge boyunca aynı anlamda kullanılmalı, gerekirse sözlük verilmeli	❌ "Kullanıcı yoksa hata döndür" → ✅ "Kullanıcı yok → `404` ve `{code: 'USER_NOT_FOUND'}` döndür"
Tam (Complete)	Mutlu yol, tüm istisna yolları ve işlevsel olmayan gereksinimleri kapsamalı	❌ Sadece başarı senaryosu yazmak → ✅ Veritabanı zaman aşımı, yetki eksikliği vb. içermeli
Atomik (Atomic)	Bir spec sadece bağımsız olarak teslim edilebilir bir işlevi tanımlamalı (AI'nın tek seferde tamamlaması için)	❌ Bir spec ile "tüm ödeme sistemi"ni yazmak → ✅ "Ödeme fişi oluşturma", "geri arama imza doğrulama", "para iadesi" olarak bölmek

3. AI ile İşbirliği Sırasında Spec Kodlama Süreci

İnsan spec'i yazar (yukarıdaki yapı, özellikle test durumları ve fonksiyon imzaları yazılır).
Spec'i tek seferde AI'ya besleyin (diyalog şeklinde ek talepler eklemeyin, vibe kirliliğinden kaçının).
AI kod + birim testleri çıktısı verir (AI, spec'teki test durumlarına göre çalıştırılabilir testler oluşturmalıdır).
Testleri çalıştırın: Eğer hepsi geçerse sonraki adıma geçin; geçmezse spec'i düzeltin veya kodu doğrudan düzeltin (küçük döngüye girilebilir ancak değişiklikler kaydedilmelidir).
İnsan incelemesi: spec dışındaki işlevlerin dahil edilip edilmediğini (scope creep), güvenlik/performansı kontrol edin.
Sabitleme: spec belgesini ve nihai kodu birlikte depoya gönderin, kalıcı belge olarak.

Anahtar Uygulama: Spec'i kodlaştırma - spec.md + test_spec.py kullanın, test dosyası doğrudan spec'teki örneklerden gelir; böylece daha sonra kod değiştirildiğinde sadece testleri çalıştırarak spec'in bozulup bozulmadığı doğrulanabilir.

4. İyi Bir Spec'in Sağladığı Faydalar (Kabul Kriteri Olarak Kullanılabilir)

Belirlilik: Aynı spec farklı AI'lara (veya farklı kişilere) verildiğinde benzer uygulamalar üretilir.
Test Edilebilirlik: Kod yazıldıktan hemen sonra %90 doğruluk otomatik olarak doğrulanabilir.
Bakım Kolaylığı: Altı ay sonra herhangi biri spec'i okuduğunda ilk tasarım niyetini anlayabilir.
Düşük İletişim Maliyeti: Ekip tartışmalarında sadece spec konuşulur, kod satırları konuşulmaz.
Güvenlik/Kalite Dahili: Güvenlik gereksinimleri (parametreli sorgular gibi) ve sınır koşulları spec'te belirtilir, AI uymak zorundadır.

5. İyi Bir Spec Örneği (Çok Basitleştirilmiş)

# Spec: Kullanıcı Kaydı API

## Kapsam
- email, password al
- Doğrulama e-postası gönderme, e-posta gerçekliğini kontrol etme

## Sözleşme
POST /register
Content-Type: application/json
Request: { "email": string, "password": string }
Response 201: { "user_id": string }
Response 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Response 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Davranış
- email RFC 5322 temel formatına (a@b.c) uygun olmalı
- password: uzunluk 8-20, en az bir rakam ve bir büyük harf içermeli
- bcrypt ile şifrelenerek saklanır, tuz maliyeti 10
- Veritabanına kaydetmeden önce email zaten varsa → 409

## Test Durumları (Girdi -> Beklenen Durum Kodu+Yanıt Alanı)
| Girdi email | password | Beklenen |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id var |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (var olan email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## İşlevsel Olmayan
- SQL parametreli sorgular kullanılmalı (enjeksiyon önleme)
- Kayıt kaynağı IP'si günlüğe kaydedilir, şifre kaydedilmez
- Yanıt süresi %95 istek < 100ms (bcrypt hariç)

## Bağımlılıklar
- Python 3.10+, FastAPI, bcrypt, asyncpg

İyi Spec Kodlama = İnsanın "tasarım kararlarını" makinenin "test durumları + tür imzaları + davranış kısıtlamaları" şeklinde yazmaktır, böylece AI sadece uygulamayı doldururken, insan her zaman kaliteyi ve yönü kontrol eder.