Teknik RFC Nasıl Yazılır: Bölüm Bölüm Rehber

Kritik bir sistem için yazılan bir RFC iki nedenden takılır: değerlendiriciler hangi problemi çözdüğünü anlayamaz ya da kendilerini ilgilendiren bölümü bulamaz. İkisi de yapısal sorundur ve ikisi de ilk inceleme yorumu gelmeden çözülebilir.

RFC’yi bir satış dokümanı gibi ele alın. Tek bir çözümü, öncelikleri çatışan dört kitleye satar: işi finanse eden yöneticiler, tasarımı denetleyen mimarlar, onu inşa eden uygulayıcılar ve sonrasında nöbeti tutan operasyon ekibi. Her kitle kendi cevabını dokümanın tamamını okumadan bulabilsin; cevapları da kitlelerin sorduğu sıraya koyun.

Sırayı Kitle Belirler#

Kısa ve sade yazılmış bir bildirim sistemi RFC’si, daha kıdemli bir yazarın teknik olarak daha derin önerisinden çoğu zaman daha hızlı onaylanır. Sebep genellikle teknik üstünlük değildir. Kısa doküman, paydaşların sorduğu soruları sordukları sırayla cevaplar.

Bölüm bölüm ilerleyelim: bir bildirim sistemi RFC’sinin her parçası neyi ortaya koymalı ve değerlendiriciler dokümanı hızlıca tararken neye bakar. Uygulama serisi böyle bir RFC’nin tarif ettiği sistemi anlatıyor.

Yönetici Özeti#

Yönetici özeti asansör konuşmanız. Meşgul bir VP’yi veya kıdemli mühendisi bu dokümanın zamanlarına değer olduğuna ikna etmek için yaklaşık 30 saniyeniz var. İşte işe yarayan:

Platform genelinde gerçek zamanlı güncellemeler, push bildirimleri, e-posta 
bildirimleri ve uygulama içi bildirimleri işleyebilen sağlam, ölçeklenebilir 
bir kullanıcı bildirim sistemi uygulamamız gerekiyor. Bu sistem kullanıcı 
etkileşimi, kritik uyarılar ve özellik duyuruları için omurga görevi görecek.

Ne olduğunu açıkça belirtiyor (bildirim sistemi), spesifik yetenekleri listeliyor (gerçek zamanlı, push, e-posta, uygulama içi), iş değerine bağlanıyor (kullanıcı etkileşimi, kritik uyarılar) ve teknik jargondan kaçınıyor.

Zayıf versiyon:

Bu RFC, birden fazla kanal üzerinde yapılandırılabilir yeniden deneme 
mekanizmalarıyla asenkron mesaj teslimatını kolaylaştırmak için Kafka, 
PostgreSQL ve WebSocket'ler kullanan mikroservis tabanlı olay güdümlü 
bir mimari uygulamayı öneriyor.

Zayıf versiyon yöneticileri “mikroservis tabanlı” kısmında kaybediyor ve kimsenin neden umursaması gerektiğini hiç açıklamıyor. Bir sistem bir ürün yöneticisine tek paragrafta anlatılamıyorsa, tasarımın netleşmeye ihtiyacı var demektir.

Değerlendiricilerin gerçekte aradığı:

• Kapsam netliği: Bu komple bir yeniden yazım mı yoksa geliştirme mi?
• İş uyumu: Gerçek bir problemi mi çözüyor yoksa CV güdümlü geliştirme mi?
• Risk değerlendirmesi: Karmaşıklık konusunda dürüst müsünüz?

Problem Tanımı#

Burada sayılar önemli: belirsiz problemler belirsiz zaman çizelgeleri alır.

Bildirim RFC’si her sorunu, paydaşların zaten takip ettiği bir etkiye bağladı:

### Mevcut Sorunlar
- Kullanıcılar projeleriyle ilgili önemli güncellemeleri kaçırıyor
- Bildirim tercihlerini yönetmek için merkezi bir yol yok
- Manuel bildirim gönderimi hata eğilimli ve ölçeklenebilir değil

