Harness engineering nedir: yapay zeka ajanını işe yarar bir araca nasıl dönüştürürsünüz

Harness engineering sade bir dille

Harness engineering, bir dil modelinin etrafında onun gerçek işi güvenilir biçimde yapabileceği bir ortamın nasıl kurulacağını anlatan bir mühendislik disiplinidir. Harness kelimesi "koşum takımı" anlamına gelir. Model güçlüdür, ama tek başına nereye gideceğini, hangi aracı kullanacağını ve ne zaman duracağını bilmez. Harness bu gücü yönlendirir.

En kısa formül şudur:

Ajan = Model + Harness

Model, akıl yürütebilen ve metin ya da kod yazabilen ağırlıklardır. Harness ise geri kalan her şeydir: sistem talimatları ve CLAUDE.md ya da AGENTS.md gibi dosyalar, araç takımı (shell, dosya düzenleme, MCP sunucuları), ajanın komutları çalıştırdığı sandbox, oturumlar arasında durumu tutan dosyalar ve ajana hatalarını bildiren testler, linter'lar ve hook'lar. Harness'i kaldırırsanız geriye yalnızca metinle yanıt verebilen bir sohbet kalır.

Ajan neden bazen "kıdemli", bazen "junior" gibi davranır

Tanıdık bir durum: bir depoda ajan deneyimli bir geliştirici gibi çalışır, başka bir depoda dünkü kararları unutur, bir de çalışmayan bir özelliği "hazır" diye bildirir. İlk tepki genellikle daha yeni bir modele geçmektir. Ancak iki durumda da model aynıdır, yani genellikle bu işe yaramaz. Fark ortamdadır.

Harness engineering'in ana bakış değişikliği burada başlar: ajan bozuk değildir, bozuk olan etrafındaki şeydir. Ajanın testlere erişimi yoksa testleri çalıştıramaz. Bir şey yazılmamışsa, daha önce neyi denediğini hatırlayamaz. Hiçbir kontrol bir özelliğin bozuk olduğunu söylemiyorsa bunu fark edemez. Bunlar modelin "karakter" özellikleri değil, tasarım kusurlarıdır ve sistematik olarak düzeltilebilirler.

Kötü bir harness'in tipik belirtileri

• Her yeni oturum ortamı onarmakla başlar: yanlış bağımlılıklar, veritabanı açılmıyor, değişkenler eksik.
• Ajan, önceki oturumu hatırlamadığı için daha önce reddedilmiş çözümleri tekrar eder.
• Kural talimatlarda açıkça yazılıdır, ama ajan onu görmezden gelir.
• "Testler yeşil" diyor, ama özellik bozuk, çünkü testler başka bir şeyi kontrol ediyordu.
• Ajan aynı anda üç görev üstlenir ve hiçbirini bitirmez.

Harness beş bileşenden oluşur

Yaygın hata, harness'i tek bir prompt dosyası sanmaktır. Oysa bu beş mekanizmanın birleşimidir ve her biri kendi biçiminde bozulur.

Talimatlar

Talimatlar "ajan doğru kuralı bulacak mı?" sorusunu yanıtlar. İyi bir giriş dosyası bir ders kitabı değil, bir haritadır: kısa bir içindekiler, kontrol komutları ve sert sınırlar. Ayrıntılar ise ajanın gerektiğinde açtığı ayrı belgelerdedir. İyi talimatlar değişmez kuralları tanımlar ("tüm SQL sorguları parametreli olsun"), her satırın nasıl yazılacağını dikte etmez.

Araçlar

Ajan yalnızca erişebildiği şeyi kontrol edebilir. Linter'ı çalıştıramıyorsa, "commit'ten önce linter'ı çalıştır" kuralı işe yaramaz. Araçlar, ajanın yerleşik yeteneklerinden (dosya okuma-yazma, komut çalıştırma) ve MCP üzerinden bağlanır. MCP, ajana veritabanlarına, tarayıcıya ve görev takip sistemlerine erişim veren bir protokoldür.

Ortam

Ortam, ajanın komutları çalıştırdığı yerdir. Tek bir komutla açılmalı, oturumdan oturuma aynı kalmalı ve hatanın zararını sınırlamalıdır: üretime erişimi olmayan bir sandbox, ayrı bir branch veya çalışma kopyası, ve her şeyi bir dakika içinde başlangıç durumuna döndürme imkanı.

Durum

Modelin oturumlar arasında hafızası yoktur: depoya yazılmayan her şey context penceresiyle birlikte kaybolur. Bu yüzden hedef, yapılanlar, alınan kararlar, çıkmaz yollar ve sonraki adım dosyalarda yaşamalıdır. Kontrolü basittir: yeni bir oturum açın, ajana "devam et" deyin ve işe başlayıp başlamadığına, yoksa ne yapacağını sormaya başlayıp başlamadığına bakın.

Geri bildirim

Geri bildirim döngüleri en önemli bileşendir. Onlar olmadan ajan kendi tek hakimidir ve görevi bitmiş saymakta samimidir. Testler, tip kontrolü, linter, her değişiklikten sonra çalışan bir hook, tarayıcıda E2E senaryosu: bunların hepsi hata hâlâ ucuzken ajana kırmızı sinyal verir.

Harness bir liste değil, bir döngüdür

Beş bileşen kapalı bir döngü gibi çalışır. Model talimatları alır, araçlarla ortamda hareket eder, depoda değişiklik yapar ve doğrulama sonucu kontrol eder. Kırmızı sonuç düzeltme için modele geri döner, yeşil sonuç durumda kaydedilir. Durum da bir sonraki oturumun talimatlarını günceller.

talimatlar → model → araçlar → ortam → değişiklikler
                ↑                              ↓
                └──── kırmızı ── doğrulama ────┘
                                     ↓ yeşil
                                 durum → (sonraki oturum)

