Niyet Odaklı Programlama: Vibe Coding'den Spec-Driven Development'a

Ünite 1: Programlamanın Soyutlama Evrimi ve Niyet Kavramı

1.1. Programlamaya Yeniden Bakmak

Programlama çoğu zaman bir programlama dilinde kod yazmakla özdeşleştirilir. Oysa kod, programlamanın kendisi değil, insanın çözüm düşüncesini bilgisayara aktarmak için kullandığı gösterimlerden biridir.

Bir programlama problemi en temel biçimiyle şu zincir üzerinden düşünülebilir:

Problem → zihinsel model → algoritma → gösterim → yürütme

Bir mühendis önce problemi anlamaya, sonra bu problem için bir çözüm tasarlamaya çalışır. Çözüm bir algoritma, durum makinesi, veri akışı, kural kümesi, matematiksel model veya bunların birleşimi olabilir. Programlama dili ise bu çözümün bilgisayar tarafından işlenebilecek biçimde ifade edilmesini sağlar.

Bu nedenle programlama tarihine yalnızca dillerin tarihi olarak bakmak eksiktir. Aynı zamanda bu tarih, insanın makineye ne istediğini giderek daha yüksek bir soyutlama düzeyinden anlatabilmesinin tarihidir.

İlk dönemlerde programcı bilgisayara büyük ölçüde nasıl çalışması gerektiğini söylüyordu. Günümüzde üretken yapay zekâ ve yazılım geliştirme ajanlarıyla birlikte giderek daha fazla ne istediğimizi, hangi sınırlar içinde istediğimizi ve doğru sonucun hangi koşulları sağlaması gerektiğini tarif ediyoruz.

Bu değişim programlamayı ortadan kaldırmaz. Programlama etkinliğinin insan tarafından görülen katmanını değiştirir.

1.2. Makineye Yaklaşmaktan Makineden Uzaklaşmaya

Bilgisayar programlama tarihinde her büyük gelişme, belirli bir ayrıntı sınıfının programcıdan gizlenmesiyle birlikte gelmiştir.

Makine kodunda işlemci komutlarının sayısal karşılıklarıyla çalışmak gerekirken, assembly dili bunlara sembolik adlar verdi. Yüksek seviyeli diller bellek adresleri ve işlemci komutları yerine değişkenler, fonksiyonlar ve veri yapıları sundu. İşletim sistemleri donanım ayrıntılarının önemli bölümünü soyutladı. Kütüphaneler ve çatı sistemleri tekrar eden altyapı işlerini hazır bileşenlere dönüştürdü.

Kabaca şu gelişim çizgisinden söz edilebilir:

Makine kodu
    ↓
Assembly
    ↓
Yüksek seviyeli programlama dilleri
    ↓
Kütüphaneler ve çalışma zamanları
    ↓
Çatı sistemleri ve alan dilleri
    ↓
Görsel ve düşük kodlu geliştirme
    ↓
Doğal dil ile yapay zekâ destekli geliştirme

Bu çizginin ortak özelliği, her aşamada programcının doğrudan yönetmek zorunda olduğu ayrıntı miktarının azalmasıdır.

C diliyle yazılmış bir döngü, makine düzeyinde çok sayıda işlemci komutuna dönüşebilir. Java'da tek bir koleksiyon işlemi altında bellek yönetimi, çalışma zamanı denetimleri ve sanal makine davranışları bulunabilir. Bir Spring Boot bildirimi arkasında HTTP sunucusu, yönlendirme, serileştirme ve bağımlılık yönetimi gibi geniş bir altyapı çalışabilir.

Yapay zekâ destekli programlama bu soyutlama eğiliminin devamı olarak görülebilir.

Önce:

for (int i = 0; i < values.length; i++) {
    ...
}

yazarken artık bazı görevlerde:

Bu kayıtları mevcut sıralama davranışını değiştirmeden
tarihe göre grupla ve en düşük ek bellek maliyetiyle işle.

gibi bir niyet tarif ediyoruz.

Aradaki temel fark, yapay zekânın yalnızca bir sözdizimi dönüştürücüsü olmamasıdır. İfade edilen amacı yorumlar, bağlamı kullanır, çözüm yolları üretir ve bunları programlama diliyle somutlaştırır.

1.3. Sözdiziminden Niyete

Geleneksel programlamada mühendisin zihnindeki temel soru çoğu zaman şöyledir:

“Tasarladığım algoritmayı bu programlama diliyle nasıl ifade ederim?”

Yapay zekâ destekli geliştirmede soru giderek değişmektedir:

“Sistemin göstermesi gereken davranışı, sınırları ve doğruluk ölçütlerini nasıl ifade ederim?”

Bu değişim küçük görünse de yazılım üretiminin merkezini değiştirmektedir.

Geleneksel akış:

Problem
  ↓
Algoritma
  ↓
Programlama dili
  ↓
Derleyici / yorumlayıcı
  ↓
Makine

Niyet odaklı akış ise daha çok şöyledir:

Problem
  ↓
Niyet
  ↓
Belirtim
  ↓
Bağlam ve kısıtlar
  ↓
Yapay zekâ / ajan
  ↓
Programlama dili
  ↓
Derleyici / çalışma zamanı
  ↓
Makine

Programlama dili ortadan kalkmamıştır. İnsan ile programlama dili arasına yeni bir yorumlama ve üretim katmanı girmiştir.

Bu nedenle doğal dile doğrudan “yeni programlama dili” demek teknik olarak yanıltıcı olabilir. Doğal dil belirsizdir; aynı cümle farklı biçimlerde yorumlanabilir. Java, C veya Rust ise biçimsel sözdizimi ve açık semantik kurallara sahiptir.

Daha doğru ifade şudur:

Doğal dil, programlama sürecinin yeni yüksek seviyeli denetim arayüzlerinden biri haline gelmektedir.

1.4. Niyet Odaklı Programlama Kavramı ve Tanımı

Niyet programlama burada yerleşik ve tek anlamlı bir sektör standardının adı olarak değil, niyet odaklı yapay zekâ destekli geliştirmeyi açıklayan kavramsal bir üst çerçeve olarak kullanılır. Güncel pratikte bu alan vibe coding, Spec-Driven Development ve bağlam mühendisliği gibi daha yaygın veya daha belirgin kavramlarla kesişir.

Niyet odaklı programlamada geliştirici, çözümün bütün uygulama ayrıntılarını doğrudan yazmak yerine ulaşılacak davranışı, sınırları, korunacak özellikleri ve doğruluk ölçütlerini tarif eder. Vibe coding bunun daha serbest ve sonuç odaklı ucunu temsil ederken, Spec-Driven Development niyeti yapılandırılmış belirtimler, kısıtlar, kabul ölçütleri ve doğrulama üzerinden disipline eder.

Buradaki “niyet”, yalnızca:

Kullanıcı yönetimi ekle.

gibi bir istek değildir.

Mühendislik açısından gerçek bir niyet daha fazla bilgi taşır:

Mevcut kullanıcı yönetiminin davranışını koru.

Yeni kullanıcı kaynağını mevcut yetkilendirme modeline ekle.

Veritabanı şemasını değiştirme.

Mevcut API sözleşmelerini bozma.

Yetki kontrolünü atlayan hiçbir yürütme yolu oluşturma.

Başarısız dış servis çağrılarında mevcut hata semantiğini koru.

Burada geliştirici artık yalnızca istenen davranışı değil, değişiklik uzayının sınırlarını da tarif etmektedir.

Bu nedenle niyet programlamanın daha doğru modeli şöyledir:

Niyet = yapılacaklar + yapılmayacaklar + korunacak değişmezler + başarı ölçütleri

Buna bağlam, araçlar ve doğrulama eklendiğinde mühendislik süreci oluşur:

Niyet
+
Belirtim
+
Bağlam
+
Kısıtlar
+
Araçlar
+
Doğrulama

İyi sonuç yalnızca iyi yazılmış bir komuta bağlı değildir. Yapay zekâ ile kod üretiminde asıl belirleyici, “zekice istem”tan çok proje mimarisi, kurallar, örnekler, araçlar, bellek ve sınırların doğru bağlama verilmesidir.

1.5. İstem Mühendisliği ile Niyet Odaklı Programlama Aynı Şey Değildir

Bir yapay zekâ modeline iyi komut yazabilmek yararlı bir beceridir. Ancak bunu niyet odaklı programlamanın tamamı olarak görmek yetersizdir.

Örneğin:

Daha hızlı çalışan bir sürüm yaz.

bir komuttur; fakat mühendislik belirtimi değildir.

“Daha hızlı” sözü şu soruları cevaplamaz:

• Hangi yük altında?
• Ortalama gecikme mi, en kötü gecikme mi?
• İşlem hacmi mi artırılacak?
• Bellek artabilir mi?
• Tutarlılık değişebilir mi?
• Sonuçların sırası korunacak mı?
• Davranış değişikliğine izin var mı?
• Ölçüm hangi donanımda yapılacak?

Bu nedenle daha olgun yapay zekâ destekli yazılım geliştirmede odak istem mühendisliğinden bağlam ve belirtim mühendisliğine kaymaktadır.

İyi bir yapay zekâ ajanının bilmesi gerekenler arasında şunlar bulunabilir:

• sistem mimarisi,
• kodlama kuralları,
• alan modeli,
• veri modeli,
• API sözleşmeleri,
• güvenlik sınırları,
• bilinen teknik borçlar,
• performans hedefleri,
• geçmiş mimari kararlar,
• değiştirilmemesi gereken davranışlar,
• kabul ölçütleri.

1.6. Vibe Coding

“Vibe coding” kavramı 2025 yılında Andrej Karpathy'nin doğal dille istenen davranışın tarif edildiği, üretilen kodun ayrıntılarına fazla inilmeden sonuç üzerinden ilerlenen bir çalışma biçimini tanımlamasıyla yaygınlaştı.

En yalın biçimiyle süreç şöyle ilerleyebilir:

İsteği yaz
   ↓
Yapay zekâ kodu üretsin
   ↓
Çalıştır
   ↓
Hata oluşursa hata mesajını yapay zekâya ver
   ↓
Yeni sürümü dene

Bu yaklaşım küçük araçlar, denemeler, kişisel uygulamalar ve hızlı prototipler için verimli olabilir.

Sorun, aynı yöntemin risk sınıfı gözetilmeden üretim sistemlerine taşınmasıdır.

Bir programın:

“çalışıyor gibi görünmesi”

ile:

“bütün tanımlı koşullarda doğru davranması”

aynı şey değildir.

Bu nedenle vibe coding burada niyet odaklı geliştirmenin tamamı değil, daha serbest ve daha az belirtim odaklı bir uç noktası olarak ele alınır.

1.7. Belirtim Odaklı ve Yapılandırılmış Yapay Zekâ Destekli Geliştirme

Vibe coding ile geleneksel mühendislik arasında geniş bir alan bulunur. Bu alanın daha disiplinli yaklaşımlarından biri Spec-Driven Development'tır. Burada belirtim; niyeti, gereksinimleri, kısıtları, kabul ölçütlerini ve doğrulamayı insan ile yapay zekâ arasında ortak bir kaynakta toplar.

Deneyimli geliştirici:

1. problemi analiz eder,
2. çözüm sınırlarını belirler,
3. mimari kararı verir,
4. yapay zekâya belirli bir alt görevi verir,
5. üretilen değişikliği inceler,
6. başarısızlığı teşhis eder,
7. düzeltmeyi yeniden yapay zekâya yaptırabilir.

Burada yapay zekâ karar verici olmaktan çok uygulama hızlandırıcısıdır.

Belirtimin uygulanabilirliği, doğal dil ifadesinin ayrıntısından çok sınanabilirliğine bağlıdır. “Sistem hızlı olmalı” gereksinimi tek başına kabul ölçütü değildir; iş yükünün tanımı, eşzamanlı kullanıcı sayısı, veri büyüklüğü, gecikmenin hangi yüzdeliğinin ölçüleceği ve hata durumunda kabul edilen davranış birlikte yazılmalıdır. Değişiklik üreten araca ayrıca dokunulmayacak arayüzler, şema, veri akışı ve geriye uyumluluk koşulları verilir. Üretilen kodun çalışması, bu koşulların sağlandığını kanıtlamaz; her koşul bağımsız bir test veya inceleme bulgusuyla eşleştirilmelidir.

1.8. Ajanlı Mühendislik

Yazılım ajanı yalnızca tek bir cevap üreten sohbet modeli değildir.

Bir görev alabilir, ortamı inceleyebilir, dosyaları okuyabilir, komut çalıştırabilir, sonucu gözlemleyebilir ve sonraki adımı buna göre belirleyebilir.

Basitleştirilmiş ajan çevrimi şöyledir:

Hedefi algıla
    ↓
Planla
    ↓
Eylem gerçekleştir
    ↓
Sonucu gözle
    ↓
Gerekirse planı değiştir
    ↓
Yinele

Bu nedenle güçlü bir dil modeline sahip olmak tek başına güçlü bir yazılım geliştirme sistemi oluşturmaz.

1.8.1. Claude Code Örneğinde Ajan Döngüsü

Claude Code bu ayrımı somutlaştıran güncel araçlardan biridir. Terminal, dosya sistemi, sürüm kontrol durumu ve izin verilen diğer araçlar üzerinden yalnızca metin üretmez; görevi yerine getirmek için çevreyi okuyabilir, işlem yapabilir ve elde ettiği sonucu sonraki adıma girdi olarak kullanabilir.

Bu davranışı tek bir “kod üret” çağrısı gibi görmek yanıltıcıdır. Daha gerçekçi model şöyledir:

Niyet
  ↓
Bağlamı edin
  ↓
Eylem seç
  ↓
Araç kullan
  ↓
Sonucu gözle
  ↓
Varsayımı güncelle
  ↓
Gerekirse başka araç kullan
  ↓
Doğrula

Bu döngüde modelin muhakemesi ile aracın gerçek dünyada oluşturduğu etki ayrıdır. Bir dosyayı okumak, bir derleyiciyi çalıştırmak, test sonucu almak veya git diff incelemek yeni kanıt üretir. Ajanın sonraki kararı bu kanıta dayanabilir.

Mühendislik açısından önemli sonuç şudur:

Ajanın kalitesi yalnızca model kalitesi değil; model + bağlam + araç sözleşmeleri + izinler + doğrulama çevriminin ortak sonucudur.

