AI ajanları için etkili SPEC yazma yöntemi - Addy Osmani

• AI ajanı üretkenliğinde en büyük farkı yaratan şey → açık ve yapılandırılmış bir SPEC
• Kötü SPEC = belirsizlik → AI drift, tekrarlayan başarısızlık, bağlam sınırının aşılması
• İyi SPEC = yaşayan belge (SPEC.md) + sürekli güncelleme

İyi bir SPEC'in temel bileşenleri

• Hedef / vizyon (neden yapıldığı, kimin için olduğu)
• Özellik listesi + önceliklendirme
• Teknoloji yığını (React 18 + TS, Node 20 gibi somut şekilde)
• Çalıştırma komutları (npm test, lint, build vb.)
• Test kriterleri (hangi testlerin çalıştırılması gerektiği ve neyin başarı sayılacağı)
• Kod yapısı / stil rehberi
• Git iş akışı (branch kuralları, commit mesajı)
• Sınırların tanımlanması (✅ her zaman / ⚠️ sor / 🚫 asla yapma)

Etkili başlangıç prompt kalıpları

• “Draft a detailed specification for … covering objectives, features, constraints, step-by-step plan”
• Önce Plan Mode → AI'nın SPEC taslağını hazırlamasını sağlamak
• Sonrasında işi küçük görevlere bölerek talimat vermek

Pratik ipuçları (yalnızca özeti)

• Ayrı bir SPEC.md dosyası tutun → her işte yalnızca ilgili bölümleri ekleyin
• Modüler yapı + alt görevlerin ayrılması
• Her görevden sonra otomatik test + SPEC'e uyumun kontrolü
• Sınır kurallarının 3 seviyesini netleştirin (Always / Ask / Never)