Ekibin kararlarını nereye yazdığı

Bir kod incelemesinde biri soruyor: retry neden üç denemede duruyor. Odadaki kimse bilmiyor. Karar bir buçuk yıl önce alınmış, o zamanlar bir sohbet kanalında on dakika tartışılmış, kanal arşivlenmiş ve kararı veren kişi artık şirkette değil. Ekip de ekiplerin yaptığını yapıyor: sayının rastgele konduğunu varsayıp onu on yapıyor ve gerekçeyi ay sonunda fatura gelince yeniden keşfediyor.

Kararlar gerçekte nerede duruyor

Bir ekibe kararlarının nerede yazılı olduğunu sorun, dürüst cevaplar şunlar olur: bir sohbet başlığı, bir pull request yorumu, tutanağı tutulmamış bir toplantı, ve bir kişi. Dördünün de son kullanma tarihi var. Sohbet araması işe yaramaz, çünkü o gün hangi kelimelerin kullanıldığını hatırlamıyorsunuz. Pull request yorumları durur ama kimse gerekçe aramak için eski yorumları gezmez. Toplantı gitmiştir. Kişi ya ayrılır ya kalır ve unutur; on sekiz ay sonra ikisi aynı şeydir.

Geriye kod kalır ve kod hikâyenin yarısıdır. Retry limitinin değerini gösterir. Bu limitin denemelerin ücretlendirilmesi yüzünden var olduğunu, bir arızadan sonra seçildiğini, ya da bir alternatifin denenip bırakıldığını gösteremez. Hayatta kalmayan kısım tam olarak gerekçedir ve bir şeyi güvenle değiştirmek için ihtiyacınız olan kısım da odur.

Kodun yanında tek paragraf

Benim oturttuğum çözüm, gerçekten yapılacak kadar küçük. Repoda bir klasör, her karar için numaralı bir dosya, her dosya bir paragraf:

# 0007: Üç denemeden sonra mesajı beklet

Tarih:   2026-03-11
Durum:   kabul edildi
Karar:   üç başarısız gönderim denemesinden sonra retry'ı kesiyoruz ve mesajı
         bir kişinin baktığı bekleyen kuyruğuna alıyoruz.
Neden:   üst taraf her denemeyi ayrı ücretlendiriyor ve son iki çeyrekte üç
         denemeyi aşan bir hata neredeyse hiç sonradan düzelmedi.
Elenen:  sınırsız retry ve backoff, çünkü maliyetin tavanı yok. Mesajı
         düşürmek, çünkü kayıt kayboluyor ve müşteri bir hafta sonra soruyor.
Yeniden: denemeler tek tek ücretlendirilmeyi bırakırsa, ya da bekleyen
         kuyruğu günde elli civarını geçerse.
Sahip:   kuyruğu işleten ekip.

Altı kısa alan. Yazması dört dakika sürdü ve bu yazıyı başlatan soruyu on saniyede cevaplıyor.

Klasörün yeri de bir karar. Tek bir servis varsa docs/kararlar/ yeterli; monorepo'da her paketin kendi klasörü olur, çünkü kaydı bulmasını istediğiniz kişi o klasörde çalışan kişidir. Dosya adı numara artı üç dört kelime olsun: numara sırayı ve atıf yapmayı kolaylaştırır, kelimeler ise ls çıktısını okunur bir içindekiler listesine çevirir. Klasöre tek başlıklı bir README koyup şablonu oraya yazın, böylece ikinci kaydı yazan kişi biçimi düşünmek zorunda kalmaz.

Asıl önemli satır Yeniden. Yeniden açılma koşulu olmayan bir karar zamanla kurala dönüşür ve kurallar gerekçelerinden uzun yaşar. Koşulu yazmak, sonraki kişiye koşul gerçekleştiğinde değeri değiştirme izni verir; gerçekleşmediğinde de dokunmamak için sağlam bir zemin. Retry politikası, rastgele görünen ama olmayan kararların iyi bir örneği; tıpkı hız sınırını kalıcı hata saymanın bedelini bir kere ödeyene kadar aşırı temkinli görünmesi gibi.

Gerekçe seçimden önemli

Tek bir alana enerjiniz varsa gerekçeyi yazın. Ne seçildiği zaten kodda duruyor, durmuyorsa düzeltilecek şey koddur.

İşe yarayan gerekçe tercihi değil kısıtı söyler. "Bunu seçtik çünkü daha temiz" cümlesi bir yıl içinde hiçbir şeye dönüşür. "Bunu seçtik çünkü üst taraf deneme başına ücret alıyor" cümlesi ise işe yarar kalır, çünkü iki yıl sonra biri gidip üst tarafın hâlâ öyle yapıp yapmadığına bakabilir. Kısıtın süresi dolmuş mu diye test edilebilir. Tercih edilemez; o yüzden önce folklora, sonra kimsenin dokunmaya cesaret edemediği bir kurala dönüşür.

Bazen dürüst gerekçe hiç de gurur duyulacak bir şey olmaz: karar sürüm gecesinde, yarım bilgiyle, iki saat içinde verilmiştir. Bunu olduğu gibi yazın. "Sürüm baskısıyla seçildi, ölçüm yapılmadı" cümlesi, sonradan uydurulmuş temiz bir gerekçeden çok daha faydalıdır, çünkü sonraki kişiye o kararın ne kadar sağlam olduğunu söyler. Sahte kesinlik, yanlış karardan daha pahalıya patlar.