Bu nedenle aynı model, iki farklı kod deposunda veya iki farklı araç yapılandırmasında belirgin biçimde farklı güvenilirlik gösterebilir. İyi düzenlenmiş bir proje; derleme, test ve statik analiz yollarını görünür kılar. Kötü düzenlenmiş bir proje ise ajanın enerjisini kod yazmaktan çok ortamı tahmin etmeye harcamasına neden olur.

Ajanlı geliştirmede planlama da tek başına güvence değildir. Plan, henüz doğrulanmamış bir hipotezdir. Dosyalar, çağrı zincirleri, yapılandırma, testler ve çalışma zamanı çıktıları planı doğrulayan veya çürüten kanıt katmanlarıdır.

Ünite 2: Yaşam Döngüsü, Mimari, Kısıtlar ve Doğrulama

Niyet temelli geliştirmede gereksinim yalnız doğal dilde bırakılmamalı; gözlenebilir kabul koşulları, değişmezler ve yasaklanan davranışlarla somutlaştırılmalıdır. Uygulama öncesi mevcut sözleşmeler ve değiştirilmemesi gereken modüller belirlenir. Üretilen değişiklik küçük parçalar hâlinde doğrulanır; derlenmesi, işlevsel regresyonu ve davranış sınırları ayrı aşamalarda kontrol edilir. Otomatik üretimin hız kazandırması, inceleme ve sorumluluk zincirini ortadan kaldırmaz.

2.1. Yazılım Geliştirme Yaşam Döngüsünün Değişimi

Geleneksel yazılım geliştirme yaşam döngüsü kabaca şu aşamalardan oluşur:

Gereksinim
↓
Analiz
↓
Tasarım
↓
Kodlama
↓
Test
↓
Dağıtım
↓
Bakım

Çevik yöntemler ve DevOps bu aşamalar arasındaki süreyi önemli ölçüde kısaltmıştı. Yapay zekâ ise aşamaların arasındaki sınırları daha fazla bulanıklaştırmaktadır.

Bir geliştirici bugün aynı oturum içinde gereksinimi tartışabilir, veri modelini değerlendirebilir, API taslağını oluşturabilir, kod üretebilir, test hazırlayabilir, hatayı inceleyebilir ve belge yazabilir.

2.2. Yazılım Mimarisinin Süregelen Önemi

Yapay zekâ mimari seçenekler önerebilir; ancak gerçek mimari kararlar yalnızca teknik bilgilerden oluşmaz.

Örneğin:

• dağıtık mı, merkezi mi?
• tutarlılık mı erişilebilirlik mi?
• düşük gecikme mi yüksek işlem hacmi mi?
• hazır ürün mü kurum içi geliştirme mi?
• genel çözüm mü özel çözüm mü?

sorularının cevapları işletme, operasyon, mevzuat, ekip yapısı ve gelecekteki kullanım biçimiyle ilgilidir.

2.3. Olumsuz Belirtim

Geleneksel gereksinim çoğunlukla sistemin yapacağı işi tarif eder:

Kullanıcı, raporu dışa aktarabilmelidir.

Yapay zekâ ile mevcut ve karmaşık kod tabanları değiştirilirken yalnızca olumlu gereksinim yeterli olmayabilir.

Şunların da tarif edilmesi gerekir:

Mevcut yetkilendirme davranışını değiştirme.

Veritabanı şemasını değiştirme.

Dinleyici tarafındaki çalışan davranışı etkileme.

Yeni bağımlılık ekleme.

Eşzamanlı çalışma semantiğini değiştirme.

Bu tür ifadeler olumsuz belirtim olarak düşünülebilir.

Niyet programlamada güçlü bir görev tanımı dört parçadan oluşabilir:

Ne yapılacak?
Ne yapılmayacak?
Neler değişmeden kalacak?
Doğruluk nasıl kanıtlanacak?

2.3.1. Tavsiye ile Zorunlu Sınır Arasındaki Fark

Bir kuralın doğal dilde yazılmış olması, onun zorunlu olarak uygulanacağı anlamına gelmez. Bu ayrım ajanlı araçlarda özellikle önemlidir.

Örneğin bir proje kılavuzuna:

Üretim veritabanında DDL çalıştırma.

yazmak güçlü bir mühendislik talimatıdır; fakat bu metin tek başına erişim denetimi değildir.

Claude Code gibi araçlarda farklı denetim katmanları farklı amaçlara hizmet eder:

CLAUDE.md / rules
→ davranışı yönlendirir

izinler (permissions)
→ hangi araç veya işlemlerin kullanılabileceğini sınırlar

kancalar (hooks)
→ belirli olaylarda deterministik denetim veya işlem çalıştırır

yalıtılmış çalışma alanı (sandbox)
→ özellikle kabuk süreçleri için işletim sistemi düzeyinde sınır uygular

Dolayısıyla “asla şu dosyaya yazma” gibi bir gereksinim yalnızca istem içinde bırakılmamalıdır; ihlalin maliyeti yüksekse uygun olduğu ölçüde teknik olarak da sınırlandırılmalıdır.

Bu, niyet programlamanın önemli bir ilkesidir:

Kritik değişmezleri yalnızca modele hatırlatma; mümkün olan yerde sistem tarafından uygulanabilir hâle getir.

2.4. Kod Tabanı Sistemin Tamamı Değildir

Bir yapay zekâ ajanı bütün kaynak kodu okuyabilir ve yine de sistemi tam olarak anlayamayabilir.

Kod tabanı ≠ sistem

Gerçek sistem daha geniştir:

Sistem =
Kod
+ Veri
+ Altyapı
+ Donanım
+ Kullanıcılar
+ Operasyon
+ Güvenlik
+ Geçmiş
+ Kurumsal kısıtlar
+ Alan bilgisi

Bu durum özellikle eski sistemlerde örtük bilgi sorununu önemli hale getirir.

2.5. Yapay Zekâ Sistemlerinin Güçlü Yönleri

Bugünkü üretken yapay zekâ sistemleri yazılım geliştirmede özellikle örüntüsü güçlü görevlerde etkilidir.

Bunlar arasında:

• tekrar eden kod üretimi,
• API istemcisi yazımı,
• veri dönüşümleri,
• temel algoritmalar,
• kod açıklama,
• belge üretme,
• biçim değiştirme,
• test taslakları,
• hata adaylarını bulma,
• eski API kullanımlarını yenileme,
• kod tabanında ilgili bölümleri bulma,
• küçük ve orta ölçekli yeniden düzenleme,
• çok dosyalı uygulama değişiklikleri

bulunabilir.

2.6. Yapay Zekâ Sistemlerinin Güvenilirlik Sınırları

Bu soruya kalıcı bir “yapamazlar listesi”yle cevap vermek doğru değildir. Model yetenekleri hızla değişmektedir.

Daha doğru yaklaşım güvenilirliği incelemektir.

Sorunlar arasında:

• eksik bağlam,
• yanlış varsayım,
• var olmayan API veya bağımlılık üretme,
• sınır durumlarını kaçırma,
• yerel olarak doğru görünen fakat sistem genelinde yanlış değişiklik,
• gereksinimi farklı yorumlama,
• sessiz davranış değişikliği

bulunabilir.

Asıl soru:

“Yapay zekâ bunu yapabilir mi?”

değil,

“Bu çıktının doğru olduğuna hangi kanıtla güvenebiliriz?”

olmalıdır.

2.7. Üretim Kolaylaştıkça Doğrulama Zorlaşır

Yapay zekâ öncesinde uygulama genellikle darboğazlardan biriydi.

Ajanlar birkaç dakika içinde yüzlerce veya binlerce satırlık değişiklik oluşturabilir.

Bu durumda yeni darboğaz oluşur:

Eski darboğaz:
uygulama

Yeni darboğaz:
doğrulama

Ajanın otuz saniyede ürettiği değişikliği bir mühendisin anlaması yarım saat sürebilir.

2.8. Test Artık Yalnızca Hata Bulma Aracı Değildir

Yapay zekâ destekli geliştirmede testlerin ek bir işlevi vardır.

Test, niyetin makine tarafından doğrulanabilir biçimidir.

Bu nedenle testler ve değerlendirme kümeleri yapay zekâ için bir çeşit yürütülebilir belirtime dönüşmektedir.

2.9. Determinizm Sorunu

Klasik programlama büyük ölçüde deterministik yapılara dayanır.

f(x) → y

Üretken model ise olasılıksal üretim yapar.

Bu ilginç bir mühendislik durumu oluşturur:

Olasılıksal geliştirme süreci
        ↓
Deterministik olması beklenen yazılım

Bu nedenle tekrar üretilebilirlik, sürüm denetimi, fark incelemesi, test ve izlenebilirlik daha önemli hale gelir.

2.10. Kritik Sistemlerde Niyet Programlama

Bir tanıtım uygulamasında yapılan yanlışlık ile kritik sistem hatası aynı risk sınıfında değildir.

Kritik sistemlerde yanlış davranış:

• veri kaybına,
• hizmet kesintisine,
• güvenlik açığına,
• hukuki sonuca,
• fiziksel zarara

neden olabilir.

Bu nedenle kritik sistemlerde:

Risk arttıkça
↓
belirtim kesinliği artmalı
↓
doğrulama artmalı
↓
gözlemlenebilirlik artmalı
↓
yetki sınırları daralmalı
↓
insan denetimi güçlenmeli

2.11. Kritik Sistemlerde Hızın Yanlış Yorumlanması

Yapay zekâ araçlarının en görünür avantajı hızdır.

Ancak yazılım mühendisliğinde geliştirme süresinin kısalması tek başına başarı değildir.

Bir özellik iki saat yerine on dakikada üretilebilir.

Fakat hata incelemesi iki saat sürüyorsa, üretimde sorun çıkarıyorsa, teknik borç oluşturuyorsa veya güvenlik açığı yaratıyorsa gerçek verim artışı tartışmalıdır.

2.12. Teknik Borcun Üretim Hızı da Arttı

Yapay zekâ iyi kodu hızlı üretebilir.

Aynı nedenle kötü kodu da hızlı üretebilir.

Bu nedenle yapay zekâyı doğrudan bir “kalite artırıcı” olarak görmek yanlıştır.

Daha doğru ifade şudur:

Yapay zekâ bir kapasite çarpanıdır.

Ünite 3: Mesleki Roller, Yetkinlik ve Üretkenlik

İnsan ile otomatik geliştirme aracının sorumluluğunu ayırmak için önce karar hakları belirlenir. İş gereksiniminin doğruluğu, mimari ödünleşim, güvenlik istisnası ve üretime alma kararı ayrı yetki gerektirir. Araç tarafından üretilen öneriler ölçülebilir kanıtla desteklenmediğinde doğrulanmış çözüm olarak kabul edilmemelidir. Değişiklik kaydında neyin istendiği, neyin değiştirildiği ve hangi testlerle güvence sağlandığı izlenebilir tutulmalıdır.

3.1. Kıdemsiz Geliştirici için Fırsat

Yapay zekâ kıdemsiz geliştiricinin üretkenliğini büyük ölçüde artırabilir.

Kıdemsiz geliştirici bilmediği bir API'yi inceleyebilir, örnek kod üretebilir, hata mesajını açıklatabilir, alternatif algoritmalar görebilir ve test senaryosu üretebilir.

Doğru kullanıldığında öğrenme hızını ciddi biçimde artırabilir.

3.2. Kıdemsiz Geliştirici için Risk

Aynı araç farklı biçimde kullanıldığında öğrenmeyi zayıflatabilir.

Bir geliştirici problemi tam anlamadan komut verir, üretilen kodu kopyalar, çalışıyorsa kabul eder ve hatada tekrar yapay zekâya dönerse çalışan ürün oluşturabilir; fakat mühendislik yetkinliği aynı hızda gelişmeyebilir.

Bu nedenle önemli sorulardan biri şudur:

Yapay zekâ, uzmanlaşmak için daha önce yapmak zorunda olduğumuz uygulama işlerini ortadan kaldırırsa yeni uzmanlar nasıl yetişecektir?

3.3. Yetkinlik Yanılsaması

Yapay zekâ ile kıdemsiz bir geliştirici birkaç dakika içinde profesyonel görünen mimari belge, test, uygulama kodu, API veya SQL üretebilir.

Ortaya çıkan ürün kişinin gerçek bilgi düzeyinden çok daha ileri görünebilir.

Kıdemli düzeyde görünen çıktı
≠
kıdemli düzeyde muhakeme

3.4. Kıdemli Geliştiricinin Değişen Rolü

Yapay zekâ uygulama maliyetini azalttıkça kıdemli geliştiricinin muhakeme gücü daha değerli hale gelebilir.

Deneyimli mühendis hangi çözümün uygulanmaması gerektiğini, hangi mimari sınırın korunacağını, hangi optimizasyonun gereksiz olduğunu ve hangi hatanın üretimde ağır sonuç doğuracağını çoğu zaman deneyimle bilir.

3.5. Kıdemli Geliştirici için Beceri Körelmesi

Risk yalnızca kıdemsiz geliştiriciye ait değildir.

Kıdemli geliştirici de yıllarca belirli işleri tamamen yapay zekâya devrederse düşük seviyeli hata ayıklama, SQL sorgu analizi, bellek davranışı veya karmaşık eşzamanlılık sorunları gibi alanlarda refleks kaybedebilir.

Sağlıklı yaklaşım, yapay zekânın mühendisin yerine düşünmesi değil, mühendisle birlikte daha yüksek soyutlama düzeyinde çalışmasıdır.

3.6. Programcı Kavramı ve Mesleki Kapsamı

Programcı algoritmayı kodlar, veri yapılarını kullanır, programlama dilini bilir ve hataları düzeltir.

Yapay zekânın en doğrudan etkilediği rol de budur; çünkü sözdizimsel üretim ve tekrar eden uygulama işleri otomasyona en uygun yazılım görevleri arasındadır.

3.7. Yazılım Geliştirici Kavramı ve Mesleki Kapsamı

Yazılım geliştirici yalnızca kod yazmaz.

Bir özelliğin gereksinimini, uygulamasını, entegrasyonunu, testini ve bakımını birlikte ele alır.

3.8. Yazılım Mühendisliği Mesleğinin Tanımı

Yazılım mühendisliği, çalışan kod üretmekten daha geniştir.

Bir sistemin güvenilir, sürdürülebilir, ölçeklenebilir, güvenli, ölçülebilir ve değiştirilebilir olmasını hedefler.

