Agent Harness ve Harness Engineering Nedir?

Eylül 5, 2026

| Yorumlar&nbsp0

Prompt engineering’i öğrendik, context engineering’e alıştık; şimdi herkes “harness” diyor. Terim hem çok geniş hem çok spesifik olduğu için kafa karıştırıyor. Gelin bu yazıda harness’ın ne olduğunu, ne olmadığını ve neden 2026’da bu kadar konuşulduğunu, OpenAI ve Anthropic’in kendi anlattıklarıyla birlikte öğrenelim.

“Harness, ajanın (agent) çalıştığı ortamdır” cümlesini muhtemelen duydunuz. Doğru ama eksik; çünkü “ortam” dediğinizde okuyucu bir Docker container’ı mı, bir prompt dosyasını mı, bir bash script’ini mi anlamalı, belli değil. Bu yazının sonunda şunları yapabileceksiniz: harness’ı prompt engineering ve context engineering’den net biçimde ayırt edebileceksiniz, bir harness’ın hangi parçalardan oluştuğunu sayabileceksiniz ve bugün en çok konuşulan harness kalıbı olan loop yapısının neden işe yaradığını anlayabileceksiniz. Gerçek rakamlarla da konuşacağız: OpenAI’ın bir ekibi bu yaklaşımla beş ayda 1 milyon satır kod yazdırdı^[1]; o hikâyenin arkasında ne var, göreceğiz.

1. Kelimenin Kendisi: Harness Ne Demek?

İngilizcede harness, atın arabaya koşulmasını sağlayan koşum takımıdır. Yazılımcılar bu kelimeyi zaten uzun süredir test harness olarak kullanıyor: test edilen kodu çalıştıran, girdi veren, çıktıyı toplayan ve doğrulayan çerçeve. Ajan bağlamındaki anlamı da tam olarak bu: modelin kendisi dışında kalan her şey.

Bu tanım camiada bir formüle indirgendi ve neredeyse herkes aynı formülü kullanıyor^[5]^[6]:

Agent = Model + Harness

Model, düşünen kısım. Harness ise modelin hangi tool’lara erişeceğini, context’in nasıl yönetileceğini, işin ne zaman bittiğine kimin karar vereceğini, hatanın nasıl yakalanacağını ve bütün bunların nasıl kayıt altına alınacağını belirleyen yapı^[7]. Parallel’in özeti akılda kalıcı: “Aynı model, farklı harness, farklı sonuç.”^[7] Claude Code, Codex, Cursor ve Cline’ın altında benzer modeller çalışıyor; deneyimlerin farklı olmasının sebebi harness.

Bir örnek verelim. Claude Code’un altındaki Claude modeli, sizin API üzerinden çağırdığınız Claude modeliyle aynı. Ama API’den çağırdığınızda karşınızda dosya okuyamayan, komut çalıştıramayan, git’e dokunamayan bir sohbet arkadaşı var. Claude Code’da ise aynı model repo’yu geziyor, test koşturuyor, commit atıyor. Aradaki fark modelde değil, etrafına örülmüş harness’ta.

Harness engineering ise bu yapıyı bilinçli olarak tasarlama işi: ajana hangi tool’ları vereceğinize, hangi işlemleri yasaklayacağınıza, işin bittiğine neyin karar vereceğine (test mi, model mi), ilerlemenin nerede tutulacağına ve ajan hata yaptığında hangi kuralın ekleneceğine siz karar veriyorsunuz. Prompt yazmak modele ne yapacağını söylemek; harness engineering ise modelin neyi yapamayacağını ve neyi kanıtlamadan geçemeyeceğini kurmak. Bir cümleyle: model kendi başına güvenilir değilse, güvenilirliği modelin etrafına inşa edersiniz.

2. Buraya Nasıl Geldik: Üç Katmanın Kısa Tarihi

Harness engineering’in adı 2026 başında kondu ama pratiği çok daha eski. Hikâyeyi üç aşamada anlatmak en kolayı^[6]:

Prompt engineering (2022–2023)

ChatGPT’nin ilk günlerinde context window (bağlam penceresi) 4.000 token civarındaydı. Bu kadar dar bir alanda yapılabilecek tek şey, doğru kelimeleri bulmaktı: rolü tarif et, örnek ver, çıktı formatını söyle. Yani prompt engineering, modele nasıl konuşacağımızla ilgiliydi.

