Altı Ay Sonra “Neden Böyle Yaptık?” Diye Sorulduğunda Ne Cevap Vereceksiniz?

Architecture Decision Recorder: Mimari Kararların Arkasındaki Gerekçeyi Belgeleyen Claude Code Slash Command

Toplantı bitti. Karar verildi. Mimari seçildi. Herkes ayrıldı.

Altı ay sonra sistemin başına geçen implementasyon mühendisi aynı soruyu sorar: “Neden bu konfigürasyonu seçtik? Neden hyperconverged değil de disaggregated? Neden senkron replikasyon bu tier’da, asenkron şu tier’da?”

Cevap çoğunlukla aynı yerde aranır: o toplantıya katılan kişinin aklında. Eğer o kişi hala oradaysa, hatırlıyorsa, ve asıl kısıtları atlayarak yanıtlamıyorsa şanslısınız demektir.

Bu sorunun sistematik çözümü yazılım mühendisliğinde onlarca yıldır kullanılıyor: Architecture Decision Record.

ADR Nedir, Ne Değildir

ADR, bir mimari kararın gerekçesini standart formatta belgeleyen bir dokümandır.

Ne karar verildiğini değil, neden o kararın verildiğini belgeler. Hangi alternatiflerin değerlendirildiğini, hangilerinin neden reddedildiğini, hangi kısıtların kararı şekillendirdiğini ve bu kararın ne getirip ne götüreceğini yazar.

Kod yazan ekipler bunu bilir. GitHub’da “adr” araması yapın, binlerce örnek çıkar. Ama kurumsal IT’de, pre-sales süreçlerinde, altyapı kararlarında ADR hala nadir bir pratik.

Neden? Çünkü yazmak zaman alır. Hangi formatta yazacaksınız? Ne soracaksınız kendinize? Nereden başlayacaksınız?

Bu soruların cevabını otomatikleştirmek için Architecture Decision Recorder’ı yazdım.

Araç Ne Yapıyor

Architecture Decision Recorder, Claude Code için bir slash command.

Claude Code’u açıyorsunuz, /adr yazıyorsunuz, mimari kararınızı birkaç cümleyle açıklıyorsunuz. Araç size bir ADR belgesi üretiyor.

/adr storage platform seçimi, iki kampüslü finansal hizmetler müşterisi,
     RPO=0 gereksinimi, mevcut Oracle RAC, 50km mesafe

Çıktı şunu içeriyor:

• Karar: Ne seçildi, tek cümlede
• Bağlam: Bu kararı gerekli kılan durum, baskı ve kısıtlar
• Değerlendirilen alternatifler: Her seçenek, dürüst artı/eksi analiziyle ve red gerekçesiyle
• Karar gerekçesi: Seçilen seçeneğin neden kazandığı, hangi kısıtların önceliklendirildiği
• Sonuçlar: Ne kolaylaşıyor, ne zorlaşıyor, hangi riskler açık kalıyor
• Kısıtlar tablosu: Bütçe, teknik, operasyonel, compliance faktörleri
• Post-implementation notları: Sistemi devralacak ekibin bilmesi gerekenler

Gerçek Çıktı Nasıl Görünüyor

Araçla üretilen bir örnek:

Senaryo: İki veri merkezi, 50km mesafe, RPO=0 zorunluluğu, Oracle RAC, sub-5ms write latency SLA.

Değerlendirilen alternatifler:

Seçenek A: Hybrid flash/HDD array Daha düşük başlangıç maliyeti. Reddedildi. Neden: Oracle RAC workload’ı için peak yük altında sub-2ms write latency sağlanamıyor. Performans tiering lisansı eklenince maliyet avantajı kayboluyor.

Seçenek B: All-flash NVMe, senkron aktif-pasif replikasyon Primary site’ta güçlü performans. Reddedildi. Neden: 50km üzerinden senkron replikasyon her write’a 2,5ms eklediğinde 5ms SLA’yı peak yük altında tutmak mümkün değil. Bu tam olarak benzer bir deployment’ta gözlemlenen hata modeli.

Seçenek C: All-flash NVMe, tier tabanlı replikasyon (seçilen) Tier-1 workload’lar için aktif-aktif konfigürasyon; kampüs mesafesi senkron replikasyon overhead’i yerine mimari tarafından absorbe ediliyor. Tier-2 ve tier-3 için asenkron replikasyon.

Seçenek D: Hyperconverged Reddedildi. Neden: Compute ve storage birlikte ölçeklenmek zorunda, oysa yalnızca storage yenileniyor. Oracle RAC lisans modeli hyperconverged node-based ölçeklemeyle çakışıyor.

Post-implementation notları: “Latency modellemesi 2,5ms kampüs RTT ve 1,5ms storage controller süresi üzerine kurulu. Go-live öncesi gerçek RTT’yi ölçün; modelden 0,5ms’den fazla sapma varsa tier-1 replikasyon konfigürasyonunu gözden geçirin.”

Bu belgeyi yazılmış olarak karşınıza koysaydım, ne hissederdiniz?