3.9. Bilgisayar Mühendisi

Bilgisayar mühendisliği yazılımın donanımdan bağımsız olmadığını hatırlatır.

Gerçek sistemler işlemci, bellek, önbellek, depolama, ağ, giriş/çıkış ve hızlandırıcılar üzerinde çalışır.

Bu nedenle yüksek trafikli ve gerçek zamanlı sistemlerde “çalışan kod” ile “uygun mühendislik çözümü” arasındaki fark büyüktür.

3.10. Bilgisayar Bilimcisi

Bilgisayar biliminin yapay zekâ çağında değerini kaybettiği düşüncesi yanlıştır.

Hesaplanabilirlik, karmaşıklık, algoritma analizi, grafik kuramı, kriptografi, bilgi kuramı ve dağıtık algoritmalar temel olmaya devam eder.

Yapay zekâ birkaç saniyede O(n²) bir çözüm üretebilir. Milyonlarca kayıt altında neden çöktüğünü anlamak bilgisayar bilimi bilgisidir.

3.11. Yazılım Bilmek ile Kod Yazmak Farklılaşmaktadır

Bir kişi çok az kod yazarak büyük uygulamalar üretebilir.

Ancak bu durum şu soruyu doğurur:

Yazılımı anlamadan yazılım üretilebilir mi?

Belirli düzeyde evet.

Ancak karmaşık sistemlerde yapay zekânın ürettiği çözümün yanlış olduğunu anlamak için çoğu zaman aynı alan hakkında yeterli bilgi gerekir.

Yapay zekânın yaptığı işi kontrol edebilmek için yaptığı işi belirli ölçüde sizin de anlamanız gerekir.

3.12. Kod Satırı Artık Üretkenlik Ölçüsü Değildir

Bir ajan birkaç dakikada on bin satır kod üretebilir.

Bu on bin satır büyük değer yaratabilir, gereksiz olabilir veya teknik borç olabilir.

Bu nedenle üretkenlik, üretilen kod miktarıyla değil; çözülmüş problem, hata oranı, üretim kesintisi, değişiklik başarısızlık oranı, bakım maliyeti, performans ve güvenlik gibi ölçülerle değerlendirilmelidir.

Ünite 4: Performans, Eşzamanlılık, Güvenlik ve Güven

4.1. Performans Mühendisliği

Yapay zekâ performans konusunda yararlı öneriler üretebilir.

Fakat “hızlandır” isteği tehlikelidir.

Gecikme ↔ işlem hacmi
Bellek ↔ CPU
Tutarlılık ↔ erişilebilirlik
Ön hesaplama ↔ bellek
Paralellik ↔ eşzamanlılık maliyeti

Performans niyetinin ölçülebilir olması gerekir.

4.2. Eşzamanlılık

Eşzamanlılık yapay zekâ ile üretilmiş kodda özellikle dikkat gerektiren alanlardan biridir.

Kod derlenebilir, testleri geçebilir, tek kullanıcıyla çalışabilir ve yine de üretimde yarış durumu oluşturabilir.

Bu nedenle kritik eşzamanlılık davranışlarında yalnızca çıktı incelemek yetmez. Korunacak değişmezler açıkça tanımlanmalıdır.

4.3. Dağıtık Sistemler

Dağıtık sistemlerde niyet programlama daha da zorlaşır.

Ağ bölünmesi, gecikmeli mesaj, yeniden deneme, yinelenen istek, sıralama, saat farkı ve kısmi başarısızlık gibi sorunlar sistem genelinde oluşur.

Bir yapay zekâ “yeniden deneme ekle” isteğini yerine getirebilir. Fakat yanlış yeniden deneme politikası aynı işlemin iki kez yapılmasına neden olabilir.

4.4. Siber Güvenlik

Yapay zekâ güvenlik çalışmalarında güçlü bir yardımcıdır.

Kod tarayabilir, zayıf örüntüler bulabilir, kayıtları ilişkilendirebilir ve saldırı senaryoları üretebilir.

Ancak güvenlik karşıt davranışlı bir alandır.

Bu nedenle sistem kötü niyetli girdiler altında da değerlendirilmeli, en az yetki, saldırı yüzeyi ve güven sınırları açık biçimde tasarlanmalıdır.

4.5. Adli Bilişim

Adli bilişimde yapay zekâ büyük veri kümelerinin incelenmesini kolaylaştırabilir.

Ancak adli süreçte yalnızca teknik doğruluk değil; delil bütünlüğü, izlenebilirlik, tekrar üretilebilirlik ve delil zinciri de önemlidir.

Bir modelin verdiği sonucun ikna edici görünmesi, sonucun adli olarak güvenilir olduğu anlamına gelmez.

4.6. Güven Problemi

Bir cevabın akıcı, ayrıntılı veya teknik olması doğruluğunu kanıtlamaz.

Dilsel güven ≠ epistemik güven

Yazılım mühendisliğinde bunun karşılığı:

Derlenen kod ≠ doğru kod

ve

Test geçen kod ≠ bütün koşullarda doğru sistem

şeklinde düşünülebilir.

4.6.1. Güven Zinciri Modelden Daha Geniştir

Ajanlı geliştirmede güven, “model doğru söylüyor mu?” sorusuyla sınırlı değildir. Araç çıktısının doğru kaynaktan gelip gelmediği, ajanın doğru dosyayı okuyup okumadığı, yetkisinin gereğinden geniş olup olmadığı ve dış içeriğin talimat gibi yorumlanıp yorumlanmadığı da önemlidir.

Bir yazılım ajanı için güven zinciri şu bileşenleri içerebilir:

kullanıcı niyeti
→ proje talimatları
→ izin sınırları
→ araç çağrısı
→ araç çıktısı
→ model yorumu
→ değişiklik
→ doğrulama kanıtı

Bu zincirin herhangi bir halkası zayıfsa akıcı bir son cevap yanlış güven yaratabilir.

Özellikle dış kaynaklardan gelen metinler, web sayfaları, issue içerikleri, loglar veya araç sonuçları güvenilmeyen veri olarak ele alınmalıdır. Bunların içinde yer alan bir cümle, proje sahibinin talimatıyla aynı yetkiye sahip değildir. Bu ayrım prompt injection riskinin yazılım geliştirme ajanlarındaki karşılığıdır.

Güvenilirlik için iki farklı mekanizma birlikte gerekir:

• karar kalitesini artıran bağlam,
• yanlış kararın etki alanını sınırlayan teknik sınırlar.

İlkini iyi belgeler ve açık görev tanımları sağlar. İkincisini ise en az yetki, izin kuralları, yalıtılmış çalışma alanı (sandbox), sürüm kontrolü, salt okunur erişim, ayrılmış kimlik bilgileri ve deterministik denetimler güçlendirir.

4.7. Sorumluluk

Yapay zekâ kod üretebilir.

Ajan kodu değiştirebilir.

Sistem otomatik olarak dağıtılabilir.

Ancak üretimde zarar oluştuğunda:

“Model böyle üretti.”

mühendislik gerekçesi değildir.

4.8. Yapay Zekâ ve Eski Sistemler

Yapay zekânın en değerli kullanım alanlarından biri eski ve karmaşık kod tabanları olabilir.

Ajan ilgili dosyaları bulabilir, çağrı zincirlerini açıklayabilir, eski API'leri gösterebilir ve değişiklik noktalarını önerebilir.

Fakat eski sistemlerde örtük bilgi daha fazladır.

4.8.1. Eski Sistemlerde Claude Code Türü Ajanların Doğru Kullanım Biçimi

Eski bir kod tabanında ilk görev çoğu zaman kod yazmak değil, sistem hakkında güvenilir bir harita çıkarmaktır. Dosya yaşı veya sınıf adı tek başına davranışın gerçek sahibini göstermeyebilir. Kullanılmıyor görünen bir yordam dış entegrasyon tarafından çağrılıyor olabilir; yinelenen kayıtlar veri kirliliği değil tarihsel sözleşmenin sonucu olabilir; beklenmedik bir hata geri dönüşü istemci tarafında yıllardır bağımlılık hâline gelmiş olabilir.

Bu nedenle eski sistemlerde güvenli ajan kullanımı genellikle şu sırayı izler:

önce keşfet
→ çağrı ve veri akışını doğrula
→ korunacak davranışları yaz
→ değişiklik alanını küçült
→ en küçük değişikliği yap
→ gerçek doğrulama yolunu çalıştır
→ diff ve etki alanını tekrar incele

Claude Code'un arama, dosya okuma, git durumu ve komut çalıştırma yetenekleri bu keşfi hızlandırabilir. Ancak hız, örtük sözleşmeleri ortadan kaldırmaz. Ajanın bir kod örüntüsünü “modernleştirme” gerekçesiyle değiştirmesi, normalleştirilmemiş veya uzun yıllardır kullanılan bir sistemde regresyon oluşturabilir.

Bu nedenle eski projelerde proje bağlamına yalnızca “hangi teknolojiler kullanılıyor?” değil, aşağıdaki türden bilgiler de girer:

• değiştirilemeyen veri modeli,
• bilinen yinelenen veri davranışları,
• özellikle korunması gereken hata semantiği,
• dış sistemlerle görünmeyen sözleşmeler,
• güvenilir olduğu kanıtlanmış eski yordamlar,
• test ortamında bulunmayan üretim bağımlılıkları,
• değişiklik yapılmaması gereken modüller.

Bu bilgiler kaynak koddan kolayca çıkarılamıyorsa, kalıcı proje bağlamında veya göreve özgü belgede açıkça tutulmaları ajan için yüksek değer taşır.

Ünite 5: Bağlam Mühendisliği ve Ajan Altyapısı

5.1. Bağlam Mühendisliği

Yapay zekâ ile yazılım geliştirmenin en önemli becerilerinden biri bağlamı yönetmektir.

5.1.1. Sürekli Bağlam

Her görevde geçerli kurallar:

• mimari ilkeler,
• kodlama standartları,
• güvenlik sınırları,
• genel kısıtlar.

5.1.2. İsteğe Bağlı Bağlam

Yalnızca ilgili görevde gereken:

• belirli modül belgeleri,
• veri modeli,
• geçmiş hata kayıtları,
• ilgili kaynak kod.

5.1.3. Claude Code'da Bağlam Yüzeyleri

Claude Code, bağlam mühendisliğini yalnızca sohbet geçmişi üzerinden yürütmez. Güncel yapıda proje bilgisi farklı yaşam sürelerine ve maliyetlere sahip birden fazla yüzeye dağıtılabilir.

En temel ayrım şöyledir:

CLAUDE.md
→ insan tarafından yazılan kalıcı proje talimatları

.claude/rules/
→ belirli dosya yollarına veya konulara bağlanabilen kurallar

auto memory
→ Claude'un oturumlar arasında yeniden kullanmak üzere çıkardığı yerel notlar

beceriler (skills)
→ belirli görev türlerinde yüklenen yeniden kullanılabilir yordam ve bilgi paketleri

alt ajanlar (subagents)
→ ayrı bağlam penceresinde çalışan uzmanlaştırılmış ajanlar

MCP
→ harici araç ve veri kaynaklarına yapılandırılmış erişim

tool outputs
→ çalışma sırasında edinilen geçici kanıt

conversation
→ o görevde biriken karar ve ara durum

Bu yüzeylerin hepsine aynı bilgiyi kopyalamak doğru değildir. Her bilginin en uygun yaşam süresi ve kapsamı vardır.

CLAUDE.md, her görevde bilinmesi gereken proje davranışları için uygundur. Derleme komutu, alışılmadık mimari sınır, değiştirilemeyen sözleşme veya ekip standardı bu gruba girebilir. Buna karşılık yalnız veritabanı göçlerinde gereken ayrıntılı yordamın sürekli bağlama yüklenmesi gereksizdir; böyle bir süreç bir beceri (skill) veya göreve özgü belge olarak tutulabilir.

Güncel Claude Code sürümlerinde otomatik bellek de ayrı bir katmandır. Bu mekanizma modelin önceki çalışmalardan derleme komutları, hata ayıklama bulguları veya proje örüntüleri gibi notlar çıkarmasına izin verir. Ancak otomatik belleğin varlığı doğruluk garantisi değildir. Kod değiştiğinde eski not geçerliliğini yitirebilir. Bu nedenle bellek, kaynak kodun yerine geçen otorite değil, sonraki keşfi hızlandıran bir indeks olarak görülmelidir.

5.1.4. Bağlam Penceresi bir Çalışma Alanıdır

Bağlama giren her şey aynı bütçeyi kullanır:

sistem talimatları
+ proje kuralları
+ konuşma
+ dosya içerikleri
+ araç çıktıları
+ yüklenen beceriler (skills)
+ MCP araç tanımları
+ ara sonuçlar

Bağlam büyüdükçe yalnız maliyet artmaz; ilgili bilginin bulunması da zorlaşabilir. Bu nedenle “model büyük bağlam destekliyor” ifadesi, bütün kod deposunu sürekli yüklemek için gerekçe değildir.

Claude Code'un güncel yaklaşımında bu maliyet farklı mekanizmalarla azaltılır. Alt dizinlerdeki bazı proje talimatları gerektiğinde yüklenebilir; beceri (skill) gövdesi yalnız kullanıldığında bağlama girer; MCP araç tanımları araç aramasıyla ertelenebilir; alt ajan (subagent) ayrı bir bağlam penceresinde çalışabilir; uzun oturumlarda compaction eski konuşmayı özetleyebilir.

Bunların ortak ilkesi aynıdır:

Sürekli bağlamda yalnız sürekli gerekli olan bilgi bulunsun; geri kalan bilgi ihtiyaç anında getirilsin.

5.1.5. Kalıcı Bağlam ile Çalışma Kanıtını Ayırmak

Bir test çıktısı, geçici stack trace veya tek görevde kullanılan büyük log dosyası kalıcı proje talimatı değildir. Buna karşılık “bu modülde entegrasyon testi şu komutla çalışır” bilgisi birçok görevde tekrar kullanılıyorsa kalıcı bağlam olabilir.

Bu ayrım yapılmadığında iki sorun oluşur:

1. kalıcı talimat dosyaları geçici ayrıntılarla şişer,
2. geçmişte doğru olan gözlemler gelecekte sorgulanmadan yeniden kullanılır.

Bağlam mühendisliği bu nedenle yalnız bilgi ekleme işi değildir. Aynı zamanda kapsam, yaşam süresi, kaynak izi ve güncellik yönetimidir.