Context engineering (2024–2025)

Sonra tool calling, RAG ve MCP geldi. Artık soru “ne söyleyeyim” değil, “modelin önüne her adımda hangi bilgiyi koyayım” oldu. Anthropic’in Eylül 2025 tarihli yazısı bunu net tanımlıyor: context engineering, modelin bir çağrıda gördüğü her şeyi (sistem talimatları, tool tanımları, dışarıdan çekilen veri, mesaj geçmişi) her adımda yeniden seçip ayıklamaktır: neyi içeri alacağız, neyi dışarıda bırakacağız^[3]. Aynı yazının tek cümlelik özetini düz Türkçeyle söylersek: modele mümkün olduğunca az şey göster, ama gösterdiğin her şey işe yarasın. Gereksiz her token, modelin dikkatini asıl işten çalıyor.

Bu dönemin coding agent’ları (Cursor, Windsurf, Cline, Aider) tool calling ile repo’yu gezip yalnızca ilgili dosyaları okumayı öğrendi. İşler gerçekten iyileşti; ama görevler uzadıkça yeni bir sorun ortaya çıktı.

Context engineering’in tavanı

Sorunun adı context rot: pencere doldukça modelin performansı düşüyor, hem de sınıra çarpmadan çok önce^[3]^[8]. Buna verilen klasik cevap compaction (sıkıştırma) oldu: context dolmaya yaklaşınca geçmişi özetle, özetle devam et^[3].

Compaction işe yarıyor, ama bir bedeli var: ajan kendi geçmişini ne kadar iyi özetleyebiliyorsa o kadar ileri gidebiliyor. On iki saatlik bir görevde birkaç kez özet üstüne özet çıkınca şu tablolar çıkıyor: yarısı bitmiş özellikler, “tamamlandı” sanılan ama hiç test edilmemiş butonlar, özetin içinde kaybolmuş kararlar. Anthropic’in kendi gözlemi de bu yönde: model projeyi erkenden bitmiş ilan ediyor, yarım kalan işleri belgelemeden bırakıyor ve sonraki oturum neyin yapılıp neyin yapılmadığını anlayamıyor^[2]. Addy Osmani’nin özeti daha da net: model kendi işine fazla iyi not veriyor, bu yüzden “bitti” demeye fazla hevesli^[8].

İşte harness engineering, tam bu tavana çarpınca doğdu. Alt-ajanlar (sub-agent) ile hiyerarşik context yönetimi, çok ajanlı yapılar, dış dosyaya yazılan ilerleme notları… Bunların hepsi ayrı ayrı deneniyordu; 2026 başında hepsine birden bir isim verildi.

Şekil 1 — Üç katman iç içe. Prompt engineering “nasıl söylerim”, context engineering “ne gösteririm”, harness engineering “nasıl hareket etmesine izin veririm” sorusuna cevap verir. Dıştaki katman içtekileri kullanır, yerine geçmez [3][6].

3. Üç Katmanı Yan Yana Koyalım

Kafa karışıklığının büyük kısmı, üç terimin aynı şeyi anlatıyormuş gibi durmasından geliyor. Sorulan soruya göre ayırınca netleşiyor^[6]^[10]:

	Prompt engineering	Context engineering	Harness engineering
Cevapladığı soru	Modele nasıl söylerim?	Modele ne gösteririm?	Modelin nasıl hareket etmesine izin veririm?
Birimi	Tek bir çağrı	Bir oturum boyunca her çağrı	Oturumların tamamı, saatler/günler
Tipik araçlar	Sistem prompt’u, few-shot örnekler	Tool calling, RAG, MCP, compaction	Loop, alt-ajan, sandbox, test kapısı, ilerleme dosyası, log
Tipik hatası	Model yanlış anlıyor	Model doğru dosyayı bulamıyor / context dolup çürüyor	Model “bitti” diyor ama iş bitmemiş; iş yarım kalıyor; geri alınamaz hata yapıyor

