Harness Mühendisliği Nedir? TÜBİTAK BİLGEM'in Kodlama Ajanı Raporundan Pratik Dersler

Aynı dil modelini kullanan iki kodlama ajanı, aynı görevde çok farklı sonuçlar verebiliyor. TÜBİTAK BİLGEM Yazılım Teknolojileri Araştırma Enstitüsü'nün (YTE) Araştırma Serisi Sayı 42 olarak yayımladığı "Kodlama Ajanı Kullanıcıları İçin Harness Mühendisliği" çalışması bu farkın nereden geldiğini sistemli biçimde ele alıyor. Raporun cevabı kısa: farkı çoğu zaman model değil, modelin etrafını saran yapı, yani "harness" (koşum) katmanı yaratıyor. Bu yazıda raporu kaynak göstererek özetliyor, ardından Claude Code ve n8n ile ajanlarla ürün geliştiren bir ekip olarak bu ilkelerin günlük işte neye karşılık geldiğini anlatıyoruz.

Harness nedir, neden model kadar önemli?

TÜBİTAK BİLGEM YTE Araştırma Serisi Sayı 42'ye göre büyük dil modeli özünde durumsuz bir metin üreticisidir: dosya sistemi, terminali ve hafızası yoktur. Ajan ise bu modelin bir döngü, bir araç seti ve durum yönetimiyle sarılmış hâlidir. Rapor bunu tek satırlık bir formülle özetliyor: "ajan = model + harness". Model akıl yürütür; harness bu akıl yürütmeyi gerçek bir bilgisayarda eyleme dönüştürür, araç çağrılarını yürütür ve sonuçları tekrar modele taşır.

Raporun kullanıcıya en önemli mesajı teşhisle ilgili. Ajan bir görevde başarısız olduğunda sebep modelin yetersizliği olabileceği gibi eksik bir araç, taşan bir bağlam penceresi, kötü yazılmış bir sistem istemi ya da hiç kurulmamış bir doğrulama döngüsü de olabilir. Rapora göre harness bilgisi olmayan kullanıcı çözümü genellikle yanlış yerde, yani model değiştirmekte arar.

Çalışma, harness'ı dört ana bileşenle tarif ediyor: ajan döngüsü (bağlam topla, eylem üret, yürüt, sonucu ekle, tekrarla), sistem istemi, araç katmanı ve çalışma ortamı. Bunların üzerine bağlam yönetimi, doğrulama döngüleri ve izin/güvenlik katmanı ekleniyor. Rapor ayrıca literatürdeki ETCLOVG taksonomisini (yürütme, araçlar, bağlam, yaşam döngüsü, gözlemlenebilirlik, doğrulama, yönetişim) bir kontrol listesi olarak kullanıyor ve hazır çözümlerin en az olduğu katmanların gözlemlenebilirlik ve yönetişim olduğuna dikkat çekiyor.

Bağlam ve hafıza: pencere bir bütçedir

TÜBİTAK BİLGEM YTE Araştırma Serisi Sayı 42, bağlam penceresini ajanın çalışma belleği ve harness'ın yönettiği en kıt kaynak olarak tanımlıyor. Pencere doldukça modelin bilgiyi isabetle geri çağırma yeteneği düşüyor; literatürde "context rot" (bağlam çürümesi) diye anılan bu olgu, uzun oturumlarda kalitenin sessizce bozulmasının başlıca sebebi olarak gösteriliyor.

Raporun öne çıkardığı stratejiler şunlar:

• Tam zamanında bağlam: Her şeyi baştan yüklemek yerine ajanın dizin listeleme ve arama ile ihtiyaç duyduğu dosyanın yalnızca ilgili kısmını okuması. Kullanıcının buradaki görevi, anlamlı dosya adları ve iyi bölünmüş modüllerle kod tabanını aranabilir kılmak.
• Sıkıştırma ve not alma: Konuşma geçmişinin özetlenmesi kayıplıdır; bu yüzden rapor görevleri bağlamı taşırmayacak parçalara bölmeyi ve önemli ara kararları pencere dışındaki bir dosyaya (yapılacaklar, ilerleme notu) yazdırmayı öneriyor.
• Kalıcı bağlam: Depo köküne konan AGENTS.md (Claude Code'da CLAUDE.md) dosyası derleme/test komutlarını, kod kurallarını ve dokunulmaması gereken alanları her oturumun başında ajana verir. Rapor bu dosyanın kısa tutulmasını, ayrıntının ise yalnızca gerektiğinde okunacak ayrı belgelere taşınmasını ("tembel okuma") öneriyor.

Raporun pratik bir kuralı da akılda kalıcı: ajana aynı şeyi ikinci kez açıklamanız gerekiyorsa, o açıklama AGENTS.md'ye ya da hafızaya yazılmalıdır.

Araçlar ve protokoller: MCP, LSP ve ACP

Rapor, araç ile protokolü birbirinden ayırıyor. Araç, modelin çağırabileceği somut bir işlevdir (dosya okuma, arama, terminal, test). Protokoller ise farklı bütünleşme sorunlarını çözen standartlardır:

• MCP (Model Context Protocol): Ajanın dış sistemlere (iş takip, veritabanı, dokümantasyon) tek tip bir yolla bağlanmasını sağlar; sunucular araç, kaynak ve istem şablonu sunabilir. TÜBİTAK BİLGEM YTE Araştırma Serisi Sayı 42'ye göre her MCP sunucusu yeni bir yetki ve saldırı yüzeyi demektir; yalnızca görev için gerçekten gerekenler açılmalıdır.
• LSP (Language Server Protocol): Kodun sembolik yapısını (tanıma gitme, referanslar, tip hataları) ajana açar. Düz metin araması yerine tek bir sembol sorgusu hem bağlamdan tasarruf ettirir hem de geri bildirimi hızlandırır.
• ACP (Agent Client Protocol): Editör ile ajan arasındaki iletişimi standartlaştırır. Rapor bunun sağlayıcı bağımsızlığı getirdiğini, ancak tam özellik eşdeğerliği garantisi olmadığını vurguluyor.

Araç tasarımı konusunda rapor, Anthropic'in araç yazma rehberine dayanarak dört ilke sıralıyor: çok sayıda parçalı araç yerine az ve kapsamlı araç; araç açıklamasını küçük bir istem gibi yazmak (ne zaman kullanılmayacağı dâhil); çıktıyı özetli ve sayfalı döndürerek bağlam bütçesini korumak; okuma yapan araçla yazma/silme yapan aracı risk düzeyine göre ayırmak. Raporun ifadesiyle, araç sayısını artırmak ajanı akıllandırmaktan çok yavaşlatabilir.

Doğrulama ve güvenlik: "hata yapmasın" değil, "zarar sınırlı olsun"

Raporda doğrulama, ajan döngüsünün en sık ihmal edilen halkası olarak geçiyor. Model, yazdığı kodun çalışıp çalışmadığını kendi başına bilemez; bunu ancak ortamdan gelen geri bildirimle öğrenir. TÜBİTAK BİLGEM YTE Araştırma Serisi Sayı 42'ye göre en güçlü geri bildirim kaynağı testlerdir; derleyici, tip denetimi, lint ve mimari kural testleri (ArchUnit, dependency-cruiser, import-linter, NetArchTest gibi) bunu tamamlar. Rapor, test paketinin hızının ajanlı projelerde doğrudan bir verimlilik ölçütü hâline geldiğini belirtiyor.

İkinci katman insan onayıdır: koda dokunmadan önce plan çıkaran "plan modu" ve geri döndürülmesi zor eylemler (silme, push, veritabanı değişikliği, dış API çağrısı) için onay kapıları. Üçüncü katman, temiz bağlamla açılan bir "gözden geçirici" alt ajandır; rapor bunun maliyetli olduğu için kritik değişikliklere saklanmasını, son kararın ise insanda kalmasını öneriyor.

Güvenlik tarafında rapor üç soru soruyor: ajan neyi yapabilir (izin modeli), nerede yapabilir (yalıtım) ve kimin sözünü dinler (istem enjeksiyonu). Özellikle iki noktanın altını çiziyor:

• İzin yorgunluğu: Her küçük adımda onay isteyen ajan, kullanıcıyı okumadan onaylamaya iter. Çözüm, izni eylemin türüne ve etki alanına göre ayrıştırmak: çalışma dizini içindeki sık ve düşük riskli işler serbest, dışına çıkanlar onaylı.
• Ölümcül üçlü: Simon Willison'ın çerçevesine göre özel veriye erişim, güvenilmeyen içeriğe maruz kalma ve dışarıya veri gönderebilme aynı ajanda birleştiğinde yapısal bir sızıntı kanalı açılır. Rapor, bu üç ayaktan en az birinin kırılmasını öneriyor.

Sanal alan (sandbox) bölümünün özeti de pratik: amaç gerçekçi olmayan bir "ajan hata yapmasın" hedefi değil, "hata yaptığında zarar sınırlı ve geri alınabilir olsun" hedefini mühendisliğe dönüştürmek. Yerel kullanımda bunun en basit hâli, ajanı ayrı bir dalda çalıştırmak ve sık commit almaktır.

Çoklu ajan: önce geniş keşif, sonra dar uygulama

TÜBİTAK BİLGEM YTE Araştırma Serisi Sayı 42, çoklu ajan mimarisini özünde bir bağlam ölçekleme tekniği olarak tanımlıyor: iş, her biri kendi temiz bağlamına sahip ajanlara bölünür. En yaygın ve en düşük riskli biçim alt ajandır; alt ajan onlarca dosyayı okuyup ana ajana yalnızca kısa bir özet döndürür.

Rapor aynı zamanda bu yaklaşımın maliyetsiz olmadığını, koordinasyon yükünün ve token tüketiminin kazancı silebileceğini belirtiyor. Yönetici–işçi (orchestrator–worker) deseninde işçilere yalnızca hedef değil; çalışabilecekleri dosya aralığı, dokunmamaları gereken bileşenler, beklenen çıktı biçimi ve durma koşulu da verilmeli. Raporun karar kuralı şöyle: görev "önce geniş keşif, sonra dar uygulama" biçimindeyse keşif alt ajanlara dağıtılır, kod değişikliği tek bir ana ajanda toplanır. Adımlar birbirine sıkı bağlıysa tek ajan ve iyi bağlam disiplini hem daha güvenli hem daha ekonomiktir.

Rapor, açık kaynak OpenCode ajanını bu kavramların somut örneği olarak inceliyor: Build ve Plan modları, LSP ile her düzenleme sonrası tanılama geri beslemesi, Git tabanlı anlık görüntülerle geri alma, opencode.json ile komut düzeyinde izin kuralları ve .opencode/commands altında özel komutlar. Raporun bu karşılaştırmadaki tutumu da dengeli: soru "hangisi daha iyi" değil, hangi harness önceliklerinin hangi kullanım bağlamına uyduğu.

Pratikte: kendi iş akışınıza uygulama kontrol listesi

Opendart ekibinde WhatsMood uygulaması ve Opendart sitesi üzerinde Claude Code ve n8n ile çalışan ajanlar kullanıyoruz: kod yazan, test eden, yedek alıp canlıya alan, sosyal medya paylaşımı hazırlayan ajanlar. Raporu okurken en çok, deneyerek vardığımız kuralların bu çerçeveye ne kadar oturduğunu fark ettik. Aşağıdaki liste, raporun ilkelerini kendi deneyimimizle birleştiriyor:

1. Önce yedek, kopyada test, sonra canlı. Raporun "zarar sınırlı ve geri alınabilir olsun" ilkesinin en sade hâli. Canlı sisteme dokunan her ajan işi bu sırayı izlemeli; geri alma yolu iş başlamadan belli olmalı.
2. Ajana dar görev ve net kapsam verin. Hangi klasörde çalışacağı, nelere dokunmayacağı ve ne zaman duracağı yazılı olsun. Bu, raporun işçi ajanlar için önerdiği "açık sınırlar" ilkesinin tek ajanlı karşılığıdır.
3. Kural dosyasını kısa tutun. AGENTS.md / CLAUDE.md'ye "bilinmesi faydalı" değil, "yanlış yapılmaması gereken" maddeleri yazın; ayrıntıyı ayrı belgelere taşıyın.
4. Gizli anahtarları ayrı tutun. Şifre ve API anahtarlarını kodun ve kural dosyasının dışında, ayrı bir klasör veya ayar katmanında saklayın. Bu, ölümcül üçlünün "özel veri" ayağını daraltır.
5. Riskli işlemleri izin sistemine bağlayın. Silme, push, veritabanı yazma ve dış servise gönderim insan onayına düşsün; okuma ve test çalıştırma serbest kalsın. Böylece izin yorgunluğu oluşmaz.
6. Doğrulamayı tek komuta indirin. Ajanın kendi başına çalıştırabileceği hızlı bir test/derleme komutu, ajana verebileceğiniz en değerli araçtır.
7. Araçları ve MCP sunucularını azaltın. Her yeni bağlantıyı yeni bir yetki alanı olarak değerlendirin.
8. Tekrarı kalıcılaştırın. Üçüncü kez yazdığınız istemi komuta, üçüncü kez tarif ettiğiniz çok adımlı işi yeteneğe (skill) dönüştürün.
9. Ölçün. Rapor, geçmişte yapılmış küçük bir gerçek görev setini harness'taki her değişiklikten sonra yeniden çalıştırmayı öneriyor; "daha iyi hissettiriyor" bir ölçüt değil.

Örnek olarak, bir projenin kök dizinine konabilecek kısa bir kural dosyası şöyle olabilir:

# AGENTS.md (örnek)

## Komutlar
- Derleme: ./build.sh
- Test: ./test.sh  (her değişiklikten sonra çalıştır)

## Kurallar
- Canlı klasöre doğrudan yazma. Önce yedek al, değişikliği kopyada dene.
- Yalnızca görevde belirtilen klasörde çalış; kapsam dışı dosyaya dokunma.
- Gizli anahtarları okuma, loglama veya koda yazma (secrets/ klasörü yasak).
- Silme, git push ve veritabanı yazma işlemlerinden önce onay iste.
- Emin değilsen dur ve sor; varsayım yapma.

## Ayrıntılı belgeler (yalnızca gerektiğinde oku)
- Mimari: docs/mimari.md
- Yayına alma adımları: docs/yayin.md

Sık Sorulan Sorular

Harness mühendisliği ile prompt (istem) mühendisliği arasındaki fark nedir?

TÜBİTAK BİLGEM YTE Araştırma Serisi Sayı 42'ye göre istem mühendisliği tek bir etkileşimin çıktısını iyileştirmeye odaklanır ve her görevde yeniden yapılır. Harness mühendisliği ise bağlamı, araçları, doğrulama döngülerini, izinleri ve çoklu ajan koordinasyonunu kapsar; bir kez doğru kurulduğunda bütün görevlerin kalitesini kalıcı olarak etkiler.

Her işte birden fazla ajan kullanmak daha mı iyidir?

Hayır. Rapor çoklu ajanı varsayılan çalışma biçimi değil, seçici kullanılan bir ölçekleme aracı olarak görüyor. Paralel keşif gerektiren geniş işlerde fayda sağlar; adımları birbirine bağlı tipik kod yazma işlerinde ise çakışma ve maliyet nedeniyle tek ajan genellikle daha doğru tercihtir.

Kodlama ajanını tam otomatik modda çalıştırmak güvenli mi?

Rapora göre bu, ortamın yalıtımına ve doğrulama altyapısının gücüne bağlıdır. Yalıtılmış bir ortamda, kolayca silinebilen bir dalda ve iyi bir test paketiyle geniş yetki makul olabilir; gerçek makinede ve canlı verilerle tam otomasyon yüksek risklidir. Geri döndürülmesi zor işlemleri onaya bağlamak en pratik orta yoldur.

Sonuç

TÜBİTAK BİLGEM YTE'nin bu çalışması, kodlama ajanlarıyla çalışanlar için Türkçe kaynaklar arasında derli toplu bir harita sunuyor. Ana tezi net: ajandan memnun değilseniz ilk bakmanız gereken yer model değil, kendi harness yapılandırmanız. Bağlam dosyası, araç seti, izin politikası ve doğrulama altyapısı sizin kontrolünüzdeki ayar noktalarıdır. Rapor ayrıca bu yapılandırmanın kişisel alışkanlık olarak kalmamasını, depoda sürümlenen ve ekipçe incelenen bir mühendislik varlığına dönüşmesini öneriyor. Kendi deneyimimiz de aynı yönde: ajanlara güveni, onları daha zeki saymak değil; yedek, test, dar kapsam ve onay kapılarıyla hatalarını küçük ve geri alınabilir tutmak sağlıyor. Raporun tamamını okumanızı öneririz.

Kaynak: TÜBİTAK BİLGEM Yazılım Teknolojileri Araştırma Enstitüsü (YTE), Araştırma Serisi Sayı 42, "Kodlama Ajanı Kullanıcıları İçin Harness Mühendisliği", Yazar: Muhsin Özbek, 2026. Yayın sayfası: bilgem.tubitak.gov.tr/yayinlar/yte-yayinlar/arastirma-serisi-yayinlari/ — PDF: 42.Sayi-KodlamaAjaniicinHarnessMuhendisligi.pdf