AI Destekli Ürün Geliştirmede Mimari Karar Alma: ADR

AI Destekli Ürün Geliştirmede Mimari Karar Alma: ADR

AI araçlarıyla kod yazıldığında karar verme hızı artıyor. ChatGPT, Claude veya Cursor bir mimari soruya dakikalar içinde üç farklı yaklaşım öneriyor. Her yaklaşımın artısı var, eksisi var. Hızlıca birini seçiyorsunuz ve ilerliyorsunuz.

Bir ay sonra o kararı neden aldığınızı hatırlamıyorsunuz. İki ay sonra yeni bir geliştirici katılıyor ve "neden böyle yapmışız?" diye soruyor. Üç ay sonra aynı soruyu farklı bir bağlamda yeniden tartışıyorsunuz — çünkü ilk tartışma hiçbir yerde kayıt altında değil.

AI hızlandırıyor. Ama hızlandırdığı şey yalnızca kod değil, karar sayısı da. Ve bu kararlar kayıt altına alınmadığında bilgi ekiple birlikte değil, kişiyle birlikte gidiyor.

AI Destekli Geliştirmede Karar Dağılması

Geleneksel geliştirmede mimari kararlar yavaş alınırdı. Araştırma yapılır, ekip tartışırdı, bazen haftalar geçerdi. Bu yavaşlık kararı hafızaya kazıyordu — süreci yaşayan herkes neden o kararın alındığını bilirdi.

AI ile bu süreç hızlandı. Artık şu senaryo çok yaygın:

Sabah 10'da bir mimari sorun çıkıyor. Claude veya ChatGPT'ye soruyorsunuz, beş dakikada üç seçenek geliyor. Değerlendiriyorsunuz, en mantıklısını seçiyorsunuz, uygulamaya geçiyorsunuz. Öğleden önce iş bitiyor.

Bu hız değerli. Ama o beş dakikalık değerlendirme — hangi alternatifleri neden elediğiniz, hangi kısıtların o kararı şekillendirdiği, hangi trade-off'ları kabul ettiğiniz — hiçbir yere yazılmadı. Sadece o an yapılan konuşmada yaşadı.

Sonuç: ekip hızla ilerliyor ama arkasında iz bırakmıyor. Kararlar kişilere bağlı, sistemlere değil. Kişiler değişince bilgi de gidiyor.

ADR Nedir ve Neden Hâlâ Gerekli?

ADR (Architecture Decision Record) her önemli mimari kararı yapılandırılmış bir formatta kayıt altına alma pratiği. 2011'de Michael Nygard tarafından tanımlandı, o günden bu yana yazılım ekiplerinin en değerli ama en az kullanılan pratiklerinden biri oldu.

Temel fikir basit: karar alındığı anda, bağlamıyla birlikte yaz.

AI çağında ADR'nin önemi azalmadı — arttı. Çünkü AI'ın sunduğu seçenek bolluğu, değerlendirme sürecinin daha da önemli hale gelmesini sağlıyor. "Bu seçeneği neden seçtik, diğerlerini neden elediği" sorusu AI önerileri arasından yapılan seçimler için de geçerli.

Klasik ADR formatı beş bölümden oluşuyor: Bağlam, Seçenekler, Karar, Sonuçlar, Durum. Alios'ta bu format node açıklamasına taşınıyor — ayrı bir doküman sistemi gerekmiyor.

Alios'ta ADR Node Formatı

Her mimari karar için ayrı bir node açılıyor. Bu node görev değil, kalıcı kayıt. Sprint'te kapatılmıyor, arşivleniyor.

📌 ADR — [Numara]: [Kararın Başlığı]
Durum: Aktif / Revize Edildi / Geçersiz
Tarih: [Karar tarihi]
Karar Alanlar: [İsimler veya roller]
AI Araçları Kullanıldı: [Claude / ChatGPT / Cursor vb.]

📍 BAĞLAM