Faros’un ifadesiyle harness engineering “otonomi ve kontrol”e odaklanıyor: modelin nasıl hareket ettiğini, tool’ları nasıl kullandığını ve kendi işini nasıl doğruladığını belirliyor^[6]. HumanLayer ise aynı şeyi ters taraftan söylüyor: ajan hatalarının çoğu “model sorunu değil, konfigürasyon sorunu”^[5]. Mitchell Hashimoto’nun (Terraform ve Vagrant’ın yaratıcısı) sıkça alıntılanan tarifi de bu bakışı özetliyor: ajan bir hata yaptığında sohbette düzeltip geçme; işin mühendisliğini ona göre yap, sistemi o hata bir daha çıkmayacak şekilde kur^[10]. Somut olarak: ajan testleri koşturmadan “bitti” dediyse, commit öncesi testleri otomatik koşturan bir hook ekle. Yanlış klasöre dosya yazdıysa, bunu yakalayan bir lint kuralı yaz. Bir API’yi yanlış kullandıysa, AGENTS.md‘ye tek satır not düş. Prod veritabanına dokunduysa, o izni kaldır. Düzeltme prompt’a değil, ajanın etrafındaki kurallara, testlere ve izinlere gidiyor; aynı hatayla bir daha uğraşmıyorsunuz.

4. Bir Harness Hangi Parçalardan Oluşur?

Kaynaklar farklı sayılar veriyor ama liste aşağı yukarı aynı^[6]^[7]^[12]:

Parça	Ne yapar?	Somut örnek
Tool orkestrasyonu	Hangi tool’lar var, nasıl zincirlenir, hata olunca ne olur	Dosya oku/yaz, bash, git, MCP server’ları
Doğrulama döngüleri	İşin bittiğine model değil, bir kontrol karar verir	Test, typecheck, lint, tarayıcıda UI kontrolü
Context ve bellek	Oturumlar arası bilgi taşıma	`progress.txt`, git geçmişi, `AGENTS.md`
Guardrail’ler	Yapılmaması gerekeni yapılamaz hale getir	Sandbox, izin sistemi, bütçe sınırı, onay adımı
Gözlemlenebilirlik	Ne olduğunu sonradan görebilmek	Log, trace, her adımın kaydı

Bu listeye bakınca “bunların hepsi zaten context engineering’de vardı” diyebilirsiniz; kısmen haklısınız. HumanLayer harness engineering’i context engineering’in bir alt kümesi olarak konumluyor^[5]; Faros ise ayrı bir katman olarak. İsimlendirme tartışması bir yana, listedeki ikinci ve dördüncü satır (doğrulama ve guardrail) context engineering döneminde pek konuşulmuyordu. Fark burada.

5. En Çok Konuşulan Kalıp: Loop

Şimdi harness engineering’i bu kadar popüler yapan asıl mekanizmaya gelelim. Fikir şaşırtıcı derecede basit: compaction ile context’i uzatmaya çalışmak yerine, her iterasyonda ajanı sıfır context ile yeniden başlat; hafızayı context’te değil, dosya sisteminde ve git’te tut.

Ralph

Bu kalıbın internette en çok yayılan hali Ralph oldu (adı Simpsons karakterinden geliyor). Ralph, aslında birkaç dosyalık bir bash script’i^[4]^[14]:

Önce bir PRD (ürün gereksinim dokümanı) yazılır, sonra bu doküman prd.json içinde küçük user story’lere bölünür. Her story’nin bir passes: false alanı vardır.
Bir bash döngüsü, her turda yeni bir ajan instance’ı başlatır (Claude Code ya da Amp).
Ajan prd.json‘daki en yüksek öncelikli tamamlanmamış story’yi seçer, yalnızca onu yapar.
Typecheck ve testler geçerse commit atar, story’yi passes: true yapar, öğrendiklerini progress.txt‘ye yazar.
Döngü, tüm story’ler geçene kadar devam eder.

while [ "$(jq '[.stories[] | select(.passes==false)] | length' prd.json)" -gt 0 ]; do
  claude -p "$(cat PROMPT.md)"     # taze context, tek story
done

Buradaki kritik nokta, her turun temiz context ile başlaması. Context çürümüyor, çünkü çürüyecek kadar dolmuyor. Kurumsal hafıza git geçmişinde ve progress.txt‘de yaşıyor^[4]. Codecentric’in gözlemine göre bu yaklaşımın başarısı büyük ölçüde story’lerin doğru boyutta olmasına bağlı: bir story tek context window’a sığmayacak kadar büyükse döngü takılıyor^[14].

Anthropic’in iki ajanlı yapısı

