ADR Yazmayı Erteleyince Kaybolan Kararlar

Kararı hatırlıyoruz. Postgres'te kaldık, event store'a geçmedik, billing'i ayırmadık. Gerekçeyi hatırlayan kişi izinli. Yeni gelen 'neden hâlâ tek veritabanı' diye soruyor, tahta yine doluyor, aynı üç seçenek, aynı yarım cümleler. Toplantı bitince yine kod duruyor, gerekçe yine havada.

ADR'ı o gün yazmamışız. Yazmamak bir tembellik gibi duruyor; asıl maliyeti tembellik değil, yokluk. Yokluk, kararı yeniden tartışılabilir kılıyor. Yeniden tartışılabilir karar, her sprint bir kez daha zaman yiyor. Zaman yiyen şey, 'belge kültürü' diye alay edilen o bir sayfa.

Bu yazı bir şablon tapınması değil. Uzun wiki, kimse okumaz. Okunmayan belge, yazılmamış belgeden daha ağır: yanılsama verir. İstediğim şey kısa, tarihli, durumu olan bir not. Not olmayınca ekip, kendi geçmişini sözlü kültürle taşıyor. Sözlü kültür, işe alımda kopar.

Karar nereye gidiyor

Kod, ne yaptığını söyler. Neden yapmadığını söylemez. {if (module == Billing)} durur; 'neden ayrı host değil' durmaz. PR açıklaması o haftayı anlatır, altı ayı anlatmaz. Slack ipliği aranmaz. Toplantı kaydı varsa bile kimse 40 dakikayı baştan izlemez.

Gerekçe üç yerde ölür. Biri, 'geçici' denilen seçim. Geçici altı ay kalır, gerekçesi bir günde unutulur. İkincisi, vazgeçilen seçenek. Neden event store durmadı? Durmama nedeni, yeni gelen için boşluk. Boşluk, aynı teklifi tekrar doğurur. Üçüncüsü, kısıt. Lisans, ekip sayısı, yasal log. Kısıt değişince karar değişebilir; kısıt yazılmazsa değişim de rastgele durur.

ADR, bu üçünü bir arada tutar. Seçilen, seçilmeyen, hangi varsayımda. Varsayım çürüyünce belge supersede edilir. Çürüme görünmezse, 'hep böyleydi' dini başlar. Din, mimari değil.

Kısa tuttuğum şekil

İki sayfa yazmıyorum. Beş başlık: bağlam, karar, sonuçlar, reddedilenler, durum. Bağlam bir paragraf. Karar bir cümle. Sonuçlar maddeler. Reddedilenler, 'neden o değil'. Durum: proposed, accepted, deprecated, superseded. Durum yoksa belge ölü veya ölümsüz; ikisi de zararlı.

# ADR 0014 — Billing ayrı process değil, modulith

Tarih: 2026-08-29
Durum: accepted

Bağlam
Tek ekip, ortak release treni. Fatura yazması siparişle aynı işlem
ister. Ayrı host, outbox + telafi ister; telafi cümlesi yok.

Karar
Billing bir modül olarak aynı process'te kalır. Kendi şeması vardır.
Dışarıya IBillingModule verir.

Sonuçlar
+ Tek transaction, tek deploy.
+ Yarın extract için yüzey küçük.
- Billing değişince sipariş testi de koşar.
- Ölçek sınıfı ayrılamaz.

Reddedilen
Ayrı billing servisi: ekip ve telafi hazır değil.
Paylaşılan orders.invoice_status kolonu: yazma sahibi bulanık.

Bunu markdown diye bir framework'e bağlamıyorum. Repo'da {docs/adr/0014-billing-modulith.md} yeter. Wiki'ye yapıştırıp unutmak, aramanın öldüğü yere gömmek. Kodun yanında durunca PR'da linklenir. Link, tartışmayı 'yeniden keşif'ten 'belgeyi güncelleyeceğiz'e çeker.

Ne zaman yazıyorum

