Ana sayfa → Teknik
Mimari Karar Kaydı: Toplantı Değil, Tek Sayfa
“Bu kuyruğu neden böyle kurmuşuz?” Odadaki üç kişi üç farklı cevap verdi. Kararı veren kişi sekiz ay önce ayrılmıştı. İki saat tartıştık ve sonunda aynı kararı yeniden verdik — ama bu sefer gerekçesi farklıydı.
- Karar kaydı geçmiş için değil, gelecekteki tartışma için yazılır. Amaç arşiv değil, aynı tartışmayı üçüncü kez yapmamak.
- En değerli bölüm “reddedilen seçenekler”. Bir yıl sonra gelen soru “bunu neden yaptık” değil, “neden şunu yapmadık” oluyor.
- Her karar yazılmaz. Sadece geri alması pahalı olanlar. Her şeyi yazmaya çalışan ekip üçüncü ayda hiçbir şey yazmıyor.
- Kayıt değiştirilmez. Karar değişirse eskisi silinmez, yerine yenisi geçer. Değiştirilen kayıt, hafızayı tahrif eder.
- Repo’da durur, wiki’de değil. Kodla birlikte değişmeyen doküman, altı ay içinde yanlış bilgi kaynağına dönüşüyor.
- Maliyeti 20 dakika. Yazmamanın maliyeti, aynı toplantının ikinci turu.
Sahadan: aynı kararı ikinci kez vermek
O iki saatlik toplantıdan çıkan sonuç “mevcut yapı kalsın” oldu; yani hiçbir şey değişmedi. Dışarıdan bakan biri toplantının boşa geçtiğini söylerdi. Bence daha kötüsü oldu: aynı kararı farklı bir gerekçeyle verdik.
Sekiz ay önceki gerekçe — sonradan eski bir mesaj kaydında buldum — işletme maliyeti ve ekibin o teknolojiyi zaten biliyor olmasıydı. Bizim ürettiğimiz gerekçe ise sıralama garantisiydi. İkisi de makul, ama farklı. Bu şu demek: gelecekte koşullar değişip “sıralama artık önemli değil” olduğunda, kararı değiştirmeyi düşüneceğiz — oysa asıl dayanak hiç o değildi.
Kendi payıma düşen hata şu: o toplantıdan çıkarken de bir şey yazmadım. “Zaten değişiklik yok” dedim. Üç ay sonra aynı soru yeniden soruldu.
Tek sayfa, altı başlık
ADR’yi karmaşıklaştıran ekiplerde yazılmıyor. Bizimki bu kadar:
# ADR-0023: Kuyruk altyapisi secimi
DURUM : Kabul edildi (2026-04-18)
[Onerildi | Kabul edildi | Yerine gecti: ADR-00xx]
KARAR : Siparis olaylari icin X kuyrugunu kullaniyoruz.
YAZAN : tek isim
KATILAN : toplantidaki kisiler (karar tek kisinin degilse)
## Baglam
O anki durum, kisitlar ve karari tetikleyen sey.
Gunde 400 bin olay; siralama siparis bazinda onemli;
ekipte 2 kisi bu teknolojiyi biliyor; butce X.
(Gelecekteki okuyucu bugunu bilmiyor. Burasi onun icin.)
## Karar
Ne yapiyoruz, tek paragraf. Emir kipi degil, gecmis zaman:
"Sectik", "Kullanacagiz".
## Sonuclar
Bu karar neyi kolaylastiriyor, neyi zorlastiriyor.
Zorlastirdigi seyi yazmak zorunlu; yoksa kayit reklam olur.
## Reddedilen secenekler
- Y : neden elendi (tek cumle)
- Z : neden elendi
- Hicbir sey yapmamak : neden yeterli degildiDört başlık zorunlu: bağlam, karar, sonuçlar, reddedilen seçenekler. Geri kalanı isteğe bağlı. Yazması 20 dakika sürüyor ve bu süre, kararı veren toplantının hemen ardından harcanmalı — ertesi gün gerekçelerin yarısı buharlaşıyor.
Neden “reddedilen seçenekler” en değerli bölüm
Bir yıl sonra kimse gelip “bunu neden yaptık” diye sormuyor. Çünkü yapılan şey ortada, kod duruyor. Soru her zaman şu: “Neden şunu yapmadık?”
O bölüm olmadan bu sorunun tek cevabı yeniden araştırma yapmak oluyor. Bölüm varsa cevap otuz saniye sürüyor — ve daha önemlisi, cevap “denedik, eledik” değil de “o zaman şu sebeple elemiştik, o sebep hâlâ geçerli mi?” oluyor. Kararı yeniden açmayı engellemiyor; doğru yerden açmayı sağlıyor.
Bir de “hiçbir şey yapmamak” seçeneğini listeye koymayı alışkanlık hâline getirdik. Çoğu mimari kararın en ciddi rakibi budur ve genelde hiç konuşulmaz.
Hangi kararlar yazılır?
- Veri modeli ve sahiplik sınırları
- Servis sınırları, neyin ayrı servis olduğu
- Mesajlaşma / kuyruk altyapısı
- Kimlik doğrulama ve yetkilendirme yaklaşımı
- Dış bağımlılık seçimi (sağlayıcı, ödeme, arama)
- Tutarlılık modeli: nerede anlık, nerede nihai
- Yardımcı kütüphane seçimi
- Klasör düzeni, isimlendirme
- Bir fonksiyonun nasıl yazıldığı
- Test kütüphanesi
- Tek bir servisin iç tasarımı
Bunlar kod incelemesinin konusu, kayıt konusu değil.
Ayrım net olmazsa iki uçtan birine düşülüyor: ya hiçbir şey yazılmıyor, ya da her PR için ADR isteniyor ve üçüncü ayda kimse yazmıyor. Bizim kullandığımız test tek cümle: bu kararı altı ay sonra geri almak bir sprint’ten uzun sürer mi? Sürerse yazılır.
Durum alanı: kayıt silinmez
En sık yapılan hata, karar değişince eski kaydı güncellemek. Böylece geçmiş kayboluyor ve dosya “bugünkü durum”u anlatan sıradan bir dokümana dönüşüyor — ki onun için zaten kod var.
ADR-0023 DURUM: Yerine gecti -> ADR-0031 (2027-02-10)
(icerigi AYNEN kalir, tek satir eklenir)
ADR-0031 DURUM: Kabul edildi (2027-02-10)
## Baglam
ADR-0023'te X secmistik. O zamanki gerekce gunde
400 bin olaydi. Bugun 3 milyon ve siralama artik
bolum bazinda yetiyor. Kosul degisti, karar degisti.Bu zincir bir yan fayda daha veriyor: yeni katılan biri kararların sırasını okuyabiliyor. “Neden böyle”nin cevabı çoğu zaman tek bir kararda değil, üç kararın üst üste binmesinde.
Nerede durur, kim yazar
Kayıtlar repo’da, docs/adr/ altında, kodla aynı PR’da. Bunun
sebebi runbook’ları wiki’den çıkardığımız
sebeple aynı: kodla birlikte değişmeyen doküman güncellenmiyor ve altı ay içinde
aktif olarak yanlış bilgi vermeye başlıyor.
Yazan kişi de belli: kararı veren toplantıdan çıkan kişi. Bir başkasına devredilen ADR yazılmıyor. Kayıt, o PR’ın parçası olarak inceleniyor — ve incelemede en çok itiraz gelen bölüm genelde “sonuçlar” oluyor, çünkü insanlar kararın zorlaştırdığı şeyi yazmayı atlıyor.
Ne izlemeli?
| Ne | Neden |
|---|---|
| Son altı ayda yazılan kayıt sayısı | Sıfırsa ya karar verilmiyor ya kaydedilmiyor; ikisi de kötü |
| “Reddedilen seçenekler” bölümü dolu olan kayıt oranı | Boşsa kayıt yarım; en sık atlanan bölüm bu |
| Yerine geçilen kayıt sayısı | Hiç yoksa kayıtlar yaşamıyor, arşiv olmuş demektir |
| Aynı konunun ikinci kez tartışılması | Sayılmaz ama fark edilir. Olduğunda “kaydı var mı” diye sor |
Bende işe yaramayanlar
- Geçmişe dönük ADR yazmak. “Son iki yılın kararlarını belgeleyelim” dedik. Altı kayıt yazıldı, hepsi genel geçer cümlelerle doluydu, çünkü kimse o günün kısıtlarını hatırlamıyordu. Kayıt ancak karar anında değerli; sonradan yazılan, tahminden ibaret.
- Şablona bölüm eklemek. “Riskler”, “maliyet analizi”, “alternatif mimari şeması” ekledik. Yazma süresi 20 dakikadan iki saate çıktı ve kayıt sayısı sıfıra indi. Geri aldık.
- Onay süreci koymak. ADR’yi “mimari kurul onaylar” yapınca kayıt yazmak, karar almanın önüne geçen bir bürokrasiye döndü. Şimdi kayıt kararın kendisi değil, kararın yazısı; onay gerekiyorsa o zaten toplantıda verilmiş oluyor.
Kontrol listesi
- Bu kararı altı ay sonra geri almak bir sprint’ten uzun sürer mi?
- Bağlam bölümü, bugünü bilmeyen birine yetecek kadar somut mu?
- Sonuçlar bölümünde kararın zorlaştırdığı şey yazıyor mu?
- Reddedilen seçenekler dolu mu — ve “hiçbir şey yapmamak” listede mi?
- Kaydı, kararı veren toplantıdan çıkan kişi mi yazdı?
- Kayıt repo’da mı, kodla aynı PR’da mı?
- Eski bir kararı değiştiriyorsa, eskisini silmek yerine “yerine geçti” yaptım mı?
Sonuç
O iki saatlik toplantının maliyeti dört kişinin yarım günü oldu ve hiçbir şey değişmedi. Sekiz ay önce birinin 20 dakika ayırmış olması, o toplantıyı tamamen gereksiz kılardı — ya da daha iyisi: toplantıyı yine yapardık ama bu sefer “koşullar değişti mi” sorusundan başlardık, sıfırdan değil.
Karar kaydı bir belgeleme alışkanlığı değil, bir tartışma kısaltma aracı. Değerini kaydı yazarken değil, bir yıl sonra birisi onu açtığında veriyor.
Test basit: ekipteki en yeni kişi, en tartışmalı mimari kararın gerekçesini tek başına bulabilir mi? Bulamıyorsa o gerekçe bir kişinin kafasında duruyordur, ve o kişi bir gün gider.