Harness Mühendisliği: AI Ajanlarını “Akıllı” Olmaktan “Güvenilir Çalışan Sistemlere” Dönüştürmek

1. Önce temel kavramlar

AI mühendisliğinde bugün birbirine çok benzeyen fakat aslında farklı seviyelerde çalışan birkaç kavram var.

Bunları şöyle düşünebiliriz:

Prompt Engineering → Context Engineering → Agent Engineering → Harness Engineering

Bunlar birbirinin alternatifi değil. İç içe geçmiş katmanlar.

Prompt Engineering

En dar katmandır.

Modele ne söylediğinizle ilgilenir.

Örneğin:

“Bu repository'yi analiz et. Next.js mimarisini değiştirme. Önce mevcut yapıyı çıkar, sonra değişiklik öner.”

Bu bir prompt'tur.

Problem şudur:

Model promptu anlayabilir ama uygulamak zorunda değildir.

Örneğin:

“Mevcut frontend stack'i değiştirme.”

dediğiniz halde ajan yeni bir UI framework kurabilir.

Çünkü prompt çoğunlukla probabilistic guidance sağlar.

2. Context Engineering

Context Engineering daha geniştir.

Buradaki soru:

Model karar verirken hangi bilgileri görmeli?

Örneğin bir developer agent çalıştırıyorsunuz.

Ajanın görmesi gerekenler:

PROJECT.md ARCHITECTURE.md AGENTS.md DESIGN_SYSTEM.md API_CONTRACT.md DATABASE_SCHEMA.md SECURITY_RULES.md repo git history open issues test results runtime logs

Bunların tamamını her istekte modele verirseniz context şişer.

Bu nedenle Context Engineering şu problemleri çözer:

Ne verilecek? Ne zaman verilecek? Ne kadar verilecek? Nereden getirilecek? Hangisi source-of-truth olacak?

LangChain'in harness yaklaşımında da temel işlerden biri her adımda modele görev için doğru context'i sağlamaktır.

3. Agent nedir?

Bir LLM kendi başına aslında agent değildir.

Kabaca:

INPUT ↓ MODEL ↓ OUTPUT

Model size cevap verir.

Agent ise:

┌──────────────┐ │ MODEL │ └──────┬───────┘ ↓ DECISION ↓ TOOL SELECTION ↓ TOOL EXECUTION ↓ RESULT ↓ MODEL AGAIN ↓ ...

şeklinde çalışan bir sistemdir.

Örneğin ajan:

Repository'yi oku ↓ Dosyaları bul ↓ Architecture.md oku ↓ Kod yaz ↓ npm test çalıştır ↓ Test başarısız ↓ Logları oku ↓ Kodu düzelt ↓ Testi tekrar çalıştır ↓ Başarılı ↓ PR oluştur

yapabilir.

Model artık yalnızca konuşmuyor.

Bir ortam içerisinde hareket ediyor.

Microsoft'un güncel tanımı da agent harness'ı, model ve tool çağrılarını yöneten, conversation state/context'i yöneten, approval politikalarını uygulayan ve uzun görevlerde agent'ın ilerlemesini sağlayan runtime scaffolding olarak tanımlıyor.

4. Peki Harness nedir?

Şimdi kritik noktaya geliyoruz.

Ortada güçlü bir model olduğunu düşünelim:

GPT / Claude / Gemini / başka model

Bu model tek başına şirketinizi, repository'nizi veya çalışma kurallarınızı bilmiyor.

Etrafına bir sistem kuruyoruz.

┌─────────────────────┐ │ MODEL │ └─────────────────────┘

MODELİN ETRAFINDA:

CONTEXT │ ┌────────┴────────┐ │ │ MEMORY TOOLS │ │ KNOWLEDGE SKILLS │ │ POLICIES SANDBOX │ │ SECURITY PERMISSIONS │ │ TESTS OBSERVABILITY │ │ EVALS FEEDBACK

İşte bu dış yapı:

HARNESS

oluyor.

LangChain — The Anatomy of an Agent Harness

LangChain'in geniş tanımı özellikle yararlı:

Model değilsen harness'ın parçasısın.

Dolayısıyla harness yalnızca prompt dosyası değildir.

5. Harness Engineering nedir?

Harness hazır bir ürün değil.

Harness Engineering, bu çalışma ortamını bilinçli biçimde tasarlama disiplinidir.

