Harness vs context engineering: harness mühendisliği prompt ve context mühendisliğinden nasıl ayrılır

Kısaca: aynı görevin üç katmanı

Prompt engineering "nasıl sorulur" sorusunu, context engineering "model şu anda neyi bilmeli" sorusunu, harness engineering ise "ajan hangi ortamda çalışır ve hatalı olduğunu nasıl öğrenir" sorusunu yanıtlar. Bunlar birbiriyle rekabet eden yaklaşımlar değil, iç içe geçmiş katmanlardır: iyi bir prompt iyi bir context'in parçasıdır, dikkatle kurulmuş bir context ise harness'in bileşenlerinden biridir.

Karışıklık, üçünün de modelin davranışını değiştirmesinden kaynaklanır, ama kaldıraçları farklıdır. Ajan testleri çalıştıramıyorsa, prompt'taki hiçbir kelime bunu düzeltmez. Ajan dünkü kararları unutuyorsa, sorun istek metninde değil, durumun nerede tutulduğundadır. Harness vs context engineering farkını anlamak haftalar kazandırır, çünkü ortam bozukken talimatları yeniden yazmazsınız.

Prompt engineering: tek bir isteğin ifadesi

Prompt engineering, istek metni üzerindeki çalışmadır: rol, görev, yanıt biçimi, örnekler (few-shot), kısıtlar, adımların sırası. Çalışma birimi tek bir model çağrısıdır. Sonuç yanıttan değerlendirilir: doğru mu, doğru biçimde mi, model konudan saptı mı?

Tipik teknikler:

• Çıktı biçimini açıkça tarif edin (JSON şeması, tablo, liste);
• 2 ila 3 örnek verin: "girdi → doğru çıktı";
• Yanıttan önce adım adım düşünmesini isteyin;
• Talimatı ve veriyi net ayraçlarla ayırın;
• Neyin yapılmayacağını söyleyin.

Prompt engineering "bir girdi — bir yanıt" görevlerinde iyi çalışır: sınıflandırma, veri çıkarma, çeviri, bir şablona göre metin üretme. Sınırı, model eyleme geçtiğinde görünür: araç çalıştırmak, dosya değiştirmek, arka arkaya onlarca adım atmak. Orada kalite artık tek bir cümleye değil, modeli çevreleyen tüm ortama bağlıdır.

Context engineering: model penceresine ne girer

Context engineering, her adımda context penceresinin içeriğini yönetmektir. Pencere sınırlıdır ve uzun bir oturumda ajan komut çıktılarını, dosya içeriklerini ve konuşma geçmişini biriktirir. Amaç, her an gereken şeyin orada olması ve gereksiz şeylerin olmamasıdır.

Buna girenler:

• Seçim: göreve göre hangi dosyaların, belgelerin ve kod parçalarının yükleneceği (arama, RAG, ihtiyaç anında okuma);
• Sıkıştırma: uzun geçmişin özetlenmesi, komut çıktılarının kırpılması, oturumun compaction'ı;
• Yapı: giriş dosyasının bir içindekiler gibi olması, ayrıntıların ajanın gerektiğinde açtığı ayrı belgelerde durması;
• İzolasyon: bir yan işi, ana akışı kirletmemesi için kendi temiz context'i olan bir subagent'a vermek.

Context engineering'in ölçüsü şudur: ajan doğru kuralı veya bilgiyi doğru anda buldu mu, gürültüde boğuldu mu? Tipik belirti: kural CLAUDE.md'ye yazılmıştır, ama ajan onu ihlal eder, çünkü dosya beş sayfa ve kural geri kalan içerikte kaybolmuştur.

Harness engineering: modelin etrafındaki her şey

Harness ("koşum takımı"), ajanın çalıştığı ortamdır. Model bu ortamda, döngüye bir kez giren bir bileşendir. Geri kalan her şeyi, yani talimatları, araçları, ortamı, durumu ve geri bildirimi, bir mühendis tasarlar. Harness engineering yalnızca kodu yazabilen değil, aynı zamanda çalıştırabilen, kontrol edebilen, hatasını öğrenebilen ve bir sonraki oturumda kaldığı yerden devam edebilen bir ajan için sorumludur.

Harness'i beş bileşene ayırmak faydalıdır:

Bu şemada context engineering ilk iki bileşenin içinde yaşar: talimatların ve araç çıktılarının pencereye nasıl girdiğini belirler. Harness ise context'e sığmayan şeyleri ekler: işleyen bir kontrol komutu, tekrarlanabilir bir ortam, yeniden başlatmayı atlatan bir durum dosyası.

Karşılaştırma tablosu

Neden tek başına prompt ve context yetmez

Klasik bir hikâye: ekip ajanın hata yaptığını görür ve bir hafta boyunca beş sayfalık bir AGENTS.md yazar. Ajan yine de commit'ten önce linter'ı çalıştırmaz. Sebep metinde değildir: ajanın doğru yetkilerle bir shell'i yoktur ve linter imajda kurulu değildir. Bu bir araç ve ortam sorunuydu, ona talimatlarla çözüm aranıyordu.

İkinci hikâye: ajan üst üste üçüncü oturumda aynı hatayı düzeltmeye çalışır, çünkü yeniden başlatmadan sonra daha önce neyi denediğini hatırlamaz. Oturum içindeki context engineering burada yardımcı olmaz, çünkü pencere temizlenir. Gereken durum bileşenidir: ajanın denemelerini ve kararlarını yazdığı bir dosya ve işe başlamadan önce onu okuma kuralı.

