# Kod Yazmadan Önceki 30 Dakika: Teknik Tasarım Notu Nasıl Yazılır?

Bir sayfalık tasarım notu, haftalarca sürecek yanlış yönü daha başlamadan görünür kılar. İçinde ne olmalı, ne olmamalı?

Bir teknik tasarım notu, kod yazmaya başlamadan önce yazılan, çoğunlukla bir sayfayı geçmeyen kısa bir belgedir. Amacı süreç eklemek değil, tam tersine: haftalar sürecek yanlış bir yönü daha ilk günde görünür kılmaktır. Ekiplerin bu adımı atlama gerekçesi hep aynıdır — "yazacak vaktimiz yok". Oysa asıl pahalı olan, yanlış çözümü üç hafta boyunca doğru sanmaktır.



Not bir sayfayı geçiyorsa, iş muhtemelen ikiye bölünmelidir.

## >Notun çözdüğü asıl problem
Yazılımda maliyetli hatalar genellikle kodun kendisinde değil, problemin yanlış anlaşılmasında olur. Geliştirici bir şeyi çözer, ürün tarafı başka bir şey bekler, ikisi de haklıdır çünkü kimse aynı cümleyi yazılı görmemiştir.


Tasarım notunun ilk faydası burada ortaya çıkar: bir problemi yazıya dökmeye çalışmak, onu gerçekten anlayıp anlamadığınızın en dürüst testidir. Cümleler dağılıyorsa, çözüm de dağılacaktır. İkinci faydası zamansaldır — geri bildirimi kod yazılmadan alırsınız. Bir yaklaşımı üç paragraf yazıp değiştirmek dakikalar sürer; üç hafta kod yazıp değiştirmek sprint yakar. Bu, kod incelemesinde geri bildirimin neden çoğu zaman "geç" kaldığının da açıklamasıdır: mimari itiraz, inceleme aşamasında geldiğinde artık pahalıdır.





## >İçinde ne olmalı?


### >Problem — çözümle karıştırmadan
En sık yapılan hata, problem bölümüne çözümü yazmaktır. "Redis önbelleği eklemeliyiz" bir problem değil, bir karardır. Problem şudur: "Sipariş listesi sayfası yoğun saatlerde 2,8 saniyede açılıyor; kullanıcıların %14'ü sayfayı terk ediyor." Sayı yoksa problem tanımı zayıftır ve sonradan başarıyı ölçemezsiniz.





### >Kapsam — ve özellikle kapsam dışı
Kapsam dışı listesi, notun en çok işe yarayan ama en çok atlanan bölümüdür. "Bu çalışmada raporlama ekranlarına dokunulmayacak" cümlesi, iki hafta sonra çıkacak bir tartışmayı bugünden bitirir. Kapsam yazılı değilse iş sessizce genişler; bu genişleme tahminlerin şaşmasının en yaygın sebeplerinden biridir.





### >Alternatifler ve reddetme gerekçesi
Tek seçenek sunan bir not, karar notu değil duyurudur. En az iki alternatif yazın ve neden elenmediklerini değil, neden elendiklerini açıklayın. Bu bölüm ileride altın değerinde olur: altı ay sonra "neden şunu yapmadık?" sorusu geldiğinde cevap yazılıdır ve aynı tartışma sıfırdan yapılmaz.





### >Başarı ölçütü
"Daha hızlı olacak" bir ölçüt değildir. "P95 yanıt süresi 2,8 saniyeden 800 ms'nin altına inecek" ölçüttür. Ölçüt yazmak aynı zamanda bir dürüstlük filtresidir: ölçülemeyen bir fayda vaat ediyorsanız, muhtemelen faydanın kendisinden de emin değilsinizdir.





### >Risk ve geri alma planı
"Ters giderse ne yaparız?" sorusunun cevabı yazılı değilse, plan tamamlanmamıştır. Veritabanı şeması değişecekse geri dönüş yolu, dağıtım kritikse geri alma adımı burada durmalıdır — geri alma planı olmayan dağıtım yazımızda ele aldığımız gibi, bu adım genellikle en kötü anda hatırlanır.





## >İçinde ne olmamalı?
Sınıf ve fonksiyon isimleri. Not, uygulama ayrıntısını değil yönü tartışır. İsimlendirme kod incelemesinin işidir.


Kesinlik taklidi. Bilmediğiniz şeyi "açık soru" olarak yazmak, uydurulmuş bir kesinlikten çok daha değerlidir. İyi notlarda "Bilmiyoruz" başlığı vardır.


On sayfalık ayrıntı. Uzun not okunmaz; okunmayan not geri bildirim üretmez ve tek faydası olan şeyi kaybeder.





## >Süreç: kim okur, ne zaman biter?
Notun bir sahibi, bir okuyucu listesi ve bir son tarihi olmalıdır. Pratikte işleyen kural şudur: iki iş günü içinde itiraz gelmezse karar geçerlidir. Onay beklemek yerine itiraz penceresi açmak, süreci kilitlenmeden ilerletir.


Kabul edildikten sonra not silinmez, depoda kodun yanında saklanır. Zamanla oluşan bu arşiv, yeni katılan geliştirici için en değerli okuma listesidir — ilk 30 gün planında anlattığımız işe alıştırma sürecini belirgin biçimde hızlandırır. Karar kayıtlarının nasıl yapılandırılacağına dair yaygın pratikler için Martin Fowler'ın mimari yazıları iyi bir başlangıçtır.





## >Ne zaman gerekmez?
Her iş için not yazmak, süreci bürokrasiye çevirir. Pratik eşik şudur: iş bir günden kısaysa, geri alınması kolaysa ve tek bir modülü ilgilendiriyorsa not gerekmez. Buna karşılık şema değişikliği, dış bağımlılık eklenmesi, birden çok ekibi etkileyen değişiklik veya geri alınması zor kararlar için not yazmamak lükstür.





## >Sonuç
Teknik tasarım notu, dokümantasyon üretmek için değil, karar kalitesini artırmak için yazılır. Problemi ölçülebilir biçimde tanımlamak, en az iki alternatifi ve reddetme gerekçesini yazmak, kapsam dışını açıkça söylemek ve geri alma planını belirlemek — bu dördü bir sayfaya sığar ve haftalarca sürecek yanlış yönü ilk günde görünür kılar. Bir sonraki büyük işinize başlamadan önce yarım saatinizi ayırın: bir sayfa yazın, ekibe gönderin ve iki gün itiraz bekleyin. Gelen ilk itiraz bile, o yarım saati fazlasıyla geri ödeyecektir.