Her PR'a ADR yok. İsimlendirme, bir indeks, bir buton rengi. Yazdığım yer: geri dönüşü pahalı seçimler. Veri deposu, süreç sınırı, kimlik modeli, 'bu event'in anlamı', tutarlılık sınıfı. Bunlar altı ay sonra pahalı. Pahalı olanı toplantıda bırakmak, faturayı sonraya imzalamak.

İkinci eşik, anlaşmazlık. Odada iki ciddi seçenek varsa, kazananı yazmak yetmez; kaybedeni de. Kaybeden yazılmazsa, kaybeden her yeni kişide yeniden aday olur. Aday olmak kötü değil; aynı gerekçeyle üç kez aday olmak israf.

Üçüncü eşik, dış kısıt. 'Şu bölgede veri durur', 'şu log 8 yıl kalır', 'şu sağlayıcıya bağlıyız'. Kısıt kodda bir config satırı olur, gerekçe olmaz. Satır silinince kısıt da silinmiş sanılır. Sanı, denetimde ortaya çıkar.

Ertelemenin tipik hali

'Sprint bitince yazarız.' Sprint biter, sonraki iş başlar. Belge, yapılacaklar listesinin en kibar yalanı olur. İkinci hali: 'kod kendini anlatıyor.' Kod, Postgres seçimini anlatır; 'neden Cockroach değil'i anlatmaz. Üçüncü hali: 'zaten hepimiz biliyoruz.' Hepimiz, bu çeyrek. Gelecek çeyrek başka hepimiz.

Dördüncü hali daha sinsi. Karar büyük, belge korkutucu sanılır. Büyük karar, aslında kısa belge ister. Büyük belge, kararsızlığın işaretidir: henüz karar yoktur, deneme vardır. Denemeyi ADR diye yazmayın; proposed yazın, tarih koyun, ne öğreneceğimizi yazın. Öğrenince accepted veya superseded.

Ertelediğim bir karar, shared {users} tablosu oldu. 'Geçici, sonra ayırırız.' Sonra gelmedi. Yeni ekranlar tabloya yaslandı. Ayırmak artık bir göç. Göçün gerekçesi de yoktu; çünkü ilk kararın gerekçesi yoktu. Yokluk, göçü de tartışmalı yaptı. Tartışmalı göç, yapılmaz. Yapılmayan göç, anti-pattern olarak kalır.

Durum makinesi

Accepted, sonsuz değildir. Varsayım çürüyünce belgeyi silmem. Deprecated veya superseded. Silmek, izi yok eder. Yok iz, aynı hatayı 'ilk kez' gibi tekrar ettirir. Superseded belge, yeni belgenin 'neden eski öldü' cümlesidir.

{
  "id": "0014",
  "title": "Billing stays a modulith module",
  "status": "accepted",
  "date": "2026-08-29",
  "supersedes": null,
  "assumptions": [
    "one team",
    "shared release train",
    "no compensation story for split invoice"
  ],
  "revisitWhen": [
    "billing team exists",
    "invoice failure may trail order acceptance"
  ]
}

{revisitWhen} en işe yarayan satır. Kararı kilitlemez, uyanma koşulu koyar. Koşul gelince belgeyi açarız, tartışma sıfırdan başlamaz. Koşul gelmeden 'bir daha konuşalım' demek, ADR'ın işini iptal etmektir.

Yazım, gurur değil

İyi ADR edebi değildir. Sıfat az, isim net. 'Daha ölçeklenebilir' yazmam. 'Şu yükte şu kilit, şu ekip sayısında şu kuyruk' yazarım. Ölçmediğim şeyi gelecek zamanla vaat etmem. Vaat, altı ay sonra yalan diye okunur; yalan diye okunan belge bir daha yazılmaz.

İsimlendirme de yazının parçası. {ADR-14} yetmez. Başlık, kararı söylemeli. 'Billing ayrı process değil'. Arayan, dosya listesinde görür. 'Mimari not 14' gören, açmaz. Açılmayan belge, yazılmamış belgedir.

İngilizce-Türkçe karışmasını dert etmiyorum. Terim zaten İngilizce duruyorsa zorla çevirmiyorum. Cümle Türkçe, kelime {outbox}. Okuyan ekip bu karışımı zaten konuşuyor. Belge, konuşmanın durmuş hali olsun; başka bir dilin gösterisi değil.

