Kodlama asistanı için proje bağlamı ve kural dosyaları

Bağlam yönetimi neden kodlama asistanının kalitesini belirler?

Bir yapay zeka kodlama asistanı, önüne konan bilgiyle çalışır. Model kod yazmayı genel olarak bilir; ama sizin projenizin katman yapısını, isimlendirme alışkanlığını, kullandığınız iç kütüphaneleri ve ekibin verdiği kararları bilmez. Bu bilgi ona verilmediğinde, makul görünen ama projeye uymayan kod üretir: yanlış klasöre dosya, projede kullanılmayan bir kütüphane, ekibin terk ettiği bir desen.

Bağlam yönetimi, asistana doğru bilgiyi doğru zamanda ve doğru miktarda vermektir. Eksik bağlam genel ve uyumsuz çıktı doğurur. Fazla ve düzensiz bağlam ise modelin dikkatini dağıtır, önemli kuralları gölgede bırakır. Hedef, az ama ilgili ve güncel bilgidir.

Kalıcı proje bağlamı: kural ve talimat dosyaları

Birçok kodlama aracı, depo içindeki özel dosyaları otomatik okuyarak asistana kalıcı bağlam verir. GitHub Copilot için GitHub belgeleri şu yapıyı tanımlar: depo genelinde .github/copilot-instructions.md, belirli dosya desenleri için .github/instructions/ altında .instructions.md ile biten ve applyTo alanıyla kapsamı belirlenen dosyalar, ve depodaki herhangi bir yerde konabilen AGENTS.md. Bir dizinde çalışırken en yakın AGENTS.md öncelik kazanır; alternatif olarak kök dizinde tek bir CLAUDE.md ya da GEMINI.md kullanılabilir. Diğer araçların da kendi adlarını taşıyan benzer kural dosyaları vardır; dosya adı araca göre değişir, mantık aynıdır.

Bu dosyalar depoda tutulduğu için git ile versiyonlanır, çekme isteğiyle gözden geçirilir ve yeni ekip üyesine de aynı bağlamı taşır. Kural dosyası, aynı zamanda ekibin yazılı mühendislik standardı hâline gelir. Standart değiştiğinde dosya da değişir; böylece asistan eski kuralı değil güncel ekip kararını izler.

Kural dosyasına ne yazılır, ne yazılmaz?

İyi bir kural dosyası kısa, kesin ve doğrulanabilirdir. İçine şunlar konur:

• Projenin tek paragraflık tanımı ve teknoloji yığını
• Dizin yapısı ve hangi kodun nerede durduğu
• Kod stili ve isimlendirme kuralları
• Test çerçevesi, testlerin nasıl çalıştırıldığı ve beklenen test düzeyi
• Derleme, çalıştırma ve kontrol komutları
• Kaçınılacak kalıplar ve ekibin bilinçli olarak yapmadığı şeyler
• Hata yönetimi, günlükleme ve güvenlik ilkeleri

Yazılmayacaklar da önemlidir. Gizli anahtar, parola, müşteri verisi asla yazılmaz. Kodu okuyunca zaten anlaşılan ayrıntılar, uzun açıklamalar ve güncelliğini yitirmiş bilgi dosyayı şişirir. Belirsiz öğütler ("temiz kod yaz") işe yaramaz; "hata durumunda özel hata sınıfı fırlat, düz metin atma" gibi somut kural işe yarar.

Anlık bağlam: görev bazında hangi bilgi verilir?

Kalıcı kuralların yanında her görev için anlık bağlam sağlanır. Asistana şu sorular yanıtlanarak görev verilir: ne yapılacak, neden yapılacak, hangi dosyalar ilgili, benzer çalışan örnek nerede, başarı nasıl anlaşılır? Mevcut bir uç noktaya benzeyen yenisi yazılacaksa o uç noktanın dosyası örnek olarak gösterilir. Hata ayıklamada hata mesajı, ilgili günlük satırları ve beklenen davranış verilir.

Bağlamın niteliği miktarından önemlidir. Tüm depoyu yüklemek yerine görevle ilgili dosyaları seçmek daha isabetli sonuç verir. Sohbet uzadıkça önceki konuşma bağlamı da şişer; konu değiştiğinde yeni bir oturum başlatmak, eski ve ilgisiz bilginin yeni göreve sızmasını önler.

Bağlam kirliliği ve çelişkili talimatlar

Bağlam büyüdükçe çelişki riski artar. Kural dosyasında "fonksiyonel stil kullan" yazarken örnek olarak gösterilen dosya sınıf tabanlıysa model hangisine uyacağını bilemez. Eski bir kural dosyası, kodun yeni durumunu yansıtmıyorsa asistan eskiyi tekrarlar.

Kirliliği önlemek için şunlar yapılır: kural dosyası düzenli aralıklarla gözden geçirilir, kodla çelişen madde silinir, asistanın tekrar eden hataları kural olarak eklenir ve kural dosyasının kendisi de çekme isteğiyle incelenir. Çok büyük projelerde talimatlar kapsamlara bölünür: genel kurallar kökte, alana özgü kurallar ilgili dizinde ya da dosya desenine bağlı kural dosyasında tutulur.

Ajan tabanlı çalışmada bağlam ve sınırlar

Asistan yalnızca öneri vermek yerine dosya düzenleyip komut çalıştıran bir ajan gibi çalıştığında bağlam yönetimine ek olarak sınır yönetimi gerekir. Kural dosyasında hangi komutların çalıştırılabileceği, hangi dizinlerin değiştirilemeyeceği, hangi işlemlerin onay isteyeceği belirtilir. Testlerin ve kontrol komutlarının nasıl çalıştırılacağını bilen ajan, kendi çıktısını doğrulayabilir.

Büyük görevler tek seferde verilmez. Önce plan istenir, plan gözden geçirilir, sonra adım adım uygulanır. Her adımın sonunda testler çalıştırılır ve değişiklik incelenir. Bağlam yönetimi, ajanın hangi bilgiye dayanarak karar verdiğini izlenebilir kılar.

Sık yapılan hatalar

• Kural dosyası yazmamak ve her seferinde aynı kuralları sohbette tekrarlamak
• Dosyayı çok uzun tutmak: önemli kurallar kaybolur
• Güncel olmayan kuralları bırakmak
• Tüm depoyu bağlam olarak yüklemek
• Çelişkili örnek ve kural vermek
• Gizli bilgiyi kural dosyasına yazmak
• Asistanın tekrar eden hatasını düzeltmek yerine her seferinde elle onarmak: hata kurala dönüştürülmeli

İyi bir alışkanlık, asistan aynı hatayı yinelediğinde kural dosyasına bir madde eklemektir. Zamanla dosya, projenin gerçek ihtiyaçlarına göre şekillenir.

Bu beceri Mindset programlarında nerede çalışılır?

Yapay Zeka Destekli Yazılım Geliştiriciliği Sertifika Programı'nın Bağlam Yönetimi ve Proje Standartları modülü doğrudan bu konuya ayrılmıştır. Geliştiriciler için İstem Mühendisliği, Cursor ile İleri Düzey Proje Geliştirme, Ajan Tabanlı Geliştirme ve Terminal Araçları ile Kurumsal Kullanım Esasları ve Verimlilik Ölçümü modülleri konuyu tamamlar.

Yazılım ekipleri, ortak kural dosyalarını ve proje standartlarını bu başlıklar üzerinden tartışabilir; teknik liderler ve mimarlar için de kurumsal ölçekte standartlaştırma açısından uygun bir yapıdır.