AI Geliştirmede Dokümantasyon: Kararlar Slack'te Kaybolmasın

AI Geliştirmede Dokümantasyon: Kararlar Slack'te Kaybolmasın

AI araçlarıyla geliştirme hızlandığında karar sayısı da artıyor. Mimari seçimler, önceliklendirme kararları, tasarım trade-off'ları, teknik borç kabulleri — bunların hepsi daha hızlı alınıyor çünkü AI seçenekleri hızla sunuyor.

Ama bu kararlar nerede yaşıyor?

Çoğu zaman Slack mesajında. Bazen bir toplantıda söylendi, yazılmadı. Bazen AI chat penceresinde kaldı, ekiple paylaşılmadı. İki ay sonra yeni bir geliştirici "neden böyle yapmışız?" diye soruyor. Cevabı bilen kişi şirkette değil artık. Ya da biliyor ama hatırlamıyor.

AI kararları hızlandırdı. Kararların yaşadığı yer değişmedi. Bu uyumsuzluk bilgi kaybına yol açıyor.

Karar Dağılması Neden AI ile Daha Hızlı Oluyor?

Geleneksel geliştirmede önemli kararlar yavaş alınırdı. Toplantı yapılırdı, e-posta yazışması olurdu, bazen RFC dokümanı hazırlanırdı. Bu yavaşlık kararı kayıt altına almayı doğal bir adım haline getiriyordu.

AI bu yavaşlığı ortadan kaldırdı. Şimdi şu senaryo çok yaygın: sabah Claude'a soruldu, beş dakikada üç seçenek geldi, biri seçildi, uygulamaya geçildi. Öğleden önce iş bitti.

O beş dakikalık değerlendirme — hangi alternatifleri neden elediğiniz, hangi kısıtlar belirleyici oldu, hangi trade-off'ları kabul ettiniz — hiçbir yere yazılmadı.

Slack yanılgısı: "Slack'te yazdık, orada duruyor" düşüncesi yaygın. Ama Slack bir arama motoru değil. Üç ay sonra o mesajı bulmak için ne aranacağını hatırlamak gerekiyor. Hatırlanmıyorsa karar kayıp.

AI chat kalıcı değil. Claude veya ChatGPT konuşmaları arşivlense bile ekiple paylaşılmıyor, projeyle ilişkilendirilmiyor, aranabilir değil. AI'ın sunduğu gerekçe orada kaldı.

Kişiye bağlı bilgi. Karar neden alındığını yalnızca o an karar veren kişi biliyor. Kişi değişince bilgi de gidiyor.

Alios'ta Karar Kaydı Formatı

Alios'ta her önemli karar node açıklamasına standart bir formatta yazılıyor. Ayrı bir doküman sistemi gerekmiyor — kararın uygulandığı görevin yanında, bağlamıyla birlikte yaşıyor.

📌 KARAR KAYDI — [Başlık]
Tarih: [Karar tarihi]
Karar Alanlar: [İsimler veya roller]
Durum: Aktif / Revize Edildi / Geçersiz

📍 BAĞLAM

[Bu karar neden gerekli oldu?]
[Hangi problem veya gereksinim tartışmayı başlattı?]
[Teknik ve iş kısıtları nelerdi?]
[AI araçları kullanıldıysa: hangi araç,
ne önerdi — özet]

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

Seçenek A: [İsim]
→ Artısı: [Madde]
→ Eksisi: [Madde]

Seçenek B: [İsim]
→ Artısı: [Madde]
→ Eksisi: [Madde]

Neden elendi: [Elenen seçenekler için 1 cümle]

✅ ALINAN KARAR

[Hangi seçenek, tek cümle]