5.2. Yazılım Üreten Sistemi Tasarlamak

Yapay zekâ destekli geliştirmede mühendisin çıktısı giderek yalnızca kaynak kod olmayabilir.

Belirtimler
+
Bağlam
+
Ajanlar
+
Araçlar
+
Testler
+
Kalite kapıları
+
Geri bildirim

Bu sistem daha sonra kod üretir.

5.2.1. Claude Code'un Yapılandırılabilir Yürütme Katmanı

Claude Code örneğinde yazılım üreten sistem, yalnız model ile CLAUDE.md dosyasından oluşmaz. Proje düzeyindeki .claude yapısı farklı sorumlulukları ayırmaya izin verir.

CLAUDE.md / rules
→ neyin bilinmesi gerektiği

beceriler (skills)
→ belirli bir işin nasıl yürütüleceği

alt ajanlar (subagents)
→ işin hangi uzman bağlamında yapılacağı

izinler (permissions)
→ hangi araçların kullanılabileceği

kancalar (hooks)
→ belirli olaylarda hangi deterministik denetimin çalışacağı

MCP
→ hangi dış sistemlere yapılandırılmış erişim sağlanacağı

testler / statik denetimler / derleme
→ üretilen değişikliğin hangi kanıtlarla sınanacağı

Bu ayrım yazılım mimarisindeki sorumluluk ayrımına benzer. Her mekanizmayı aynı probleme uygulamak, bağlamı büyütür ve bakım maliyetini artırır.

Örneğin “her Java dosyası değiştiğinde biçim denetimini çalıştır” kuralı doğal dil talimatı olmaktan çok bir hook adayıdır. “Bu projede domain katmanı infrastructure katmanına bağımlı olamaz” ifadesi proje kuralıdır. “Bir veri tabanı sorgusunu inceleme adımları” tekrar eden bir beceri (skill) olabilir. “Issue sisteminden kayıt getir” ise MCP veya uygun bir CLI aracıyla çözülebilir.

Buradaki temel tasarım ilkesi şöyledir:

Muhakeme gerektiren işi modele, tekrarlanabilir ve zorunlu işi deterministik mekanizmaya ver.

Bir linter sonucunun yorumlanması model işi olabilir; linter'ın her değişiklikten sonra gerçekten çalıştırılması kanca veya CI işi olmalıdır.

5.2.2. Araç Sözleşmesi de Yazılım Tasarımıdır

Bir ajan için araç adı, parametre şeması ve dönen veri biçimi yalnız entegrasyon ayrıntısı değildir. Bunlar model ile deterministik sistem arasındaki API'dir.

Belirsiz, birbirine çok benzeyen veya gereğinden geniş araçlar yanlış araç seçimini artırabilir. Büyük ve gürültülü araç çıktıları bağlamı tüketebilir. Bu nedenle araç tasarımında da klasik API ilkeleri geçerlidir:

• görev sınırı açık olmalı,
• parametreler tek anlamlı olmalı,
• hata durumu ayırt edilebilir olmalı,
• çıktı yalnız gerekli veriyi taşımalı,
• yüksek etkili işlemler daha dar yetkiyle ayrılmalı.

Bu bakış MCP sunucuları için de geçerlidir. MCP, modele doğrudan yetki vermek yerine harici sistemleri açık araç sözleşmeleriyle sunar. Ancak protokol kullanmak kendiliğinden güvenlik sağlamaz; sunucu tarafındaki kimlik doğrulama, yetkilendirme, girdi denetimi ve günlükleme yine gerçek sistemin sorumluluğudur.

5.3. İnsan ve Ajanlardan Oluşan Ekipler

Yapay zekâ ajanları belirli görevleri üstlenen yarı özerk yazılım bileşenleri olarak kullanıldığında ekip yapısı değişebilir.

İnsan
  ↓
Mimari karar ve görev tanımı

Ajan
  ↓
Uygulama

Test sistemi
  ↓
Doğrulama

Ajan
  ↓
Düzeltme

İnsan
  ↓
Son inceleme

5.3.1. Alt Ajanlar: Paralellikten Önce Bağlam Yalıtımı

Claude Code'daki alt ajan (subagent) mekanizmasının önemli değeri yalnız aynı anda daha fazla iş yapmak değildir. Her alt ajan kendi bağlam penceresinde, kendi araç sınırları ve rol talimatlarıyla çalışabilir. Böylece geniş keşif çıktıları ana konuşmayı doldurmadan bir uzman göreve ayrılabilir.

Örneğin büyük bir değişiklikte şu ayrım yapılabilir:

ana ajan
→ niyet, kapsam ve sentez

keşif alt ajanı
→ ilgili dosya ve çağrı zincirlerini bul

güvenlik alt ajanı
→ yetki ve veri sınırlarını incele

test alt ajanı
→ etkilenen doğrulama yüzeyini çıkar

Alt ajanların dönüş değeri ham çalışma günlüğü değil, ana karar için gerekli kanıt olmalıdır. Aksi durumda bağlam yalıtımının kazancı, büyük özetlerin ana pencereye geri taşınmasıyla kaybolur.

Paralellik de dikkat gerektirir. Aynı dosyayı değiştiren iki ajanın paralel çalışması birleştirme çatışması ve karar tutarsızlığı üretebilir. Buna karşılık bağımsız okuma, araştırma veya ayrı modüllerde doğrulama işleri paralelleşmeye daha uygundur.

Bu nedenle insan-ajan ekibinde görev dağıtımının ölçütü “hangi işi ajan yapabilir?” değil, şu üç sorudur:

1. Görev hangi bağlama ihtiyaç duyuyor?
2. Hangi araç ve yetkiler gerçekten gerekli?
3. Sonuç hangi kanıt biçiminde ana sürece dönmeli?

Ajan sayısını artırmak tek başına kapasite artışı değildir. Koordinasyon maliyeti, paylaşılan durum ve doğrulama ihtiyacı da artar.

Ünite 6: Mesleğin Geleceği, Sorumluluk ve Sistem Düşüncesi

6.1. Geleceğin Temel Becerisi Sistem Düşüncesidir

Belirli bir dili bilmek önemini kaybetmez.

Ancak tek başına yeterli farklılaştırıcı olmayabilir.

Gelecekte güçlü mühendis şu zinciri birlikte değerlendirebilen kişi olacaktır:

Gereksinim
↓
Alan modeli
↓
Mimari
↓
Veri
↓
Eşzamanlılık
↓
Güvenlik
↓
Performans
↓
Hata durumları
↓
Operasyon
↓
Gözlemlenebilirlik

6.2. Yazılım Mesleklerinin Geleceği

Kesin bir sayı veya tarih vermek mümkün değildir.

Ancak görev bileşimlerinin değişmesi oldukça olasıdır.

Göreli değeri azalabilecek işler:

• tekrar eden kod üretimi,
• standart CRUD geliştirme,
• mekanik dönüşümler,
• basit belge üretimi.

Göreli değeri artabilecek işler:

• alan bilgisi,
• mimari,
• güvenlik,
• performans,
• belirtim,
• doğrulama,
• sistem düşüncesi,
• teknik sorumluluk.

6.3. Programlama Bilgisinin Gelecekteki Gerekliliği

Basit yazılım üretiminde kod bilgisine duyulan ihtiyaç azalabilir.

Ancak karmaşıklık ve risk arttıkça bu durum değişir.

Bir sistem finansal işlem yapıyor, kişisel veri işliyor, çok yüksek trafik taşıyor, gerçek zamanlı çalışıyor veya fiziksel süreç kontrol ediyorsa üretim aracının çıktısını değerlendirecek mühendislik bilgisi gerekir.

6.4. Niyet Programlamanın Felsefi Yönü

Bir mühendis gereksinimi belirler, mimariyi tasarlar, kısıtları tarif eder; ajan on bin satır kod üretir ve mühendis yalnızca kritik değişiklikleri inceler.

Bu durumda programı kim yazmıştır?

Yapay zekâ mı?

Mühendis mi?

Yoksa insan ve yapay zekâdan oluşan sistem mi?

Yazarlık giderek:

Davranışı kim tasarladı?

sorusuna yaklaşabilir.

6.5. İnsan Düşüncesi ile Makine Üretimi Arasındaki Yeni Sınır

Eskiden çeviri yükünün büyük kısmı insandaydı.

Algoritmayı düşün
↓
Sözdizimini yaz
↓
Hataları düzelt

Yeni yaklaşımda çevirinin bir bölümü modele devredilmektedir:

İnsan:
Amaç + sınır + muhakeme

Yapay zekâ:
Uygulama + dönüşüm + tekrar

İnsan:
Doğrulama + sorumluluk

6.6. Temel Mühendislik Bilgisinin Artan Önemi

Soyutlama yükseldikçe alt katman bilgisinin günlük kullanım sıklığı azalabilir; kritik olduğunda değeri artabilir.

Bir geliştirici her gün bellek düzeniyle uğraşmayabilir. Fakat üretim ortamındaki sorun bellek baskısından kaynaklandığında bunu anlayacak kişiye ihtiyaç vardır.

Bu nedenle temel bilgi, sürekli uygulanacak mekanik beceriden çok gerektiğinde soyutlamayı delip alt katmanı anlayabilme kapasitesi haline gelebilir.

6.7. Niyet Programlamada İyi Mühendislik Modeli

Pratik bir çalışma modeli şu şekilde kurulabilir.

1. Problemi tanımla.
2. Mevcut sistemi anla.
3. Niyeti yaz.
4. Kısıtları yaz.
5. Başarı ölçütünü yaz.
6. Uygun bağlamı sağla.
7. Değişikliği üret.
8. Doğrula.
9. Üretimi gözle.
10. Bilgiyi geri besle.

Böylece yapay zekâ kullanımı tek bir “istem → kod” işlemi olmaktan çıkar ve kapalı çevrim mühendislik sistemine dönüşür.

6.7.1. Aynı Modelin Claude Code ile Uygulanması

Bu on adımlı model, bir kodlama ajanında somut yürütme sırasına çevrilebilir:

1. Niyeti ve kabul sınırını yaz.
2. Değiştirilmeyecek davranışları ayır.
3. Kod deposunda ilgili alanı keşfet.
4. Proje talimatlarını ve göreve özgü kaynakları getir.
5. Araç ve izin yüzeyini göreve göre daralt.
6. Küçük bir değişiklik üret.
7. Derleme, test, statik analiz veya çalışma zamanı kanıtını al.
8. Diff'i ve etki alanını incele.
9. Başlangıçtaki niyetle sonucu tekrar karşılaştır.
10. Yalnız kalıcı değer taşıyan yeni bilgiyi proje belleğine aktar.

Claude Code açısından burada önemli bir ayrıntı vardır: CLAUDE.md, beceri (skill) veya otomatik bellek uygulamanın kendisi değildir. Bunlar ajanın karar vermesine yardımcı olan bağlam katmanlarıdır. Doğruluk kanıtı yine kod, test, derleyici, veri sözleşmesi ve çalışma zamanı davranışından gelmelidir.

Aynı şekilde izin sistemi de görev tanımının yerine geçmez. Ajan yalnızca güvenli işlemlere erişebiliyor olsa bile yanlış dosyayı güvenli biçimde değiştirebilir. Güvenli yürütme ile doğru mühendislik aynı şey değildir.

İyi iş akışı bu iki ekseni birleştirir:

doğru niyet + yeterli bağlam + sınırlı yetki + gerçek doğrulama

6.8. Özlü bir Mühendislik Yaklaşımı

Niyet programlamada ayrıntı vermek ile gereksiz ayrıntı vermek arasındaki sınır önemlidir.

Uzun komut her zaman iyi komut değildir.

İdeal olan modele her şeyi anlatmak değil, doğru şeyi anlatmaktır.

İyi belirtim:

• kısa,
• açık,
• çelişkisiz,
• ölçülebilir,
• sınırları belirli

olmalıdır.

Niyet programlama, çok konuşmak değildir.

Belirsizliği azaltmaktır.

Ünite 7: Kod Deposu Bağlamı, Bellek ve Doğrulama Mühendisliği

7.1. Kod Deposu Bağlamı bir Mühendislik Eseridir

Büyük bir kod deposu, rastgele kaynak dosyaları sürekli olarak ajanın bağlamına yüklenerek verimli biçimde anlaşılamaz. Kod deposunun kendisi, üzerinde gezilebilir bir bilgi katmanına ihtiyaç duyar.

Bu bağlam katmanı altı farklı sorumluluğa ayrılabilir: kalıcı kurallar, mimari haritalar, iş akışı açıklamaları, veri sözleşmeleri, bilinen riskler ve göreve özgü kaynak. Bu parçaların aynı sıklıkta yüklenmesi gerekmez; görev için sürekli gerekli olan bilgiyle yalnız belirli bir durumda gereken bilgi aynı bağlam katmanında tutulmamalıdır.

Kalıcı talimatlar geniş ölçüde geçerli kuralları içermelidir. Ayrıntılı mimari, veritabanı davranışı, iş akışları, doğrulama süreçleri ve geçmişten çıkarılan dersler ise gerektiğinde erişilebilen odaklı belgelerde tutulmalıdır.

Bu yaklaşım, belgeleri edilgen metin olmaktan çıkarıp yazılım üretim sisteminin bir parçası hâline getirir. Kısa bir giriş belgesi ajana nereye bakacağını söyleyebilir; kod deposunun içerdiği her şeyi anlatmak zorunda değildir.

Bu ayrım önemlidir; çünkü bağlamın bir maliyeti vardır. Büyük talimat dosyaları görevle, ilgili kaynak kodla, araç çıktılarıyla ve modelin çalışma durumuyla aynı bağlam bütçesi için yarışır. Bu nedenle bir kod deposu kılavuzu, ansiklopediye dönüştüğünde değil, harita görevi gördüğünde daha yararlıdır.

7.1.1. Kod Deposunda Bağlamın Fiziksel Yerleşimi

Claude Code'un güncel proje yapısı, bu kuramsal ayrımı somutlaştırır. Her bilgi aynı dosyada tutulmak zorunda değildir.

Örnek bir dağılım şöyledir:

CLAUDE.md
→ kısa, sürekli ve proje genelinde geçerli talimatlar

.claude/rules/
→ yol veya konu bazlı kurallar

.claude/skills/
→ gerektiğinde yüklenen iş akışları ve alan bilgisi

.claude/agents/
→ uzman alt ajan tanımları