Ama bence kavramın özünü Mitchell Hashimoto'nun yaklaşımı çok daha iyi anlatıyor.

HashiCorp'un kurucularından ve Terraform'un yaratıcısı Mitchell Hashimoto, 5 Şubat 2026 tarihli yazısında kendi AI kullanım sürecinin beşinci aşamasını:

“Engineer the Harness”

olarak tanımladı.

Temel prensibi şuydu:

Agent bir hata yaptığında yalnızca o hatayı düzeltme. Sistemi değiştir ki aynı hata tekrar oluşmasın.

Bu Harness Engineering'in belki de en önemli prensibidir.

Klasik AI kullanımı Agent hata yaptı ↓ İnsan fark etti ↓ İnsan prompt verdi ↓ Agent düzeltti

Bir hafta sonra:

Agent aynı hatayı tekrar yaptı.

İnsan yeniden düzeltir.

Harness Engineering yaklaşımı Agent hata yaptı ↓ Hata sınıflandırıldı ↓ Neden oluştu? ↓ Harness değiştirildi ↓ Kural / test / tool / validator oluşturuldu ↓ Aynı hata artık otomatik yakalanıyor

Yani:

Her hata sistemin kurumsal hafızasına dönüşür.

Bu çok önemli bir paradigma değişimidir.

6. Harness Engineering nasıl ortaya çıktı?

Kavramın kökü aslında yeni değil.

Yazılım mühendisliğinde uzun zamandır:

test harness

kavramı vardı.

Bir yazılım bileşenini kontrollü biçimde çalıştıran, input veren ve çıktıyı ölçen sistemlere test harness deniliyordu.

Makine öğrenmesinde de evaluation harness'ları kullanıldı.

2026'da ise kavram AI agent dünyasında çok daha geniş bir anlam kazandı. Yakın tarihli akademik çalışma da kelimenin soy ağacını “horse tack → classic test harness → ML evaluation harness → agent harness” şeklinde inceliyor.

Modern kullanımın yaygınlaşmasında Şubat 2026 özellikle önemli.

Mitchell Hashimoto 5 Şubat'ta kendi AI kullanım yolculuğunda “Engineer the Harness” kavramını kullandı.

Altı gün sonra OpenAI'nin Harness Engineering yazısı yayımlandı.

Oradaki deney çok çarpıcıydı.

Üç kişilik ekip, beş ay boyunca bir ürünü elle yazılmış sıfır satır kod yaklaşımıyla geliştirdi. Uygulama kodundan testlere, CI yapılandırmasından dokümantasyona ve observability araçlarına kadar repository içindeki kod Codex tarafından üretildi; sistem yaklaşık bir milyon satıra ulaştı.

Burada ortaya çıkan temel ders şuydu:

İnsanların ana işi kod yazmak yerine environment tasarlamak, intent tanımlamak ve feedback loop kurmak haline gelmeye başladı.

OpenAI bunu:

Humans steer. Agents execute.

şeklinde özetledi.

Nisan ayında aynı yaklaşım Symphony orkestrasyon sistemine doğru ilerledi: proje yönetimindeki görevler agent'lara atanabiliyor, agent'lar sürekli çalışıyor ve insanlar sonuçları gözden geçiriyor.

7. Neden şimdi ortaya çıktı?

Çünkü modellerin problemi değişti.

2023 civarında temel soru şuydu:

Model bunu yapabilir mi?

Sonra:

Modele nasıl prompt yazmalıyım?

Sonra:

Modele hangi context'i vermeliyim?

Şimdi ise:

Model bunu 500 kez güvenilir biçimde yapabilir mi?

İşte Harness Engineering esas olarak bu son sorunun cevabı.

Çünkü production sisteminde:

%80 başarı çoğu zaman başarısızlıktır.

Bir developer agent günde 100 işlem yapıyorsa ve %95 doğru çalışıyorsa:

yaklaşık 5 problem/gün üretir.

Dolayısıyla mesele artık yalnızca intelligence değildir.

Reliability + Control + Verification problemidir.

8. Harness'ın temel bileşenleri

Pratikte güçlü bir harness'ı yaklaşık sekiz sistem halinde düşünebiliriz.

1 — Instructions

Agent ne yapmalı?

SYSTEM PROMPT AGENTS.md PROJECT.md RULES POLICIES SKILLS SOP 2 — Context