İnsanların atladığı diğer alan Elenen ve en çok zaman kazandıran alan o. Olmadığında, sezgisi iyi olan her yeni geliştirici aynı bariz alternatifi önerir ve ekip bir öğleden sonrayı bunun neden olmadığını yeniden keşfederek geçirir. Tek satırlık elenen seçenek listesi, o öğleden sonrayı bir cümleye indirir.

Yazılacak kadar kısa tutmak

Tanıdığım her ekibin ölmüş bir dokümantasyon sistemi var. Hepsi ağırlıktan öldü. Bende işe yarayan savunmalar:

• Sınır bir paragraf. Karar üç sayfa istiyorsa o üç sayfa bir tasarım dokümanıdır, kayıt ona link verir.
• Kayıt, değişikliği yapan pull request'in içinde yazılır, sonradan değil. Sonradan hiç gelmiyor.
• İnceleme kuralı bunu otomatikleştirir: değişiklik bir limite, timeout'a, varsayılana, şemaya veya üçüncü taraf sınırına dokunuyorsa inceleyen kişi kaydı ister. Kapı olarak değil, soru olarak.
• Kayıtlar yeni bir görüşe göre düzenlenmez. Değişen karar yeni bir dosya alır, eskisine Durum: 0019 ile değiştirildi yazılır. Değer tarihin kendisinde.
• Kaydı kimse onaylamaz. Bu bir not, sözleşme değil. Onay gerektiği an yazma durur.

En zoru ilk kayıttır, çünkü klasör boştur ve format tören gibi hissettirir. Ben genelde ilk müşteri toplantısının çıktısıyla başlatıyorum, çünkü başlangıçta sorduğum beş soru tam olarak bu şekilli bilgiyi üretiyor: ne konuşuldu, ne elendi, kim karar veriyor.

Karşılığını nerede alırsınız

Bütün alışkanlığı değerli kılan iki an var.

Birincisi, olmayacak bir saatte gelen arıza. Bir şey limitte patlıyor ve en hızlı çıkış yolu limiti yükseltmek gibi görünüyor. Tek arama o sayının tahmin mi yoksa koruma mı olduğunu söyler:

grep -ril "bekleyen\|retry" docs/kararlar/
# docs/kararlar/0007-uc-denemeden-sonra-beklet.md

On saniye sonra değerin bilerek konduğunu ve neyi koruduğunu biliyorsunuz. Bu da arızadaki en pahalı hamleyi engeller: anlamadığınız bir korumayı, tam işini yaptığı anda kapatmak. Karar kayıtları burada iyi log'ların yanında durur; gecenin üçünde merak ettiğiniz şeylerin çoğunu ikisi birlikte cevaplar, bu yüzden doğru seçilmiş üç log alanı ile kararlar klasörü genelde aynı kod tabanlarında bulunur.

İkincisi yeni gelen kişi. Yirmi kısa kaydı bir saatte okuyup iki yıllık bağlamla çıkabilir; ekibin daha önce çarptığı problemlerin şeklini de öğrenir. Bunu bir anlatım turu vermez, çünkü turu veren kişi hangi kısımların şaşırtıcı olduğunu artık hatırlamıyordur.

Yeni gelenin ilk işini de buradan çıkarıyorum: ilk haftada anlamadığı ilk üç şeyi not etsin, sonra birine sorup cevabı kayıt olarak yazsın. İki faydası var. Kişi repoya ilk katkısını ikinci günde yapmış olur ve ekibin körleştiği yerleri kaydeden tek kişi odur, çünkü o körlük bir hafta sonra ona da bulaşacaktır.

Nelere dikkat etmeli

• Her şeyi kaydetmek. Dört yüz dosyalık klasör kimsenin okumadığı klasördür. Geri alması pahalı olanı, dışarıdan yanlış görüneni ve görünmeyen bir kısıta dayananı yazın.
• Kaydın koddan ayrışması. Davranış değişip kayıt değişmediğinde kendinden emin bir yanlış bilgi üretmiş olursunuz. Onları koda bağlı tutan şey inceleme kuralıdır.
• Kaydı savunma metni gibi yazmak. Sadece seçimi savunan kayıt bir reklamdır. Dürüst kılan şey elenen seçenekler ve yeniden bakma koşuludur.
• Login isteyen ve araması çalışmayan bir yere koymak. Repoda değilse işin yanında değildir ve bir kere okunur.

Bir ekibin gerçek hafızası, orada bulunan insanlardan geriye ne kalıyorsa odur. Sohbet kalmaz, toplantı kalmaz, kod ise gerekçesi olmadan kalır. Kararın alındığı anda yazılan ve açıkladığı kodun yanında duran bir paragraf, gerekçeyi açıkladığı şeye bağlı tutmanın bildiğim en ucuz yolu. Testi bu hafta kendi projenizde yapabilirsiniz: konfigürasyonunuzdaki en tuhaf sayıyı seçin ve o değerin neden öyle olduğunu birinin söyleyip söyleyemediğine bakın.