.claude/settings.json
→ izinler, kancalar (hooks) ve proje düzeyi davranış ayarları

.mcp.json
→ paylaşılabilir MCP sunucu tanımları

docs/
→ insan ve ajan için ayrıntılı mimari/sözleşme belgeleri

Bu yapıdan çıkarılacak genel ders, belirli dosya adlarını kullanmak değildir. Asıl ders bilginin yüklenme sıklığına ve yaptırım gereksinimine göre ayrılmasıdır.

Bir kural her turda bilinmek zorundaysa sürekli bağlamda yer alabilir. Yalnız belirli görevde gerekiyorsa isteğe bağlı bilgi olmalıdır. İhlali teknik olarak engellenmesi gereken bir sınırsa yalnız belge olarak kalmamalıdır.

Ayrıca bağlam dosyalarının kaynak kodu açıklayan ikinci bir kod deposuna dönüşmemesi gerekir. Dosya listelerini ve sınıf açıklamalarını elle çoğaltmak hızla eskir. Bunun yerine yapılandırılmış harita, arama, sembol çözümleme ve hedefli okuma ile kaynak kodun kendisine dönülebilmelidir.

7.2. Bağlamın Aşamalı Sunulması

Bir ajana görevin başında tüm kod deposunu vermek kapsamlı görünebilir; ancak eksiksizlik ile ilgililik aynı özellik değildir.

Daha ekonomik akış, görevden kod deposu haritasına; oradan ilgili alt sistem ile iş akışı veya sözleşmeye; son olarak hedefli kaynak okuması ve uygulamaya ilerler.

Bu, aşamalı bağlam sunumu yaklaşımıdır: bağlam, kanıtlar gerekli kıldıkça devreye alınır.

Bir veritabanı yazma değişikliği önce veritabanı sözleşmesini ve veri akışını gerektirebilir. Etkilenen servis belirlendikten sonra ilgili varlık ve kalıcılık kodunun okunması gerekebilir. Bir kullanıcı arayüzü değişikliği ise iş akışı açıklamasıyla ilgili sayfa uygulamasını gerektirebilir; veritabanı belgesine ihtiyaç duymayabilir.

Amaç ne pahasına olursa olsun token azaltmak değildir. Kritik bir değişmezi token tasarrufu uğruna çıkarmak sahte ekonomidir. Amaç token başına yararlı bilgi miktarını en üst düzeye çıkarmaktır.

Kısa fakat eksik bağlam hızlı ve yanlış sonuç üretebilir. Aşırı büyük bağlam ise önemli kısıtı ilgisiz ayrıntıların arasına gömebilir. Etkili bağlam bu iki uç arasındadır.

7.2.1. Becerilerle (Skills) Aşamalı Yükleme

Claude Code'daki beceriler (skills) mekanizması aşamalı bağlam sunumuna doğrudan bir örnektir. Beceri tanımı, görevin ne zaman ilgili olduğunu söyleyen kısa bir açıklamayla keşfedilebilir; ayrıntılı SKILL.md içeriği ise beceri gerçekten kullanıldığında bağlama girer. Büyük başvuru dosyaları, örnekler veya yardımcı betikler beceri dizininde ayrı tutulabilir.

Bu tasarım iki zıt maliyeti aynı anda azaltır. Her şeyi CLAUDE.md içine koymak sürekli bağlam şişmesine yol açarken, her ayrıntıyı her görevde yeniden keşfetmek yinelenen arama ve token maliyeti üretir.

İyi bir beceri (skill), genel teknoloji eğitimi vermekten çok proje veya görev için tekrar eden karar yolunu kodlar. Örneğin “veritabanı göçü nasıl yapılır?” yerine “bu projede güvenli göç için hangi dosya, doğrulama komutu ve geri dönüş kuralı izlenir?” sorusuna cevap vermesi daha değerlidir.

Aşamalı yükleme yalnız belge için değil araçlar için de geçerlidir. Çok sayıda MCP aracı bulunan ortamlarda tüm ayrıntılı araç şemalarını her turda taşımak yerine araç araması ve gerektiğinde yükleme kullanılabilir. Böylece bağlam yüzeyi, mevcut görevin gerçek ihtiyaçlarına yaklaşır.

7.3. Kod Deposu Haritaları ve Bilgi Grafikleri

Dosya adları ve dizin ağaçları yararlı yapı sağlar; ancak olgun sistemlerde ilişkiler çoğu zaman bu sınırları aşar.

Bir servis bir varlığa bağımlı olabilir, bir iş akışı birden fazla denetleyiciye dayanabilir ve bir güvenlik kuralı onu uygulayan koddan çok uzakta belgelenmiş olabilir. Kod deposu bilgi grafiği bu ilişkileri açık biçimde gösterebilir.

Denetleyici
    ↓ çağırır
Servis
    ↓ kullanır
Depo
    ↓ eşler
Varlık

Graf odaklı kod deposu araçları kodu; mimari notlar, iş akışı belgeleri, belirtimler ve diğer eserlerle de ilişkilendirebilir.

Bunun bir örneği Graphify'dır. Graphify proje grafiği oluşturabilir ve query, path ile explain gibi işlemler sunabilir. Sağlanan belgelerde kod için yerel sözdizim ağacı çıkarımı açıklanır ve doğrudan çıkarılan ilişkiler ile çıkarımsal ilişkiler birbirinden ayrılır. Belirli bir üründen daha önemli olan mühendislik ilkesi şudur: önce yapıyı sorgula, sonra doğrulamak için gereken en küçük kaynak kümesini oku.

graf sorgusu
   ↓
aday düğümler ve ilişkiler
   ↓
yol/açıklama
   ↓
hedefli kaynak okuması
   ↓
kaynak düzeyinde doğrulama

Graf kaynak kodun yerine geçmez. Gezinme ve bağlam seçimi katmanıdır. Çıkarımsal bir ilişki, nerede inceleme yapılacağına ilişkin kanıttır; çalışma zamanı davranışının kanıtlandığı anlamına gelmez.

7.4. Haritaların, İş Akışlarının, Sözleşmelerin ve Derslerin Görevleri Farklıdır

Kod deposu belgeleri, her belge türü dar bir sorumluluk taşıdığında daha yararlı olur.

• Ajan talimatları: Her zaman hangi kurallara uyulmalı?
• Kod haritası: Bir yetenek nerede uygulanıyor?
• Veri akışı: Bilgi sistem içinde nasıl hareket ediyor?
• İş akışı: Hangi davranış sırası bozulmadan korunmalı?
• Veritabanı sözleşmesi: Hangi kalıcılık varsayımları değişmezdir?
• Çalışma zamanı güvenliği: Her ortamda neler güvenle çalıştırılabilir?
• Bilinen riskler: Görünüşte yerel bir değişiklik nerede zarar doğurabilir?
• Dersler: Daha önce ne başarısız oldu ve ne öğrenildi?
• Tamamlama doğrulaması: Görevin bittiğini ne kanıtlar?

Bunların tümünü tek büyük belgede birleştirmek seçiciliği azaltır. Ayrıştırmak ise ajanın yalnızca mevcut değişiklikle ilgili içeriği getirmesini sağlar.

Belgeler yetkili kaynağı gereksiz yere kopyalamak yerine ona işaret etmelidir. Kopyalanan bilgiler zamanla ayrışır. Bir kuralın uygulandığı yeri gösteren harita, aynı uygulamayı birden fazla belgede tekrar etmekten çoğu zaman daha güvenlidir.

7.5. Bağlamın Güncelliği Doğruluğun bir Parçasıdır

Dünün kodunu anlatan bir kod deposu haritası, hiç harita olmamasından daha tehlikeli olabilir; çünkü yanlış güven oluşturur.

Bu nedenle üretilen haritalar, grafikler ve belgeler bir güncellik stratejisine ihtiyaç duyar. Kod değişikliği önce doğrulanmalı; sözleşme değişmişse ilgili belge güncellenmeli; ardından graf veya indeks yenilenmelidir. Sonraki görev ancak bu zincir korunursa güncel bağlamla başlayabilir.

Değişen içeriği güvenilir biçimde belirleyebildiği durumlarda artımlı güncelleme tercih edilir. Her küçük değişiklikten sonra her eseri yeniden oluşturmak zaman ve token israfına yol açabilir; hiç güncellememek ise sapma oluşturur.

Otomasyon yardımcı olabilir. Kod deposu hook'ları commit veya dal değişikliklerinden sonra yapısal indeksleri yenileyebilir; açık güncellemeler merge veya pull işlemlerini izleyebilir. Tam mekanizmadan daha önemli olan değişmez şudur:

Gezinme katmanı, anlattığı kaynaktan sessizce kopmamalıdır.

Üretilen bağlam, uygun olduğunda özyinelemeli veya önbelleğe duyarlı indeksleme yollarının dışında tutulmalıdır. Aksi hâlde otomatik yeniden yazılan bir graf veya rapor kendi başına gereksiz geçersizleştirmeyi ya da yinelenen indekslemeyi tetikleyebilir.

7.6. Token Verimliliği İstemi Kısaltmak Değildir

Kısa bir istem, ajan kod deposunu baştan keşfetmek zorunda kalıyorsa yine çok yüksek token tüketimine yol açabilir.

Buna karşılık, doğru alt sistemi, değişmezleri, doğrulama yolunu ve yasak değişiklikleri gösteren biraz daha uzun bir görev belirtimi toplam maliyeti düşürebilir.

Toplam bağlam maliyeti ≈
Görev belirtimi
+
Kod deposu keşfi
+
Kaynak okumaları
+
Araç çıktısı
+
Yeniden denemeler
+
Düzeltmeler
+
Doğrulama

Yalnızca ilk terimi eniyilemek yanıltıcıdır.

Kod deposu keşfi özellikle önemlidir. Kodlama ajanları üzerine güncel araştırmalar, kod deposu keşfini uygulamadan ayırmanın çözücü token tüketimini azaltabildiğini bildirirken; başka çalışmalar kod deposu talimatlarını ayrım gözetmeden eklemenin görev başarısını artırmadan çıkarım maliyetini yükseltebildiğini göstermektedir.

Buradan tek bir erişim tekniğinin her durumda en iyi olduğu sonucu çıkmaz. Statik haritalar, sözcüksel arama, yapısal analiz, anlamsal erişim, graf dolaşımı ve ajan güdümlü gezinme farklı güçlü yönlere sahiptir.

Kanıtı göreve göre getir; yalnızca var olduğu için bağlamı önceden yükleme.

7.6.1. Araç Çıktısı ve Şema Maliyeti

Token maliyetinin önemli bölümü kullanıcı isteminden değil araç sonuçlarından gelebilir. Büyük bir test günlüğü, bütün veritabanı şeması, binlerce satırlık git diff veya geniş MCP cevabı tek çağrıda bağlamı doldurabilir.

Bu nedenle araç arayüzlerinde klasik veri erişim ilkeleri yararlıdır:

• filtreleme,
• sayfalama,
• aralık seçimi,
• özet alanları,
• gerektiğinde ayrıntıya inme,
• makul çıktı sınırları.

Bir ajan için “çok veri” ile “çok kanıt” aynı şey değildir. Doğru satır aralığı veya hedefli sorgu, yüzlerce kilobaytlık ham çıktıdan daha değerlidir.

MCP tarafında araç adı ve şeması da sürekli bağlam maliyeti oluşturabilir. Araç kataloğu büyüdükçe açıklamalar kısa ama ayırt edici olmalı; birbirine benzeyen araçlar azaltılmalı; geniş bir genel amaçlı araç yerine risk ve sorumluluğa göre daha dar araçlar tercih edilmelidir.

Dolayısıyla token verimliliği şu biçimde ele alınabilir:

yararlı kanıt / toplam bağlam maliyeti

Amaç yalnız paydadaki token sayısını küçültmek değil, bağlama giren her parçanın karar değerini yükseltmektir.

7.7. En Küçük Kalıcı Talimat Kümesi

Kalıcı kod deposu talimatları, değişmezleri görevler arasında koruyabildiği için değerlidir.

Ancak her yerel tercih, tarihsel ayrıntı ve geçici çözüm sürekli yüklenen kurala dönüştürüldüğünde zararlı hâle gelebilir.

Kalıcı bir talimat genellikle şu koşullardan en az birini sağlıyorsa yerini hak eder:

• ihlali ciddi kusura yol açabilir,
• birçok görev için geçerlidir,
• kaynak koddan güvenilir biçimde çıkarılamaz,
• başvurulması zorunlu yetkili bir belgeyi gösterir,
• zorunlu doğrulama veya güvenlik sınırı tanımlar.

Göreve özgü ayrıntılar görevin yakınında kalmalıdır. Kalıcı çekirdek yalnız yönlendirme ve değişmezleri taşır; görevle ilgili belgeler graf veya arama yoluyla bulunur, hedefli kaynak okunur ve son karar çalışma zamanı ya da derleme kanıtıyla doğrulanır.

Kod deposu düzeyindeki ajan bağlamı üzerine 2026'da yayımlanan araştırmalar da ölçülü olma gereğini desteklemektedir: gereksiz gereksinimler içeren kod deposu talimat dosyaları keşif ve çıkarım maliyetini artırabilir. Kalıcı bağlam bu nedenle ekibin bildiği her şeyin döküldüğü alan değil, kıt bir mühendislik kaynağı olarak görülmelidir.

7.7.1. Kalıcı Kurallarda Çelişki ve Otorite Denetimi

Bir depo talimatını kısaltmadan önce kuralların hangi işi yönettiği belirlenmelidir. Her kural için kapsam (tüm depo veya belirli alt sistem), kaynak (kalıcı yönerge, görev talebi, araç kısıtı), ihlalin etkisi ve uygulanabilir doğrulama ayrıştırılır. Aynı dosya üzerinde biri bütün testlerin, diğeri yalnız değişen modül testlerinin çalıştırılmasını zorunlu kılıyorsa bu bir metin uzunluğu değil, kapsam ve öncelik çakışmasıdır. Sadece sözcük silmek çelişkiyi çözmez; yetkili kural ve istisna sınırı açıkça belirlenmelidir.

Güvenlik denetimi, veri değişmezleri ve erişim kısıtları mümkünse yürütme zamanında uygulanabilir denetimlerle desteklenir. Buna karşılık tek kullanımlık görev tarifi sürekli yüklenen depo talimatında tutulmaz. Talimat dosyasındaki her değişiklik, en az bir normal görev ve bir sınır ihlali örneğiyle sınanarak hem gereksiz maliyet hem de güvenlik gerilemesi bakımından karşılaştırılabilir.