Agent ne bilmeli?

Repository Architecture Documentation Database schema API contracts Previous decisions Issues Runtime state Logs 3 — Tools

Agent ne yapabilir?

read_file write_file git terminal database browser API deployment monitoring ticketing 4 — Permissions

Agent ne yapmaya yetkilidir?

Örneğin:

READ repo ✓ WRITE feature ✓ RUN tests ✓ CREATE PR ✓

DELETE database ✗ MERGE main ✗ DEPLOY production approval required CHANGE firewall approval required

Burada artık prompt değil gerçek control plane vardır.

5 — Verification

Agent yaptığı işin doğru olduğunu nasıl anlayacak?

lint typecheck unit tests integration tests E2E architecture tests security scan schema validation visual regression performance tests

Burası Harness Engineering'in en kritik bölümlerinden biridir.

6 — Feedback Loop ACT ↓ OBSERVE ↓ VERIFY ↓ FAIL? ↓ YES DIAGNOSE ↓ REPAIR ↓ VERIFY AGAIN

Agent'ın kendi hatasını görebilmesi gerekir.

7 — Memory

Sistem geçmişten ne öğreniyor?

Decisions Failures Solutions Architecture choices Known issues User preferences Project history

Burada önemli ayrım:

Context = şu anda bilmesi gerekenler

Memory = geçmişten saklanan bilgiler

8 — Observability

Agent'ın kendisini de gözlemlemek gerekir.

Agent runs Tool calls Token usage Cost Latency Errors Retries Failed tasks Success rate Human interventions Policy violations

Yani observability artık yalnızca uygulamaya değil:

AI çalışanına da uygulanır.

9. Feedforward ve Feedback

Thoughtworks'ten Birgitta Böckeler'in Martin Fowler sitesindeki Harness Engineering analizinde çok yararlı bir ayrım var.

Harness iki yönden agent'ı kontrol eder.

Feedforward

Agent hata yapmadan önce yönlendirmek.

Örneğin:

Architecture.md coding rules examples API contracts skills AGENTS.md design system

Mesaj:

“Böyle çalış.”

Feedback

Agent yaptıktan sonra sonucu kontrol etmek.

tests linters validators security scanners runtime checks visual tests AI reviewers

Mesaj:

“Yaptığın şey doğru mu?”

İyi harness ikisini birlikte kullanır:

FEEDFORWARD ↓ AGENT ↓ ACT ↓ RESULT ↓ FEEDBACK │ └────────→ AGENT

Bu aslında klasik control-system engineering mantığıdır.

10. Deterministic ve probabilistic kontrol

Burada Harness Engineering açısından son derece önemli başka bir ayrım var.

Bir agent'a:

“Database migration yaparken production database'i asla silme.”

demek bir talimattır.

Agent büyük ihtimalle uyar.

Ama bu:

probabilistic control

olur.

Bunun yerine production credentials agent'ın sandbox'ında hiç bulunmuyorsa:

deterministic control

oluşur.

Aynı şekilde:

"TypeScript hatası bırakma."

prompt.

Ama:

npm run typecheck

başarısızsa PR oluşturmayı engellemek gerçek kontrol.

Harness Engineering mümkün olduğunca:

talimat → mekanik enforcement

dönüşümünü hedefler.

11. Ne zaman Harness Engineering gerekir?

Her AI kullanımında büyük harness kurmak gerekmez.

Örneğin:

“Bana bu maili düzelt.”

için harness engineering gereksizdir.

Ama aşağıdaki denklem büyüdükçe harness ihtiyacı hızla artar:

Autonomy × Complexity × Duration × Risk

Örneğin:

Tek prompt ↓ Chatbot ↓ Tool kullanan agent ↓ Repository agent ↓ Uzun süre çalışan agent ↓ Multi-agent ↓ Production'a dokunan agent ↓ Şirket operasyonu yöneten agent

Aşağı indikçe harness kritik hale gelir.

12. Harness kurmak için hangi bilgiler gerekir?

Burası uygulamada en önemli bölüm.

Bir harness'a başlamadan önce model seçmekten önce aşağıdaki soruların cevapları gerekir.

A. Amaç

Agent'ın görevi nedir?

Developer mı? Security agent mı? CFO agent mı? Customer support mu? Research agent mı? Operations agent mı? B. Environment

Nerede çalışıyor?

