Harness Mühendisliği: Gerçekten İşe Yarayan AI Ajanları Nasıl Geliştirilir?

Çoğu kişi AI agent'ları yanlış katmanda düzeltmeye çalışıyor.

Bir agent hata yaptığında prompt'u baştan yazıyorlar. Tekrar hata yaptığında daha fazla talimat ekliyor, modeli değiştiriyor, context penceresini büyütüyor ya da başka bir araç bağlıyorlar.

Sonra aynı sorunlar geri dönüyor.

Agent önemli bir kararı unutuyor. Yanlış aracı kullanıyor. Üç adım önce ne olduğunu gözden kaçırıyor. Sonucu kontrol etmeden görevin tamamlandığını iddia ediyor. Bütçe tükenene kadar başarısız olan aynı eylemi tekrar tekrar deniyor.

Sorun her zaman model değil.

Sorun, modelin etrafındaki ortam.

İşte bu ortama harness diyoruz.

Harness Engineering (Kontrol Ortamı Mühendisliği), bir modelin etrafına kurulan ve onun ne görebileceğine, ne yapabileceğine, neyi hatırlayacağına, başarının nasıl tanımlanacağına ve bir şeyler ters gittiğinde ne olacağına karar veren sistemi inşa etme pratiğidir.

Daha iyi bir prompt tek bir yanıtı iyileştirebilir.

Daha iyi bir harness ise her çalıştırmayı iyileştirir.

AI agent'ları, otomasyon ve production sistemleri hakkında daha fazla pratik analiz için Substack hesabımı takip edin:

substack.com/@lunarresearcher

1. Model, Agent'ın Kendisi Değildir

Bir model akıl yürütebilir, üretebilir, karşılaştırabilir ve seçim yapabilir.

Bu onu güvenilir bir agent yapmaz.

Gerçek bir agent'ın ayrıca doğru context'i bulması, araçları kullanması, state'i koruması, izinlere uyması, kendi işini doğrulaması ve ortam beklendiği gibi davranmadığında toparlanması gerekir.

Model yalnızca akıl yürütme motorudur.

Harness ise o akıl yürütmeyi gerçek bir uygulamaya dönüştüren her şeydir.

1KULLANICI TALEBİ
2      |
3      v
4+-----------------------------+
5|           HARNESS           |
6|                             |
7| sözleşme      context       |
8| araçlar       state         |
9| politika      doğrulama     |
10| izler         kurtarma      |
11+-----------------------------+
12      |
13      v
14    MODEL
15      |
16      v
17GERÇEK ORTAM

Aynı modeli bir sohbet kutusuna koyun, soruları yanıtlar.

Onu terminal erişimi, testler, tarayıcı araçları, proje hafızası, kontrollü izinler ve bir inceleme döngüsü olan bir repository içine koyun; gerçek işleri tamamlayabilir.

Model değişmedi.

Değişen harness oldu.

2. Her Talebi Bir Sözleşmeye Dönüştürün

Doğal dil esnektir.

Otonom yürütme ise esnek olmamalıdır.

Şöyle bir talep:

Kullanıcıya ilk deneyim akışını (onboarding) iyileştir.

modelin yanında bir insan oturuyorsa gayet uygundur.

Ancak production ortamında bir talimat olarak felakettir.

Agent harekete geçmeden önce talebi sınırları belli bir görev sözleşmesine dönüştürün.

1objective: onboarding terk oranını düşür
2
3inputs:
4  - ürün özeti
5  - analitik verileri
6  - repository
7
8constraints:
9  - kimlik doğrulamayı koru
10  - veritabanı şemasını değiştirme
11  - mevcut mobil davranışı koru
12
13deliverable:
14  - incelenebilir pull request
15
16done_when:
17  - testler başarılı
18  - analitik olayı doğru tetikleniyor
19  - masaüstü akışı incelemeyi geçiyor
20  - mobil akış incelemeyi geçiyor
21
22approval_required:
23  - production dağıtımı

Buradaki kritik kısım done_when'dir.

O olmadan agent, sorunun biraz daha kolay bir versiyonunu çözüp görevin tamamlandığını büyük bir özgüvenle söyleyebilir.

Onunla birlikte tamamlanma ölçülebilir hale gelir.

Agent şunu sormamalıdır:

Sırada ne yapmalıyım?

Şunu sormalıdır:

Hangi eylem mevcut ortamı sözleşmedeki sonuca yaklaştırır?

Bu çok daha güçlü bir döngüdür.

3. Agent'a Dev Bir Context Penceresi Değil, Bir Harita Verin