7.7.2. CLAUDE.md için Kalıcılık Ölçütü

Claude Code'da CLAUDE.md kalıcı talimatların doğal yeridir; bu nedenle dosyanın büyümesi kolaydır. Oysa her faydalı bilgi burada bulunmamalıdır.

Bir bilginin sürekli yüklenmesi için dört soru yeterlidir: birçok görevde gerçekten gerekli mi; koddan güvenilir biçimde çıkarılamıyor mu; yanlış bilinmesi tekrarlayan hata üretiyor mu; kısa ve eyleme dönük biçimde yazılabiliyor mu? Cevapların çoğu “hayır” ise bilgi beceri (skill), ayrıntılı belge veya göreve özgü bağlam için daha uygun olabilir.

Örneğin aşağıdaki içerikler kalıcı bağlama adaydır:

• alışılmadık derleme/test komutları,
• mimari katman yasağı,
• veri kaybı riski taşıyan değişmez,
• belirli dizinlerin salt okunur kabul edilmesi,
• ekip için zorunlu doğrulama adımı.

Buna karşılık uygulama çatısı öğreticileri, uzun API belgeleri, kolayca keşfedilen klasör listeleri ve tek bir geçmiş hataya ait ham log kalıcı bağlamı gereksiz yere büyütür.

Kalıcı dosyanın kısa tutulması estetik tercih değil, dikkat bütçesi yönetimidir.

7.8. Çalışma Belleği ve Mühendislik Belleği

Uzun süreli yapay zekâ destekli geliştirme başka bir sorun doğurur: aynı hatalar tekrar tekrar keşfedilebilir. Burada çalışma belleği ile mühendislik belleğini ayırmak gerekir.

Çalışma belleği geçici durumu içerir: şu anda neyin değiştirildiği, hangi dosyaların incelendiği, çözülmemiş sorular ve ara araç çıktıları.

Mühendislik belleği ise kalıcı bilgiyi içerir: başarısız bir yaklaşım ve neden başarısız olduğu, hata ayıklamada keşfedilen gizli bir değişmez, tekrar eden doğrulama gereksinimi veya sürekli gerilemeye yol açan bir bağımlılık.

Geçici izler otomatik olarak kalıcı kurallara dönüşmemelidir. Önce denemenin sonucu değerlendirilmeli; gerçekten yeniden kullanılabilir bir ders varsa özü çıkarılıp kaynak iziyle saklanmalı; yalnız ilgili görevlerde geri getirilmeli ve kod değişmişse yeniden doğrulanmalıdır.

Graf tabanlı araçlar, dersleri ilgili kavram veya dosyalara bağlayarak bunu destekleyebilir. Önemli özellik kaynak izidir: ajan, güncel kaynaktan çıkarılan gözlemi, çıkarımı ve önceki bir görevden türetilen dersi birbirinden ayırabilmelidir.

Bu yaklaşım eski deneyimi sorgulanmayan doğruya dönüştürmeden yinelenen keşfi azaltır.

7.8.1. Auto Memory: Kolaylık, Otorite Değil

Claude Code'un otomatik bellek mekanizması önceki çalışmalardan yararlı notları oturumlar arasında taşıyabilir. Bu özellik özellikle tekrar eden derleme komutları, proje tercihleri ve daha önce keşfedilmiş hata ayıklama ipuçlarında zaman kazandırır.

Ancak otomatik olarak yazılan her not, kalıcı mühendislik gerçeği değildir.

Bir bellek kaydı üç sınıftan birine konmalıdır: doğrulanmış proje gerçeği, geçici görev gözlemi veya model çıkarımı. İlk grup kalıcı bağlama ya da yetkili belgeye taşınabilir. İkinci grup zamanla silinmelidir. Üçüncü grup ise kaynakla doğrulanmadan değişmez hâline getirilmemelidir.

Bu nedenle belleğin iyi kullanımı “model her şeyi hatırlasın” yaklaşımı değildir. Daha güvenli model şudur:

Bellek keşfi hızlandırsın; son kararı güncel kaynak ve doğrulama versin.

Kod deposu değiştikçe bellek kayıtlarının da eskime ihtimali vardır. Mimari karar, komut veya dosya yolu değiştiğinde eski bilginin sessizce kullanılmasını önlemek için kaynak izi ve güncellik önemlidir.

7.9. Doğrulama Kapsamı Bağlam Kapsamını İzlemelidir

Verimli bağlam seçimi, verimli doğrulamayla eşleşmelidir.

Küçük bir değişiklik her zaman mevcut en büyük test takımını gerektirmez. Sistemin birçok bölümünü kesen kritik bir değişiklik ise tek bir yerel test geçti diye kabul edilmemelidir. Doğrulama, değişiklik kapsamından etkilenen sözleşme ve iş akışlarına doğru genişlemeli; ancak risk gerçekten gerektiriyorsa daha geniş test yüzeyine çıkmalıdır. Bu, aşamalı bağlam sunumunun doğrulama karşılığıdır.

Uygulamanın yerini bulmaya yardımcı olan kod deposu haritaları, olası yayılma etkilerini belirlemeye de yardımcı olabilir. Bir graf yolu, değiştirilen servisin birden fazla denetleyiciye ulaştığını gösterebilir; iş akışı belgesi ise arka uç odaklı kaynak aramasının hiçbir zaman ortaya çıkaramayacağı bir etkileşimi gösterebilir.

Ajan iki farklı soruya cevap vermelidir:

1. Değişikliği yapmak için neyi okumalıyım?
2. Değişikliğe güvenmek için neyi doğrulamalıyım?

Bu iki küme kesişir; ancak aynı değildir.

7.9.1. Kancalarla (Hooks) Zorunlu Doğrulama Noktaları

Doğrulama yalnız ajanın “testleri çalıştırdım” demesine bırakılamayacak kadar önemli olduğunda deterministik bir kapı gerekir.

Claude Code kancaları (hooks) bu amaçla belirli yaşam döngüsü olaylarına işlem bağlamaya izin verir. Örneğin:

dosya düzenlendikten sonra
→ linter çalıştır

belirli bir araç çağrısından önce
→ parametreyi denetle

ajan tamamlandı dediğinde
→ zorunlu kontrolü çalıştır

Kancanın değeri, modelin hatırlamasına bağlı olmamasıdır. Bununla birlikte kanca da bütün doğruluğu kanıtlamaz. Yanlış test komutu her seferinde deterministik olarak çalıştırılabilir. Bu nedenle zorunlu yürütme ile doğru doğrulama kapsamı ayrı tasarım problemleridir.

Yüksek riskli bir değişiklikte doğrulama yüzeyi, yalnız değişen satırların değil etkilenen sözleşmelerin kapsamını izlemelidir. Yetkilendirme değişikliği güvenlik testini, veri yazma değişikliği bütünlük kontrolünü, eşzamanlılık değişikliği yarış ve sıra varsayımlarını, dış API değişikliği sözleşme doğrulamasını gerektirir.

7.10. Token Verimli Niyet Programlama İş Akışı

Önceki ilkeler pratik bir kod deposu iş akışında birleştirilebilir:

1. Küçük kalıcı talimat kümesini oku.
2. Görevi ve riskini sınıflandır.
3. Kod deposu haritalarını veya bilgi grafiğini sorgula.
4. Yalnızca ilgili iş akışı, sözleşme ve risk belgelerini oku.
5. Hedefli kaynak kodu incele ve graf kaynaklı varsayımları doğrula.
6. Amaçlanan değişikliği ve değişmeden kalacak değişmezleri belirt.
7. En küçük tutarlı değişikliği uygula.
8. Etkilenen sözleşmelerle orantılı doğrulama çalıştır.
9. Yalnızca sözleşme değiştiyse yetkili belgeleri güncelle.
10. Kod deposu grafiğini/indeksini yenile.
11. Yalnızca sonuç yeniden kullanılabilir bir ders üretiyorsa kalıcı ders kaydet.

Bu yaklaşım kaynak kodu yetkili kaynak olarak tutarken kod deposunun tekrar tekrar keşfedilmesini azaltır.

Amaç yalnızca daha az token tüketmek değildir. Tokenları belirsizliği azalttıkları yerde harcamaktır.

Bu yaklaşım şu oranla özetlenebilir:

Bağlam verimliliği = ilgili kanıt / toplam bağlam

Yalnızca paydayı küçültmekten daha önemli olan paydır.

7.11. Kod Deposu Ajan Yürütme Çerçevesinin Parçası Hâline Gelir

Geleneksel geliştirmede kod deposu düzeni temel olarak insan geliştiricilere ve derleme araçlarına hizmet eder.

Kodlama ajanlarıyla birlikte kod deposunun yapısı makinenin muhakemesini de etkiler.

Adlandırmalar, dizinler, belge sınırları, haritalar, doğrulama komutları, araç arayüzleri ve üretilen indeksler birlikte kaynak kodun çevresinde bir ajan yürütme çerçevesi oluşturur.

Bu, her projenin bir yapay zekâ modeli için yeniden yapılandırılması gerektiği anlamına gelmez. Makine tarafından okunabilir mühendislik disiplini ile insan tarafından okunabilir mühendislik disiplininin giderek örtüştüğünü kabul etmek anlamına gelir.

İyi yapılandırılmış bir kod deposu; insanların davranışın yerini bulmasına, ajanların bağlam getirmesine, inceleyenlerin değişiklik kapsamını anlamasına, otomatik denetimlerin değişmezleri doğrulamasına ve gelecekteki çalışmaların doğrulanmış bilgiyi yeniden kullanmasına yardımcı olur.

Bu nedenle niyet programlamanın en güçlü biçimi uzun bir istem değildir.

Kod deposunun kendisinin niyeti sınırları belirli ve doğrulanabilir bir değişikliğe dönüştürmeye yardımcı olduğu sistemdir.

7.11.1. İzinler, Yalıtılmış Çalışma Alanı (Sandbox) ve Dış Araçlar da Kod Deposu Mimarisinin Uzantısıdır

Ajanın bir projede ne yapabildiği yalnız kaynak kodla belirlenmez. İzin dosyaları, kancalar (hooks), MCP sunucuları, yerel komutlar ve yürütme ortamı da fiilen geliştirme mimarisinin parçasıdır.

Claude Code'da izin kuralları araç çağrılarını allow/ask/deny biçiminde sınırlayabilir. Yalıtılmış çalışma alanı (sandbox) ise özellikle Bash ve onun alt süreçleri için dosya sistemi ve ağ erişimini işletim sistemi düzeyinde daraltabilir. Bu iki katman birbirinin yerine geçmez; birlikte savunma derinliği sağlar.

MCP sunucuları dış sistemlere erişim yüzeyini genişletir. Bu yüzden “hangi araç var?” sorusu kadar “araç hangi kimlikle, hangi veri alanına, hangi işlem kapsamıyla erişiyor?” sorusu da önemlidir.

Kurumsal veya kritik sistemlerde uygun model şudur:

ajanın görevi
⊂
izin verilen araçlar
⊂
yalıtılmış çalışma alanı / işletim sistemi sınırı
⊂
harici sistem yetkileri
⊂
kurumsal güvenlik politikası

En içteki doğal dil talimatı en dıştaki güvenlik katmanlarının yerine geçmez.

Bu nedenle yapay zekâya hazır kod deposu, yalnız iyi belgelenmiş depo değildir. Aynı zamanda araç erişimi, doğrulama kapıları ve etki alanı açık biçimde tasarlanmış bir çalışma ortamıdır.

Ünite 8: Ajanlı Geliştirmede Değişiklik Kontrolü ve Kanıt

8.1. Kısıt Hasadı ve Kanıtlanmış Kalıplarla Ajanlı Geliştirme

Ajanlı geliştirmede proje büyüdükçe her yeni görevin daha uzun istem gerektirmesi zorunlu değildir. Tersine, tekrar eden kararlar yetkili proje bağlamına taşındıkça sonraki görevlerin seçenek uzayı daralabilir. Bunun için tamamlanan çalışmalardan yalnız kalıcı ve tekrar kullanılabilir bilginin çıkarılması gerekir. Bu sürece kısıt hasadı denebilir.

Bir değişiklik tamamlandığında şu sorular sorulabilir:

Yeni bir değişmez ortaya çıktı mı?
Yeni bir kanıtlanmış kalıp oluştu mu?
Eski bir karar artık geçersiz mi?
Tekrar yaşanmaması gereken bir hata öğrenildi mi?
Bunlardan hangisi gelecekteki görevlerde gerçekten gerekli?

Her gözlemi kalıcı kurala çevirmek doğru değildir. Bir butonun geçici piksel değeri proje değişmezi değildir; büyük veri sorgusunun zorunlu bir sınır olmadan çalışmaması ise olabilir. İyi kod deposu bağlamı çok bilgi taşıyan değil, karar vermeyi etkileyen bilgiyi taşıyan bağlamdır.

Kanıtlanmış kalıp kullanımı da ajan performansını güçlendirir. Yeni özelliği sıfırdan tasarlatmak yerine en yakın çalışan davranış referans gösterildiğinde problem şu biçime dönüşür:

Yeni özellik
= mevcut kanıtlanmış kalıp
+ alan farkı
+ açıkça izin verilen davranış farkı

Bu yaklaşım hata olasılığını azaltır çünkü modelin her seferinde veri erişimi, hata sunumu, duyarlı arayüz davranışı, klavye modeli veya yetkilendirme akışı için yeni karar üretmesi gerekmez. Tekrar burada kod kopyalamak anlamına gelmez; davranış sözleşmesinin tekrar kullanılması anlamına gelir.

Değişiklik riski, okunacak bağlam ve doğrulama derinliğini de belirlemelidir. Yerel ve davranış eşdeğerliği açık bir değişiklikte doğrudan bölge ve çağrıcıları yeterli olabilir. Veri yazma, yetkilendirme, eşzamanlılık veya kritik iş akışında ise uçtan uca akış, hata yolları ve geri dönüş davranışı birlikte incelenmelidir. Böylece ajan ne bütün depoyu gereksiz yere okur ne de kritik değişikliği yerel bir düzenleme gibi ele alır.

düşük risk  -> dar bağlam + dar doğrulama
yüksek risk -> geniş etki analizi + güçlü doğrulama