Toplantıyı belgenin önüne koymamak

Karar toplantıda alınabilir. Kalıcı olan, toplantı değil. Toplantıdan çıkan üç madde, o gün bir dosyaya iner. İinmediği toplantıyı, karar saymıyorum. Saymadığım şey, kodda bir {TODO} olarak kalır. {TODO}, sahiplik değildir.

Bazen toplantı, belgeyi yazmamak için yapılır. 'Bir daha konuşalım' ucuzdur, yazmak netleştirir. Netleşmek, itirazı görünür kılar. Görünür itiraz sağlıklıdır. Sağlıksız olan, herkesin farklı gerekçeyle aynı koda evet demesi. Altı ay sonra gerekçeler çarpışır, kod suçlanır.

Deniz'in like'ladığı şey biraz bu: kaybolan gerekçe. Like, belgeyi yazmaz. Yazmazsam, like da bir toplantı alkışıdır. Alkış, {revisitWhen} değildir.

Küçük karar, büyük boşluk

Büyük kararları yazıp küçükleri atlamak da bir erteleme. 'Idempotency key header'da' küçük durur. Yazılmazsa bir client yeni anahtar üretir, diğeri üretmez, destek çift siparişi 'arada bir' diye kapatır. Küçük karar, kullanıcıya büyük gelir. Büyük gelen şeyi toplantı notuna gömmeyin.

Öteki uç: her şeyi yazmak. O zaman kimse okumaz. Filtre, geri dönüş maliyeti. Maliyet düşükse PR yeter. Maliyet yüksekse ADR. İkisinin arasında 'neden bu değil' cümlesi PR'da durabilir; durmuyorsa yine dosya.

Okunurluk için indeks tutuyorum. Tek {README} , durum ve başlık. 40 belge olunca arama da yetmez, indeks şart. İndeks yoksa belge var sanılır, yoktur: kayıptır.

Erteleyince kaybolan şey karar değil

Karar kodda durur. Kaybolan, seçilmeyendir. Seçilmeyen yoksa, her yeni kişi aynı seçilmeyeni tekrar önerir. Öneri kötü olmayabilir; bağlam değişmiş olabilir. Bağlam yazılmamışsa, değişip değişmediğini bilemeyiz. Bilmeyince tartışma 2026 Mart'ına döner. Mart'taki tahta silinmiştir.

İkinci kayıp, cesaret. Yazılmamış gerekçe, kararı savunulamaz kılar. Savunulamayan karar, ilk itirazda devrilir. Devrilmesi doğru olabilir. Doğru devrilme, belgeyle olur: varsayım çürüdü, yeni ADR. Belgesiz devrilme, zevk değişimidir. Zevk, üretimde pahalıdır.

Üçüncü kayıp, onboarding. Yeni biri, 'neden böyle' diye sorar. Cevap 'Emre biliyordu' ise Emre tatile çıkınca mimari de tatile çıkar. Belge, kişiyi tek kaynak olmaktan çıkarır. Kişi hâlâ anlatır; anlatısı belgeye dayanır, efsaneye değil.

Geri gelen bir karar

2026 Mart'ında billing'i ayırmadık. Gerekçe toplantıdaydı, dosya yoktu. Ağustos'ta yeni biri aynı teklifi getirdi. Teklif kötü değildi; ekip hâlâ tekti, telafi hâlâ yoktu. Bunu söylemek 20 dakika sürdü, çünkü Mart'taki varsayımları yeniden kurduk. 20 dakika ucuz, üç kişinin takvimi değil. Asıl maliyet, 'belki bu sefer' duygusu. Duygu, belgesiz kararın yemi.

Ağustos sonunda 0014'ü yazdım. Yazınca tartışma bitti değil; tartışma dosyaya taşındı. 'Telafi cümlesi gelince revisit' satırı duruyor. Gelirse yeni belge. Gelmeden 'bir daha konuşalım' artık bir gündem maddesi değil, bir koşul bekleyişi. Bekleyiş, toplantıdan ucuz.