Agent hatalarına verilen yaygın tepki, modele daha fazla context vermektir.

Daha fazla dokümantasyon.

Daha fazla konuşma geçmişi.

Daha fazla dosya.

Daha fazla araç çıktısı.

Sonunda agent her şeyi alır ama daha az anlar.

Context bir depolama alanı değildir.

Bir dikkat bütçesidir.

Her çalıştırmada tüm projeyi agent'ın önüne yığmak yerine, ona faydalı bilgilerin nerede olduğuna dair küçük bir harita verin.

1PROJE HARİTASI
2
3ürün kuralları     -> docs/product/
4mimari             -> docs/architecture.md
5frontend           -> apps/web/
6backend            -> services/api/
7testler            -> tests/
8komutlar           -> docs/commands.md
9güvenlik           -> docs/security.md

Sonra sadece gerektiğinde genişletin.

1GÖREV
2  |
3  v
4PROJE HARİTASI
5  |
6  v
7İLGİLİ SİSTEM
8  |
9  v
10TAM DOSYALAR
11  |
12  v
13YEREL TALİMATLAR

Kaynak materyal bunu aşamalı ifşa (progressive disclosure) olarak tanımlıyor: harness, sırf bilgi mevcut olduğu için değil, görev gerektirdiği için daha fazla bilgi yüklemelidir.

Hedef maksimum context değildir.

Hedef maksimum faydalı sinyaldir.

4. Model ile Araçları Arasına Bir Geçit Koyun

Yirmi araca sahip bir model otomatik olarak yirmi kat daha yetenekli olmaz.

Sadece hata yapmak için yirmi yeni yolu olabilir.

Her aracın bir sözleşmesi olmalıdır.

1ARAÇ: edit_file
2
3GİRDİLER
4path
5patch
6
7ÖN KOŞULLAR
8path mevcut
9path workspace içinde
10
11BAŞARI
12patch uygulandı
13diff döndürüldü
14
15HATA
16yapılandırılmış hata
17kısmi üzerine yazma yok
18
19RİSK
20geri alınabilir

Böylece yürütme yolu şu hale gelir:

1MODEL ÖNERİR
2      |
3      v
4GEÇİT DOĞRULAR
5      |
6      v
7POLİTİKA YETKİLENDİRİR
8      |
9      v
10ARAÇ ÇALIŞTIRIR
11      |
12      v
13HARNESS SONUCU KAYDEDER

Model hangi eylemi istediğine karar verir.

Harness ise o eylemin geçerli, izinli ve güvenli olup olmadığına karar verir.

Araçlar mesaj gönderebildiğinde, production ortamını değiştirebildiğinde, para harcayabildiğinde veya veri silebildiğinde bu ayrım kritik hale gelir.

İyi bir araç geçidi ayrıca zaman aşımları ekleyebilir, argümanları doğrulayabilir, dosya yollarını kısıtlayabilir, hataları standartlaştırabilir ve yeniden denemeleri güvenli hale getirebilir.

İyi araçlar, modelin tahmin etmek zorunda kaldığı şeylerin sayısını azaltır.

5. Hafızayı Konuşmanın Dışına Taşıyın

Konuşma, sistemin kayıt defteri olmamalıdır.

Uzun süre çalışan agent'lar eninde sonunda context limitlerine takılır, çöker, yeniden başlar veya işi başka bir oturuma devreder.

Eğer her önemli karar yalnızca konuşma dökümünün içinde varsa, iş akışı kırılgandır.

Kalıcı state'i ayrı bir yerde saklayın.

1{
2  "task_id": "feature_042",
3  "status": "verifying",
4  "current_step": "mobile_check",
5
6  "completed": [
7    "implementation",
8    "unit_tests",
9    "desktop_check"
10  ],
11
12  "decisions": [
13    "reuse existing export endpoint",
14    "preserve current date format"
15  ],
16
17  "artifacts": [
18    "export.csv",
19    "desktop-after.png"
20  ],
21
22  "open_risks": [
23    "mobile toolbar may overflow"
24  ],
25
26  "next_action": "render mobile viewport"
27}

Faydalı bir sistem hafızayı dört kategoriye ayırır:

1GERÇEKLER
2değişmeyen bilgi
3
4KARARLAR
5neyin ve neden seçildiği
6
7STATE
8mevcut çalıştırmanın neresinde olunduğu
9
10DERSLER
11gelecekteki çalıştırmaları etkilemesi gereken hatalar

Bir sonraki agent oturumu, önceki konuşmanın sıkıştırılmış bir özetini değil, işin mevcut state'ini devralmalıdır.