Anthropic, Kasım 2025’te yayımladığı yazıda aynı fikrin biraz daha yapılandırılmış halini anlatıyor^[2]^[11]. Benzetmeleri şu: uzun bir projeyi tek context’te bitiremeyen ajan, vardiya değişiminde önceki vardiyanın hiçbir şeyini hatırlamayan mühendisler gibi. Çözüm iki ayrı ajan:

Initializer agent yalnızca ilk oturumda çalışır: ortamı kuran init.sh‘i, claude-progress.txt dosyasını ve ilk git commit’ini oluşturur. Ayrıca kullanıcı isteğini 200’den fazla ayrıntılı özellik içeren bir JSON dosyasına açar; her özellik “failing” olarak başlar.
Coding agent her sonraki oturumda çalışır ve hep aynı ritüelle başlar: çalışma dizinine bak, git log‘u oku, ilerleme notlarını oku, uygulamanın temel işlevini çalıştırıp doğrula, sonra sıradaki tamamlanmamış özelliği seç.

Özellik listesinin JSON’da durması ve her özelliğin ancak uçtan uca doğrulandıktan sonra “passing” olması, modelin projeyi erkenden bitmiş ilan etmesini engelliyor^[2]. Yani “bitti mi?” sorusunu artık model değil, dosya cevaplıyor.

Şekil 2 — Ralph ve Anthropic’in iki ajanlı yapısının ortak iskeleti. Her tur temiz context ile başlar; neyin yapıldığı, neyin kaldığı ve neyin öğrenildiği diskte durur. “Bitti” kararını model değil, story listesindeki passes alanı verir [2][4].

6. Prod’da Ne Oluyor: OpenAI’ın Deneyi

Loop kalıbı bireysel geliştiriciler arasında yayıldı; ama harness engineering’in şirket ölçeğinde neye benzediğini en iyi anlatan kaynak OpenAI’ın Şubat 2026’da yayımladığı yazı^[1]^[13]. Rakamlar şöyle: Ağustos 2025’te boş bir repo ile başlayan ekip beş ayda yaklaşık 1 milyon satır kod ve 1.500 merge edilmiş PR üretti; günde mühendis başına 3,5 PR. Ekip 3 kişiden 7 kişiye büyüdü ve kodun tamamına yakınını Codex yazdı. Sloganları: “İnsanlar yönlendirir, ajanlar uygular.”

Bu ekibin harness’ından üç ders çıkıyor:

1. Uzun talimat dosyası yazmayın. Ekip önce dev bir AGENTS.md yazmayı denedi, sonra vazgeçti. Nihai hali yaklaşık 100 satır ve bir içindekiler tablosu gibi çalışıyor: asıl bilgi docs/ altında duruyor, ajan ihtiyacı olanı oradan okuyor. Gerekçeleri context engineering’den tanıdık: “Context kıt bir kaynak. Dev bir talimat dosyası, görevin kendisini, kodu ve ilgili dokümanları dışarı iter.”^[1] HumanLayer de aynı öneriyi veriyor: CLAUDE.md 60 satırın altında kalsın, otomatik üretilmesin, içine ne gireceğine insan karar versin^[5].

2. Ajanın kendi işini görebileceği geri bildirim döngüleri kurun. Ekip, Chrome DevTools Protocol entegrasyonuyla ajanın yaptığı UI değişikliğini kendisinin tarayıcıda kontrol etmesini sağladı; log, metrik ve trace’lerin olduğu lokal bir observability yığını kurdu. Böylece ajan bir bug’ı kendisi yeniden üretip düzeltip test edebiliyor; altı saatten uzun kesintisiz koşular bu sayede mümkün oldu^[1].

3. Kuralları lint’e çevirin, teknik borcu düzenli ödeyin. Katmanlı mimarinin bağımlılık kuralları özel linter’larla mekanik olarak zorlanıyor; “golden principles” denilen kurallara göre periyodik Codex görevleri repo’yu tarayıp sapmaları bulan refactor PR’ları açıyor. Ekip buna garbage collection diyor: teknik borç birikip sonra ödenen bir şey değil, sürekli ödenen bir abonelik^[1].

Yazının belki de en önemli cümlesi de şu: “Yazılım üretmek hâlâ disiplin istiyor; ama disiplin artık kodda değil, iskelede görünüyor.”^[1] Harness engineering’in bir cümlelik tarifi buysa, budur.