Oklardan birini kaldırın, döngü tam orada kopar. Doğrulama yoksa ajan hatayı fark etmez. Durum yoksa bir sonraki oturum işe başlamak yerine eski izleri aramakla geçer. Bu yüzden bir bileşene yapılan yatırım başka bir bileşendeki açığı kapatmaz: beş sayfalık bir AGENTS.md eksik testlerin yerini tutmaz.

Harness engineering, prompt ve context engineering'den nasıl ayrılır

Bu kavramlar birbirlerinin içinde yer alır, birbirleriyle yarışmazlar.

Prompt engineering, talimatlar bileşeninin bir parçasıdır. Context engineering, talimatlar ve durum bileşenlerinin ikisini de kapsar: ajanın her an neyi gördüğünü. Harness engineering ise context'e sığmayan şeyleri ekler: erişim, sandbox, testler, hook'lar ve iş süreci. İyi yazılmış bir prompt, ajan testleri çalıştıramıyorsa işe yaramaz.

Uzun görevlerin matematiği: harness neden gerekli

İnsan sezgisi, adımların %95'ini doğru yapan bir modelin neredeyse mükemmel olduğunu düşünür. Ancak ajanın görevi birçok adımdan oluşur ve hatalar birikir. Adımlar bağımsızsa, hiçbir hata yapmadan hepsini geçme olasılığı olasılıkların çarpımıdır:

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

Onuncu adıma kadar hiç hata yapmadan yalnızca yaklaşık %60 çalıştırma ulaşır, ellinci adıma ise on çalıştırmadan birinden az. Modeli %97'ye çıkarmak pahalıdır ve sizin elinizde değildir. Ancak hatayı aynı adımda yakalamak ve ajana geri vermek harness'in işidir. Geri bildirim döngüsü, "bir hata bir sonrakini çeker" zincirini kısa, düzeltilebilir adımlardan oluşan bir zincire dönüştürür.

Örnek: aynı ajan, iki depo

Görev: FastAPI ile yazılmış bir ödeme backend'ine promosyon koduyla indirim eklemek.

Harness olmadan

Ajan birkaç dosya okur, indirim hesaplama fonksiyonunu ve yalnızca bu fonksiyonu izole olarak kontrol eden bir unit test yazar. Test yeşil çıkar, ajan "hazır" yazar. Toplam tutarın hesaplandığı modülü bilmiyordu ve veritabanını kaldırıp sipariş akışının tamamını çalıştıramadı. Bir gün sonra sepette indirimin hiç uygulanmadığı ortaya çıkar.

Harness ile

Kökte birkaç düzine satırlık bir AGENTS.md vardır: ortamın nasıl kaldırılacağı, hangi kontrol komutlarının zorunlu olduğu, ödeme mimarisinin nerede anlatıldığı. Ortam docker compose up -d ile açılır. Depoda, bitiş ölçütü yazılı bir plan dosyası vardır: "promosyon kodlu sipariş akışının E2E senaryosu geçer". Her değişiklikten sonra bir hook linter ve tip kontrolünü çalıştırır, ajan tamamlamadan önce E2E testini çalıştırmak zorundadır.

# AGENTS.md (kısım)
## Kontrol — "hazır" demeden önce zorunlu
make lint        # ruff + mypy
make test        # pytest, unit ve integration
make e2e         # sipariş akışı senaryosu

## MUST
- Para tutarları kuruş cinsinden tam sayı (int) ile hesaplanır, asla float ile değil
- Tüm SQL sorguları parametreli olur
- Üretimde uygulanmış migration'lar değiştirilmez

Model aynıdır. Ama artık ajan, proje haritası sayesinde tutar hesaplayan modülü bulur, E2E testi ilk denemede başarısız olur, ajan indirimin sepete ulaşmadığını görür, düzeltir ve yalnızca yeşil bir çalıştırmadan sonra rapor verir. Sonuç farkının tamamı harness'in katkısıdır.

Nereden başlamalı

1. Ajanın işini nasıl doğruladığını yazın: zorunlu olarak çalıştırması gereken bir ila üç komut. Geri bildirim en büyük etkiyi sağlar, bu yüzden başlangıç burasıdır.
2. Ortamı tekrarlanabilir hale getirin: tek komutla açılsın ve hızlıca geri alma yolu olsun.
3. Bir durum dosyası oluşturun: hedef, yapılanlar, kararlar ve çıkmaz yollar, sonraki adım.
4. Talimatları bir haritaya indirgeyin: kontrol komutları, sert kurallar, ayrıntılı belgelerin bağlantıları.
5. Ajanın hatalarının bir günlüğünü tutun: her arızada hangi bileşenin sorumlu olduğunu not edin. Günlük, bir sonraki düzeltmenin nerede olduğunu gösterecektir.

Faydalı bir alıştırma: beş bileşenin her birini 1 ile 5 arasında puanlayın, en zayıf olanına yarım saat ayırın ve aynı beş tipik görevi düzeltmeden önce ve sonra çalıştırın. Böylece harness iyileştirmeleri "hissedilen" değil, ölçülebilir olur.

Sonuç

Harness engineering, modele değil, onu çevreleyen her şeye yapılan bir çalışmadır: talimatlar, araçlar, ortam, durum ve geri bildirim döngüleri. Ajanın güvenilirliği bu döngünün en zayıf halkasıyla belirlenir. Bu yüzden modeli değiştirmek nadiren istikrarsızlığı düzeltir, eklenen tek bir test ya da plan dosyası ise çoğu zaman düzeltir. Beş bileşenin ve harness'in bütününün nasıl kurulacağı, tek bir proje üzerinden uygulamalı bir kursta ele alınmıştır.