Bu model İstem Mühendisliği ile birlikte düşünüldüğünde kalıcı proje bilgisinin görev isteminden ayrılması doğal hale gelir. Temiz Kod ve Bakım Mühendisliği açısından ise aynı fikir değişiklik yüzeyini küçültür: yeni davranış yalnız gerçekten farklı olan noktada eklenir.

Ajanlı geliştirmede olgunluk, modele her görevde daha çok metin vermek değildir. Proje ilerledikçe hangi kararların artık verilmesine gerek olmadığını belirleyip bunları kararlı sözleşmelere dönüştürmektir.

8.1.1. Yetkili Bağlam Hiyerarşisi ve Negatif Kısıtlar

Ajanlı geliştirmede yalnız “ne yapılmalı?” bilgisini saklamak yeterli değildir. “Neye dokunulmamalı?”, “hangi davranış değişmemeli?” ve “hangi kaynak diğerinden daha yetkili?” soruları da bağlamın parçasıdır. Özellikle büyük kod depolarında çelişkili açıklama dosyaları, eski tasarım notları ve güncel kaynak kod aynı anda bulunabilir.

Bu nedenle bağlam hiyerarşisi açık olmalıdır:

kalıcı güvenlik / veri değişmezleri
              |
              v
güncel kaynak ve çalışma sözleşmesi
              |
              v
alan kuralları ve kanıtlanmış kalıplar
              |
              v
göreve özgü istem
              |
              v
üretilmiş rapor ve geçici notlar

Alt katmandaki bilgi üst katmanla çelişirse otomatik olarak doğru kabul edilmemelidir. Üretilmiş bir analiz raporu, güncel kaynak koddan daha yeni görünse bile davranışın gerçek kaynağı olmayabilir. Ajan, özellikle veri yazma, yetkilendirme ve concurrency gibi yüksek riskli alanlarda iddiayı kaynak üzerinden yeniden doğrulamalıdır.

Negatif kısıtlar token verimliliğini de artırır. “Yeni kütüphane ekleme”, “şemayı değiştirme”, “çalışan klavye akışını bozma” gibi sınırlar baştan biliniyorsa model uygulanamayacak çözüm uzayını araştırmaz. Ancak negatif kısıt kısa ve davranışa bağlı olmalıdır; yüzlerce mikro kural bağlamı yeniden gürültüye dönüştürür.

Doğrulama kapsamı da risk sınıfından türetilebilir. Görev istemi her seferinde bütün test planını tekrar yazmak yerine depo bağlamında “düşük riskli görsel değişiklik”, “veri yazma değişikliği”, “yetkilendirme değişikliği” gibi sınıflara bağlanabilir. Böylece Yazılım Test Mühendisliği içindeki kanıt katmanları ajanlı geliştirmede tekrar kullanılabilir bir politika haline gelir.

İyi bağlam, en çok bilgiyi taşıyan bağlam değildir. Kararı değiştirmeyen ayrıntıyı eleyen; buna karşılık ihlali gerçek regresyon doğuracak sınırları görünür tutan bağlamdır.

8.2. Spesifikasyon Kayması ve Niyetten Uygulamaya Kanıt Zinciri

Niyet doğal dilde başlar; uygulama planına, mimari kararlara ve kaynak kod değişikliklerine dönüştükçe ayrıntı kazanır. Bu ayrıntılanma gerekli olmakla birlikte başlangıçtaki iş hedefinin sessizce değişmesi riskini de taşır. Spesifikasyon kayması, kodun son spesifikasyona uygun olmasına karşın bu spesifikasyonun artık ilk niyeti doğru temsil etmemesi durumudur.

Bu nedenle kabul kriteri, değişmez kısıt, mimari karar, değişen dosya ve doğrulama kanıtı birbirine bağlanmalıdır. Uzun bir ajan açıklamasından daha değerli olan, hangi kısıtın hangi uygulama kararıyla karşılandığının ve bu kararın hangi kanıtla doğrulandığının izlenebilmesidir.

Ajan tarafından üretilen değişiklik yalnız diff büyüklüğüyle değerlendirilmemelidir. Veri modeli, yetkilendirme, hata davranışı, eşzamanlılık veya dış sözleşme değişiyorsa etki alanı ve doğrulama yüzeyi de aynı kapsamda ele alınmalıdır.

Testlerin geçmesi tek başına niyet doğrulaması değildir; testler yanlış ya da kaymış bir spesifikasyonu eksiksiz biçimde doğrulayabilir. Son kontrolde kullanıcı hedefi, kabul kriterleri ve değişmezler yeniden karşılaştırılmalı; istemde açıkça bulunmayan varsayımların koda taşınıp taşınmadığı ayrıca incelenmelidir.

Bu zincir, niyet programlamada izlenebilirliğin en küçük yararlı birimidir: niyet → kısıt → karar → değişiklik → doğrulama kanıtı. Zincirin herhangi bir halkası açıklanamıyorsa sistem teknik olarak çalışsa bile değişikliğin doğru problemi çözdüğü henüz kanıtlanmış sayılmaz.

8.2.1. Sonuç

Programlama tarihinde her önemli soyutlama katmanı, insanın makineyle iletişim biçimini değiştirdi.

Bugün yeni bir katman oluşmaktadır:

İnsan
  ↓
Niyet
  ↓
Belirtim
  ↓
Yapay zekâ / ajan
  ↓
Kaynak kod
  ↓
Derleyici / çalışma zamanı
  ↓
Makine

Bu dönüşüm programlamanın sonu değildir.

Programlamanın bir sonraki soyutlama katmanıdır.

Soyutlama yükseldikçe mühendislik gereksiz hâle gelmez.

Kod üretmek kolaylaştıkça yanlış kod üretmek de kolaylaşır.

Değişiklik hacmi büyüdükçe doğrulama zorlaşır.

Uygulama ayrıntıları daha az görünür oldukça temel sistem davranışını anlayan kişilerin değeri artar.

Bu nedenle geleceğin en önemli ayrımı yapay zekâ kullanan ve kullanmayan geliştiriciler arasında olmayabilir.

Daha anlamlı ayrım şudur:

yapay zekâ ile kod üretebilen kişi

ile

yapay zekâ aracılığıyla güvenilir bir sistemi tasarlayabilen, sınırlandırabilen ve doğrulayabilen mühendis.

Programcı için merkez uzun süre koddu.

Niyet programlamada merkez giderek doğru davranışın tanımıdır.

Kod hâlâ önemlidir.

Ancak kod artık her zaman başlangıç noktası değildir.

Bazen yalnızca iyi ifade edilmiş bir mühendislik düşüncesinin makine tarafından üretilmiş ara gösterimidir.

8.3. Yama Kökeni, Geri Alma ve Doğrulama

Ajanlı geliştirmede ortaya çıkan diff'in yalnız "çalışıyor" olması yeterli değildir. Değişikliğin hangi niyetten, hangi kanıttan ve hangi doğrulamadan üretildiği izlenebilir olmalıdır.

8.3.1. Değişiklik Kökeni

Her yama için zincir şu biçimde tutulabilir:

kullanıcı niyeti
   ↓
çıkarılan kısıtlar
   ↓
incelenen dosya / kanıt
   ↓
değişiklik
   ↓
doğrulama

Bu yapı modelin özel düşünme sürecini kaydetmeyi gerektirmez. Kaydedilmesi gereken şey mühendislik açısından denetlenebilir girdi, karar gerekçesi, diff ve test kanıtıdır.

8.3.2. Küçük ve Geri Alınabilir Patch

Büyük bir otomatik yeniden yazım birden fazla varsayımı aynı diff içinde gizler. Bunun yerine bağımsız davranış değişiklikleri mümkün olduğunca ayrı patch'lerde tutulmalıdır.

İyi bir patch:

• tek bir açık amacı karşılar,
• gereksiz format değişikliği üretmez,
• ilgisiz dosyalara dokunmaz,
• rollback edildiğinde önceki sözleşmeyi geri getirir,
• hangi testin onu doğruladığı bilinir.

Revert teknik olarak mümkün olsa bile veri göçü veya harici yan etki geri alınamıyorsa değişiklik tam anlamıyla reversible değildir. Bu ayrım release planında açıkça yazılmalıdır.

8.3.3. Test Kanıtı

Ajanın "testler geçti" demesi kanıt değildir. Komut, kapsam ve sonuç birlikte görünür olmalıdır:

build command
test command
targeted regression test
result

Testin bulunmaması durumunda ajan yeni bir doğrulama yöntemi üretmeli veya doğrulanamayan varsayımı açıkça bırakmalıdır; başarıyı varsaymamalıdır.

8.3.4. İnsan Onay Sınırı

Kod üretmek ile etkili işlemi gerçekleştirmek farklı yetkilerdir. Aşağıdaki işlemler ayrı onay sınırı gerektirebilir:

• production deploy,
• kalıcı veri değişikliği,
• secret/credential kullanımı,
• güvenlik politikasını gevşetme,
• dış sisteme yazma,
• geri dönüşü zor migration.

Bu ayrım, ajanı "her şeyi yapabilen kullanıcı" olarak değil sınırlı yetkilerle çalışan bir yürütücü olarak konumlandırır.

8.3.5. Son Durumun Doğrulanması

Patch sonrasında yalnız dosya içeriği değil, beklenen sistem davranışı doğrulanmalıdır:

niyet
  =? gereksinim
  =? diff
  =? test
  =? çalışma zamanı davranışı

Bu eşitlik zincirlerinden biri kanıtlanamıyorsa çalışma tamamlanmış değil, yalnız değiştirilmiş kabul edilmelidir.

8.4. Ek — Token Verimli, Yapay Zekâya Hazır Kod Deposu için Yeniden Kullanılabilir İstem

Aşağıdaki istem bilinçli olarak kısa tutulmuştur. Mevcut bir projenin kök dizininde bir yapay zekâ kodlama platformuna kopyalanarak, belgeleri kodun ikinci bir kopyasına dönüştürmeden tekrar eden keşfi azaltan küçük bir kod deposu bağlam katmanı oluşturmak için kullanılabilir.

# Görev — Token Verimli Kod Deposu Bağlam Katmanı
Oluştur

Bu kod deposunu, en düşük yinelenen bağlam maliyetiyle
yapay zekâ kodlama ajanlarının anlayabileceği hâle
getir.

## Amaç
Gelecekteki ajanların tüm kod deposunu tekrar tekrar
okumadan davranışları, kısıtları, iş akışlarını,
riskleri ve doğrulama yollarını bulmasını sağlayacak en
küçük yararlı Markdown bağlam dosyası kümesini oluştur.

## Kurallar
- Yazmadan önce incele. Varsayımları belgelemeye
  çalışma.
- Kaynak kod, derleme/çalışma zamanı yapılandırması,
  şemalar ve mevcut sözleşmeler yetkili kaynaktır.
- Kopyalanmış uygulama ayrıntıları yerine işaretçiler ve
  haritalar kullan.
- Kalıcı talimatları kısa tut; göreve özgü ayrıntıları
  odaklı belgelere taşı.
- Tekrar eden kod deposu keşfini azaltmayan belge
  oluşturma.
- Aynı bilgiyi birden fazla dosyada yineleme.
- Değişmezleri, sınırları, gerekçeyi ve gezinme
  yollarını kaydet; koddan kolayca çıkarılabilen
  açıklamalardan kaçın.
- Belirsiz veya çıkarımsal ifadeleri açıkça işaretle.
- Mevcut davranışı koru. Bu görev için ürün kodunu
  yeniden düzenleme.
- Bağımlılık ekleme.
- Belge sayısını değil, token başına ilgili bilgiyi
  eniyile.

## Keşif
1. Önce mevcut yapay zekâ/proje talimatlarını oku.
2. Kod deposu grafiği/indeksi zaten varsa geniş kaynak
  okumalarından önce onu sorgula.
3. Graphify kuruluysa şunları tercih et:
   - `graphify query "<görev veya alt sistem>"`
   - `graphify path "<A>" "<B>"`
   - `graphify explain "<kavram>"`
   Ardından önemli bulguları kaynak koddan doğrula.
4. Aksi hâlde hedefli arama, derleme dosyaları, giriş
  noktaları, yapılandırma ve temsilî kaynak yollarını
  kullan.
5. Gerekmedikçe büyük dosyaları veya tüm dizinleri
  okuma.

## Yalnızca Yararlı Olanı Oluştur veya İyileştir
Eşdeğer dosyalar zaten varsa mevcut adları kullan.
Aşağıdaki yapıyı tercih et; ancak ilgisiz dosyaları
oluşturma:

- `AGENTS.md`
  - çok kısa, her zaman geçerli kurallar;
  - önce nereye bakılacağı;
  - yasak/yüksek riskli değişiklikler;
  - doğrulama giriş noktaları.

- `CODEMAP.md`
  - yetenek/alt sistem → yetkili
    dosyalar/sınıflar/modüller;
  - uygulama kopyası yok.

- `WORKFLOWS.md`
  - kritik kullanıcı/sistem akışları;
  - sıralı adımlar, durum geçişleri, korunacak davranış;
  - yalnızca sıranın önemli olduğu iş akışları.

- `DATAFLOW.md`
  - sınırlar arasındaki önemli veri yolları;
  - kaynak → dönüşüm → kalıcılık/çıktı;
  - ilgili olduğunda kimlik, sahiplik, yönlendirme,
    önbellek veya eşzamanlılık sınırları.

- `docs/ai/database-contract.md`
  - yalnızca kalıcılık önemliyse;
  - kimlik kuralları, okuma/yazma sınırları, değişmez
    şema varsayımları, işlem/kilitleme kuralları, geçiş
    kısıtları.

- `docs/ai/runtime-safety.md`
  - ortamlar;
  - çalıştırılması güvenli/güvensiz komutlar;
  - üretim kısıtları;
  - dış servis ve yıkıcı işlem sınırları.

- `docs/ai/known-risks.md`
  - açık olmayan gerileme alanları;
  - eski sistem tuzakları;
  - yüksek riskli dosyalar/akışlar;
  - neden riskli oldukları.

- `docs/ai/completion-validation.md`
  - değişiklik türüne göre gereken en küçük doğrulama;
  - sözdizimi/derleme/çalışma zamanı/el ile denetimler;
  - daha geniş doğrulamanın ne zaman gerektiği.