OpenAI bu harness’ı ürünleştirdi de: Codex’in altındaki agent loop’u, CLI, IDE eklentisi, masaüstü ve web’in ortak kullandığı bir “App Server” olarak ayrıştırıp thread / turn / item primitifleriyle standart bir protokole dönüştürdüler^[9]. Yani harness artık uygulamanın içine gömülü bir detay değil, başlı başına bir katman.

7. Prompt ve Context Engineering Öldü mü?

Hayır, ve bu noktayı net söylemek gerekiyor. Cline gibi açık kaynak coding agent’ların kaynağına bakın; sistem prompt’u hâlâ uzun ve özenle yazılmış. Prompt engineering ajana kim olduğunu ve nasıl davranacağını söylüyor; context engineering her adımda önüne doğru bilgiyi koyuyor; harness engineering ise bu ikisinin üstünde, ajanı adım adım ilerleten, doğrulayan ve sınırlayan yapıyı kuruyor. Şekil 1’deki gibi: dıştaki katman içtekileri kullanıyor, yerine geçmiyor^[3]^[6].

Değişen şey ağırlık merkezi. 2023’te bir ajanı iyileştirmek için prompt’la oynardınız; 2025’te hangi tool’u verip hangi dosyayı okutacağınıza kafa yorardınız; 2026’da ise ajanın hata yaptığı yere bir test, bir lint kuralı, bir izin sınırı ya da bir ilerleme dosyası koyuyorsunuz. Faros’un aktardığı bir ölçüm bunun ne kadar önemli olduğunu gösteriyor: 211 gerçek mühendislik görevinde, güçlü bir harness’la eşleştirilmiş açık kaynak modeller pahalı frontier modellerle başa baş ya da daha iyi sonuç vermiş^[6]. Harness, modeller arasındaki farkı kapatabiliyor.

8. Kapanış: Kendi Harness’ınıza Nereden Başlarsınız?

“Harness engineering” adı 2026’da konuldu; sub-agent’lar, ilerleme dosyaları, test kapıları gibi altındaki pratiklerin çoğu ondan önce de vardı. Bu yüzden terime “yeni ambalajda eski mal” demek kısmen haklı. Ama isimden bağımsız, sahada somut bir şey değişti: bir ajan hata yaptığında ilk refleks artık prompt’u düzeltmek ya da daha büyük model beklemek değil, modelin etrafına test, loop, izin ve log koymak. Yazının tamamını bu tek cümleye indirgeyebilirsiniz. Bunu kendi işinizde nasıl uygularsınız, altı adımda toparlarsak:

#	Adım	Neden
1	İşi küçük, doğrulanabilir parçalara bölün (PRD → story listesi)	Bir story bir context’e sığmalı; “bitti” kararı dosyada olmalı
2	Hafızayı diske taşıyın: `progress.txt` + git	Context’e güvenmek yerine yeniden başlatılabilir olun
3	Her turu bir kapıdan geçirin: test, typecheck, lint	Model kendi işine iyi not verir; kapı vermez
4	`AGENTS.md`‘yi kısa tutun, derin bilgiyi `docs/`‘a koyun	Context kıt; talimat dosyası görevi dışarı itmesin
5	Ajan her hata yaptığında prompt’u değil, hatayı yakalayacak kuralı ekleyin: test, lint kuralı, hook, izin sınırı ya da `AGENTS.md`‘ye bir satır	Aynı hata aynı şekilde bir daha yapılamasın; prompt düzeltmesi bir sonraki oturumda unutulur, kural unutulmaz
6	Her adımı loglayın	Altı saatlik koşuda ne olduğunu sonradan görmeniz gerekecek

Ve şunu unutmayın: bu listedeki hiçbir madde yeni bir model gerektirmiyor. Bir bash döngüsü, bir JSON dosyası ve zaten sahip olduğunuz test suite’i ile başlayabilirsiniz. Ralph’ın repo’sunun bu kadar küçük olması, Anthropic’in örnek harness’ının birkaç dosyadan ibaret olması tesadüf değil^[4]^[11]. Harness engineering’in iyi haberi bu: en etkili kısmı, en basit kısmı.

Kaynaklar

Bir yanıt yazın Yanıtı iptal et

Yorum yapabilmek için oturum açmalısınız.