Gerekçe:
[Neden bu seçenek? Hangi kısıtlar belirleyici oldu?]
[AI önerisinden ne alındı, ne değiştirildi?]
[Kabul edilen trade-off'lar neler?]

⚠️ KABUL EDİLEN SONUÇLAR

→ [Kazanılan şey]
→ [Kaybedilen veya kabul edilen risk]
→ [Henüz bilinmeyen — ilerleyen süreçte netleşecek]

🔄 REVİZYON KOŞULU

[Bu karar hangi koşulda gözden geçirilmeli?]
[Örnek: Kullanıcı sayısı 50K'yı geçerse]

🔗 BAĞLANTILAR

→ İlgili node: [Görev veya epik adı]
→ AI konuşması özeti: [Varsa belirleyici gerekçe]
→ Döküman: [RFC, benchmark, resmi kaynak]
→ PR / Commit: [Kararın uygulandığı kod]

Hangi Kararlar Kaydedilmeli?

Her teknik seçim için karar kaydı açmak gerekmez. Şu kriterleri karşılayan kararlar yazılıyor:

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, "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ı ve geçici çözümler karar kaydı gerektirmiyor.

Arama ve Linkleme: Tek Kaynak Yaklaşımı

Karar kaydı yazmak yeterli değil — bulunabilir olması gerekiyor. Alios'ta iki mekanizma bunu sağlıyor.

Arama ile Bulunabilirlik

Karar kaydı node başlıkları tutarlı bir format izlediğinde arama sonuçları anlamlı hale geliyor:

KARAR — Veritabanı: PostgreSQL vs MongoDB
KARAR — Auth: JWT vs Session
KARAR — Real-time: WebSocket vs SSE
KARAR — Deploy: Monolith vs Microservice

"KARAR" prefix'i ile yapılan aramada tüm karar kayıtları bir arada çıkıyor. Yeni ekip üyesi onboarding'de bu listeye bakarak sistemin neden böyle kurulduğunu anlıyor.

Linkleme ile Bağlam Zinciri

Karar kaydı tek başına değil, ilgili node'larla birlikte yaşıyor. Her karar kaydı uygulandığı göreve, o görev de karar kaydına bağlanıyor:

📁 Q3 — Real-time Dashboard Özelliği
│
├── 📌 KARAR — Real-time: WebSocket vs SSE
│   → Alınan karar: SSE
│   → Gerekçe: Tek yönlü iletişim, ekip HTTP
│     bilgisiyle hızlıca öğrenebilir
│
├── 📌 SSE altyapısı kurulumu
│   → Bağlı karar: "KARAR — Real-time: WebSocket vs SSE"
│
└── 📌 Real-time dashboard component
    → Bağlı karar: "KARAR — Real-time: WebSocket vs SSE"

Bu zincir kurulduğunda geliştirici göreve baktığında kararı görüyor, karara baktığında görevi görüyor. "Neden SSE kullandık?" sorusu göreve bakılarak yanıtlanıyor.

AI Konuşmalarını Karar Kaydına Taşımak

AI konuşmaları kalıcı değil. Link kırılabilir, konuşma silinebilir, bağlam kaybolabilir. Belirleyici olan AI çıktısını karar kaydına taşımak bu riski ortadan kaldırıyor.

Taşıma yöntemi kopyala-yapıştır değil — özet:

AI konuşması özeti:
Claude'a "WebSocket vs SSE, tek yönlü
real-time, Node.js + Express ortamı"
soruldu. Yanıt özeti: "Tek yönlü
iletişimde SSE, WebSocket'e göre daha az
kompleks ve aynı amacı karşılar. HTTP/2
ortamında bağlantı limiti izlenmeli."
Bu gerekçe seçimi belirleyici etkisi
yaptı.

Bu özet AI konuşmasının yerini tutmuyor ama kararın neden alındığını anlatan yeterli bağlamı sağlıyor.

Karar Kaydı Kültürünü Kurmak

Sistem ne kadar iyi tasarlanırsa tasarlansın, karar kaydı yazmak alışkanlık haline gelmezse kullanılmıyor. Üç pratik bu kültürü kuruyor.

Sprint sonunda retrospektif notu olarak: Her sprint kapanışında "bu sprint hangi önemli kararlar alındı?" sorusu sorularak kaydedilmemiş kararlar yakalanıyor. Hepsi değil, belirleyici olanlar.

Onboarding'de referans olarak: Yeni ekip üyesi sisteme katıldığında "KARAR" prefix'li node listesi paylaşılıyor. "Neden böyle kurulmuş?" sorusu büyük ölçüde bu liste tarafından yanıtlanıyor.

"Neden?" sorusu gelince kayıt açılıyor: Birileri "bunu neden böyle yaptık?" diye sorduğunda cevap Slack'e yazılmak yerine karar kaydı node'una yazılıyor. Bir kez yazılıyor, sürekli bulunabiliyor.

Son Düşünce

AI karar almayı hızlandırdı. Bu hız değerli. Ama hız dokümantasyonu atlamak için gerekçe değil.

Alios'ta karar kaydı formatı bu dengeyi kuruyor. Karar alınıyor, beş dakikada node'a yazılıyor, ilgili görevlere linkleniyor. Slack mesajı değil, arşivde yaşayan kayıt.

Altı ay sonra "neden böyle yapmışız?" sorusu geliyor. Cevap node'da yazıyor.