6. Tamamlanmanın Kapısını Kanıta Dayandırın

Bir agent'ın "bitti" demesi, işin gerçekten bittiğinin kanıtı değildir.

Bu sadece bir başka model çıktısıdır.

Harness'in gözlemlenebilir kanıta ihtiyacı vardır.

1İDDİA                     KANIT
2
3"hata düzeltildi"         hata veren test artık başarılı
4
5"sayfa çalışıyor"         tarayıcı akışı tamamlandı
6
7"veri doğru"              değerler kaynakla eşleşiyor
8
9"migration güvenli"       dry run + rollback başarılı
10
11"görev tamamlandı"        tüm kabul testleri başarılı

Önce deterministik kontrolleri kullanın.

1sözdizimi
2  |
3  v
4tipler
5  |
6  v
7odaklı testler
8  |
9  v
10entegrasyon testleri
11  |
12  v
13görsel / anlamsal inceleme
14  |
15  v
16insan onayı

Bir derleyicinin, testin, şemanın veya veritabanı sorgusunun kanıtlayabileceği bir şey için başka bir modele sormayın.

Modelleri değerlendirme için kullanın.

Gerçekler için deterministik sistemleri kullanın.

Model ürünü yaratır.

Ortam, o ürün hakkında kanıt üretir.

Harness ise kanıtın yeterli olup olmadığına karar verir.

7. İnşa Eden ile Doğrulayanı Ayırın

Kendi kendini incelemenin bir başka sorunu daha var.

Hatayı yapan agent, genellikle aynı varsayımları incelemeye de taşır.

Daha güçlü bir mimari, işçi ile doğrulayıcıyı birbirinden ayırır.

1İNŞA EDEN
2   |
3   v
4adayı oluşturur
5   |
6   v
7DOĞRULAYICI
8   |
9   +-- sözleşmeyi kontrol eder
10   +-- eksik durumları arar
11   +-- desteklenmeyen iddiaları test eder
12   +-- sonucu bozmaya çalışır
13   |
14   +------ BAŞARILI ------> KABUL ET
15   |
16   +------ HATA ------> KANITI GERİ GÖNDER

Doğrulayıcı şunu sormamalıdır:

Bu iyi görünüyor mu?

Şunu sormalıdır:

Bunu kabul edilemez kılacak şey nedir?

Bu, incelemeyi bir onaylama sürecinden çıkıp bir çürütme girişimine dönüştürür.

Kaynak materyal, doğrulamaya kendi ret kriterlerini ve ilk sonucu üreten varsayımlara meydan okuyabilecek kadar bağımsızlık verilmesini açıkça tavsiye ediyor.

8. İzinleri Modelin Dışına Taşıyın

Bazı kurallar asla modelin onları hatırlamasına bağlı kalmamalıdır.

1onay almadan asla yayınlama
2secret'ları asla açığa çıkarma
3harcama limitini asla aşma
4workspace dışına asla yazma
5çalıştırılmadıkça testlerin geçtiğini asla iddia etme

Bunlar prompt önerileri değildir.

Bunlar politikadır.

Basit bir izin merdiveni:

1DÜŞÜK RİSK
2
3oku
4ara
5incele
6
7-> otomatik
8
9GERİ ALINABİLİR
10
11workspace düzenle
12test çalıştır
13taslak oluştur
14
15-> otomatik + iz kaydı
16
17DIŞ ETKİ
18
19gönder
20dağıt
21satın al
22
23-> onay gerekli
24
25GERİ ALINAMAZ / HASSAS
26
27veri sil
28kimlik bilgilerini yenile
29global olarak yayınla
30
31-> katı geçit veya yasaklı

Sonuç ne kadar ciddiyse, kontrol de o kadar sıkı olmalıdır.

Model eylemi önerebilir.

Harness buna yetki verir.

Araç ise uygular.

Otonomi, kontrolün yokluğu değildir.

Belirlenmiş sınırlar içindeki özgürlüktür.

9. Körü Körüne Yeniden Denemeyi Bırakın

En kötü kurtarma politikalarından biri şudur:

Bir şey başarısız oldu. Tekrar dene.

Hiçbir şey değişmezse, sistem sadece aynı hatayı yeniden üretmek için para harcıyordur.

Önce hatalar sınıflandırılmalıdır.

1ARAÇ ZAMAN AŞIMI
2-> gecikmeli yeniden dene
3
4GEÇERSİZ ARGÜMANLAR
5-> araç çağrısını düzelt
6
7EKSİK CONTEXT
8-> eksik kaynağı getir
9
10BAŞARISIZ TEST
11-> hata veren davranışı incele
12
13İZİN REDDEDİLDİ
14-> onay iste
15
16ÇELİŞEN GEREKSİNİMLER
17-> üst seviyeye aktar
18
19DEĞİŞMEYEN TEKRARLANAN HATA
20-> dur