[Bu karar neden gerekli oldu?]
[Hangi problem veya gereksinim bu tartışmayı başlattı?]
[Varsa AI'dan gelen önerinin özeti:]
"AI şu üç yaklaşımı önerdi: ..."
[Teknik ve iş kısıtları nelerdi?]

⚖️ DEĞERLENDİRİLEN SEÇENEKLER

Seçenek A: [İsim]
Kaynak: [Kendi araştırma / Claude önerisi / Döküman]
Artıları:
- [Madde]
- [Madde]
Eksileri:
- [Madde]
- [Madde]

Seçenek B: [İsim]
Kaynak: [Kendi araştırma / ChatGPT önerisi / Benchmark]
Artıları:
- [Madde]
Eksileri:
- [Madde]

Seçenek C: [İsim — elenme gerekçesiyle]
Neden elendi: [1-2 cümle]

✅ ALINAN KARAR

[Hangi seçenek seçildi — tek cümle]

Gerekçe:
[Neden bu seçenek? Hangi kısıtlar belirleyici oldu?]
[AI önerisinden ne alındı, ne değiştirildi?]
[Trade-off'lar nelerdi, hangisi kabul edildi?]

⚠️ KABUL EDİLEN SONUÇLAR

Olumlu sonuçlar:
- [Bu kararla birlikte ne kazanıyoruz]

Olumsuz / Trade-off:
- [Ne kaybediyoruz veya hangi riski kabul ediyoruz]

Bilinmeyen:
- [Henüz net olmayan, ilerleyen süreçte netleşecek]

🔗 REFERANSLAR

AI konuşması: [Varsa link veya özet]
İlgili node'lar: [Bağlantılı görev veya epik]
Dökümanlar: [Benchmark, RFC, resmi döküman]
PR / Commit: [Kararın uygulandığı kod]

🔄 REVİZYON KOŞULU

[Bu karar ne zaman gözden geçirilmeli?]
[Hangi koşul bu kararı geçersiz kılar?]
[Örnek: Kullanıcı sayısı 100K'yı geçerse]

📋 KAPANIŞ KRİTERİ

Bu ADR node'u şu koşullar sağlandığında "Aktif" olarak
işaretlenir ve arşive alınır:
- [ ] Karar uygulandı — PR veya commit linki eklendi
- [ ] Ekip bu karardan haberdar edildi
- [ ] Etkilenen diğer node'lara bu ADR referans verildi
- [ ] Revizyon koşulu yazıldı
- [ ] Yeni ekip üyesi bu node'u okuyarak bağlamı
      anlayabilir mi? Evet ise kapatılabilir.

Örnek: Tam Doldurulmuş ADR

AI önerisiyle alınan gerçekçi bir mimari karar üzerinden:

📌 ADR-007: Real-time Özellik için WebSocket vs SSE Seçimi
Durum: Aktif
Tarih: 18 Mart 2025
Karar Alanlar: CTO, Lead Backend Dev
AI Araçları Kullanıldı: Claude Sonnet

📍 BAĞLAM

Dashboard'da real-time veri güncelleme özelliği
ekliyoruz. Kullanıcılar sayfayı yenilemeden anlık
sipariş durumu ve stok değişikliklerini görmeli.

Claude'a mimari seçenekler soruldu. Üç yaklaşım önerdi:
WebSocket, Server-Sent Events (SSE) ve Long Polling.
Her birinin trade-off'larını karşılaştırmalı anlattı.

Teknik kısıtlar:
- Mevcut altyapı: Node.js + Express, AWS EC2
- Ekip: 3 backend geliştirici, WebSocket deneyimi sınırlı
- Kullanıcı sayısı: Şu an 2.000, 6 ayda 15.000 hedef
- Tarayıcı desteği: Tüm modern tarayıcılar

İş kısıtları:
- 2 sprint içinde canlıya alınmalı
- Altyapı kompleksitesini artırmamak öncelik

⚖️ DEĞERLENDİRİLEN SEÇENEKLER

Seçenek A: WebSocket
Kaynak: Claude önerisi + MDN dökümantasyonu
Artıları:
- İki yönlü iletişim — ilerleyen özellikler için esnek
- Düşük latency, gerçek real-time
- Geniş ekosistem desteği
Eksileri:
- HTTP/2 proxy'lerle uyumluluk sorunları olabilir
- Ekip deneyimi sınırlı — öğrenme maliyeti var
- Bağlantı yönetimi karmaşık (reconnect, heartbeat)

Seçenek B: Server-Sent Events (SSE)
Kaynak: Claude önerisi + web.dev makalesi
Artıları:
- Tek yönlü (sunucudan istemciye) — kullanım senaryomuz
  için yeterli
- HTTP üzerinden çalışır — proxy sorunu yok
- Otomatik reconnect yerleşik
- Ekip mevcut HTTP bilgisiyle hızlıca öğrenebilir
- Express ile entegrasyonu basit
Eksileri:
- Sadece sunucudan istemciye — istemciden veri göndermek
  için ayrı HTTP endpoint gerekiyor
- Bazı tarayıcılarda max bağlantı limiti var (HTTP/1.1)

Seçenek C: Long Polling
Neden elendi: SSE ve WebSocket'e göre daha fazla
sunucu yükü yaratıyor. Modern tarayıcı desteği
iyi olduğundan SSE veya WebSocket varken tercih
edilmesi için geçerli sebep yok.

✅ ALINAN KARAR

Server-Sent Events (SSE) seçildi.

Gerekçe:
Kullanım senaryomuz tek yönlü — sunucu istemciye
veri gönderiyor, istemciden real-time veri akışı
gerekmiyor. SSE bu senaryo için WebSocket'ten daha
sade ve öğrenmesi daha kolay.

Claude önerisi WebSocket'i öne çıkardı ama
"iki yönlü iletişim ihtiyacın olmadığı senaryolarda
SSE daha az kompleks ve aynı amacı karşılar" notu
eklemişti. Bu notu belirleyici bulduk.

Ekip HTTP bilgisiyle SSE'yi hızlıca öğrenebilir,
sprint hedefini karşılayabiliriz. WebSocket'in
avantajları mevcut ihtiyaç için fazla.

⚠️ KABUL EDİLEN SONUÇLAR

Olumlu:
- 2 sprint içinde canlıya alınabilir
- Proxy ve altyapı sorunu olmaz
- Ekip öğrenme maliyeti düşük

Olumsuz / Trade-off:
- İlerleyen süreçte istemciden sunucuya real-time
  veri göndermek gerekirse SSE yetmez,
  WebSocket'e geçiş gerekebilir
- HTTP/1.1 ortamında bağlantı limiti izlenmeli

Bilinmeyen:
- 15.000 kullanıcıda SSE performansı — yük testi
  henüz yapılmadı, Q3'te değerlendirilecek

🔗 REFERANSLAR

Claude konuşması: [Konuşma özeti — bağlam kaybolmasın diye
ana noktalar kopyalandı: "SSE vs WebSocket karşılaştırması,
single direction için SSE öneri"]
MDN SSE dökümanı: [Link]
web.dev SSE makalesi: [Link]
İlgili node: "Real-time Dashboard Özelliği" epiği
PR: [Uygulandığında eklenecek]

🔄 REVİZYON KOŞULU

Şu koşullarda bu karar gözden geçirilmeli:
- Kullanıcı sayısı 50.000'i geçerse — SSE ölçek testi
- İstemciden sunucuya real-time veri gönderme ihtiyacı
  doğarsa — WebSocket'e geçiş değerlendirilmeli
- HTTP/1.1 ortamında bağlantı limiti sorunları çıkarsa

📋 KAPANIŞ KRİTERİ

- [x] Karar uygulandı — PR #58 merge edildi
- [x] Ekip Slack'te bilgilendirildi — 20 Mart
- [x] "Real-time Dashboard" epik node'una bu ADR
      referans verildi
- [x] Revizyon koşulu yazıldı
- [x] Yeni geliştirici bu node'u okuyarak neden SSE
      kullandığımızı anlayabilir
→ AKTIF olarak işaretlendi, arşive alındı

AI Konuşmalarını ADR'ye Taşımak

AI önerisini ADR'ye taşırken üç şey kritik.

AI'ın önerisini değil, gerekçeyi kaydet. "Claude WebSocket önerdi" bir ADR değil. "Claude WebSocket önerdi, ancak tek yönlü iletişim senaryomuz için SSE'nin daha uygun olduğunu belirtti — bu gerekçeyi belirleyici bulduk" bir ADR.

Ne aldın, ne değiştirdin, neden? AI önerisi her zaman doğrudan uygulanmıyor. Ekip bağlamını, kısıtlarını ve önceliklerini AI bilmiyor. Bu bağlamla AI önerisinin nasıl şekillendiği ADR'nin en değerli bölümü.

Konuşmanın özünü kopyala. AI konuşmaları kalıcı değil. Link kırılabilir, konuşma silinebilir. Belirleyici olan AI çıktısını — karşılaştırma tablosu, kritik not, uyarı — ADR'nin referans bölümüne kopyalamak veya özetlemek kalıcılığı sağlıyor.

Hangi Kararlar ADR Gerektiriyor?

Her teknik seçim için ADR açmak gerekmiyor. Şu kriterleri karşılayan kararlar kaydedilmeli:

Geri dönmesi maliyetli: Veritabanı seçimi, framework kararı, API mimarisi, kimlik doğrulama yaklaşımı.

AI önerisi belirleyici oldu: AI'ın sunduğu karşılaştırma veya gerekçe kararı şekillendirdiyse bu süreç kayıt altına alınmalı.

Ekipte tartışma yarattı: Görüş ayrılığı olan kararlar — "neden bu değil" sorusu sorulacak kararlar.

Başka kararları kısıtlıyor: Bir seçim sonraki seçimlerin alanını daraltıyorsa bu kısıt görünür olmalı.

Küçük implementasyon detayları, araç konfigürasyonları, geçici çözümler ADR gerektirmiyor.

Son Düşünce

AI araçları karar alma hızını artırıyor. Bu iyi. Ama hız, iz bırakmama anlamına gelmemeli.

Alios'ta ADR node'ları AI destekli geliştirmede karar hafızasını kuruyor. Ekip hızlı ilerliyor ve arkasında iz bırakıyor. Yeni geliştirici "neden böyle yapmışız?" diye soruyor — cevap node'da yazıyor.

AI öneriyor, ekip karar veriyor, Alios kaydediyor.