repository server AWS local Docker browser ERP CRM database C. Knowledge

Bilginin source-of-truth'u neresi?

GitHub documentation database Drive CRM API knowledge graph D. Tools

Agent hangi eylemleri yapabilmeli?

E. Permissions

Her tool için:

READ WRITE EXECUTE DELETE APPROVE

tanımlanmalı.

F. Constraints

Agent'ın kesinlikle yapmaması gerekenler nedir?

G. Success criteria

Agent işi bitirdiğini nasıl bilecek?

Bu soru olağanüstü önemlidir.

“Dashboard yap.”

yetersizdir.

Ama:

route exists API connected no mock data typecheck passes tests pass visual reference matches architecture rules pass

ölçülebilir başarı kriterleridir.

H. Failure modes

Agent hangi hataları yapabilir?

Harness Engineering'in büyük kısmı burada oluşur.

Her failure:

FAILURE ↓ ROOT CAUSE ↓ HARNESS CHANGE

döngüsüne girer.

13. Dolayısıyla Harness Engineering bir defalık kurulum değildir

Bu nokta çok önemli.

Harness:

“Bir kez AGENTS.md yazdım, tamamdır.”

değildir.

Asıl süreç:

Agent çalışır ↓ Hata oluşur ↓ Hata sınıflandırılır ↓ Root cause bulunur ↓ Harness değiştirilir ↓ Yeni test / rule / tool eklenir ↓ Agent tekrar çalışır ↓ Yeni hata bulunur ↓ Harness gelişir

Böylece agent kadar:

agent'ın çalışma sistemi de öğrenir.

Hashimoto'nun yaklaşımının güçlü tarafı tam olarak budur: tekrar eden yanlış davranışı sürekli promptla düzeltmek yerine AGENTS.md veya programatik verification mekanizmasıyla sistem seviyesinde ortadan kaldırmak.

14. Framework, Orchestrator ve Harness aynı şey değildir

Bu ayrım da önemli.

Framework

Agent yapmak için yapı taşları verir.

Orchestrator

Birden fazla agent'ın ne zaman ve hangi sırayla çalışacağını yönetir.

Harness

Agent'ın çalışabileceği kontrollü dünyayı oluşturur.

Dolayısıyla:

ORCHESTRATOR

Agent A Agent B │ │ ┌────▼────┐ ┌────▼────┐ │ HARNESS │ │ HARNESS │ └────┬────┘ └────┬────┘ │ │ MODEL MODEL

şeklinde sistemler oluşabilir.

Akademik literatürde de agent harness'ın agent framework, SDK, IDE plugin, eval harness ve orchestrator'dan ayrıştırılması artık ayrıca ele alınıyor.

15. Prompt Engineering → Context Engineering → Harness Engineering

Üç kavramı tek örnekte görelim.

Bir Developer Agent'a:

Prompt Engineering

“Mevcut frontend mimarisini bozma.”

Context Engineering

Agent'a:

frontend architecture design tokens components reference implementation Figma specifications repo structure

getirilir.

Harness Engineering

Sistem şunu uygular:

Agent ↓ Architecture rules loaded ↓ Allowed packages checked ↓ Implementation ↓ Lint ↓ Typecheck ↓ Architecture fitness test ↓ Visual comparison ↓ Forbidden dependency check ↓ PASS? ├── NO → Agent repairs └── YES → PR

İşte esas fark budur.

Prompt “ne yapacağını” söyler.

Context “ne bilmesi gerektiğini” sağlar.

Harness “hangi dünyada çalışacağını ve sonucunun nasıl kabul edileceğini” belirler.

16. Bu kavramın daha büyük sonucu

Harness Engineering yalnızca developer agent meselesi olarak başladıysa da prensip aslında çok daha geniş.

Bir CFO Agent düşünelim.

Model:

reasoning analysis forecasting

yapıyor.

Harness:

ERP access bank APIs invoice data budget rules company policies approval thresholds audit log financial validations permissions human approval

sağlıyor.

Security Agent:

MODEL + server telemetry logs WAF SIEM security policies runbooks permission boundaries approval gates incident history

Operations Agent:

MODEL + KPIs CRM ERP tickets SOPs alerts workflows approvals audit

Dolayısıyla gelecekte büyük şirketlerde muhtemelen yalnızca:

AI Agent

değil,

Agent + Enterprise Harness

konuşacağız.