Geri gelen kararın bir başka hali, vazgeçilen araç. Event store'u 2025'te eledik, gerekçe 'ekip iki kişi, operasyon yok'. 2026'da ekip altı kişi olunca teklif döndü. Dönerse bakacağım şey, o günkü 'operasyon yok' hâlâ doğru mu. Doğruysa hayır. Değilse yeni ADR. Eski hayır, kutsal değil; yazılı olduğu için sınanabilir.

Review'da link

Sınır değişiren PR'da ADR linki istiyorum. Link yoksa soru tek: bu yeni bir karar mı, eski bir kararın uygulanması mı? Uygulama ise link. Yeni ise taslak. Taslak PR ile aynı dalda durabilir. Merge, {accepted} olmak zorunda değil; {proposed} da merge olur, iş bitmemiş görünür. Görünür bitmemişlik, gizli karardan iyi.

Link, okuyanı cesaretlendirir. Cesaret, 'bu neden böyle'yi yazara özel mesajda sormamak. Mesaj, kişiye bağlı hafıza. Hafıza izne çıkınca kopar. Dosya kopmaz.

Bazı PR'lar küçük durur, kararı taşır: {readPreference} değiştirmek, PACELC yazısındaki Else kolunu sessizce L yapmak. Küçük diff, büyük varsayım. Varsayım ADR'da yoksa, review'da büyür. Büyümesi doğru. Büyümeden geçmesi, altı ay sonra 'neden replica'dan okuyoruz' toplantısıdır.

ADR'a girmeyenler

Girmeyen: kütüphane yaması, bir indeks, bir log satırı, bir buton metni. Girmeyen ama PR'da duran: 'neden bu indeks'. Girmesi gereken: indeks bir okuma modelini, bir tutarlılık sınıfını, bir yasal kısıtı değiştiriyorsa. Filtre yine geri dönüş maliyeti. Maliyet düşükse gürültü yapmayın. Yüksekse sessiz kalmayın.

Girmeyen bir başka şey, slayt. Slayt karar değildir. Slayt, kararın reklamı olabilir. Reklamı repo'ya koymuyorum; gerekçeyi koyuyorum. Gerekçe sıkıcıdır. Sıkıcı metin, altı ay sonra okunur. Parlak slayt, altı ay sonra 404.

Kişi adı da dikkat. 'Bunu Selin istedi' bir gerekçe değil, bir otorite. Otorite gidince karar boşalır. İsim, tarih satırında durabilir. Cümlede durmamalı. Cümle, kısıt ve sonuç konuşur.

Yazmaya başladığım kural

Toplantıda 'karar' dendiği gün, aynı gün taslak. Taslak çirkin olabilir. Çirkin taslak, mükemmel niyetten iyidir. Ertesi gün durum {accepted} olur veya {proposed} kalır. Kalırsa, iş bitmemiştir. Bitmemiş işi kodda 'bitti' diye görmeyiz; belgede de görmeyelim.

İkinci kural: PR, ilgili ADR'ı linkler. Link yoksa ve sınır değişiyorsa, review'da sorarım. Soru geciktirir. Gecikme, altı ay sonraki ikinci toplantıdan ucuz.

Üçüncü kural: silmem, durum değiştiririm. Yanlış karar da izdir. İz, aynı yanlışı 'yeni fikir' diye satmayı zorlaştırır. Zorlaştırmak, cezalandırmak değil; hafızadır.

Bir sayfanın tutmadığı tek şey, o gün odada olmayan kişidir. Sayfa, onu odaya çağırmaz; odaya gelince tahtayı baştan kurdurmaz. Bu yeter. Kahramanlık beklemiyorum. Hafıza istiyorum.

ADR yazmayı erteleyince kaybolan şey kahramanlık değil. Kaybolan, neden'dir. Neden gidince karar bir alışkanlık olur. Alışkanlık tartışılınca herkes haklıdır, çünkü kimse o günkü kısıtı taşımaz. Kısıtı bir sayfada bırakın. Sayfa kısa olsun. Yokluğu uzun sürer.