- `docs/ai/LESSONS.md`
  - yalnızca önceki başarısızlık veya düzeltmelerden
    çıkarılan kalıcı ve doğrulanmış dersler;
  - kaynak izi ve yeniden doğrulama notları ekle;
  - geçici görev geçmişini saklama.

Proje küçükse daha az dosya oluştur.

## İçerik Tasarımı
Her belge için:
- ajanın eyleme geçmek için ihtiyaç duyduğu bilgiyle
  başla;
- tablolar, kısa maddeler, tanımlayıcılar, yollar ve
  değişmezler kullan;
- yinelenen açıklamaları kaldır;
- içeriği kopyalamak yerine yetkili dosyalara bağlantı
  ver;
- `OLGU`, `DEĞİŞMEZ`, `RİSK` ve `DOĞRULA` ayrımını
  yalnızca değer katıyorsa kullan;
- operasyonel olarak gerekli değilse öğretici
  metinlerden, genel en iyi uygulamalardan, proje
  tarihinden ve üslup açıklamalarından kaçın.

## Gezinme Sözleşmesi
`AGENTS.md` dosyasını küçük giriş noktası yap.

Gelecekteki ajanları kabaca şu sıraya yönlendirsin:

`AGENTS.md → ilgili harita/iş akışı/sözleşme →
graf/sorgu/arama → hedefli kaynak → doğrulama`

Kod deposunun tüm modelini `AGENTS.md` içine koyma.

## Güncellik
Üretilen haritalar/grafikler varsa:
- nasıl yenilendiklerini belgele;
- artımlı güncellemeyi tercih et;
- üretilen graf çıktısının özyinelemeli indekslenmesini
  önle;
- belge/kaynak değişikliklerinden sonra yalnızca
  gerekeni yenile.
Graphify zaten yapılandırılmışsa `graphify update .` ile
bitir.

## Doğrulama
Bitirmeden önce:
- belgelenen her yolun/sembolün var olduğunu doğrula;
- önemli iddiaları kaynak/yapılandırmaya göre doğrula;
- yinelenen veya varsayımsal ifadeleri kaldır;
- gizli bilgi, kimlik bilgisi, kişisel veri, üretim
  tanımlayıcısı veya ortama özgü hassas değerlerin
  belgelere kopyalanmadığını doğrula;
- kalıcı bağlamın indekslediği kod deposu bilgisinden
  belirgin biçimde daha küçük olduğunu doğrula.

## Çıktı
Belgeleri doğrudan uygula.
Yalnızca şunları döndür:
1. oluşturulan/güncellenen dosyalar,
2. her birinin tek satırlık amacı,
3. çözülemeyen belirsizlikler,
4. varsa tam yenileme/doğrulama komutu.

Bu istem ajandan “tüm projeyi belgelemesini” özellikle istemez. Amacı kod deposunun metinsel bir kopyasını üretmek değil, bağlam için gezinme sistemi oluşturmaktır.

Ünite 9: Ajan Mimarileri, Araçlar ve Yapay Zekâ Mühendisliği

9.1. Yapılandırılmış Çıktı ile Niyetten Uygulanabilir Sözleşmeye

Niyet odaklı programlamada kullanıcı “ne istediğini” doğal dille söyler. Ancak üretim kodu serbest metin niyetini doğrudan çalıştırmamalıdır. Niyet önce yapılandırılmış ve doğrulanabilir bir sözleşmeye dönüştürülmelidir.

Doğal dil niyeti
      |
      v
LLM
      |
      v
Yapılandırılmış aday
      |
      v
Şema doğrulama
      |
      v
Yetki + kısıt + test
      |
      v
Uygulanabilir işlem

Örnek yapı:

operation
target_files
constraints
acceptance_tests
risk_level

Bu temsil, “model ne demek istedi?” sorusunu azaltır. Yapılandırılmış çıktı yine model hatasına açıktır; şema geçerli diye semantik olarak doğru olmak zorunda değildir.

Bir araştırma ajanının önerdiği işlem ile yürütülebilir işlem aynı katman değildir. “Kaynakları karşılaştır ve raporla” isteği; kaynak seçimi, alıntı kaydı, hesaplama ve rapor oluşturma alt adımlarına ayrıldığında her adımın girdisi, izin verilen araçları, çıktı şeması ve doğrulama koşulu tanımlanmalıdır. Ajanın ürettiği bibliyografik kayıt gerçekte doğrulanmadan güvenilir kaynak olarak eklenmemelidir. Bir sonraki adımın yürütülmesi önceki adımın geçerli ve izlenebilir çıktısına bağlanır. Araç hatası veya yetkisiz veri talebinde plan, sessizce alternatif veri uydurmak yerine kontrollü olarak durmalıdır.

9.2. Function Calling ve Tool Calling

Yazılım ajanı araç çağırırken iki düzey ayrılmalıdır.

Model:

tool = search_code
arguments = {...}

önerir.

Uygulama:

• araç whitelist'te mi,
• argümanlar geçerli mi,
• dosya kapsamı izinli mi,
• işlem salt okunur mu,
• zaman/kaynak bütçesi uygun mu

diye denetler.

Araç çağırma, doğal dil modelini yetkilendirme sistemi yapmaz.

9.2.1. Yazma Araçlarında İki Aşama

Yüksek riskli işlem için:

PLAN
  |
  v
DRY RUN / DIFF
  |
  v
VALIDATION
  |
  v
APPROVAL
  |
  v
WRITE

deseni daha güvenlidir.

9.3. Planner–Executor Ayrımı

Tek ajan hem plan üretip hem bütün adımları denetimsiz uyguladığında hata zincirleme büyüyebilir.

Planner–executor mimarisi:

İstek
 |
 v
Planner
 |
 v
Adım listesi
 |
 +--> Executor 1
 +--> Executor 2
 +--> Executor 3
 |
 v
Verifier

şeklinde kurulabilir.

Planner hedefi ve bağımlılıkları çözer. Executor sınırlandırılmış aracı kullanır. Verifier sonucu spesifikasyona karşı kontrol eder.

Bu ayrım her projede zorunlu değildir. Küçük görevde tek ajan daha basit ve güvenilir olabilir.

9.4. Ajan Belleğini Tek Kavram Saymamak

“Ajanın hafızası” farklı katmanları kapsayabilir.

Kısa süreli
 -> mevcut konuşma / görev

Çalışma belleği
 -> aktif plan, ara sonuçlar

Uzun süreli
 -> kalıcı kullanıcı/proje bilgisi

Bilgi tabanı
 -> RAG ile getirilen dış kaynaklar

Bunların saklama süresi ve güvenlik sınırı aynı değildir.

Kod ajanında geçmiş bir konuşmadaki varsayımın yeni projeye taşınması hata olabilir. Kalıcı bellek yalnız açık kapsam ve provenance ile kullanılmalıdır.

9.5. Çoklu Ajan Sistemlerinin Kullanım Koşulları

Birden fazla ajan kullanmak kaliteyi otomatik artırmaz.

Faydalı olduğu durumlar:

• görevler gerçekten bağımsız uzmanlıklara ayrılıyorsa,
• paralel araştırma maliyeti uygunsa,
• sonuçları birleştiren açık sözleşme varsa,
• ajanların yetkileri birbirinden ayrılabiliyorsa.

Riskler:

• koordinasyon maliyeti,
• aynı hatanın çoğalması,
• bağlam tekrarları,
• sonsuz devir,
• kaynak tüketimi,
• sorumluluğun belirsizleşmesi.

çok ajan
   !=
daha zeki sistem

9.6. MCP ve A2A: Araç Bağlamak ile Ajan Bağlamak

2026 itibarıyla iki protokol ailesi farklı mimari sınırları temsil eder.

MCP, model destekli uygulamanın dış araç ve kaynaklarla standart arayüz üzerinden çalışmasına odaklanır. 2026-07-28 spesifikasyonu stateless protocol core ve yetkilendirme iyileştirmeleri getirmiştir.

A2A, bağımsız ajanların yetenek keşfetmesi, görev alışverişi yapması ve birlikte çalışması için ajanlar arası iletişim standardıdır. Güncel A2A spesifikasyonu 1.0.0 sürümündedir.

Uygulama
   |
  MCP
   |
Araç / Kaynak

Ajan A
   |
  A2A
   |
Ajan B

Bir kod ajanının dosya sistemi veya derleyiciye erişmesi MCP benzeri araç katmanıyla; başka bir uzman ajanla görev paylaşması A2A benzeri ajan katmanıyla ele alınabilir.

9.7. Yerel ve Uzak Modeli Aynı İş Akışında Kullanmak

Her adımın en büyük uzak modele gönderilmesi gerekmeyebilir.

Yerel küçük model
 -> sınıflandırma
 -> dosya özetleme
 -> basit kod dönüşümü

Uzak / güçlü model
 -> zor mimari problem
 -> geniş bağlam
 -> karmaşık akıl yürütme

Ancak routing kararında gizlilik dikkate alınmalıdır. Hassas kod önce yerel modelde işlense bile özet içinde gizli bilgi kalabilir.

Bu nedenle:

veri sınıfı
 -> izinli model sınıfı
 -> izinli araçlar

politikası uygulanmalıdır.

9.8. AI Engineering ile “AI Kullanarak Kod Yazmak” Ayrımı

AI engineering, yalnız geliştiricinin kod üretimini hızlandırması değildir.

Daha geniş yaşam döngüsü:

problem tanımı
 |
veri / bağlam
 |
model seçimi
 |
istem / tool contract
 |
eval
 |
serving
 |
gözlem
 |
regression / rollback

kapsar.

Bir web uygulamasını sohbetle hızlı üretmek AI destekli yazılım geliştirmedir. Model, RAG, eval, araçlar, güvenlik ve izleme katmanını üretim sistemi olarak tasarlamak ise AI engineering problemidir.

Niyet Odaklı Programlama açısından temel sonuç şudur: niyet doğal dilde başlayabilir, fakat iyi mühendislik niyeti test, spesifikasyon, yetki ve doğrulanabilir artefakta dönüştürür.

9.9. Niyetten Yürütülebilir ve Denetlenebilir Spesifikasyona

Güvenlik ve güvenilirlik ayrı sonradan-eklenen özellikler değil, ortak hata ve kötüye kullanım yüzeyini yöneten tasarım özellikleridir. Niyet odaklı geliştirmede spesifikasyon yalnız beklenen çıktıyı değil kaynak bütçesini, izin verilen yan etkileri, yetki sınırını, güvenli varsayılanı ve geri alma koşulunu da ifade etmelidir; aksi halde model doğru görünen fakat blast radius'u belirsiz bir değişiklik üretebilir. Özellikle DoS sınıfı problemlerde güvenlik kontrolünün kendisinin kullanılabilirliği tüketmemesi gerekir.

• Doğal dil niyetinin doğrulanabilir kabul kriterlerine çevrilmesi.
• Üretilen değişikliğin blast radius ve rollback planıyla sınırlandırılması.
• Agent/LLM çıktısının yetki ve dosya kapsamı dışında işlem yapamamasının mekanik olarak uygulanması.

Kaynakça

• Anthropic. “Automate actions with hooks.” Claude Code Docs. Erişim: 16 Eylül 2026. https://code.claude.com/docs/en/hooks-guide

• Anthropic. “Beyond permission prompts: making Claude Code more secure and autonomous.” 20 Ekim 2025. https://www.anthropic.com/engineering/claude-code-sandboxing

• Anthropic. “Configure permissions.” Claude Code Docs. Erişim: 16 Eylül 2026. https://code.claude.com/docs/en/permissions

• Anthropic. “Connect Claude Code to tools via MCP.” Claude Code Docs. Erişim: 16 Eylül 2026. https://code.claude.com/docs/en/mcp

• Anthropic. “Create custom subagents.” Claude Code Docs. Erişim: 16 Eylül 2026. https://code.claude.com/docs/en/sub-agents

• Anthropic. “Effective context engineering for AI agents.” 2025. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents

• Anthropic. “Extend Claude with skills.” Claude Code Docs. Erişim: 16 Eylül 2026. https://code.claude.com/docs/en/skills

• Anthropic. “How Claude remembers your project.” Claude Code Docs. Erişim: 16 Eylül 2026. https://code.claude.com/docs/en/memory

• Anthropic. “Writing effective tools for AI agents — with AI agents.” 2025. https://www.anthropic.com/engineering/writing-tools-for-agents

• Gloaguen, T., Mündler, N., Müller, M. N., Raychev, V., Vechev, M. “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?” ICLR 2026 MemAgents Workshop. https://www.sri.inf.ethz.ch/publications/gloaguen2026agentsmd

• Graphify Labs. “Graphify.” GitHub kod deposu, v8. Erişim: 16 Eylül 2026. https://github.com/Graphify-Labs/graphify/tree/v8 — Kod deposu grafiği, query/path/explain iş akışı, güven etiketleri, artımlı güncellemeler, kancalar ve çalışma belleği davranışı için incelendi.

• Gupta, A. “Spec-Driven Development: A Spec-First Approach to AI-Native Engineering.” Microsoft for Developers, 10 Haziran 2026. https://developer.microsoft.com/blog/spec-driven-development-ai-native-engineering/

• Heather Adkins; Betsy Beyer; Paul Blankinship; Piotr Lewandowski; Ana Oprea; Adam Stubblefield. Building Secure & Reliable Systems: Best Practices for Designing, Implementing, and Maintaining Systems. O’Reilly Media, 2020.

• Karpathy, A. “There's a new kind of coding I call 'vibe coding'...” 2 Şubat 2025. https://x.com/karpathy/status/1886192184808149383

• Microsoft Research. “GraphRAG.” https://microsoft.github.io/graphrag/

• OpenAI. “Harness engineering: leveraging Codex in an agent-first world.” 2026. https://openai.com/index/harness-engineering/

• Zhang, S., Wang, M., Shi, Y., et al. “FastContext: Training Efficient Repository Explorer for Coding Agents.” arXiv ön baskısı, arXiv:2606.14066, 2026. https://arxiv.org/abs/2606.14066

• Zhu, J., Hu, M., Wu, J. “SWE Context Bench: A Benchmark for Context Learning in Coding.” arXiv ön baskısı, arXiv:2602.08316, 2026. https://arxiv.org/abs/2602.08316

• A2A Project. Agent2Agent (A2A) Protocol Specification, sürüm 1.0.0. https://a2a-protocol.org/dev/specification/

• Model Context Protocol. “The 2026-07-28 Specification.” 2026. https://blog.modelcontextprotocol.io/posts/2026-07-28/