Üçüncü hikâye en pahalı olanıdır: ajan "hazır" yazar, unit testler yeşildir, ama özellik çalışmaz. "Dikkatli kontrol et" diyen bir prompt da, bağlama fazladan belge eklemek de ajana bağımsız bir kontrol vermez. Bunu yalnızca makineden gelen geri bildirim verir: uçtan uca test, bir doğrulama betiği veya yapanın gerekçelerini görmeyen ayrı bir değerlendirici.

Genel sonuç: prompt ve context modelin ne düşündüğünü etkiler. Harness ise modelin ne yapabildiğini ve bir eylemden sonra neyi öğrendiğini etkiler.

Neden modeli değiştirmek çözüm değildir

İstikrarsız bir ajana karşı yaygın tepki daha güçlü bir model almaktır. Bu genellikle sorunu çözmez: aynı model, iyi kurulmuş bir depoda deneyimli bir kıdemli gibi çalışır, ama kontrol komutları ve stack açıklaması olmayan bir depoda şaşırır. Daha güçlü bir model ekibinizin geleneklerini kendiliğinden bilmez, erişimi olmayan bir veritabanına ulaşamaz ve çalıştırılmamış bozuk bir migration'ı fark edemez.

Harness yeni modellerle eskimez. Talimatlar, tekrarlanabilir ortam ve kontroller her modele lazımdır. Değişen tek şey, ne kadar elle yönlendirmeye ihtiyaç olduğudur: güçlü bir model için değişmezler yeterlidir ("veri sınırda doğrulanır"), adım adım talimatlar gerekmez.

Hangi katmanı düzeltmeniz gerektiğini nasıl anlarsınız

Belirtilere bakmak, deneme yanılmadan daha hızlı teşhis koyar:

Harness'e nereden başlamalı

Sıfırdan kuruyorsanız pratik sıra şudur: geri bildirim → talimatlar → durum → ortam → araçlar. Geri bildirim önce gelir, çünkü onsuz diğer değişikliklerin etkisini ölçemezsiniz. "Çalışıyor mu, çalışmıyor mu" sorusuna dürüstçe yanıt veren bir komut yoksa, talimatlardaki her iyileştirme göz kararıyla değerlendirilir.

Minimal bir başlangıç kabaca şöyle görünür:

# AGENTS.md (kısım)
## Nasıl kontrol edilir
- make check   # lint, tip, unit testler
- make e2e     # uçtan uca senaryolar
Özellik ancak iki komut da 0 koduyla bittiğinde hazırdır.

## Kurallar
- MUST: tüm SQL sorguları parametreli olsun
- MUST: commit'ten önce make check çalıştır
- Ödeme ayrıntıları: docs/payments.md (görev ödemeyle ilgiliyse oku)

Son satıra dikkat edin: bu, harness'in içinde bir context engineering uygulamasıdır. Giriş dosyası bir ders kitabı değil, bir haritadır ve ayrıntılar "ne zaman" koşuluyla yüklenir.

Her bileşenin katkısını nasıl ölçersiniz

Harness'in prompt'ta olmayan bir metriği vardır: ajanın "hazır" dediği ama bağımsız kontrolün doğrulamadığı görevlerin oranı. Buna verification gap denir. Son 10 görevi alın, her biri için ajanın "hazır" deyip demediğini ve kontrolün geçip geçmediğini kaydedin. Ortaya çıkan oran, değişikliklerin karşılaştırılacağı bir ölçüdür.

Hangi bileşenin etkili olduğunu anlamak için ablation yöntemi kullanılır: model ve görev kümesi sabit tutulur, bileşenler teker teker kapatılır ve düşüşe bakılır. İki noktayı akılda tutun. Ablation'dan önce önce bir hata günlüğü tutun; darboğazı daha hızlı gösterir. Ve sıfır düşüş, bileşenin işe yaramadığı anlamına gelmez: seçilen görevler onu kullanmamış olabilir.

Sık yapılan hatalar

• Prompt dosyasını harness sanmak. Talimatlar beşte bir bileşendir. Tarif kitabı olan bir dolap mutfak değildir.
• Araç eksikliğini metinle tedavi etmek. "Her zaman testleri çalıştır" işe yaramaz, testler ajanın ortamında hiç çalışmıyorsa.
• Talimatları şişirmek. Dosya uzadıkça önemli kuralın okunmama olasılığı artar. Önemli kuralları çalışan kontrollere dönüştürün.
• Ajanın kendi raporuna güvenmek. Kendi işini değerlendiren bir model sonucu olduğundan iyi gösterme eğilimindedir. Kontrolü bir betik veya temiz context'li ayrı bir ajan yapmalı.
• Harness'i bir kez kurup bırakmak. Kod gibi eskir: kurallar gerçeklikten sapar, komutlar değişir. Düzenli gözden geçirilmelidir.

Sonuç

Prompt engineering isteğin ifadesini geliştirir, context engineering modelin penceresindeki bilgiyi seçer, harness engineering ise araçları, ortamı, durumu ve kontrolleri içeren tüm ajan çevresini kurar. Ajan uzun süre çalışıp kendi kodunu değiştirdiğinde harness belirleyici hale gelir: "ajan hazır dedi"yi "sistem çalıştığını doğruladı"ya dönüştürür. Bu yüzden harness vs context engineering bir "ya–ya" sorusu değildir: context harness'in bir parçasıdır ve belirtilerin işaret ettiği katmanı düzeltmek gerekir. Bu konu, bir ödeme backend'i üzerinde uygulamalı bir kursta ele alınmıştır.