Üç Yıllık Kod Tabanında Yapay Zekanın Halüsinasyonlarını Nasıl Durdurdum?

Üç yıldır süren karmaşık bir fintech projesinde, yapay zeka destekli kodlama araçlarını kullanmaya başladıktan sonra karşılaşılan en büyük sorun, AI’nın gerçek dünya verilerini ve projenin mimarisini anlamamasıydı. AI, basit bir contacts tablosu oluşturma göreviyle karşılaştığında, var olan users tablosunu görmezden geldi ve verileri kopyalayan yeni bir tablo oluşturdu. Bu durum, AI’nın bağlamsal bilgiye ihtiyacı olduğunu net bir şekilde ortaya koydu.

AI’nın kod üretimini güvenilir hale getirmek için atılan adımlar, yalnızca yeni özellikler eklemekle kalmadı; aynı zamanda projenin dokümantasyonunu AI’nın anlayabileceği şekilde yeniden yapılandırdı. Bu yaklaşım, AI’nın hata yapma olasılığını önemli ölçüde azalttı ve ekibin daha hızlı çalışmasını sağladı.

Üç Yıllık Kod Tabanında AI’nın Karşılaştığı Temel Sorunlar

Bir fintech projesinde, iki React tabanlı arayüz (yönetici paneli ve müşteri uygulaması), FastAPI backend ve karmaşık ilişkisel bir veritabanı bulunuyor. Proje üç yıldır aktif olarak geliştiriliyor ve finansal veriler ile kullanıcı bilgileri hassasiyetle korunuyor. Yeni özellikler eklerken karşılaşılan en büyük zorluk, veritabanı yapısının yalnızca bir kişi tarafından tam olarak anlaşılmasıydı. Her yeni sorgu veya tablo ilişkisi için, o kişinin onayına ihtiyaç duyuluyordu.

AI destekli araçları kullanmaya başladıklarında, karşılaşılan ilk sorunlardan biri, AI’nın mevcut tablo yapısını tanımamasıydı. Örneğin, müşteri verilerini saklayan users tablosu varken, AI’nın contacts tablosu oluşturması ve verileri kopyalaması, veritabanı bütünlüğünü tehdit etti. Bu durum, AI’nın bağlamsal bilgiye sahip olmadığını gösteriyordu.

Bu deneyim, AI’nın performansını artırmak yerine, "AI’nın doğru kararlar alabilmesi için ne gibi bilgilere ihtiyacı var?" sorusunu gündeme getirdi.

AI’nın Güvenilirliği için Bağlamı Belirgin Hale Getirmek

AI’nın güvenilirliğini artırmak için, Matt Pocock’un yapılandırılmış AI iş akışları üzerine yaptığı çalışmalardan esinlenerek, projenin bağlamını AI’nın anlayabileceği şekilde düzenledik. Temel fikir basitti: AI, yalnızca verilen bağlama kadar iyidir. Bu nedenle, bağlamı açık ve yetkili hale getirmek için aşağıdaki adımları attık.

1. Mimari Karar Kayıtları (ADR)

Projede, docs/adrs/ adlı bir dizin oluşturarak, mimari kararları kaydetmeye başladık. Bu kayıtlar, yalnızca ne kararları alındığını değil, neden bu kararların alındığını da açıklıyordu. Her ADR, AI’nın karşılaşabileceği spesifik soruları yanıtlıyordu:

• Yeni bir tablo nasıl oluşturulmalı?
• Tablolar nasıl ilişkilendirilmeli?
• Yeni bir API rotası nasıl yapılandırılmalı?
• Dosyalar kod tabanında nerede yer almalı?

Örneğin, contacts tablosu hatası, ADR-001 olarak kaydedildi: Yeni bir tablo oluştururken, mevcut tabloları kontrol edin. İlgili alanlar varsa, yabancı anahtar kullanın. Kullanıcı verilerini asla kopyalamayın. Var olan bir tabloya ait olabilecek yeni sütunlar için her zaman onay alın.

Artık AI, yeni bir tablo göreviyle karşılaştığında, bu kuralı okuyarak hareket ediyor.

2. Bağlam Dosyası ve Sözlük

Kod tabanımızda, AI’nın genel kod eğitiminden farklı anlamlar taşıyan terimler bulunuyordu. Bu terimleri açıklamak için context.md adlı bir dosya oluşturduk. Bu dosya, her terimin projemizdeki özel anlamını, terimler arasındaki ilişkileri ve benzer görünen ancak farklı olan kavramları açıklıyordu.