### İş Etkisi
- Azalan kullanıcı etkileşimi ve tutma
- Kaçırılan iletişimler nedeniyle artan destek biletleri
- Churn'e yol açan kötü kullanıcı deneyimi

Her sorunun, birilerinin zaten izlediği bir iş etkisiyle nasıl eşleştiğine dikkat edin. Bu şekilde yazılan sorunlar, lansman sonrası raporlayacağınız metriklere dönüşür; fazladan bir paragrafa değmesinin sebebi bu.

İşe yaramayan:

Mevcut sistem eskimiş ve bakımı zor. Mühendisler kod tabanından şikayet 
ediyor ve yeni özellikler eklemek zorlu.

Bu bana aksiyona geçirilebilir hiçbir şey söylemiyor. Ne kadar eski? Hangi spesifik bakım sorunları? Hangi özellikler engelleniyor? Spesifikler olmadan, bu her eski sistem gibi okunuyor.

Güçlü RFC’ler şunları içerir:

• Mevcut metrikler: “Geçen ay kaçırılan bildirimlerle ilgili 847 destek bileti”
• Maliyet etkileri: “Mühendisler sprint zamanının %15’ini manuel bildirim görevlerine harcıyor”
• Fırsat maliyeti: “Bildirim sınırlamaları nedeniyle üç özellik lansmanı ertelendi”

Önerilen Çözüm: Vizyon ve Spesifiklik Dengesi#

Çoğu RFC’nin raydan çıktığı yer burası. Mühendisler ya uygulama detaylarında kayboluyorlar ya da o kadar üst düzeyde kalıyorlar ki kimse neyin inşa edildiğini bilmiyor.

Bildirim RFC’si mükemmel dengeyi buldu:

### Sistem Mimarisi

┌─────────────────┐  ┌──────────────────┐  ┌─────────────────┐
│  Bildirim  │  │  Bildirim  │  │  Bildirim  │
│  Kaynakları  │───▶│  Motoru  │───▶│  Kanalları  │
└─────────────────┘  └──────────────────┘  └─────────────────┘

### Temel Bileşenler
- Olay İşleyici: Gelen bildirim olaylarını işler
- Şablon Motoru: Bildirim şablonlarını ve kişiselleştirmeyi yönetir
- Hız Sınırlama: Bildirim spam'ini önler

Büyük resmi görsel olarak gösteriyor, anlaşılabilir bileşenlere ayrılıyor ve her bileşenin ne yaptığını açıklıyor.

Dikkat edilmesi gerekenler:

• Problem arayan çözümler (“GraphQL subscription’ları kullanacağız çünkü modern”)
• Teknoloji bingosu (“Kubernetes, Istio, Envoy, Linkerd…”)
• Erken optimizasyon (“İlk günden veritabanını shard’layacağız”)

Pratikte uygulamalar çoğu zaman RFC’nin önerdiğinden daha basit başlar. Modüler tasarım karmaşıklığı kademeli eklemenize izin verir; hız sınırlama üçüncü ayda eklenir.

Teknik Uygulama#

İyi teknik özellikler tahmin edilebilecek kadar somut ama uyarlanabilecek kadar esnektir.

RFC şemayı somut olarak verdi ve bunu operasyonu düşünerek yazdı:

CREATE TABLE notification_events (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    notification_type VARCHAR(100) NOT NULL,
    template_id UUID REFERENCES notification_templates(id),
    data JSONB DEFAULT '{}',
    status VARCHAR(20) DEFAULT 'pending',
    sent_at TIMESTAMP,
    delivered_at TIMESTAMP,
    read_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

Denetim izi sent_at, delivered_at ve read_at zaman damgalarıyla baştan yerleşiktir, JSONB veri alanı RFC’nin öngörmediği gereksinimleri soğurur ve durum sütunu production sorunlarını debug etmek için gereklidir.

Production gerçekliği sıklıkla gözden kaçan index gereksinimlerini (user_id, status ve created_at üzerinde bileşik index), zaman serisi verileri için bölümleme stratejisini (aylık bölümler) ve eski bildirimleri soğuk depolamaya taşıyan arşiv stratejisini ekler.

Bu gereksinimlerin pratikte nasıl ortaya çıktığı production debugging yazısında detaylandırılıyor.

API tasarımı da aynı somutluğu hak eder. Temsili bir endpoint seti şöyle görünür:

POST  /api/notifications/send
GET  /api/notifications/user/:userId
PUT  /api/notifications/:id/read

Ama harika RFC’ler şunları da düşünür:

• Liste endpoint’leri için sayfalama stratejileri
• Verimlilik için toplu işlemler
• Gelecekteki değişiklikler için versiyonlama stratejisi
• API seviyesinde hız sınırlama

Offset sayfalama ölçekte performans sorunları yarattığında cursor tabanlı sayfalamaya geçilir; RFC’nin öngörebileceği bir nokta.

Uygulama Aşamaları#

### Aşama 1: Temel Altyapı (Hafta 1-4)
- Veritabanı şeması uygulaması
- Temel bildirim motoru
- Uygulama içi bildirim sistemi

### Aşama 2: Gelişmiş Özellikler (Hafta 5-8)
- Push bildirimleri
- Şablon yönetim sistemi
- Zamanlama ve hız sınırlama

Bu aşamalandırma ayakta duruyor çünkü aşama 1’de değer teslim ediyor (kullanıcılar bildirimleri ilk aşamanın sonunda görür), zor problemi öne alıyor (gerçek zamanlı teslimat önce gelir) ve aşama 2’yi, aşama 1’in öğrettiklerini soğuracak kadar gevşek bırakıyor.

Aşamalar tahmin edilebilir yerlerde sarkar:

• Kimlik doğrulama veya faturalama entegrasyonu tahmini aşar, çünkü başka bir takımın takvimi sizin planınızda yoktur
• Hız sınırlama ve yeniden deneme mantığındaki edge case’ler yalnızca yük altında görünür
• Son aşama, gerçek kullanım kalıpları geldiğinde kısmen kapsam dışı kalır

RFC tahminin bir tahmin olduğunu söylediyse bunların hiçbiri planlama hatası değildir. Uygulama serisi paydaş güvenini korurken zaman çizelgesinin nasıl uyarlanacağını belgeliyor.

Sık görülen boşluklar arasında keşifler için tampon bırakılmaması (“Hafta 1: Her şeyi uygula”), ayrılan test zamanının olmaması, diğer takımlara bağımlılığın hesaba katılmaması ve harici servislerle “basit entegrasyon” varsayımı sayılabilir; hiçbiri gerçekte basit değildir.

Teknik Değerlendirmeler#

RFC ölçek hakkında spesifik oldu:

### Performans Hedefleri
- Bildirim teslimi: Uygulama içi için < 100ms, e-posta için < 5s
- Sistem verimi: Saniyede 10.000+ bildirim
- Veritabanı sorgu performansı: Tercih aramaları için < 50ms

Bunlar keyfi sayılar değil. Şunlardan türetilmiş:

• Mevcut kullanıcı tabanı (10.000 bildirim/saniye = peak yük × 3)
• Kullanıcı deneyimi araştırması (100ms anlık hissettiriyor)
• Altyapı kısıtlamaları (veritabanı bağlantı limitleri)

Hedefleri sonradan biri kontrol edebilsin diye yazın ve en az birinin yanlış çıkacağını varsayın:

• Teslimat gecikmesi genelde hedefe yakın çıkar, çünkü tasarımın optimize ettiği sayı odur
• Peak verim genelde tahminin altında kalır, çünkü tahmin peak yükün güvenlik katsayısıyla çarpımıydı
• Sorgu gecikmesi en sık ıskalanan kalemdir; tercih aramaları RFC’nin belirtmediği bir index ister

Her sayıyı okunacağı yerle eşleştirin: bir dashboard paneli, bir log alanı, bir yük testi. Bu hedeflerin nasıl ölçüme bağlandığı analitik ve optimizasyon yazısında detaylandırılıyor.

Güvenlik de aynı somutluğu gerektirir:

• Kimlik doğrulama: “15 dakikalık süreli JWT token’ları”
• Yetkilendirme: “Granüler izinlerle rol tabanlı erişim”
• Hız sınırlama: “Üstel geri çekilmeli kullanıcı başına limitler”
• Veri gizliliği: “PII’nin diskte şifrelenmesi, GDPR uyumluluğu”

Aylar sonra biri bildirim sistemini spam için kullanmaya kalktığında bir güvenlik olayı ortaya çıkabilir; bunu önleyen de RFC’de belirtilen hız sınırlama stratejisidir.

Test Stratejisi#

Belirtilmeye değer yük testleri:

### Yük Testleri
- Yüksek hacimli bildirim gönderimi
- Eşzamanlı kullanıcı bağlantıları
- Yük altında veritabanı performansı
- Kuyruk işleme kapasitesi

Değeri detaylarda saklı: hangi yükün test edildiğini adlandırır, net geçti/kaldı koşulları koyar ve aracı adıyla belirtir (k6, Gatling, Locust), seçimi işi devralana bırakmaz.

Test bölümleri genelde bağımlılık arızaları için kaos testini (önbellek veya broker kesintisi gibi), çapraz tarayıcı WebSocket uyumluluğunu, kalıcı bağlantılardan kaynaklanan mobil uygulama pil etkisini ve şablonlarda uluslararası karakter seti işlemeyi atlar.

İzleme ve Analitik#

Çoğu izleme bölümü olası her metriği listeler. İyileri sistem sağlığını gösteren 3-5 metriği tanımlar.

### Anahtar Metrikler
- Teslimat başarı oranı (hedef: %99.9)
- Kanala göre teslimat zamanı
- Kullanıcı etkileşim oranları
- Destek bileti hacmi

Bir takımın her gün kontrol ettiği metrik sayısı aşağı yukarı dörttür.

RFC şunlarda alarm önerdi:

• Yüksek hata oranları (> %5)
• Teslimat gecikmeleri (> 10s)
• Sistem kaynak kullanımı (> %80)

Gerçekte alarm verilmesi gereken durumlar ise teslimat başarı oranının %99’un altına düşmesi, e-posta teslimatında P99’un 30 saniyeyi aşması veya veritabanı bağlantı havuzunun tükenmesidir.

Gerçek zamanlı teslimat yazısı gerçek bir sorunun normal varyanstan nasıl ayırt edileceğini açıklıyor.

Maliyet Analizi#

İyi maliyet bölümleri hem anlık hem de devam eden maliyetleri kabul eder.

### Altyapı Maliyetleri
- Veritabanı: $200-500/ay
- Mesaj Kuyruğu: $50-150/ay
- Push Bildirim Servisleri: 1000 bildirim başına $0.50

Bu tür kalemler tutar, çünkü yayınlanmış fiyatlandırmaya dayanır.

Tahmin edilebilir kalemler faturanın tamamı olmaz. Genelde dışarıda kalanlar:

• Log toplama ve saklama; ne kadar loglamaya karar verdiğinizle birlikte büyür
• Bildirim arşivi için nesne depolama
• Sorgu gecikmesi bozulunca eklenen ek okuma replikası
• Bakım için mühendislik zamanı; proje bittikten sonra da devam eden bir maliyettir

Altyapı kalemleri genellikle toplam sahip olma maliyetinin küçük yarısıdır. Fiyatlandıramasanız bile atlanan kalemleri RFC’de adıyla yazın.

RFC’nin tahmini:

• Destek biletlerinde %20-30 azalma
• Kullanıcı tutmada %5-15 artış

Bir aralık ancak ölçüm yöntemi yanında geldiğinde işe yarar: hangi bilet kategorileri sayılacak, hangi retention kohortu, hangi zaman aralığında; bu olmadan lansman sonrası tartışma sonuçlar üzerine değil, tanımlar üzerine döner.

Riskler ve Önlemler#

En iyi risk bölümleri yazarların ne bilmediğini kabul eder.

Risk: Yüksek hacimde veritabanı performansı bozulması
Azaltma: Uygun indexleme, okuma replikaları, sorgu optimizasyonu

Bir bildirim RFC’sinin listelediği riskler içinde gerçekleşen genelde budur. Sorgu gecikmesi kademeli bozulur, sonra zaman aşımları toplu gelmeye başlar. Listelenen önlem işe yarar ama indexleme, okuma replikaları ve sorgu yeniden yazımı bir öğleden sonranın değil, haftaların işidir.

Başka öngörülemeyen riskler de var: load balancer’daki WebSocket bağlantı limitleri, iç içe koşullularla şablon render performansı, zamanlanmış bildirimler için saat dilimi edge case’leri ve mobil operatörlerin SMS sağlayıcısını engellemesi.

Başarı Kriterleri#

Ölçülebilir ve gerçekçi yapın.

### Teknik Başarı
- %99.9 bildirim teslimat başarı oranı
- < 100ms uygulama içi bildirim teslimatı
- Sistem saniyede 10.000+ bildirimi işler

Ölçülebilirler (spesifik sayılar), ulaşılabilirler (temenniye değil, benzer sistemlere dayalı) ve ilgilidirler (doğrudan kullanıcı deneyimine bağlı).

Kriterler lansmandan sonra genelde yeniden pazarlık konusu olur:

• Erişilebilirlik hedefi bir dokuz düşer, çünkü son dokuz getirdiğinden fazlasına mal olur
• Gecikme hedefleri kullanıcının fark edebildiği eşiğe gevşer
• Verim gereksinimi tahmin edilen değil, gözlenen peak yüke iner

Bir kriterin neden değiştiğini kayda geçirmek ve yenisi için paydaş onayı almak, değişikliği meşru kılar.

Her Kitlenin Aradığı#

Farklı paydaşlar farklı şeyleri önemser:

Kitle	Önce neye bakar
VP’ler / direktörler	İş değerini açıklayan yönetici özeti, net ROI ile maliyet analizi, kilometre taşı teslimatlı zaman çizelgesi, karmaşıklığı gizlemeyen risk bölümü
Kıdemli mühendisler	Derin anlayış gösteren teknik uygulama, gerçek metriklere dayalı ölçeklenebilirlik değerlendirmesi, alternatif yaklaşımlar ve reddedilme gerekçeleri, mevcut sistemlerle entegrasyon noktaları
Takım liderleri	Değeri iteratif teslim eden uygulama aşamaları, gerçekten uygulanabilir test stratejisi, takımın arkasında durabileceği başarı kriterleri, alarm yorgunluğu yaratmayan izleme yaklaşımı
Güvenlik takımları	Kimlik doğrulama/yetkilendirme yaklaşımı, veri gizliliği değerlendirmeleri, hız sınırlama ve kötüye kullanım önleme, denetim izi yetenekleri

RFC’lerin Sürekli Hafife Aldıkları#

Dokümantasyon Sistemin Bir Parçası#

Siz planlasanız da planlamasanız da RFC birincil dokümantasyon kaynağına dönüşür, bu yüzden baştan canlı dokümantasyon olarak yapılandırmakta fayda var.

Migrasyon Stratejisi Önemli#

RFC’ler yeni sisteme odaklanır, eskisinden çıkıştan nadiren bahseder; oysa migrasyon başlı başına bir proje olduğu için yine de bir plan gerektirir.

Operasyonel Runbook’lar#

RFC operasyonel runbook’ları içermeli veya zorunlu kılmalıdır; bu boşluk ilk production olayında belirginleşir.

Feature Flag’ler#

Aşamalı dağıtımdan feature flag’lere göre daha sık bahsedilir; oysa bir flag, kötü giden sürümü rollback olmaktan çıkarıp config değişikliğine dönüştürür.

Canlı Doküman Olarak RFC#

Faydalı bir RFC onaydan sonra da kullanımda kalır ve şunlara evrilir:

• Mimari dokümantasyonu
• Yeni takım üyeleri için onboarding materyalleri
• Gelecek referans için karar logları
• İşler ters gittiğinde post-mortem bağlamı

Güvenilir Bir RFC’yi Ayıran Özellikler#

Belirsizlik Kabulü#

En iyi RFC’ler “Henüz Bilmediklerimiz” veya “Yanlış Olabilecek Varsayımlar” başlıklı bölümler içerir.

Geri Çekilme Planı ve Ölçülebilir Başarı#

Sistemi nasıl kuracağınızı ve işler ters giderse nasıl geri çekileceğinizi birlikte anlatmak onayı kolaylaştırır. Belirsiz başarı kriterleri sonsuz tartışmalara yol açar: spesifik sayılar gerçekte neyi başarmaya çalıştığınız konusunda netlik zorlar.

Yeterli Teknik Derinlik#

Başka bir takımın tasarımınızı uygulayabileceği kadar detay ekleyin.

Mükemmelin Sınırları#

Mükemmel RFC yoktur. Yukarıda adım adım incelenen bildirim sistemi RFC’sinin gerçek boşlukları var: karmaşıklığı hafife alıyor, operasyonel konularda zayıf kalıyor ve zaman çizelgelerinde iyimser; yine de paydaşları yeterince iyi bir çözümde hizalayıp onu geliştirmek için bir çerçeve bırakarak asıl işi görüyor.

RFC Paradoksu#

Pek çok organizasyonda tekrarlayan bir örüntü var: en iyi RFC’leri yazan takımlar genellikle onlara en az ihtiyaç duyanlardır. İletişimleri zaten güçlü, düşünceleri net, mühendislik pratikleri sağlamdır; doküman da zaten yaptıklarını resmileştirir. RFC’lerle boğuşan takımların ise genellikle belirsiz gereksinimler, çatışan vizyonlar veya her çözümü karmaşıklaştıran teknik borç gibi daha derin sorunları vardır; onlar için RFC bir zorlayıcı fonksiyona dönüşür.

Öneri takım sınırlarını aşıyorsa, bütçe bağlıyorsa veya geri dönüşü pahalıysa yapının tamamını kullanın. Değişiklik tek takımı ilgilendiriyorsa ve bir öğleden sonrada geri alınabiliyorsa atlayın; pull request’e düşülen kısa bir tasarım notu aynı bilgiyi daha az merasimle taşır. İkisinin arasında kalan durumlarda problem tanımını ve başarı kriterlerini yazın, gerisini uygulamaya bırakın.

Kaynaklar#

• RFC Editörü (yeni sekmede açılır) - RFC Üretim Merkezi tarafından sürdürülen, yayımlanan RFC’ler için yetkili kaynak
• IETF RFC Süreci (yeni sekmede açılır) - RFC’lerin nasıl oluşturulduğunu, incelendiğini ve yayımlandığını açıklayan resmi IETF belgeleri
• Mimari Karar Kayıtları - adr.github.io (yeni sekmede açılır) - Mimari kararları kaydetmek için hafif bir alternatif olan ADR’lere ilişkin topluluk kaynağı
• ADR Şablonları (yeni sekmede açılır) - Yaygın kullanılan Nygard formatı dahil ADR şablonları koleksiyonu
• Google Mühendislik Uygulamaları (yeni sekmede açılır) - Google’ın tasarım inceleme süreçleri de dahil mühendislik uygulamalarına ilişkin genel belgeleri