Faydalı bir agent döngüsü şöyle görünür:

1GÖZLEMLE
2   |
3   v
4KARAR VER
5   |
6   v
7EYLEME GEÇ
8   |
9   v
10ÖLÇ
11   |
12   +---- KABUL ET
13   |
14   +---- DÜZELT
15   |
16   +---- AKTAR
17   |
18   +---- DUR

Her döngünün deneme sayısı, süre, harcama ve yıkıcı etki kapsamı açısından sınırları olmalıdır.

Güvenilir bir agent nasıl devam edeceğini bilmelidir.

Ayrıca yeni bir denemenin ne zaman artık değmeyeceğini de bilmelidir.

10. Tekrarlanan Talimatları Altyapıya Dönüştürün

Diyelim ki prompt şunu içeriyor:

Her zaman formatlayıcıyı çalıştır.

Formatlayıcı otomatik çalışırsa bu kural çok daha güçlü olur.

Diyelim ki talimatlar şöyle diyor:

UI kodu doğrudan veritabanına erişemez.

Bu kural ihlal edildiğinde hata veren bir mimari testi olarak çok daha güçlüdür.

İlerleme şöyle görünür:

1AÇIKLAMA
2      |
3      v
4KONTROL LİSTESİ
5      |
6      v
7ŞABLON
8      |
9      v
10OTOMATİK KONTROL
11      |
12      v
13UYGULANAN POLİTİKA

Prompt değerlendirmeyi açıklamalıdır.

Harness ise değişmez kuralları uygulamalıdır.

Tekrarlayan her hata, bu merdivende biraz daha aşağı inmeli.

Sonunda modelin o dersi hatırlamasına gerek kalmaz.

Ortam, onu model adına hatırlar.

11. Çalıştırmayı Kaydedin

Kusursuz bir nihai ürün, berbat bir yürütme yolunu gizleyebilir.

Belki agent yanlış kaynağa erişti.

Belki başarısız bir komutu görmezden geldi.

Belki harici bir eylemi iki kez tekrarladı.

Belki beklenen bütçenin on katını harcadı.

Belki doğru cevabı yanlış sebeple buldu.

Ne olduğunu yeniden yapılandıracak kadar bilgi kaydedin.

109:14  görev sözleşmesi oluşturuldu
209:15  architecture.md yüklendi
309:17  checkout.ts düzenlendi
409:18  odaklı test başarısız oldu
509:21  uygulama düzeltildi
609:22  odaklı test başarılı oldu
709:24  entegrasyon testi başarılı oldu
809:25  dağıtım engellendi: onay gerekli

Faydalı izler; context kaynaklarını, araç çağrılarını, state değişikliklerini, doğrulama sonuçlarını, yeniden deneme nedenlerini, onay kararlarını, maliyeti ve gecikmeyi içerir.

Amaç eğlence olsun diye log toplamak değil.

Amaç hatayı yerel tutmak.

1. adımda bir şey kırılırsa, sadece 18. adımı düzeltebilmelisiniz.

Tüm çalıştırmayı baştan oynatmak zorunda kalmamalısınız.

12. Her Çalıştırmaya Bir Makbuz Verin

İnsanı kırk mesajlık bir dökümü incelemeye zorlamayın.

Sonucu küçük bir makbuza dönüştürün.

1HEDEF
2
3Kuponun çift uygulanması hatasını düzelt.
4
5DEĞİŞTİRİLENLER
6
7checkout doğrulaması
8regresyon testi
9
10DOĞRULANANLAR
11
12lint başarılı
13birim testleri başarılı
14entegrasyon testi başarılı
15
16DOĞRULANMAYANLAR
17
18production ödeme sağlayıcısı
19
20RİSKLER
21
22eski mobil istemci kullanılamıyor
23
24ONAY GEREKLİ
25
26staging'e dağıtım

Bu, modelin gerçekleştiğini iddia ettiği şeylerin bir özeti değildir.

Harness'in gerçekleştiğini kanıtlayabildiği şeylerin bir özetidir.

Bu ayrım, makbuzu inceleme, devir teslim ve gelecekteki agent oturumları için faydalı kılar.

13. Her Hatanın Harness'i İyileştirmesini Sağlayın

Çoğu ekip başarısız olan çıktıyı düzeltir.

Daha iyi yaklaşım, o hataya izin veren sistemi düzeltmektir.