Ayrıca, projenin genel yapısını ve bileşenlerinin nasıl etkileşimde bulunduğunu gösteren plot.md adlı bir harita da ekledik. Her iki dosyanın da en üstünde yer alan kural şuydu: docs dizini yetkili kaynaktır. Bu kurallar öneri değil, zorunluluktur. Adımları atlamayın.

3. Tüm API’ler için Test Durumları

Artık her yeni API rotası, test durumlarıyla birlikte sunuluyor. Bu testler opsiyonel değil; her commit öncesinde çalıştırılması zorunlu. Testler, AI’nın uzun süreli kullanımında güvenilirliğini artırmaktan daha fazlasını yaptı.

Örneğin, AI’nın ortak bir yardımcı fonksiyonda yaptığı küçük bir değişiklik, on iki farklı yerde kullanılan bu fonksiyonu sekiz yerde bozdu. Test paketi hatayı hemen yakaladı. AI, başarısızlıkları gördü, sorunu yardımcı fonksiyona kadar izledi ve yalnızca eski davranışı eski haline getirmek yerine, hem eski hem de yeni gereksinimleri karşılayan yeni bir fonksiyon versiyonu oluşturdu. AI, kendi hatasını düzeltmeyi başardı.

Bu testler olmasaydı, hata yayınlanabilirdi.

Ekibin Deneyimindeki Değişim

Bu sistemi ekibime gösterdiğimde, bazıları şüpheciydi. Daha önce AI araçlarının yanlış kararlar verdiğini, güvenilir olmadığını görmüşlerdi. Ancak oturumun ardından üç ekip üyesi, kendi projelerinde aynı sistemi kurmamı istedi.

Bu değişim, AI’ya olan güveni artırmaktan çok, AI’nın güvenilir olması için yapıya ihtiyaç duyduğunu anlamaktan geçiyordu. Tıpkı yeni bir geliştiricinin kod tabanını anlaması için dokümantasyona, kod incelemesine ve eğitime ihtiyaç duyması gibi, AI’nın da aynı desteğe ihtiyacı vardı. Yeni bir çalışanı, kod tabanını bilmediği için suçlamazsınız; dokümantasyon sağlarsınız. Biz de AI için aynı şeyi yaptık.

Bu Sistemi Uygulamak İsteyenler İçin Adımlar

Aşağıdaki dosya yapısını düzenleyerek başlayabilirsiniz:

docs/
├── context.md          # Projenin ne olduğu, terimlerin anlamı, bileşenlerin ilişkisi
globals/
├── plot.md             # Projenin yüksek seviyeli haritası
└── adr/
    ├── 001-tablo-oluşturma.md
    ├── 002-api-yapısı.md
    └── 003-sorgu-patternleri.md

Uygularken dikkat edilmesi gerekenler:

• ADR’lerde spesifik olun. "İyi veritabanı uygulamaları izleyin" yerine, "Yeni bir tablo oluştururken mevcut tabloları kontrol edin" gibi net kurallar belirleyin.
• Dokümantasyonu yetkili kaynak olarak tanımlayın. AI’ya bu kuralların her zaman ilk sırada olduğunu belirtin.
• AI her hata yaptığında yeni bir ADR ekleyin. Başarısızlıkları kurala dönüştürün.
• Her yeni API için test durumları yazın. Her commit öncesinde testleri çalıştırın. AI bir şeyi bozduğunda, o durumu yakalayan bir test ekleyin ve AI’nın aynı hatayı tekrar yapmasını engelleyin.

Sonuç: AI’yı Mükemmel Hale Getirmek Değil, Tahmin Edilebilir Kılmak

Bu sistem AI’yı mükemmel hale getirmedi; yalnızca tahmin edilebilir kıldı. AI hata yapmaya devam ediyor, ancak artık bu hatalar daha küçük, yakalanması daha kolay ve öğrenilebilir nitelikte. Her hata, gelecekteki kararları iyileştirmek için bir fırsata dönüşüyor.

Asıl amaç, AI’nın her şeyi doğru yaptığı bir kod tabanı yaratmak değil; AI’nın tutarlı çalıştığı ve ekibin daha hızlı ilerlediği bir ortam oluşturmaktı. Bunu başardık.

Yapay zekanın potansiyelini en üst düzeye çıkarmak için, yalnızca aracı değil, aracın çalıştığı ortamı da optimize etmek gerekiyor. Bu yaklaşım, gelecekteki projelerde AI’nın güvenilirliğini artırmak için önemli bir model sunuyor.