Neden Önemli

Mimari kararlar üç yerde kaybolur.

Toplantıda. Kimse not almamıştır ya da notlar karar değil sonuç odaklıdır.

Kişinin aklında. Karar veren ayrılırsa, gerekçe de gider.

Varsayımlarda. “Herkes biliyordur” diye düşünülen şey hiç söylenmemiştir.

ADR bu üç kaybı önler. Ama el ile yazmak zaman alır ve hangi soruları sormak gerektiğini bilmek gerektirir. Araç bu iki engeli kaldırıyor.

Bunun ötesinde üç pratik katkısı var:

Müşterinin iç onay sürecinde işinize yarar. “Neden hyperconverged değil?” sorusu teknik değerlendirme komitesinden gelecek. ADR belgesi bu soruyu önceden yanıtlıyor.

Implementasyon ekibi sıfırdan başlamıyor. Pre-sales’in öğrendikleri, kararların arkasındaki kısıtlar, değerlendirilen ve reddedilen alternatifler; bunlar devir belgesi olarak implementation’a geçiyor.

Kendi kararlarınızı sorguluyorsunuz. “Neden bu değil de o?” sorusunu müşteriye anlatmadan önce kendinize anlatmak zorundasınız. Araç bu süreci yapılandırıyor.

Kim İçin

Teknik direktörler: Ekibiniz aldığı kararları belgeliyor mu? Altı ay sonra “bu sistemi neden böyle kuruldu?” sorusu geldiğinde cevabı kimde arayacaksınız?

Kıdemli pre-sales mühendisleri: Her teklifte sizing yapıyorsunuz ama mimari kararları belgelemenin standart bir yolu var mı? ADR formatı pre-sales çıktısını “kapasiteden çözüme” taşıyan en pratik araç.

Solution architect’ler: Karar gerekçelerini sunum slaytında değil, ekibin devralabileceği bir belgede tutuyorsanız zaten ADR yazıyorsunuzdur. Araç bunu hızlandırıyor.

Kurulum

İki seçenek var.

User-level skill (tüm projelerde çalışır):

git clone https://github.com/diabolikss-debug/architecture-decision-recorder.git
mkdir -p ~/.claude/skills/adr
cp architecture-decision-recorder/SKILL.md ~/.claude/skills/adr/SKILL.md

Kurulumdan sonra /adr komutu her Claude Code oturumunda kullanılabilir.

Project-level slash command:

mkdir -p .claude/commands
curl -o .claude/commands/adr.md \
  https://raw.githubusercontent.com/diabolikss-debug/architecture-decision-recorder/main/.claude/commands/adr.md

Claude Code gerekiyor. Başka dependency yok.

Nasıl Kullanılıyor

Yeterli bağlam verirseniz araç hemen belge üretiyor. Az bilgi verirseniz en fazla iki, üç hedefli soru soruyor ve devam ediyor.

Bağlam ne kadar spesifik olursa belge o kadar kullanılabilir oluyor:

/adr PostgreSQL seçildi, MongoDB reddedildi, raporlama workload'ı,
     OLTP gecikmesi kritik değil, 5-kişilik ekip

/adr microservices değil monolith, 4-kişilik iç araç ekibi,
     deployment karmaşıklığı öncelikli endişe

/adr on-prem storage yerine cloud-tiered, 3 yıllık veri büyümesi,
     KVKK kısıtı Türkiye'de veri yerleşimi zorunlu

Her karar türü için çalışıyor: platform seçimi, mimari yaklaşım, vendor tercihi, deployment modeli.

Araç Hakkında Dürüst Bir Not

ADR belgesi ancak içine koyduğunuz kadar iyi.

Araç size yapıyı sağlıyor ve doğru soruları soruyor. Ama alternatifleri gerçekten değerlendirip değerlendirmediğinizi, kısıtları doğru tanımlayıp tanımlamadığınızı, reddedilen seçeneklere dürüst davranıp davranmadığınızı araç bilemez.

“Seçmediğimiz seçenek neden iyi değildi?” sorusunu gerçekten cevaplayamazsanız, belge de işe yaramaz.

Araç süreci hızlandırıyor. Düşünme işini yapmanızı sağlamıyor; düşündüklerinizi standart forma döküyor.

GitHub

Repo, README ve örnek ADR çıktısı burada:

**github.com/diabolikss-debug/architecture-decision-recorder**

MIT lisansı. Pull request açıktır.

Bu araç, “İyi Bir Pre-Sales Nasıl Olur?” yazı dizisinin 7. bölümüyle birlikte yayınlandı.

1. bölüm: “Çözüm Tasarımı, Sizing’in Ötesinde” başlığıyla sizing ve mimari tasarım arasındaki farkı, dört boyutlu tasarım çerçevesini, trade-off analizini ve post-sales devir belgesini ele alıyor.

Önceki araç: Pre-Sales Discovery Assistant (Bölüm 4, Discovery Sanatı)

medium.com/@diabolikss | Spotify: İyi Bir Pre-Sales Nasıl Olur?