Açık kaynak müfredat
Düzenek Mühendisliği (Harness Engineering)
AI kod ajanlarını güvenilir kılan çevreyi tasarlamak: repo, durum, geri bildirim, doğrulama ve gözlemlenebilirlik.
harnessbeş aparat
Düzeneğin temel mekanizması
Bir düzenek (harness), modeli çevre yoluyla yönlendirir. Beş aparatı vardır:
- 01RepoTek hakikat kaynağı. Talimat, kod ve karar tarihçesi burada yaşar.
- 02Durum (state)Oturumlar arası süreklilik.
progress.md,decisions.md, init script'leri. - 03Çalışma zamanı geri bildirimiAjan kendi kodunu test eder, hataları görür, düzeltir.
- 04Öz-doğrulamaBağımsız rol ayrımı: hallucination ve "erken zafer" engellenir.
- 05GözlemlenebilirlikHer eylem izlenebilir, başarısızlık sessizce gerçekleşmez.
12 ders6 proje8 şablonCC0 1.0
Başla
- 01İlk dersi okuDers 01: Yetkin Ajanlar Neden Hâlâ Başarısız Oluyor ile teorik zemini kur.
- 02İlk projeyi çalıştırProje 01: Kural Öncelikli ile farkı kendi gözünle gör.
- 03Şablonları indirKütüphane altındaki temel dosyaları kendi reponuza kopyalayın.
Bu doküman, Düzenek Mühendisliği (Harness Engineering) disiplinine giriştir. Konu, modeli daha güçlü kılmak değil, modeli kuşatan çevreyi (repoyu, durumu, geri bildirim döngülerini, doğrulama mekanizmalarını ve gözlemlenebilirliği) bir mühendislik problemi olarak ele almaktır.
Terim kullanımı. Bu dokümanlarda "Düzenek Mühendisliği (Harness Engineering)" terimi her geçtiğinde parantez içinde özgün İngilizce karşılığıyla birlikte yazılır. Tek başına "harness" yerine "düzenek" kullanılır.
Neden düzenek?
Modern modeller (Claude, GPT, Gemini) bağımsız olarak değil, bir düzenek (harness) içinde çalışırken üretkendir. Düzenek olmadığında en yetkin model bile şu hataları yapar:
- Bağlamı kaybeder, oturumlar arasında devam edemez
- Erken "tamamladım" der, gerçekte yarım bırakır
- Kendi çıktısını doğrulamadan teslim eder
- Repo'da iz bırakmaz, sonraki oturum sıfırdan başlar
Düzenek Mühendisliği (Harness Engineering) bu beş aparatı sistematik olarak kurar: repo, durum, çalışma zamanı geri bildirimi, öz-doğrulama ve gözlemlenebilirlik.
Dersler
Her ders bir anti-pattern teşhisi: yetkin ajanların neden başarısız olduğu, neyin işlediği ve hangi mekanizmanın bunu çözdüğü.
12 ders
- 01Aynı Model, Farklı SonuçAynı model, aynı prompt, farklı çevre. Çıktı kategorik olarak farklı. Modelden önce sorgulanması gereken şey düzenektir.
- 02Düzeneğin AnatomisiDüzenek (harness) bir prompt dosyası değil, model ağırlıklarının dışında kalan her şeydir: talimat, araç, ortam, durum ve geri bildirimden oluşan beş katmanlı bir mühendislik birimi.
- 03Repo: Hakikat KaynağıDüzenek Mühendisliği (Harness Engineering) için repo, ajanın tek hakikat kaynağıdır. Repoda olmayan bilgi, ajan için yoktur.
- 04Şişmiş Talimat SendromuDüzenek Mühendisliği (Harness Engineering) müfredatında dördüncü durak: tek dev AGENTS.md neden çürür, yönlendirici dosya + konu dokümanları neden çalışır.
- 05Vardiya DefteriBağlam penceresi sonludur, unutkanlık varsayılandır. Süreklilik ancak dosya sistemine yazılıp vardiya rutinleriyle uygulandığında ayakta kalır.
- 06Önce Temel, Sonra DuvarBaşlangıç (initialization) ayrı bir fazdır, ayrı bir optimizasyon hedefi vardır. Uygulama ile karıştırıldığında dört yerden birden çatlar. Düzenek Mühendisliği (Harness Engineering) müfredatının altıncı dersi.
- 07WIP=1 DisipliniAşırıya kaçmak ve yarım bırakmak aynı madalyonun iki yüzüdür. Kanban'dan WIP=1, Little's Law ve VCR ile Düzenek Mühendisliği (Harness Engineering) bu simbiyozu kırar.
- 08Özellik Listesi Bir PrimitiftirDüzenek Mühendisliği (Harness Engineering) içinde özellik listesi (feature list) insan için bir not değil, scheduler, verifier, handoff reporter ve progress tracker'ın okuduğu işletim primitifidir.
- 09Erken Zafer İlanıAjan 'tamamlandı' der, e-posta hiç gönderilmemiştir. Tamamlanma yargısı ajanın değil, Düzenek Mühendisliği (Harness Engineering) sözleşmesinin işidir.
- 10Üç Katmanlı Doğrulama KapısıBirim testler bileşen sınırlarına mimari olarak kördür. Yalnız uçtan uca test sistem düzeyi kusurların yokluğunu kanıtlar ve ajanın davranışını değiştirir.
- 11Düzeneğin GözleriGözlemlenebilirlik, Düzenek Mühendisliği (Harness Engineering) için sonradan eklenen bir özellik değil: runtime ve süreç olmak üzere iki paralel katmanda birlikte tasarlanan mimari bir özelliktir.
- 12Temiz TeslimEntropi varsayılan. Düzenek Mühendisliği (Harness Engineering) uzun vadeli güvenilirliği işletim disiplinine bağlar. Temiz state, tamamlanma tanımının parçasıdır.
Projeler
Her proje starter/ ve solution/ ile hands-on uygulama. Sonunda capstone'da uçtan uca bir düzenek kuruyorsun.
6 proje · kod GitHub'da
- 01Kural ÖncelikliAynı görev, iki düzenek seviyesi. Yalın prompt'tan AGENTS.md + Makefile + smoke test'e geçişin etkisini kendi reponuzda ölçün.
- 02Bilgi MimarisiBloated tek AGENTS.md'den yönlendirici dosya + konu dokümanları + per-module ARCHITECTURE.md'ye geçiş. Bilgi görünürlüğü boşluğunu kapatın.
- 03Vardiya SüreklilikYarım kalmış bir özelliği kasıtlı bırak, süreklilik aparatları (PROGRESS.md + DECISIONS.md + init.sh + vardiya rutinleri) ile bir sonraki oturum dakikalar içinde devam etsin.
- 04Geri Bildirim HalkasıSerbest formda features.md'den yapılandırılmış features.json + verify.sh + WIP=1 kuralına. Çalışma zamanı geri bildirimini ajan otomasyonuna bağlayın.
- 05Yapan ve DenetleyenAynı kod tabanı, iki rol modeli. Tek executor'da gizli kalan PUT-404 bug'ı, yapan/denetleyen ayrımı + üç katmanlı doğrulama ile 30 saniyede yakalanır.
- 06Capstone: Bütünleşik DüzenekBeş aparat + gözlemlenebilirlik + temiz teslim, tek bir çalışan kod tabanında birleşir. Tam OpenTelemetry instrumentation, Quality.md, session_close.sh, idempotent cleanup.
Kütüphane
Kopyala-kullan şablonlar: AGENTS.md, progress.md, init script'leri, doğrulama hook'ları.
8 şablon · kütüphane sayfası
- 01AGENTS.mdRepo kökündeki yönlendirici dosya: ajanın iniş sayfası, ansiklopedi değil router.
- 02PROGRESS.md & DECISIONS.mdVardiya defteri ile gerekçe günlüğü: süreklilik kaybını yapısal olarak engelleyen iki durum aparatı.
- 03Makefile & init.shTek komutla başlatan, tek komutla doğrulayan bir ortam aparatı için minimum çalışan iskelet.
- 04features.jsonDüzeneğin (harness) geri bildirim aparatının primitifi: scheduler, verifier, handoff reporter ve progress tracker'ın okuduğu makine-okunabilir özellik listesi.
- 05verifier.md & Definition of DoneTamamlanma yargısını yapandan alıp denetleyene veren iki sözleşme: verifier'ın rolü ve AGENTS.md içindeki DoD bloğu.
- 06Sprint Sözleşmesi & RubrikÜreten ile değerlendiren arasında kod yazımından önce kurulan ön-anlaşma ve değerlendirme varyansını düşüren A/B/C/D bant tablosu.
- 07OpenTelemetry İzHer oturum için tek bir iz: runtime gerçeğini AgentOps, Inspect AI ve Jaeger arasında taşıyabilen tek standart.
- 08Session Close & Quality DocBir oturum ya commit ile ya rollback ile biter, ortada kalış yok. İki aparat: çıkış kontrol listesi ve modül başına sağlık tablosu.
Kaynak
Bu müfredat walkinglabs/learn-harness-engineering (yeni sekmede açılır) temel alınarak Türkçe'ye uyarlanmıştır. Düzenek Mühendisliği (Harness Engineering) terminolojisi orijinal kaynaktaki "harness engineering" söylemine karşılık gelir.