1EKSİK CONTEXT
2-> proje haritasını iyileştir
3
4YANLIŞ ARAÇ
5-> yönlendirmeyi veya araç sözleşmesini iyileştir
6
7KÖTÜ ÇIKTI
8-> doğrulayıcı ekle
9
10TEKRARLAYAN DÖNGÜ
11-> yeniden deneme sınırı ekle
12
13GÜVENSİZ EYLEM
14-> izin geçidi ekle
15
16KAYIP KARAR
17-> state'i kalıcı hale getir
18
19BİLİNMEYEN HATA
20-> izlemeyi iyileştir

Harness engineering'in bileşik getiri sağlamaya başladığı yer burasıdır.

Düzeltilen bir çıktı tek bir çalıştırmaya yardımcı olur.

Düzeltilen bir harness ise ondan sonraki her çalıştırmayı iyileştirir.

En iyi agent sistemleri daha güvenilir hale gelir çünkü hatalar geride bir altyapı bırakır.

14. En Küçük Faydalı Harness ile Başlayın

Başlamak için devasa bir orkestrasyon platformuna ihtiyacınız yok.

Katman katman inşa edin.

1SEVİYE 0
2
3prompt
4model
5
6SEVİYE 1
7
8görev sözleşmesi
9proje haritası
10araçlar
11
12SEVİYE 2
13
14yapılandırılmış state
15doğrulama
16sınırlı döngü
17
18SEVİYE 3
19
20izinler
21izler
22kurtarma
23insan geçitleri

Kısa bir araştırma görevi sadece bir prompt ve bir inceleme gerektirebilir.

Dosya erişimi, ağ erişimi ve dağıtım yeteneği olan altı saatlik bir kodlama görevi çok daha fazlasını gerektirir.

Karmaşıklığı, hata yüzeyi bunu hak ettiğinde ekleyin.

Agent mimarisi havalı göründüğü için değil.

Harness Engineering Kontrol Listesi

Bir agent'a anlamlı bir otonomi vermeden önce şunları sorun:

1[ ] Başarı, yürütmeden önce tanımlandı mı?
2
3[ ] Agent her şeyi yüklemeden doğru context'i
4    bulabiliyor mu?
5
6[ ] Her aracın net bir amacı, şeması ve hata durumu var mı?
7
8[ ] Önemli kararlar konuşmanın dışında saklanıyor mu?
9
10[ ] Tamamlanma kanıt gerektiriyor mu?
11
12[ ] Riskli eylemler politikayla korunuyor mu?
13
14[ ] Her döngünün bir yeniden deneme sınırı var mı?
15
16[ ] Çalıştırma kesinti sonrası devam edebiliyor mu?
17
18[ ] Her önemli eylemi yeniden yapılandırabiliyor musunuz?
19
20[ ] Hata bir kuralı, aracı, testi, haritayı veya izni iyileştiriyor mu?
21
22[ ] Son değişiklik geri alınabilir mi?

Cevapların birkaçı hayır ise, daha güçlü bir model agent'ı otomatik olarak güvenilir kılmaz.

Sadece hatanın daha hızlı ve daha pahalı olmasını sağlayabilir.

Asıl Dönüşüm

Prompt engineering şunu sorar:

Modele ne söylemeliyim?

Context engineering şunu sorar:

Model şu an ne bilmeli?

Harness engineering şunu sorar:

Modelin harekete geçmesini, işini doğrulamasını, hatalardan kurtulmasını ve güvenli çalışmasını sağlayan sistem nedir?

1PROMPT
2-> talimat
3
4CONTEXT
5-> çalışma görünümü
6
7HARNESS
8-> işletim ortamı
9
10DÖNGÜ
11-> yerel düzeltme
12
13GRAFİK
14-> koordinasyon

Modeller değişmeye devam edecek.

Kalıcı avantaj onların etrafında yaşar.

Sözleşmeleriniz iyileşir.

Araçlarınız iyileşir.

Testleriniz iyileşir.

State'iniz temizlenir.

İzinleriniz güvenli hale gelir.

Kurtarma mantığınız akıllanır.

Hatalarınız altyapıya dönüşür.

Yetenekli modellerin güvenilir agent'lara dönüşme yolu budur.

İşte bu Harness Engineering'dir.

Buraya Kadar Okuduysanız

Bu rehberi yer imlerine ekleyin.

Beni X'te takip edin: x.com/0xjmori

Substack hesabıma abone olun: substack.com/@lunarresearcher

Bu makaleyi, her agent hatasını daha uzun bir prompt'la çözmeye çalışan birine gönderin.