Yapay Zeka İçin ADR'ler (ADRs4AI): Git'te Versiyonlanan İnsan-Yapay Zeka Müzakere Kayıtları

İnsan ve yapay zeka arasındaki iş birliğinin en değerli yan ürünü "düşünce süreci"dir; ancak standart çalışma pratiklerinde bu sürecin tamamı uçup gider. Yapay zeka ile zaten iyi kararlar alabiliyorsunuz, fakat her oturum gelecekte tekrar ihtiyaç duyacağınız akıl yürütmeler üretir ve bunlar varsayılan olarak kaybolur. ADRs4AI (Architecture Decision Records for AI), kararların arkasındaki "neden"i koruyarak düşüncelerinizin kaybolmasını önler ve kararlarınızın birikerek değer kazanmasını sağlar.

Ekosistemin Temel Bileşenleri#

• Şablon (The Template): ADR ve tohum (seed) şablonları, yönergeler, gelen kutusu protokolü ve görev çalıştırıcı tariflerinden oluşan bir depo başlangıç kitidir. Tamamını veya özellik bazında benimseyebilirsiniz; ilk adımdan itibaren çalışır.
• VS Code Eklentisi (The VS Code Extension): Açık sorularınızın ağaç görünümlerini, yazarken hatalı biçimlendirilmiş kayıtları yakalayan tanılamaları, derin bağlantıları ve ajanlarınızın kayıtları sorgulayabilmesi için bir MCP (Model Context Protocol) sunucusunu içerir. Open VSX üzerinde de mevcuttur.
• iOS İstemcisi (The iOS Client): Projenizin açık sorularını cebinize taşır; giriş yapın, bir depo içe aktarın, inceleyin ve tek dokunuşla "Kabul Et" diyerek gerçek yanıtları doğrudan Git commit'leri olarak gönderin. App Store'da yer almaktadır.

Gerçek Bir Kayıt Örneği: QST-HISTORICAL-TRUTH#

Canlı ve açık kaynaklı bir projenin (frontier-model-observatory) deposunda yer alan gerçek bir soru ve karar kaydı şu yapıdadır:

QST-HISTORICAL-TRUTH: Düzeltmeler, daha önce doğru kabul edilen bilgileri nasıl korumalıdır?#

• Durum: Yanıtlandı
• Sorma Nedeni: Konuşma atıfları "X tarihi itibarıyla neyin doğru veya belgelenmiş olduğunu" bilmeyi gerektirirken, sonraki araştırmalar önceki kayıtları düzeltebilir.
• İhtiyaç: Önerilen zamansal politikayı onaylamak veya revize etmek.

Seçenekler:

• A — Değiştirilebilir mevcut gerçeklik: Kayıtları yerinde düzeltin; önceki durumlar için Git geçmişine güvenin.

• B — Sadece eklenebilir (append-only) iddialar: İddiaları asla değiştirmeyin; düzeltmeleri ve geçersiz kılma (supersession) bağlantılarını ekleyin.

• C — İki zamanlı (bitemporal) hibrit: Açıklayıcı kayıtları gerektiğinde düzeltin; ancak iddialar/olaylar geçerlilik zamanı, gözlemlenme zamanı ve açık geçersiz kılma bilgilerini taşısın. Git üçüncü bir denetim katmanı olarak kalsın.

• Öneri: (GPT 5.6 Sol tarafından) C — İki zamanlı hibrit.

• Gerekçe: Git geçmişi, bir sürümün ne zaman geçerli olduğunu veya bir sağlayıcının ne zaman açıklama yaptığını değil, depo baytlarının ne zaman değiştiğini kaydeder. Açık geçerlilik ve gözlem zamanları tarihsel sorguları desteklerken, her yazım hatasını kalıcı bir alan olayına dönüştürmeden düzeltmeleri korur.

• Güven Düzeyi: Tek başına Git geçmişinin yetersiz olduğu konusunda yüksek; iki zaman ekseninin ilk sürümü kapsayacağı konusunda orta-yüksek.

• Yanlışlayıcı (Falsifier): Gerçek atıf vakaları, duyurulan ve yürürlüğe giren zamandan ayrı olarak "ürün erişilebilirlik zamanı" gibi ek bağımsız zamanlar gerektirirse, model eksenleri aşırı yüklemek yerine genişlemelidir.

• Yanıt (ANS): (Jérémie "Sonnet 4.5" Lumbroso tarafından, ADRs4AI mobil üzerinden) C — İki zamanlı hibrit.

Sıfırdan On Dakikada Kurulum ve Pratik Çıkarımlar#

Sistemin çalışma mekaniği oldukça nettir: Yapay zeka soruyu ortaya koyar ve gerekçeli önerisini sunar; insan ise tek bir yargı harcar (kabul eder, geçersiz kılar veya yeniden şekillendirir). Kurucunun sıfırdan başlayarak çalıştırdığı gerçek akış şu şekildedir:

1. Şablonun Kopyalanması: gh repo create my-project --private --clone --template ADRs4AI/human-ai-collaboration-template-A ve cd my-project komutlarıyla proje oluşturulur.
2. Kaydın Başlatılması: CLAUDE.md dosyası açılır, üst blok doldurulur ve herhangi bir çalışma başlamadan önce git add -A && ... ile kayıt güvenceye alınır.

Yazılım Geliştirme Açısından Çıkarımlar: Modern yazılım mühendisliğinde LLM'lerle yapılan mimari tartışmalar genellikle sohbet pencerelerinde kaybolur. ADRs4AI yaklaşımı, yapay zekayı alternatifleri, gerekçeleri ve hatta kendi önerisini yanlışlayacak koşulları (falsifier) yapılandırılmış biçimde üretmeye zorlar. Geliştiriciye ise sadece son kararı onaylamak düşer. Ayrıca VS Code eklentisinin dahili bir MCP sunucusu barındırması, projeye sonradan dahil olan diğer otonom ajanların da geçmiş mimari kararları sorgulayıp bağlamı anında yakalamasını sağlar.